|
|
@@ -0,0 +1,97 @@
|
|
|
+# 报告类型→商城商品链接配置（设计）
|
|
|
+
|
|
|
+- 日期：2026-10-30
|
|
|
+- 状态：待派发
|
|
|
+- 优先级：P1
|
|
|
+- 模块：cfc-backend / cfc-frontend / cfc-web
|
|
|
+- 需求方：廖总
|
|
|
+- 需求原文：小程序上传报告页面，列出了支持的报告类型，其中菌群检测和 DAN 报告支持直接链到商品，哪种报告可链接、链接到哪个商品，可以在后台配置。
|
|
|
+
|
|
|
+## 1. 背景与现状
|
|
|
+
|
|
|
+小程序上传报告页 `cfc-frontend/pages/health/report-upload.vue` 的「支持的报告类型」列表为**前端硬编码** 5 种（菌群检测报告 / 素质测评 A2 / 体检报告 / 舌象照片 / 体脂秤报告），无任何商品链接能力。
|
|
|
+
|
|
|
+报告类型的权威定义为数据库表 `report_type_registry`（实体 `ReportTypeRegistry`），目前仅注册两种：
|
|
|
+
|
|
|
+| type_id | family | display_name | 对应小程序列表项 |
|
|
|
+|---|---|---|---|
|
|
|
+| `gut_flora` | gut_flora | 菌群检测 | 菌群检测报告 |
|
|
|
+| `dan_a2` | dan | 素质测评A2 | 素质测评 A2 |
|
|
|
+
|
|
|
+体检 / 舌象 / 体脂秤在 registry 中无记录（舌诊走专用 `uploadType=tongue` 流程，体检/体脂秤走 `health_reports` 通用表）。
|
|
|
+
|
|
|
+商城商品：`Product` → `products` 表，后台管理页 `cfc-web/src/views/admin/ProductManage.vue`（路由 `product-manage`），小程序商品详情页路由 `/pages/discover-detail/product-detail/product-detail?id=<productId>`。测评类商品（菌群测评、DAN 测评）为运行时由管理员在后台创建，非种子数据，配置时须从现有商品列表选择。
|
|
|
+
|
|
|
+后台已有报告类型管理页 `cfc-web/src/views/admin/ReportTypeManagement.vue`，但**仅类型/指纹配置，无商品关联字段**；「报告类型→商品」配置在**后端、前端、数据库三层均不存在**。
|
|
|
+
|
|
|
+## 2. 方案（定稿）
|
|
|
+
|
|
|
+### 2.1 数据层
|
|
|
+
|
|
|
+给 `report_type_registry` 直接加一列，无需新表（registry 已覆盖用户聚焦的 gut_flora / dan_a2，最小侵入）：
|
|
|
+
|
|
|
+```sql
|
|
|
+linked_product_id BIGINT NULL COMMENT '关联商城商品 products.id，NULL=不可链接'
|
|
|
+```
|
|
|
+
|
|
|
+- 迁移：`DatabaseInitializer` 用 `ensureColumn("report_type_registry", "linked_product_id", ...)`，取最新迁移编号递增；**必须同步** `schema.sql` 中 `report_type_registry` 的 `CREATE TABLE`。
|
|
|
+- 幂等：可重复执行。
|
|
|
+
|
|
|
+### 2.2 后端
|
|
|
+
|
|
|
+1. 实体 `ReportTypeRegistry.java` 加字段 `private Long linkedProductId;`（MyBatis-Plus 驼峰映射）。
|
|
|
+2. 管理端 `ReportParserAdminController`：
|
|
|
+ - `/api/admin/report-parser/types`（查列表）返回含 `linkedProductId` 与商品名（可 join products 或前端二次解析）。
|
|
|
+ - `/api/admin/report-parser/types/save` 接收并保存 `linkedProductId`（允许清空=NULL）。
|
|
|
+3. 小程序端公开查询接口：在 `ReportParserController` 新增 `POST /api/report-parser/types/links`（**遵循 AGENTS.md：统一 `@PostMapping`，禁止 GET**），返回激活类型链接配置：
|
|
|
+ ```json
|
|
|
+ [{ "typeId": "gut_flora", "displayName": "菌群检测", "linkedProductId": 12, "productName": "肠道菌群测评" }]
|
|
|
+ ```
|
|
|
+ 仅返回 `is_active=1 AND linked_product_id IS NOT NULL` 的记录（供小程序显示「查看商品」入口）。若某类型未配置链接则不出现在结果中（小程序回退为纯展示）。
|
|
|
+
|
|
|
+### 2.3 小程序前端（cfc-frontend/pages/health/report-upload.vue）
|
|
|
+
|
|
|
+- **保留**现有硬编码 5 项列表（不因 registry 仅 2 条而移除体检/舌象/体脂秤，避免产品倒退）。
|
|
|
+- `onLoad` 拉取 `/api/report-parser/types/links`，对配置了链接的类型（gut_flora / dan_a2 等）在对应 `guide-item` 右侧追加「查看商品」入口（箭头 + 商品名），点击 `uni.navigateTo('/pages/discover-detail/product-detail/product-detail?id=' + linkedProductId)`。
|
|
|
+- 未配置链接的类型保持纯展示；接口失败时静默回退纯展示（不阻断页面）。
|
|
|
+
|
|
|
+### 2.4 后台管理端（cfc-web/src/views/admin/ReportTypeManagement.vue）
|
|
|
+
|
|
|
+- 编辑对话框新增「关联商品」选择器：下拉选项来自现有商品列表接口（可复用 `/api/admin/product/list` 或等价接口），展示商品名，可清空（=不可链接）。
|
|
|
+- 列表新增「关联商品」列，显示商品名或「— 未链接」。
|
|
|
+- 保存时提交 `linkedProductId`。
|
|
|
+
|
|
|
+## 3. 涉及文件清单
|
|
|
+
|
|
|
+| 层 | 文件 | 改动 |
|
|
|
+|---|---|---|
|
|
|
+| 后端 | `cfc-backend/src/main/java/com/etotem/cfc/entity/ReportTypeRegistry.java` | +linkedProductId |
|
|
|
+| 后端 | `cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java` | +迁移列 |
|
|
|
+| 后端 | `cfc-backend/src/main/java/com/etotem/cfc/controller/ReportParserAdminController.java` | types/save 支持 linkedProductId |
|
|
|
+| 后端 | `cfc-backend/src/main/java/com/etotem/cfc/controller/ReportParserController.java` | +POST /types/links |
|
|
|
+| 后端 | `cfc-backend/src/main/resources/schema.sql` | report_type_registry +linked_product_id |
|
|
|
+| 小程序 | `cfc-frontend/pages/health/report-upload.vue` | 列表叠加「查看商品」入口 |
|
|
|
+| 小程序 | `cfc-frontend/utils/api.js` | +getReportTypeLinks() |
|
|
|
+| 后台 | `cfc-web/src/views/admin/ReportTypeManagement.vue` | +关联商品选择器/列 |
|
|
|
+
|
|
|
+## 4. 验收标准
|
|
|
+
|
|
|
+- [ ] 小程序上传页菌群检测、DAN（素质测评 A2）项显示「查看商品」，点击跳转到配置的商品详情页。
|
|
|
+- [ ] 后台 ReportTypeManagement 可为某类型配置/清除关联商品，保存后小程序刷新即生效。
|
|
|
+- [ ] 未配置链接的类型不显示「查看商品」，列表展示与现状一致（5 项均在）。
|
|
|
+- [ ] 后端迁移幂等（重复启动不报错）；老数据 `linked_product_id=NULL` 正常。
|
|
|
+- [ ] `mvn clean compile`（cfc-backend）通过；`npm run build:mp-weixin`（cfc-frontend）通过；`npm run build`（cfc-web）通过。
|
|
|
+- [ ] 小程序无可选链 `?.`、无 CSS Grid、`:key` 用方法调用（遵循 AGENTS.md 小程序限制）。
|
|
|
+
|
|
|
+## 5. 技术约束（AGENTS.md 铁律）
|
|
|
+
|
|
|
+- 后端接口统一 `@PostMapping`，禁止 `@GetMapping/@PutMapping/@DeleteMapping`；`@Resource` 注入；控制器内手动检查 `@RequestAttribute("role")`。
|
|
|
+- MyBatis-Plus `@TableName` + 驼峰映射；迁移唯一入口 `DatabaseInitializer.runMigrations()` + `ensureColumn`，必须同步 `schema.sql`。
|
|
|
+- 新增接口前查阅 `docs/superpowers/api/API_REFERENCE.md` 避免重复。
|
|
|
+- 小程序禁止可选链、禁止 CSS Grid、禁止 `:key` 表达式、禁止直接 `new Date(string)`。
|
|
|
+
|
|
|
+## 6. 边界与取舍
|
|
|
+
|
|
|
+- 本次仅实现「报告类型→商品」关联配置与跳转；**不改动**报告类型列表的展示来源（仍硬编码），避免移除现有 3 项造成产品倒退。
|
|
|
+- 测评商品（菌群/DAN）需先在后台创建并上架，配置时才能选择；若未创建，对应类型显示「查看商品」入口但后端返回空链接时前端自动隐藏。
|
|
|
+- 不做「点击跳转时校验商品是否在售」——由商品详情页自身处理下架状态。
|
Agnes Agent