docs: add gap analysis between extraction results and miniprogram/backend

docs/参考资料/差异分析-数据采集vs小程序后端.md

@@ -0,0 +1,220 @@
+# 菌群报告数据采集 vs 小程序/后端 差异分析
+
+> 基于 Python 提取脚本(extract_full_report_v5.py)当前采集的完整数据结构，
+> 对比分析现有 Java 后端和 uni-app 前端需要修改的内容。
+
+---
+
+## 一、数据采集现状（Python 提取脚本输出）
+
+| 模块 | 采集项数 | 输出位置 |
+|------|---------|---------|
+| 报告概述 | 12项 | `报告概述` |
+| 疾病风险评估 | 18项 | `疾病风险评估` |
+| 主要营养评估 | 5项 | `主要营养评估` |
+| 氨基酸评估 | 15项 | `氨基酸评估` |
+| 维生素评估 | 10项 | `维生素评估` |
+| 微量元素评估 | 2项 | `微量元素评估` |
+| 抗生素风险评估 | 9项 | `抗生素风险评估` |
+| 肠道屏障及代谢物 | 11项 | `肠道屏障及代谢物` |
+| 短链脂肪酸 | 4项 | `短链脂肪酸` |
+| 神经递质及激素 | 11项 | `神经递质及激素` |
+| 主要消化道致病菌 | 5项 | `主要消化道致病菌` |
+| 个体化食物推荐表 | 224条 | `个体化食物推荐表` |
+| 核心菌属 | 22条 | `菌群检出详细列表.核心菌属` |
+| 益生菌（种水平） | 22条 | `菌群检出详细列表.益生菌` |
+| 有害菌属 | 13条 | `菌群检出详细列表.有害菌属` |
+| 其它重要菌属 | 12条 | `菌群检出详细列表.其它重要菌属` |
+| 病原菌属 | 12条 | `菌群检出详细列表.病原菌属` |
+| 病原菌检出 | 4条 | `菌群检出详细列表.病原菌检出` |
+| **菌纲构成** | **13条** | **`菌群检出详细列表.菌纲构成`** |
+| **菌目构成** | **14条** | **`菌群检出详细列表.菌目构成`** |
+| **菌科构成** | **20条** | **`菌群检出详细列表.菌科构成`** |
+| **菌属构成** | **20条** | **`菌群检出详细列表.菌属构成`** |
+| **菌种构成** | **20条** | **`菌群检出详细列表.菌种构成`** |
+
+---
+
+## 二、后端 (Java) 需要修改的内容
+
+### 2.1 现有实体是否覆盖
+
+| 数据 | 现有实体 | 是否覆盖 | 问题 |
+|------|---------|---------|------|
+| 报告概述 | `HealthReport` | ✅ | 字段已覆盖(gutAge, gutType, scores) |
+| 疾病风险评估 | `HealthDiseaseRisk` | ✅ | 已覆盖 |
+| 营养/氨基酸/维生素/微量元素 | `HealthIndicator` | ✅ | 用 `category` 区分 |
+| 抗生素风险评估 | `HealthIndicator` | ✅ | `category='抗生素风险评估'` |
+| 肠道屏障/SCFA/神经递质 | `HealthIndicator` | ✅ | 同上 |
+| 主要消化道致病菌 | `HealthIndicator` | ⚠️ | 现有用 `HealthIndicator` 但可能有独立表 |
+| 核心菌属/有害菌属/其它菌属 | `HealthGutFlora` | ✅ | 用 `category` 区分 |
+| 益生菌种水平 | `HealthGutFlora` | ✅ | `level=SPECIES` |
+| 病原菌属/检出 | `HealthGutFlora` | ⚠️ | 现有 `category` 可能没有 `pathogen_genus`/`pathogen_detection` |
+| **菌纲构成/菌目构成/菌科构成/菌属构成/菌种构成** | `HealthGutFlora` | **❌** | **现有 `level` 枚举只有 GENUS/SPECIES，缺少 CLASS/ORDER/FAMILY** |
+
+### 2.2 需要修改的 Java 文件
+
+#### A. `HealthGutFlora.java` — 扩展 level 枚举
+
+```java
+// 当前: level 字段只有 GENUS/SPECIES
+// 需要扩展支持:
+// CLASS（纲）, ORDER（目）, FAMILY（科）, GENUS（属）, SPECIES（种）
+// 建议: 将 level 字段改为字符串类型，不再限制枚举值
+```
+
+#### B. `ParsedReportPayload.java` — 新增 Taxonomy 层级 DTO
+
+```java
+// 当前: 只有 gutFlora (GENUS级别) 和 probioticSpecies (SPECIES级别)
+// 需要增加:
+// - taxonomyClass: List<Flora>  // 纲级别
+// - taxonomyOrder: List<Flora>   // 目级别
+// - taxonomyFamily: List<Flora>  // 科级别
+// - taxonomyGenus: List<Flora>   // 属级别（区别于核心菌属）
+// - taxonomySpecies: List<Flora> // 种级别（区别于益生菌种）
+```
+
+#### C. `PdfParseService.java` — 增加 Taxonomy 解析
+
+```java
+// 在 PDF 解析逻辑中，增加对 taxonomy 层级数据的解析
+// 当前解析 PDF 的 Java 端可能不完整，需要同步 Python 脚本的提取逻辑
+```
+
+#### D. `HealthReportService.java` — 增加 Taxonomy 存储
+
+```java
+// buildGutFloraFromPayload() 方法需要扩展以处理新 level 类型
+// 目前只处理 gutFlora 和 probioticSpecies
+// 需要增加 taxonomyClass/Order/Family/Genus/Species 的处理
+```
+
+#### E. `HealthReportController.java` — 增加 API 端点
+
+```java
+// 1. 报告详情 API (/api/health/report/detail) 返回 taxonomy 数据
+// 2. 需要增加 taxonomy 相关的查询和编辑 API
+```
+
+#### F. `DatabaseInitializer.java` — 数据迁移
+
+```java
+// 如果 health_gut_flora 表的 level 字段当前是 VARCHAR(10)，
+// 需要扩展为 VARCHAR(20) 以支持 CLASS/ORDER/FAMILY
+// 迁移: health_gut_flora 表扩展 level 字段长度
+```
+
+---
+
+## 三、前端 (uni-app) 需要修改的内容
+
+### 3.1 现有页面覆盖情况
+
+| 页面 | 用途 | 当前状态 | 需要修改 |
+|------|------|---------|---------|
+| `gut-flora-detail.vue` | 报告详情总览 | ✅ 已有 | 增加 taxonomy 入口 |
+| `gut-flora-species-detail.vue` | 菌群分类详情 | ⚠️ 需修改 | 增加 taxonomy 标签页，移除已禁用的疾病相关菌标签 |
+| `gut-flora-risks-detail.vue` | 疾病风险详情 | ✅ 已有 | 无大改 |
+| `gut-flora-foods-detail.vue` | 饮食推荐 | ✅ 已有 | 无大改 |
+| `physical-exam-detail.vue` | 体检报告详情 | ✅ 新建 | 无大改 |
+| `report-list.vue` | 报告列表 | ✅ 已更新 | 无大改 |
+| `report-upload.vue` | 报告上传 | ✅ 已更新 | 无大改 |
+| `report-survey.vue` | 调研问卷 | ✅ 已重写 | 无大改 |
+
+### 3.2 需要修改的前端文件
+
+#### A. `gut-flora-species-detail.vue` — 主要修改
+
+**当前标签页**：
+```
+核心菌属 | 益生菌 | 有害菌 | 其它菌属 | 病原菌 | 肥胖相关 | 便秘相关 | 抑郁相关 | 过敏相关 | 腹胀相关 | 失眠相关 | 全部
+```
+
+**问题**：
+1. "肥胖相关/便秘相关/抑郁相关/过敏相关/腹胀相关/失眠相关" 标签在 Python 提取中已禁用（疾病相关菌已移到知识库），Java 后端 `getGutFloraByCategory()` 返回空数据
+2. 缺少 taxonomy 层级标签：菌纲构成、菌目构成、菌科构成、菌属构成、菌种构成
+3. 缺少"病原菌检出"标签
+
+**修改方案**：
+```javascript
+// 新的标签页（移除疾病相关菌，增加 taxonomy 层级）
+tabs: [
+  { key: 'core', label: '核心菌属' },
+  { key: 'probiotic', label: '益生菌' },
+  { key: 'harmful', label: '有害菌' },
+  { key: 'other', label: '其它菌属' },
+  { key: 'pathogen_genus', label: '病原菌属' },
+  { key: 'pathogen_detection', label: '病原菌检出' },
+  // Taxonomy 层级
+  { key: 'taxonomy_class', label: '菌纲' },
+  { key: 'taxonomy_order', label: '菌目' },
+  { key: 'taxonomy_family', label: '菌科' },
+  { key: 'taxonomy_genus', label: '菌属' },
+  { key: 'taxonomy_species', label: '菌种' },
+  { key: 'all', label: '全部' }
+]
+```
+
+#### B. `gut-flora-detail.vue` — 增加 taxonomy 入口
+
+在快速导航卡区域增加 taxonomy 入口：
+```html
+<view class="nav-card" @tap="goToTaxonomy">
+  <text class="nav-icon">🔬</text>
+  <text class="nav-label">菌群层级</text>
+  <text class="nav-count">{{ taxonomyCount }}级</text>
+</view>
+```
+
+#### C. `api.js` — 增加 API 调用
+
+```javascript
+// 1. 获取 taxonomy 数据（可能从 report/detail 已有）
+// 2. 保存 taxonomy 编辑
+```
+
+#### D. `pages.json` — 如果新增页面需要注册
+
+当前 taxonomy 数据在 `gut-flora-species-detail.vue` 中通过标签页切换，
+不需要新增页面，只需修改现有页面的标签。
+
+---
+
+## 四、修改优先级
+
+### P0（必须修改 — 数据缺失）
+1. `HealthGutFlora.java` — 扩展 `level` 字段支持 CLASS/ORDER/FAMILY/GENUS/SPECIES
+2. `ParsedReportPayload.java` — 增加 taxonomy 层级 DTO
+3. `HealthReportService.java` — 扩展 `buildGutFloraFromPayload()` 处理 taxonomy 数据
+4. `gut-flora-species-detail.vue` — 新增 taxonomy 标签页，移除已禁用的疾病相关菌标签
+
+### P1（体验优化 — 数据显示不全）
+5. `gut-flora-detail.vue` — 增加 taxonomy 入口和抗生素风险评估独立区域
+6. `HealthReportController.java` — 确保 taxonomy 数据在 report/detail 接口返回
+
+### P2（可用性 — 已禁用功能清理）
+7. 移除前端疾病相关菌标签（肥胖/便秘/抑郁/过敏/腹胀/失眠）
+8. 清理 `DatabaseInitializer.java` 中过时的迁移
+
+---
+
+## 五、数据流示意图
+
+```
+Python 提取脚本 (extract_full_report_v5.py)
+  ↓ JSON
+Java 后端 (PdfParseService → ParsedReportPayload)
+  ↓ 存储到数据库
+health_report         ← 报告概述
+health_indicator      ← 营养/氨基酸/维生素/微量元素/屏障/SCFA/神经递质/抗生素
+health_disease_risk   ← 疾病风险评估
+health_gut_flora      ← 核心菌属/益生菌/有害菌/其它菌属/病原菌属/病原菌检出
+                        + 菌纲构成/菌目构成/菌科构成/菌属构成/菌种构成 (需新增)
+  ↓ 查询 API
+前端 (uni-app)
+  gut-flora-detail.vue        ← 报告总览 + 指标
+  gut-flora-species-detail.vue ← 菌群分类详情 (需修改标签)
+  gut-flora-risks-detail.vue   ← 疾病风险
+  gut-flora-foods-detail.vue   ← 饮食推荐
+```