菌群报告页面重构设计规范

基于参考 JSON 完整数据，重构「肠道菌群报告详情页」，覆盖查看+编辑混合场景。页面只展示个性化数据（个人测定值），标准说明通过弹出框从知识库获取。

版本： v1.1（v1.0 修正：仅展示个性化数据 + 知识库弹出框 + 异常值颜色箭头）
日期： 2026-07-17
状态： Draft
作者： Sisyphus

1. 背景与目标

1.1 现状问题

现有 pages/health/gut-flora-detail.vue 只展示 5 个评分圆环 + 3 组菌属分类 + 食物推荐
后端 /api/health/report/detail 已返回完整数据：report + indicators + gutFlora + diseaseRisks
Reference JSON 显示完整报告含 200+ 菌属条目、50+ 评估指标、224 种食物推荐
现有页面覆盖率不足 5%，大量有价值数据丢失

1.2 设计目标

完整展示：将所有报告板块（评分/指标/菌群/疾病风险/食物）全部呈现
仅展示个性化值：页面只显示该人的测定数值，标准说明不内嵌
知识库弹出框：每个菌、营养素、指标的名称可点击 → 弹出详细说明（来自独立知识库表）
异常值颜色+箭头：超出正常范围的数值用颜色区分，名称上标 ↑（过高）↓（过低）
可编辑：用户可在查看页面转向编辑模式，调整解析错误的数据

1.3 不在本文档范围

报告上传 / 解析流程（已稳定）
后端 PDF 解析逻辑（已由 PdfParseService 完成）
报告列表页（/pages/health/report-list，未变动）

2. 设计决策

决策项	选择	理由
页面拆分	主页 + 3 个详情页	食物 224 条 + 菌群 200 条过长，必须分页；指标用手风琴折叠到主页
模式	混合（默认查看 + 编辑切换）	满足「全字段可编辑」同时保留查看优先体验
编辑范围	仅修改现有条目（不增删）	当前需求是修正 AI 解析错误，不是新增数据
保存路径	新增 `POST /api/health/report/edit`	编辑已发布报告（不用 draftId）
说明展示	不内嵌，点击名称弹出知识库	页面干净，知识库可独立维护

3. 页面架构

pages/health/
├── gut-flora-detail.vue           # 主页 (本文件重写)
├── gut-flora-species-detail.vue   # 菌群详情 (新增)
├── gut-flora-foods-detail.vue     # 食物推荐 (新增)
└── gut-flora-risks-detail.vue     # 疾病风险 (新增)

page.json 中需新增 3 个路径：

Path	Title
`pages/health/gut-flora-species-detail`	菌群详情
`pages/health/gut-flora-foods-detail`	饮食推荐
`pages/health/gut-flora-risks-detail`	疾病风险

4. 异常值颜色与箭头规则（通用）

所有页面（主页手风琴、菌群卡片、营养指标列表）统一使用以下规则：

状态	颜色	箭头	示例
`正常` / `低风险`	默认文本 #333	无	维生素A 84
`偏高` / `过多` / `高`	红色 #C62828	↑	双歧杆菌属↑ 12.8%
`偏低` / `缺乏` / `不足` / `低`	琥珀色 #E65100	↓	维生素B1↓ 2
`异常`	红色 #C62828	⚠	炎症水平⚠ 16
`注意`	黄色 #F59E0B	⚠	甲状腺疾病⚠

实现方式（Vue 2 inline 表达式）：

