|
|
@@ -1,10 +1,11 @@
|
|
|
# 菌群报告页面重构设计规范
|
|
|
|
|
|
> 基于参考 JSON 完整数据，重构「肠道菌群报告详情页」，覆盖查看+编辑混合场景。
|
|
|
+> 页面只展示个性化数据（个人测定值），标准说明通过弹出框从知识库获取。
|
|
|
|
|
|
-**版本：** v1.0
|
|
|
+**版本：** v1.1（v1.0 修正：仅展示个性化数据 + 知识库弹出框 + 异常值颜色箭头）
|
|
|
**日期：** 2026-07-17
|
|
|
-**状态：** Approved
|
|
|
+**状态：** Draft
|
|
|
**作者：** Sisyphus
|
|
|
|
|
|
---
|
|
|
@@ -21,8 +22,10 @@
|
|
|
### 1.2 设计目标
|
|
|
|
|
|
1. **完整展示**：将所有报告板块（评分/指标/菌群/疾病风险/食物）全部呈现
|
|
|
-2. **可编辑**：用户可在查看页面转向编辑模式，调整解析错误的数据
|
|
|
-3. **保存兼容**：复用现有 `HealthReportDraft` 两阶段入库机制
|
|
|
+2. **仅展示个性化值**：页面只显示该人的测定数值，标准说明不内嵌
|
|
|
+3. **知识库弹出框**：每个菌、营养素、指标的名称可点击 → 弹出详细说明（来自独立知识库表）
|
|
|
+4. **异常值颜色+箭头**：超出正常范围的数值用颜色区分，名称上标 ↑（过高）↓（过低）
|
|
|
+5. **可编辑**：用户可在查看页面转向编辑模式，调整解析错误的数据
|
|
|
|
|
|
### 1.3 不在本文档范围
|
|
|
|
|
|
@@ -38,8 +41,9 @@
|
|
|
|--------|------|------|
|
|
|
| 页面拆分 | 主页 + 3 个详情页 | 食物 224 条 + 菌群 200 条过长，必须分页；指标用手风琴折叠到主页 |
|
|
|
| 模式 | 混合（默认查看 + 编辑切换） | 满足「全字段可编辑」同时保留查看优先体验 |
|
|
|
-| 编辑范围 | 仅修改现有条目（不增删） | YAGNI：当前需求是修正 AI 解析错误，不是新增数据 |
|
|
|
-| 保存路径 | `HealthReportDraft` + `/api/health/report/confirm` | 现有机制已支持修改后整体提交 |
|
|
|
+| 编辑范围 | 仅修改现有条目（不增删） | 当前需求是修正 AI 解析错误，不是新增数据 |
|
|
|
+| 保存路径 | 新增 `POST /api/health/report/edit` | 编辑已发布报告（不用 draftId） |
|
|
|
+| 说明展示 | 不内嵌，点击名称弹出知识库 | 页面干净，知识库可独立维护 |
|
|
|
|
|
|
---
|
|
|
|
|
|
@@ -63,9 +67,80 @@ page.json 中需新增 3 个路径：
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 4. 主页：gut-flora-detail.vue
|
|
|
+## 4. 异常值颜色与箭头规则（通用）
|
|
|
|
|
|
-### 4.1 板块布局（由上至下）
|
|
|
+所有页面（主页手风琴、菌群卡片、营养指标列表）统一使用以下规则：
|
|
|
+
|
|
|
+| 状态 | 颜色 | 箭头 | 示例 |
|
|
|
+|------|------|------|------|
|
|
|
+| `正常` / `低风险` | 默认文本 #333 | 无 | 维生素A 84 |
|
|
|
+| `偏高` / `过多` / `高` | 红色 #C62828 | ↑ | **双歧杆菌属↑** 12.8% |
|
|
|
+| `偏低` / `缺乏` / `不足` / `低` | 琥珀色 #E65100 | ↓ | **维生素B1↓** 2 |
|
|
|
+| `异常` | 红色 #C62828 | ⚠ | **炎症水平⚠** 16 |
|
|
|
+| `注意` | 黄色 #F59E0B | ⚠ | **甲状腺疾病⚠** |
|
|
|
+
|
|
|
+实现方式（Vue 2 inline 表达式）：
|
|
|
+```html
|
|
|
+<text :class="'name-' + item.status" v-if="item.status !== '正常'">{{ item.name }}<text class="arrow">{{ arrowMap[item.status] }}</text></text>
|
|
|
+<text v-else>{{ item.name }}</text>
|
|
|
+```
|
|
|
+
|
|
|
+不可用方法调用（`statusClass(item.status)`），必须内联 `:class="'status-' + item.status"`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 知识库弹出框（通用组件）
|
|
|
+
|
|
|
+### 组件：`components/health-knowledge-popup.vue`
|
|
|
+
|
|
|
+每个菌属名/营养素名/指标名都是可点击的，点击后打开一个弹出框显示该项目的知识库说明。
|
|
|
+
|
|
|
+```html
|
|
|
+<!-- 使用方式 -->
|
|
|
+<text class="kb-link" @tap="showKnowledge(item.type, item.name)">{{ item.name }}</text>
|
|
|
+
|
|
|
+<!-- 弹出框组件 -->
|
|
|
+<health-knowledge-popup
|
|
|
+ :visible="knowledgeVisible"
|
|
|
+ :item-type="knowledgeType" <!-- 'bacteria' | 'nutrient' | 'indicator' | 'vitamin' | 'amino_acid' -->
|
|
|
+ :item-name="knowledgeName" <!-- 如 "双歧杆菌属 Bifidobacterium" -->
|
|
|
+ @close="closeKnowledge" />
|
|
|
+```
|
|
|
+
|
|
|
+### 弹出框内容结构
|
|
|
+
|
|
|
+```
|
|
|
+┌────────────────────────────────┐
|
|
|
+│ 双歧杆菌属 Bifidobacterium [×]│
|
|
|
+│ ────────────────────────────── │
|
|
|
+│ 【分类】有益菌 │
|
|
|
+│ 【正常范围】0.19-14.59% │
|
|
|
+│ 【功能说明】 │
|
|
|
+│ 最重要的益生菌，参与肠道免疫屏障│
|
|
|
+│ 维护，抑制有害菌生长，促进营养 │
|
|
|
+│ 物质吸收...（完整说明文字） │
|
|
|
+│ │
|
|
|
+│ 【相关建议】 │
|
|
|
+│ 补充来源：酸奶、开菲尔等发酵食品│
|
|
|
+└────────────────────────────────┘
|
|
|
+```
|
|
|
+
|
|
|
+### 数据来源
|
|
|
+
|
|
|
+知识库数据存储在独立数据库表 `health_knowledge_base` 中。
|
|
|
+
|
|
|
+后端接口：
|
|
|
+```
|
|
|
+POST /api/health/knowledge/query
|
|
|
+body: { itemType: "bacteria", itemName: "双歧杆菌属 Bifidobacterium" }
|
|
|
+返回: { code: 200, data: { itemType, itemName, category, normalRange, description, suggestion } }
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 主页：gut-flora-detail.vue
|
|
|
+
|
|
|
+### 6.1 板块布局（由上至下）
|
|
|
|
|
|
1. **报告头部**（hero 渐变背景）
|
|
|
- 姓名、年龄、性别、报告编号、报告日期
|
|
|
@@ -78,7 +153,7 @@ page.json 中需新增 3 个路径：
|
|
|
- 🍽️ 饮食推荐（X 项）
|
|
|
- 📋 全部指标（X 项）
|
|
|
4. **肠道功能面板**（手风琴 Accordion）
|
|
|
- - 肠道屏障与代谢物
|
|
|
+ - 肠道屏障与代谢物 → 指标列表，名称可点击弹知识库，异常值带颜色+箭头
|
|
|
- 短链脂肪酸
|
|
|
- 神经递质与激素
|
|
|
- 抗生素风险评估
|
|
|
@@ -88,31 +163,38 @@ page.json 中需新增 3 个路径：
|
|
|
- 维生素（9 项）
|
|
|
- 微量元素
|
|
|
|
|
|
-### 4.2 两种模式
|
|
|
+### 6.2 两种模式
|
|
|
|
|
|
| 模式 | 显示 | 操作 |
|
|
|
|------|------|------|
|
|
|
-| 查看模式 | 只展示数值 + 状态徽章 | 点击「编辑」按钮切到编辑 |
|
|
|
+| 查看模式 | 只展示数值 + 状态颜色+箭头 | 点击名称弹知识库 |
|
|
|
| 编辑模式 | 数值改为 input / 状态改为 picker | 点击「取消」「保存」 |
|
|
|
|
|
|
-### 4.3 顶部 FAB
|
|
|
+查看模式下，名称仍然可点击弹知识库。编辑模式下知识库弹框仍然可用。
|
|
|
+
|
|
|
+### 6.3 顶部 FAB
|
|
|
|
|
|
- 查看模式：右下显示「✏️ 编辑」浮动按钮
|
|
|
- 编辑模式：底部显示「取消」「保存（草稿）」双按钮固定栏
|
|
|
|
|
|
-### 4.4 营养/代谢板块的数据来源
|
|
|
+### 6.4 手风琴中指标卡结构
|
|
|
|
|
|
-后端 `getReportDetail` 已返回 `indicators` 字段，其中每条含：
|
|
|
-- `category`: 类别（"营养"/"氨基酸"/"维生素"/"微量元素"/"抗生素"/"肠屏障"/"脂肪酸"/"神经递质"）
|
|
|
-- `indicatorName`, `indicatorValue`, `status`, `refRange`
|
|
|
+```
|
|
|
+┌───────────────────────────────────┐
|
|
|
+│ 维生素B1 ↓ 数值: 2 │
|
|
|
+│ 正常范围: 4-20 │
|
|
|
+└───────────────────────────────────┘
|
|
|
+```
|
|
|
|
|
|
-前端按 category 分组渲染手风琴。
|
|
|
+- 名称 `维生素B1` → 可点击，弹出知识库
|
|
|
+- `↓` 箭头 + 红色字体（偏低）
|
|
|
+- 正常范围的用默认色，无箭头
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 5. 菌群详情：gut-flora-species-detail.vue
|
|
|
+## 7. 菌群详情：gut-flora-species-detail.vue
|
|
|
|
|
|
-### 5.1 顶部导航（12 分类 Tab）
|
|
|
+### 7.1 顶部导航（12 分类 Tab）
|
|
|
|
|
|
| Tab | 数据源 |
|
|
|
|-----|--------|
|
|
|
@@ -129,264 +211,372 @@ page.json 中需新增 3 个路径：
|
|
|
| 失眠相关 | category="insomnia" |
|
|
|
| 全部 | 不过滤 |
|
|
|
|
|
|
-### 5.2 卡片结构
|
|
|
+### 7.2 卡片结构
|
|
|
|
|
|
-每个菌属一条，竖向列表：
|
|
|
+**无内嵌说明**，标准说明通过点击名称弹出知识库获取。
|
|
|
|
|
|
```
|
|
|
-┌───────────────────────────────────┐
|
|
|
-│ 双歧杆菌属 Bifidobacterium [偏低]│
|
|
|
-│ 丰度 0.2973% | 正常范围 0.19-12.59│
|
|
|
-│ 人群水平 53% | 检出率 97.12% │
|
|
|
-│ ─────────────────────────────────│
|
|
|
-│ 说明：最重要的有益菌，参与肠道免疫│
|
|
|
-└───────────────────────────────────┘
|
|
|
+┌─────────────────────────────────────────┐
|
|
|
+│ 双歧杆菌属 Bifidobacterium ↑ │ ← 名称可点(弹出知识库), ↑红色(偏高)
|
|
|
+│ 丰度 0.2973% | 正常范围 0.19-12.59 │
|
|
|
+│ 人群水平 53% | 检出率 97.12% │
|
|
|
+└─────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
-字段：bacteriaName, bacteriaValue, normalRange, populationLevel, detectionRate, description, status
|
|
|
+- 菌名：可点击 → 弹出知识库（`itemType="bacteria"`）
|
|
|
+- 丰度值：显示数值 + 正常范围
|
|
|
+- 状态：通过菌名颜色+箭头体现，不在卡片上单独显示状态文字
|
|
|
+- 人群水平/检出率：灰色小字辅助信息
|
|
|
|
|
|
-### 5.3 编辑模式
|
|
|
+### 7.3 编辑模式
|
|
|
|
|
|
-可编辑字段：`丰度值（bacteriaValue）`、`状态（status）`、`说明（description）`
|
|
|
-不可编辑：菌属名称（bacteriaName）、正常范围（normalRange）、人群水平、检出率（系统判定）
|
|
|
+可编辑字段：`丰度值（bacteriaValue）`、`状态（status）`
|
|
|
+不可编辑：菌属名称、正常范围、人群水平、检出率
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 6. 食物推荐：gut-flora-foods-detail.vue
|
|
|
+## 8. 食物推荐：gut-flora-foods-detail.vue
|
|
|
|
|
|
-### 6.1 顶部筛选
|
|
|
+### 8.1 顶部筛选
|
|
|
|
|
|
- 分类筛选条（主食 / 蔬菜 / 水果 / 肉类 / 其它），滑动横向
|
|
|
- 排序：推荐指数降序（-X 高优 → +X 高优）；用户可切换「仅看推荐」（score ≥ 5）
|
|
|
|
|
|
-### 6.2 卡片结构
|
|
|
+### 8.2 卡片结构
|
|
|
|
|
|
```
|
|
|
┌────────────────────────────────────┐
|
|
|
-│ 大麦 推荐:+10 [主食] │
|
|
|
+│ 大麦 推荐指数: +10 [主食] │
|
|
|
│ 蛋白12 | 脂肪2 | 碳水73 | 纤维17 │
|
|
|
│ 能量 1481KJ │
|
|
|
└────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
-字段：foodName, category, score, energyKj, protein, fat, carbs, starch, fiber, cholesterol
|
|
|
+食物无知识库需求（数据自包含），但名称可点击 → 视需求可未来接入。
|
|
|
|
|
|
-### 6.3 编辑模式
|
|
|
+### 8.3 编辑模式
|
|
|
|
|
|
可编辑字段：`推荐指数（score）`
|
|
|
-不可编辑：营养数据（来自食材固定库）
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 7. 疾病风险：gut-flora-risks-detail.vue
|
|
|
+## 9. 疾病风险：gut-flora-risks-detail.vue
|
|
|
|
|
|
-### 7.1 顶部状态卡片
|
|
|
+### 9.1 布局
|
|
|
|
|
|
-数量徽章 + 重要风险（注意/异常）置顶
|
|
|
+重要风险（注意/异常）置顶，其余按风险等级排序。
|
|
|
|
|
|
-### 7.2 列表（按风险等级排序）
|
|
|
+### 9.2 卡片结构
|
|
|
|
|
|
```
|
|
|
┌────────────────────────────────────┐
|
|
|
-│ ⚠️ 甲状腺疾病 [注意] │
|
|
|
-│ 风险值 0.33 (中等) │
|
|
|
+│ 甲状腺疾病 ⚠ │ ← 名称可点弹出知识库
|
|
|
+│ 风险值: 0.33 风险等级: [注意] │
|
|
|
└────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
-字段：diseaseName, riskValue, riskLevel
|
|
|
+风险等级颜色：低风险→绿、注意→黄/⚠、异常→红
|
|
|
|
|
|
-风险等级颜色：低风险→绿、注意→黄、异常→红
|
|
|
+疾病名称可点击 → 弹出知识库（`itemType="disease"`）
|
|
|
|
|
|
-### 7.3 编辑模式
|
|
|
+### 9.3 编辑模式
|
|
|
|
|
|
-可编辑字段：`风险值（riskValue）`、`风险等级（riskLevel picker）`
|
|
|
-不可编辑：疾病名称（diseaseName）
|
|
|
+可编辑字段：`风险值（riskValue）`、`风险等级（riskLevel picker）`
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 8. 公共交互规范
|
|
|
+## 10. 知识库架构
|
|
|
+
|
|
|
+### 10.1 数据库表
|
|
|
+
|
|
|
+```sql
|
|
|
+CREATE TABLE IF NOT EXISTS health_knowledge_base (
|
|
|
+ id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
|
|
+ item_type VARCHAR(50) NOT NULL COMMENT '类型: bacteria/nutrient/indicator/vitamin/amino_acid/disease',
|
|
|
+ item_name VARCHAR(200) NOT NULL COMMENT '项目名称（精确匹配）',
|
|
|
+ category VARCHAR(100) COMMENT '分类（如 有益菌/有害菌）',
|
|
|
+ normal_range VARCHAR(200) COMMENT '正常范围参考',
|
|
|
+ description TEXT COMMENT '详细说明',
|
|
|
+ suggestion TEXT COMMENT '相关建议（如补充来源）',
|
|
|
+ source VARCHAR(100) COMMENT '数据来源',
|
|
|
+ created_at DATETIME,
|
|
|
+ updated_at DATETIME,
|
|
|
+ UNIQUE KEY uk_type_name (item_type, item_name),
|
|
|
+ INDEX idx_type (item_type)
|
|
|
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='健康知识库 - 菌属/营养素/指标说明';
|
|
|
+```
|
|
|
+
|
|
|
+### 10.2 初次数据填充
|
|
|
|
|
|
-### 8.1 编辑状态机
|
|
|
+参考 JSON 文件中所有菌属的 `说明` 字段、指标的 `健康状况`/参考范围等，一次性导入 `health_knowledge_base`。
|
|
|
+
|
|
|
+### 10.3 API
|
|
|
|
|
|
```
|
|
|
-查看模式 ─[点击编辑]→ 编辑模式 ─[点击取消]→ 查看模式 (丢弃改动)
|
|
|
- ─[点击保存]→ 上传草稿 → 显示保存中 → 返回查看模式
|
|
|
+POST /api/health/knowledge/query
|
|
|
+body: { itemType: "bacteria", itemName: "双歧杆菌属 Bifidobacterium" }
|
|
|
+→ { code: 200, data: { id, itemType, itemName, category, normalRange, description, suggestion } }
|
|
|
+
|
|
|
+POST /api/health/knowledge/batch-query
|
|
|
+body: { queries: [{ itemType, itemName }, ...] }
|
|
|
+→ { code: 200, data: { "bacteria:双歧杆菌属 Bifidobacterium": {...}, ... } }
|
|
|
```
|
|
|
|
|
|
-### 8.2 编辑按钮触发位置
|
|
|
+批查询用于首次加载时预取当前页面所有项目的知识库。单查询用于点击时按需加载。
|
|
|
+
|
|
|
+---
|
|
|
|
|
|
-主页、固定在右下 FAB（查看模式）。
|
|
|
-详情页（菌群/食物/风险），固定在顶部导航栏右侧文字按钮「编辑」。
|
|
|
+## 11. 公共交互规范
|
|
|
|
|
|
-### 8.3 数据流
|
|
|
+### 11.1 编辑状态机
|
|
|
|
|
|
```
|
|
|
-进入页面 → onLoad(options) {
|
|
|
- reportId = options.reportId
|
|
|
- loadReportDetail() // GET /api/health/report/detail (返回 report/indicators/gutFlora/diseaseRisks)
|
|
|
- // 前端缓存于 this.viewData
|
|
|
-}
|
|
|
+查看模式 ─[点击编辑]→ 编辑模式 ─[点击取消]→ 查看模式 (丢弃改动)
|
|
|
+ ─[点击保存]→ POST /api/health/report/edit → toast → 重新加载 → 查看模式
|
|
|
+```
|
|
|
+
|
|
|
+### 11.2 编辑按钮触发位置
|
|
|
+
|
|
|
+- 主页：右下 FAB（查看模式）
|
|
|
+- 详情页：顶部导航栏右侧文字按钮「编辑」
|
|
|
+
|
|
|
+### 11.3 数据流
|
|
|
|
|
|
-点击编辑 → 深拷贝 this.viewData → this.editData
|
|
|
- 进入编辑模式，input/picker 可用
|
|
|
-点击取消 → 丢弃 this.editData，回到查看模式
|
|
|
-点击保存 →
|
|
|
- payload = {
|
|
|
- report: 当前报告 metadata,
|
|
|
- indicators: 当前 indicators ,
|
|
|
- gutFlora: 编辑后的 gutFlora,
|
|
|
- diseaseRisks: 编辑后的 diseaseRisks,
|
|
|
- foods: 编辑后的 foods (仅本页实际被改)
|
|
|
- }
|
|
|
- POST /api/health/report/edit
|
|
|
- params: { reportId, payload }
|
|
|
- → 成功 → toast → 调 loadReportDetail 重新拉 → 回到查看模式
|
|
|
+```
|
|
|
+进入页面 → onLoad({ reportId }) → loadReportDetail()
|
|
|
+ GET /api/health/report/detail → 缓存于 this.reportData
|
|
|
+
|
|
|
+点击编辑 → 深拷贝 this.reportData → this.editData → 进入编辑模式
|
|
|
+点击取消 → 丢弃 this.editData → 回查看模式
|
|
|
+点击保存 →
|
|
|
+ POST /api/health/report/edit { reportId, payload: { indicators, gutFlora, diseaseRisks, foods }, subjectId }
|
|
|
+ → 200 → toast "已保存" → loadReportDetail() 重新拉 → 查看模式
|
|
|
```
|
|
|
|
|
|
-### 8.4 新增 API
|
|
|
+### 11.4 知识库弹出框数据流
|
|
|
|
|
|
-| Endpoint | 用途 | 备注 |
|
|
|
-|----------|------|------|
|
|
|
-| `POST /api/health/report/edit` | 编辑已发布报告 | 新增；接收 reportId + payload；先 selectById → 抹写 indicators/gutFlora/diseaseRisks → update；最后 `dimensionScoreService.refreshFromGutReport` 刷新 7 维 |
|
|
|
+```
|
|
|
+首次加载 → 遍历报告的 indicators/gutFlora，
|
|
|
+ 收集所有不重复的 (itemType, itemName) 对
|
|
|
+ → POST /api/health/knowledge/batch-query → 缓存入 this.knowledgeMap
|
|
|
+ → 前端 <text @tap="showKnowledge(type, name)"> 直接从缓存取
|
|
|
|
|
|
-不修改现有 `/api/health/report/confirm` 接口以保持兼容；额外添加一个新接口 `/api/health/report/edit` 专门用于编辑已发布报告。
|
|
|
+点击名称 → if (cache[type+name]) → 直接显示
|
|
|
+ else → POST /api/health/knowledge/query → 显示并加入缓存
|
|
|
+```
|
|
|
|
|
|
-### 8.4 mini-program 限制
|
|
|
+### 11.5 mini-program 限制
|
|
|
|
|
|
-- 禁可选链 `?.`，全部改用 `&&` 短路
|
|
|
+- 禁可选链 `?.`，全部用 `&&` 短路
|
|
|
- 禁 CSS Grid，全部 flex
|
|
|
- Vue 2 Options API
|
|
|
-- 状态类徽章用 `:class="'status-' + item.status"` 内联（不可方法调用）
|
|
|
+- 状态类徽章用 `:class="'status-' + item.status"` 内联
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 9. 数据契约
|
|
|
+## 12. 数据契约
|
|
|
|
|
|
-### 9.1 GET /api/health/report/detail — 后端已有
|
|
|
+### 12.1 GET /api/health/report/detail — 后端已有（不变）
|
|
|
|
|
|
-返回：
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": {
|
|
|
- "report": { "id":..., "personName":..., "overallScore":..., "gutHealthScore":..., ... },
|
|
|
- "indicators": [{ "category":"营养", "indicatorName":"碳水", "indicatorValue":"96", "status":"正常", "refRange":"..." }, ...],
|
|
|
- "gutFlora": [{ "bacteriaName":"...", "bacteriaValue":"0.2973", "category":"core", "status":"偏低", ... }, ...],
|
|
|
- "diseaseRisks": [{ "diseaseName":"...", "riskValue":"0.33", "riskLevel":"注意" }, ...]
|
|
|
+ "report": { "id":..., "personName":"某人", "overallScore":57, "gutHealthScore":76, ... },
|
|
|
+ "indicators": [
|
|
|
+ { "category":"营养", "indicatorName":"碳水化合物", "indicatorValue":"96", "status":"正常", "refRange":"..." },
|
|
|
+ { "category":"氨基酸", "indicatorName":"胱氨酸", "indicatorValue":"86", "status":"正常", "refRange":"..." },
|
|
|
+ { "category":"维生素", "indicatorName":"维生素B1", "indicatorValue":"2", "status":"缺乏", "refRange":"..." },
|
|
|
+ ...
|
|
|
+ ],
|
|
|
+ "gutFlora": [
|
|
|
+ { "bacteriaName":"双歧杆菌属 Bifidobacterium", "bacteriaValue":"0.2973", "category":"core", "status":"偏低", "normalRange":"0.19-12.59", "populationLevel":"53%", "detectionRate":"97.12%" },
|
|
|
+ ...
|
|
|
+ ],
|
|
|
+ "diseaseRisks": [
|
|
|
+ { "diseaseName":"甲状腺疾病", "riskValue":"0.33", "riskLevel":"注意" }
|
|
|
+ ]
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-**当前返回结构已能覆盖所有页面**，不再需要新增后端接口。
|
|
|
-
|
|
|
-### 9.2 POST /api/health/report/confirm — 修改报告（编辑保存）
|
|
|
+### 12.2 POST /api/health/report/edit — 新增
|
|
|
|
|
|
-请求体：
|
|
|
```json
|
|
|
{
|
|
|
- "draftId": 123,
|
|
|
+ "reportId": 123,
|
|
|
"payload": {
|
|
|
- "summary": { "overallScore": 76, "gutHealthScore": 53, ... "personName":"某人", ... },
|
|
|
- "indicators": [...],
|
|
|
- "gutFlora": [...], // 编辑修改后的菌群
|
|
|
- "probioticSpecies": [...],
|
|
|
- "foods": [...],
|
|
|
- "diseaseRisks": [...] // 编辑修改后的疾病风险
|
|
|
+ "indicators": [...], // 编辑后的完整 list
|
|
|
+ "gutFlora": [...], // 编辑后的完整 list
|
|
|
+ "probioticSpecies": [...], // 编辑后的菌门 list
|
|
|
+ "foods": [...], // 编辑后的食物 list
|
|
|
+ "diseaseRisks": [...] // 编辑后的疾病风险 list
|
|
|
},
|
|
|
"subjectId": 456
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-**后端机制已支持**：`/api/health/report/confirm` 接收 payload 后整体覆盖入库（参考 `HealthReportController.confirmDraft`）。
|
|
|
+### 12.3 POST /api/health/knowledge/query — 新增
|
|
|
+
|
|
|
+```json
|
|
|
+// 请求
|
|
|
+{ "itemType": "bacteria", "itemName": "双歧杆菌属 Bifidobacterium" }
|
|
|
+// 响应
|
|
|
+{ "code":200, "data": {
|
|
|
+ "id":1, "itemType":"bacteria", "itemName":"双歧杆菌属 Bifidobacterium",
|
|
|
+ "category":"有益菌",
|
|
|
+ "normalRange":"0.19-14.59",
|
|
|
+ "description":"最重要的益生菌，参与肠道免疫屏障维护...",
|
|
|
+ "suggestion":"补充来源：酸奶、开菲尔等发酵食品"
|
|
|
+}}
|
|
|
+```
|
|
|
|
|
|
-但 confirm 要 draftId 已发布报告没有 draft。因此新增一个独立接口 `/api/health/report/edit` 处理已发布报告编辑。
|
|
|
+### 12.4 POST /api/health/knowledge/batch-query — 新增
|
|
|
|
|
|
-### 9.3 后端需补充
|
|
|
+```json
|
|
|
+// 请求
|
|
|
+{ "queries": [
|
|
|
+ {"itemType":"bacteria","itemName":"双歧杆菌属 Bifidobacterium"},
|
|
|
+ {"itemType":"vitamin","itemName":"维生素B1"}
|
|
|
+]}
|
|
|
+// 响应
|
|
|
+{ "code":200, "data": {
|
|
|
+ "bacteria:双歧杆菌属 Bifidobacterium": { ... },
|
|
|
+ "vitamin:维生素B1": { ... }
|
|
|
+}}
|
|
|
+```
|
|
|
|
|
|
-| 改动 | 位置 | 说明 |
|
|
|
-|------|------|------|
|
|
|
-| 新增 `POST /api/health/report/edit` | `HealthReportController.java` | 接收 `{reportId, payload, subjectId}`；先 selectById → 抹写 indicators/gutFlora/diseaseRisks/foods；刷新 7 维评分；返回最新 reportDetail |
|
|
|
-| 新增 `updateReportFromPayload(reportId, payload, subjectId)` | `HealthReportService.java` | 同上数据流；优先复用 `confirmDraft` 的构造逻辑 |
|
|
|
-| 新增 `editHealthReport(...)` | `HealthReportController.java` | 实现 `dimensionScoreService.refreshFromGutReport` 触发 |
|
|
|
+---
|
|
|
+
|
|
|
+## 13. 后端需补充
|
|
|
+
|
|
|
+| 改动 | 位置 | 方法 | 说明 |
|
|
|
+|------|------|------|------|
|
|
|
+| 新建 Entity | `entity/HealthKnowledgeBase.java` | — | @TableName("health_knowledge_base") |
|
|
|
+| 新建 Mapper | `mapper/HealthKnowledgeBaseMapper.java` | — | MyBatis-Plus BaseMapper |
|
|
|
+| 新建 Service | `service/HealthKnowledgeBaseService.java` | `query(itemType, itemName)`, `batchQuery(List<Pair>)` | 查知识库 |
|
|
|
+| 新建 Controller | `controller/HealthKnowledgeBaseController.java` | `POST /api/health/knowledge/query`, `POST /api/health/knowledge/batch-query` | 知识库 API |
|
|
|
+| 编辑 API | `controller/HealthReportController.java` | `POST /api/health/report/edit` | 编辑已发布报告 |
|
|
|
+| 编辑 Service | `service/HealthReportService.java` | `updateReportFromPayload(reportId, payload, subjectId)` | 抹写并刷新 7 维 |
|
|
|
+| 数据库迁移 | `config/DatabaseInitializer.java` | 创建 `health_knowledge_base` 表 + 导入参考 JSON 的说明数据 | 迁移 N+1 |
|
|
|
+| schema.sql | `resources/schema.sql` | 追加新表 DDL | 同步 |
|
|
|
+
|
|
|
+### 13.1 KnowledgeBaseService 方法签名
|
|
|
+
|
|
|
+```java
|
|
|
+public HealthKnowledgeBase query(String itemType, String itemName) {
|
|
|
+ return mapper.selectOne(
|
|
|
+ new LambdaQueryWrapper<HealthKnowledgeBase>()
|
|
|
+ .eq(HealthKnowledgeBase::getItemType, itemType)
|
|
|
+ .eq(HealthKnowledgeBase::getItemName, itemName)
|
|
|
+ );
|
|
|
+}
|
|
|
|
|
|
-不需要修改 `confirmDraft`——保持兼容。
|
|
|
+public Map<String, HealthKnowledgeBase> batchQuery(List<QueryPair> queries) {
|
|
|
+ // 按 (type, name) 批量查询
|
|
|
+}
|
|
|
+```
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 10. 验收标准
|
|
|
+## 14. 验收标准
|
|
|
|
|
|
-### 10.1 主页（gut-flora-detail.vue）
|
|
|
+### 14.1 主页（gut-flora-detail.vue）
|
|
|
|
|
|
- [ ] 长 scroll 顺畅渲染 >= 1000rpx 高度
|
|
|
- [ ] 报告头部显示姓名/年龄/性别/编号/日期
|
|
|
- [ ] 健康评分圆环绘制（11 项可滚动横向）
|
|
|
- [ ] 4 个快速跳转入口可见，且能跳到对应详情页
|
|
|
- [ ] 肠道功能 / 营养指标 双手风琴，能折叠/展开
|
|
|
+- [ ] 每个指标名称可点击 → 弹出知识库弹出框
|
|
|
+- [ ] 异常值：偏高/过多 → 红色 + ↑；偏低/缺乏/不足 → 琥珀色 + ↓
|
|
|
+- [ ] 正常值：默认色无箭头
|
|
|
- [ ] 右下 FAB「编辑」按钮可见
|
|
|
- [ ] 点击「编辑」后 input/picker 可用，「保存」固定底部出现
|
|
|
- [ ] 保存成功后正确返回查看模式 + toast 提示
|
|
|
|
|
|
-### 10.2 菌群详情（gut-flora-species-detail.vue）
|
|
|
+### 14.2 菌群详情（gut-flora-species-detail.vue）
|
|
|
|
|
|
- [ ] 12 分类 Tab 正常切换
|
|
|
- [ ] 每个 Tab 显示对应菌属列表
|
|
|
-- [ ] 卡片显示丰度/正常范围/人群水平/检出率/说明
|
|
|
-- [ ] 编辑模式可改丰度/状态/说明，点击保存后写入
|
|
|
+- [ ] 卡片显示菌名（可点弹知识库）、丰度、正常范围、人群水平、检出率
|
|
|
+- [ ] 无内嵌说明文字
|
|
|
+- [ ] 菌名带颜色+箭头指示偏高/偏低
|
|
|
+- [ ] 编辑模式可改丰度/状态，保存后写入
|
|
|
|
|
|
-### 10.3 食物推荐（gut-flora-foods-detail.vue）
|
|
|
+### 14.3 食物推荐（gut-flora-foods-detail.vue）
|
|
|
|
|
|
- [ ] 分类筛选条切换生效
|
|
|
- [ ] 列表按推荐指数降序
|
|
|
- [ ] 卡片显示名称/分类/推荐指数/营养数据
|
|
|
- [ ] 编辑模式可改推荐指数
|
|
|
|
|
|
-### 10.4 疾病风险（gut-flora-risks-detail.vue）
|
|
|
+### 14.4 疾病风险（gut-flora-risks-detail.vue）
|
|
|
|
|
|
- [ ] 重要风险（注意/异常）置顶
|
|
|
-- [ ] 风险等级用颜色徽章：低风险=绿/注意=黄/异常=红
|
|
|
+- [ ] 风险等级用颜色徽章：低风险=绿/注意=黄+⚠/异常=红
|
|
|
+- [ ] 疾病名称可点击弹知识库
|
|
|
- [ ] 编辑模式可改风险值/风险等级
|
|
|
|
|
|
-### 10.5 E2E 测试
|
|
|
+### 14.5 知识库
|
|
|
+
|
|
|
+- [ ] 后端 `batch-query` 支持一次预取全部知识库条目
|
|
|
+- [ ] 弹出框正确显示类型/说明/建议
|
|
|
+- [ ] 数据库迁移幂等可重复运行
|
|
|
+- [ ] 参考 JSON 说明数据正确导入
|
|
|
|
|
|
-- [ ] `tests/e2e/flora-microbiome-flow.spec.js` 中场景 4（菌种丰度明细展示）通过：检查 `.bacteria-card`/`.flora-item`/`.gut-flora-row` 类名都出现
|
|
|
-- [ ] 新增 `.preview-result`、`.save-btn` 选择器匹配现有页面元素
|
|
|
+### 14.6 E2E 测试
|
|
|
+
|
|
|
+- [ ] `tests/e2e/flora-microbiome-flow.spec.js` 现有场景通过
|
|
|
+- [ ] 新增 `.kb-link`、`.knowledge-popup` 选择器覆盖知识库交互
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 11. 文件变更清单
|
|
|
+## 15. 文件变更清单
|
|
|
|
|
|
| 文件 | 操作 | 内容 |
|
|
|
|------|------|------|
|
|
|
-| `cfc-frontend/pages/health/gut-flora-detail.vue` | 重写 | 长 scroll + 手风琴 + 双模式 + FAB |
|
|
|
-| `cfc-frontend/pages/health/gut-flora-species-detail.vue` | 新建 | 12 Tab + 卡片 + 编辑 |
|
|
|
+| `cfc-frontend/pages/health/gut-flora-detail.vue` | 重写 | 长 scroll + 手风琴 + 知识库弹框 + 颜色箭头 + 双模式 |
|
|
|
+| `cfc-frontend/pages/health/gut-flora-species-detail.vue` | 新建 | 12 Tab + 卡片(无说明) + 颜色箭头 + 知识库弹框 |
|
|
|
| `cfc-frontend/pages/health/gut-flora-foods-detail.vue` | 新建 | 分类筛选 + 卡片 + 编辑 |
|
|
|
-| `cfc-frontend/pages/health/gut-flora-risks-detail.vue` | 新建 | 重要置顶 + 卡片 + 编辑 |
|
|
|
+| `cfc-frontend/pages/health/gut-flora-risks-detail.vue` | 新建 | 重要置顶 + 卡片 + 知识库弹框 |
|
|
|
+| `cfc-frontend/components/health-knowledge-popup.vue` | 新建 | 通用知识库弹出框组件 |
|
|
|
| `cfc-frontend/pages.json` | 改 | 注册 3 个新页面路径 |
|
|
|
-| `cfc-frontend/utils/api.js` | 改 | 新增 `editHealthReport` 函数（POST `/api/health/report/edit`） |
|
|
|
-| `cfc-backend/src/main/java/com/etotem/cfc/controller/HealthReportController.java` | 改 | 新增 `POST /api/health/report/edit` 端点 + `editHealthReport` 方法 |
|
|
|
-| `cfc-backend/src/main/java/com/etotem/cfc/service/HealthReportService.java` | 改 | 新增 `updateReportFromPayload(reportId, payload, subjectId)` |
|
|
|
-| `tests/e2e/flora-microbiome-flow.spec.js` | 检查 | 现有 selector 兼容 |
|
|
|
+| `cfc-frontend/utils/api.js` | 改 | 新增 `editHealthReport`、`queryKnowledge`、`batchQueryKnowledge` |
|
|
|
+| `cfc-backend/.../entity/HealthKnowledgeBase.java` | 新建 | 知识库实体 |
|
|
|
+| `cfc-backend/.../mapper/HealthKnowledgeBaseMapper.java` | 新建 | 知识库 Mapper |
|
|
|
+| `cfc-backend/.../service/HealthKnowledgeBaseService.java` | 新建 | 知识库 Service |
|
|
|
+| `cfc-backend/.../controller/HealthKnowledgeBaseController.java` | 新建 | 知识库 API |
|
|
|
+| `cfc-backend/.../controller/HealthReportController.java` | 改 | 新增 `POST /api/health/report/edit` |
|
|
|
+| `cfc-backend/.../service/HealthReportService.java` | 改 | 新增 `updateReportFromPayload` |
|
|
|
+| `cfc-backend/.../config/DatabaseInitializer.java` | 改 | 创建 health_knowledge_base 表 + 导入数据 |
|
|
|
+| `cfc-backend/.../resources/schema.sql` | 改 | 追加 health_knowledge_base DDL |
|
|
|
+| `tests/e2e/flora-microbiome-flow.spec.js` | 检查/更新 | 适配新选择器 |
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 12. 风险与权衡
|
|
|
+## 16. 风险与权衡
|
|
|
|
|
|
| 风险 | 缓解 |
|
|
|
|------|------|
|
|
|
-| 编辑时大批量数据（200+ 菌属 + 224 食物）并发上传可能慢 | 前端只提交被改过的索引列表；后端使用批量 update 而非循环 update |
|
|
|
-| 当前 confirm 要 draftId 已发布报告没有 draft | 后端添加 reportId 编辑路径（见 9.3） |
|
|
|
-| 编辑后是否会破坏 7 维评分关联 | 编辑路径同样调用 `dimensionScoreService.refreshFromGutReport` 刷新评分 |
|
|
|
-| mini-program 真机性能（200+ 卡片渲染） | 使用 `v-if` 分组懒加载，避免 canvas 重复 `uni.createCanvasContext` |
|
|
|
+| 200+ 菌属首次加载时 batch-query 知识库可能慢 | 并行请求；知识库表小（<500 行），加索引后毫秒级 |
|
|
|
+| 知识库数据导入工作量 | 参考 JSON 已有完整的 `说明` 字段，可用脚本批量入库 |
|
|
|
+| 编辑时大批量数据上传慢 | 前端只提交被改过的索引列表 |
|
|
|
+| 编辑后是否破坏 7 维评分 | 编辑路径同样调用 `refreshFromGutReport` 刷新 |
|
|
|
+| mini-program 真机性能（200+ 卡片） | `v-if` 分组懒加载 |
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 13. 实现顺序
|
|
|
-
|
|
|
-1. 后端 confirmDraft 加 reportId 编辑分支 → `updateReportFromPayload` → `mvn clean compile`
|
|
|
-2. 新建 `gut-flora-foods-detail.vue`（最简单，先验证编辑流）
|
|
|
-3. 新建 `gut-flora-risks-detail.vue`
|
|
|
-4. 新建 `gut-flora-species-detail.vue`
|
|
|
-5. 重写 `gut-flora-detail.vue`（最复杂）
|
|
|
-6. 更新 `pages.json` 注册新路径
|
|
|
-7. 跑 `tests/e2e/flora-microbiome-flow.spec.js` 验证兼容
|
|
|
-8. 微信开发者工具手动验证关键操作
|
|
|
+## 17. 实现顺序
|
|
|
+
|
|
|
+1. 后端：`HealthKnowledgeBase` 表迁移 + 实体/Mapper/Service/Controller → `mvn clean compile`
|
|
|
+2. 后端：`POST /api/health/report/edit` + `updateReportFromPayload` → `mvn clean compile`
|
|
|
+3. 导入参考 JSON 的说明数据到 `health_knowledge_base`
|
|
|
+4. 前端：`components/health-knowledge-popup.vue` 通用弹框组件
|
|
|
+5. 前端：新建 `gut-flora-foods-detail.vue`（最简单）→ 验证编辑流
|
|
|
+6. 前端：新建 `gut-flora-risks-detail.vue` + 知识库弹框
|
|
|
+7. 前端：新建 `gut-flora-species-detail.vue` + 12 Tab + 颜色箭头 + 知识库弹框
|
|
|
+8. 前端：重写 `gut-flora-detail.vue`（手风琴 + 指标知识库 + 颜色箭头 + 双模式）
|
|
|
+9. 更新 `pages.json` + `utils/api.js`
|
|
|
+10. 跑 `tests/e2e/flora-microbiome-flow.spec.js` 验证
|
|
|
+11. 微信开发者工具手动验证关键操作
|