<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`

每个菌属名/营养素名/指标名都是可点击的，点击后打开一个弹出框显示该项目的知识库说明。

<!-- 使用方式 -->
<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 板块布局（由上至下）

报告头部（hero 渐变背景）
- 姓名、年龄、性别、报告编号、报告日期
- 肠道预测年龄 / 肠型（徽章）
健康评分总览（圆形进度环，5-11 个）
- 健康总分（综合）/ 菌群健康 / 慢病控制 / 营养均衡 / 平衡 / 多样性 / 有益菌 / 有害菌 / 核心菌属
快速跳转入口（4 个图标卡，进入详情页）
- 🦠 菌群详情（X 种）
- ⚠️ 疾病风险（X 项）
- 🍽️ 饮食推荐（X 项）
- 📋 全部指标（X 项）
肠道功能面板（手风琴 Accordion）
- 肠道屏障与代谢物 → 指标列表，名称可点击弹知识库，异常值带颜色+箭头
- 短链脂肪酸
- 神经递质与激素
- 抗生素风险评估
营养指标面板（手风琴 Accordion）
- 主要营养（碳水/蛋白/脂肪/纤维素/乳制品）
- 氨基酸（10 项）
- 维生素（9 项）
- 微量元素

6.2 两种模式

模式	显示	操作
查看模式	只展示数值 + 状态颜色+箭头	点击名称弹知识库
编辑模式	数值改为 input / 状态改为 picker	点击「取消」「保存」

查看模式下，名称仍然可点击弹知识库。编辑模式下知识库弹框仍然可用。

6.3 顶部 FAB

查看模式：右下显示「✏️ 编辑」浮动按钮
编辑模式：底部显示「取消」「保存（草稿）」双按钮固定栏

6.4 手风琴中指标卡结构

┌───────────────────────────────────┐
│ 维生素B1 ↓      数值: 2           │
│ 正常范围: 4-20                    │
└───────────────────────────────────┘

名称 维生素B1 → 可点击，弹出知识库
↓ 箭头 + 红色字体（偏低）
正常范围的用默认色，无箭头

7. 菌群详情：gut-flora-species-detail.vue

7.1 顶部导航（12 分类 Tab）

Tab	数据源
核心菌属	payload.gutFlora → category="core"
益生菌（菌门）	payload.probioticSpecies → category="probiotic"
有害菌	category="harmful"
其它菌属	category="other"
病原菌	category="pathogen"
肥胖相关	category="obesity"
便秘相关	category="constipation"
抑郁相关	category="depression"
过敏相关	category="allergy"
腹胀相关	category="bloating"
失眠相关	category="insomnia"
全部	不过滤

7.2 卡片结构

无内嵌说明，标准说明通过点击名称弹出知识库获取。

┌─────────────────────────────────────────┐
│ 双歧杆菌属 Bifidobacterium ↑            │  ← 名称可点(弹出知识库), ↑红色(偏高)
│ 丰度 0.2973%  |  正常范围 0.19-12.59    │
│ 人群水平 53% | 检出率 97.12%            │
└─────────────────────────────────────────┘

菌名：可点击 → 弹出知识库（itemType="bacteria"）
丰度值：显示数值 + 正常范围
状态：通过菌名颜色+箭头体现，不在卡片上单独显示状态文字
人群水平/检出率：灰色小字辅助信息

7.3 编辑模式

可编辑字段：丰度值（bacteriaValue）、状态（status）
不可编辑：菌属名称、正常范围、人群水平、检出率

8. 食物推荐：gut-flora-foods-detail.vue

8.1 顶部筛选

分类筛选条（主食 / 蔬菜 / 水果 / 肉类 / 其它），滑动横向
排序：推荐指数降序（-X 高优 → +X 高优）；用户可切换「仅看推荐」（score ≥ 5）

8.2 卡片结构

┌────────────────────────────────────┐
│ 大麦   推荐指数: +10   [主食]       │
│ 蛋白12 | 脂肪2 | 碳水73 | 纤维17   │
│ 能量 1481KJ                        │
└────────────────────────────────────┘

食物无知识库需求（数据自包含），但名称可点击 → 视需求可未来接入。

8.3 编辑模式

可编辑字段：推荐指数（score）

9. 疾病风险：gut-flora-risks-detail.vue

9.1 布局

重要风险（注意/异常）置顶，其余按风险等级排序。

9.2 卡片结构

┌────────────────────────────────────┐
│ 甲状腺疾病 ⚠                       │  ← 名称可点弹出知识库
│ 风险值: 0.33  风险等级: [注意]      │
└────────────────────────────────────┘

风险等级颜色：低风险→绿、注意→黄/⚠、异常→红

疾病名称可点击 → 弹出知识库（itemType="disease"）

9.3 编辑模式

可编辑字段：风险值（riskValue）、风险等级（riskLevel picker）

10. 知识库架构

10.1 数据库表

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 初次数据填充

参考 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": {...}, ... } }

批查询用于首次加载时预取当前页面所有项目的知识库。单查询用于点击时按需加载。

11. 公共交互规范

11.1 编辑状态机

查看模式 ─[点击编辑]→ 编辑模式 ─[点击取消]→ 查看模式 (丢弃改动)
                              ─[点击保存]→ POST /api/health/report/edit → toast → 重新加载 → 查看模式

11.2 编辑按钮触发位置

主页：右下 FAB（查看模式）
详情页：顶部导航栏右侧文字按钮「编辑」

11.3 数据流

进入页面 → 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() 重新拉 → 查看模式

11.4 知识库弹出框数据流

首次加载 → 遍历报告的 indicators/gutFlora，
           收集所有不重复的 (itemType, itemName) 对
          → POST /api/health/knowledge/batch-query → 缓存入 this.knowledgeMap
          → 前端 <text @tap="showKnowledge(type, name)"> 直接从缓存取

点击名称 → if (cache[type+name]) → 直接显示
          else → POST /api/health/knowledge/query → 显示并加入缓存

11.5 mini-program 限制

禁可选链 ?.，全部用 && 短路
禁 CSS Grid，全部 flex
Vue 2 Options API
状态类徽章用 :class="'status-' + item.status" 内联

12. 数据契约

12.1 GET /api/health/report/detail — 后端已有（不变）

{
  "code": 200,
  "data": {
    "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":"注意" }
    ]
  }
}

12.2 POST /api/health/report/edit — 新增

{
  "reportId": 123,
  "payload": {
    "indicators": [...],      // 编辑后的完整 list
    "gutFlora": [...],         // 编辑后的完整 list
    "probioticSpecies": [...], // 编辑后的菌门 list
    "foods": [...],            // 编辑后的食物 list
    "diseaseRisks": [...]      // 编辑后的疾病风险 list
  },
  "subjectId": 456
}

12.3 POST /api/health/knowledge/query — 新增

// 请求
{ "itemType": "bacteria", "itemName": "双歧杆菌属 Bifidobacterium" }
// 响应
{ "code":200, "data": {
    "id":1, "itemType":"bacteria", "itemName":"双歧杆菌属 Bifidobacterium",
    "category":"有益菌",
    "normalRange":"0.19-14.59",
    "description":"最重要的益生菌，参与肠道免疫屏障维护...",
    "suggestion":"补充来源：酸奶、开菲尔等发酵食品"
}}

12.4 POST /api/health/knowledge/batch-query — 新增

// 请求
{ "queries": [
    {"itemType":"bacteria","itemName":"双歧杆菌属 Bifidobacterium"},
    {"itemType":"vitamin","itemName":"维生素B1"}
]}
// 响应
{ "code":200, "data": {
    "bacteria:双歧杆菌属 Bifidobacterium": { ... },
    "vitamin:维生素B1": { ... }
}}

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 方法签名

public HealthKnowledgeBase query(String itemType, String itemName) {
    return mapper.selectOne(
        new LambdaQueryWrapper<HealthKnowledgeBase>()
            .eq(HealthKnowledgeBase::getItemType, itemType)
            .eq(HealthKnowledgeBase::getItemName, itemName)
    );
}

public Map<String, HealthKnowledgeBase> batchQuery(List<QueryPair> queries) {
    // 按 (type, name) 批量查询
}

14. 验收标准

14.1 主页（gut-flora-detail.vue）

长 scroll 顺畅渲染 >= 1000rpx 高度
报告头部显示姓名/年龄/性别/编号/日期
健康评分圆环绘制（11 项可滚动横向）
4 个快速跳转入口可见，且能跳到对应详情页
肠道功能 / 营养指标双手风琴，能折叠/展开
每个指标名称可点击 → 弹出知识库弹出框
异常值：偏高/过多 → 红色 + ↑；偏低/缺乏/不足 → 琥珀色 + ↓
正常值：默认色无箭头
右下 FAB「编辑」按钮可见
点击「编辑」后 input/picker 可用，「保存」固定底部出现
保存成功后正确返回查看模式 + toast 提示

14.2 菌群详情（gut-flora-species-detail.vue）

12 分类 Tab 正常切换
每个 Tab 显示对应菌属列表
卡片显示菌名（可点弹知识库）、丰度、正常范围、人群水平、检出率
无内嵌说明文字
菌名带颜色+箭头指示偏高/偏低
编辑模式可改丰度/状态，保存后写入

14.3 食物推荐（gut-flora-foods-detail.vue）

分类筛选条切换生效
列表按推荐指数降序
卡片显示名称/分类/推荐指数/营养数据
编辑模式可改推荐指数

14.4 疾病风险（gut-flora-risks-detail.vue）

重要风险（注意/异常）置顶
风险等级用颜色徽章：低风险=绿/注意=黄+⚠/异常=红
疾病名称可点击弹知识库
编辑模式可改风险值/风险等级

14.5 知识库

后端 batch-query 支持一次预取全部知识库条目
弹出框正确显示类型/说明/建议
数据库迁移幂等可重复运行
参考 JSON 说明数据正确导入

14.6 E2E 测试

tests/e2e/flora-microbiome-flow.spec.js 现有场景通过
新增 .kb-link、.knowledge-popup 选择器覆盖知识库交互

15. 文件变更清单

文件	操作	内容
`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/components/health-knowledge-popup.vue`	新建	通用知识库弹出框组件
`cfc-frontend/pages.json`	改	注册 3 个新页面路径
`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`	检查/更新	适配新选择器

16. 风险与权衡

风险	缓解
200+ 菌属首次加载时 batch-query 知识库可能慢	并行请求；知识库表小（<500 行），加索引后毫秒级
知识库数据导入工作量	参考 JSON 已有完整的 `说明` 字段，可用脚本批量入库
编辑时大批量数据上传慢	前端只提交被改过的索引列表
编辑后是否破坏 7 维评分	编辑路径同样调用 `refreshFromGutReport` 刷新
mini-program 真机性能（200+ 卡片）	`v-if` 分组懒加载

17. 实现顺序

后端：HealthKnowledgeBase 表迁移 + 实体/Mapper/Service/Controller → mvn clean compile
后端：POST /api/health/report/edit + updateReportFromPayload → mvn clean compile
导入参考 JSON 的说明数据到 health_knowledge_base
前端：components/health-knowledge-popup.vue 通用弹框组件
前端：新建 gut-flora-foods-detail.vue（最简单）→ 验证编辑流
前端：新建 gut-flora-risks-detail.vue + 知识库弹框
前端：新建 gut-flora-species-detail.vue + 12 Tab + 颜色箭头 + 知识库弹框
前端：重写 gut-flora-detail.vue（手风琴 + 指标知识库 + 颜色箭头 + 双模式）
更新 pages.json + utils/api.js
跑 tests/e2e/flora-microbiome-flow.spec.js 验证
微信开发者工具手动验证关键操作

2026-07-17-flora-microbiome-report-page-design.md 22 KB 文件历史 原始文件