docs: add implementation plan for mini-program and Java backend modifications

docs/参考资料/小程序后端修改计划.md

@@ -0,0 +1,293 @@
+# 小程序页面 + Java 后端修改计划
+
+> 基于 Python 提取脚本当前的完整数据采集能力，制定小程序前端和 Java 后端的修改实施方案
+
+---
+
+## 一、数据流现状
+
+```
+Python 提取 (extract_full_report_v5.py) → JSON (17个模块)
+  ↓
+Java 后端解析 (PdfParseService → ParsedReportPayload)
+  ↓ 存储
+health_report, health_indicator, health_gut_flora, health_disease_risk
+  ↓ 查询 API
+前端 uni-app 展示
+```
+
+### 当前 Python 采集的完整模块
+
+| # | 模块 | 数据量 | 后端存储位置 | 前端展示 |
+|---|------|-------|-------------|---------|
+| 1 | 报告概述 | 12字段 | `HealthReport` | ✅ `gut-flora-detail.vue` |
+| 2 | 报告解读 | 2字段 | 新增 | ❌ 未展示 |
+| 3 | 疾病风险评估 | 18项 | `HealthDiseaseRisk` | ✅ `gut-flora-risks-detail.vue` |
+| 4 | 主要营养评估 | 5项 | `HealthIndicator` | ✅ 营养手风琴 |
+| 5 | 氨基酸评估 | 15项 | `HealthIndicator` | ✅ 营养手风琴 |
+| 6 | 维生素评估 | 10项 | `HealthIndicator` | ✅ 营养手风琴 |
+| 7 | 微量元素评估 | 2项 | `HealthIndicator` | ✅ 营养手风琴 |
+| 8 | 抗生素风险评估 | 9项 | `HealthIndicator` | ✅ 肠道功能手风琴 |
+| 9 | 肠道屏障及代谢物 | 11项 | `HealthIndicator` | ✅ 肠道功能手风琴 |
+| 10 | 短链脂肪酸 | 4项 | `HealthIndicator` | ✅ 肠道功能手风琴 |
+| 11 | 神经递质及激素 | 11项 | `HealthIndicator` | ✅ 肠道功能手风琴 |
+| 12 | 主要消化道致病菌 | 5项 | `HealthIndicator` | ❌ 未展示 |
+| 13 | 个体化食物推荐表 | 224条 | `Food` | ✅ `gut-flora-foods-detail.vue` |
+| 14 | 核心菌属 | 22条 | `HealthGutFlora` | ✅ 菌群详情页 |
+| 15 | 益生菌(种水平) | 22条 | `HealthGutFlora` | ✅ 菌群详情页 |
+| 16 | 有害菌属 | 13条 | `HealthGutFlora` | ✅ 菌群详情页 |
+| 17 | 其它重要菌属 | 12条 | `HealthGutFlora` | ✅ 菌群详情页 |
+| 18 | 病原菌属 | 12条 | `HealthGutFlora` | ❌ 缺少前端标签 |
+| 19 | 病原菌检出 | 4条 | `HealthGutFlora` | ❌ 缺少前端标签 |
+| 20 | **菌纲构成** | **13条** | **`HealthGutFlora`** | **❌ 缺少level支持** |
+| 21 | **菌目构成** | **14条** | **`HealthGutFlora`** | **❌ 缺少level支持** |
+| 22 | **菌科构成** | **20条** | **`HealthGutFlora`** | **❌ 缺少level支持** |
+| 23 | **菌属构成** | **20条** | **`HealthGutFlora`** | **❌ 缺少level支持** |
+| 24 | **菌种构成** | **20条** | **`HealthGutFlora`** | **❌ 缺少level支持** |
+
+---
+
+## 二、实施步骤
+
+### 阶段一：后端 Java 扩展（4个文件）
+
+#### Step 1: `HealthGutFlora.java` — 扩展 level 枚举
+
+**当前**：`level` 字段仅支持 `GENUS/SPECIES`，用于区分核心菌属和益生菌种
+
+**修改**：扩展为支持所有 5 个分类层级和 2 个特殊分类
+
+```java
+// 新增分类常量
+public static final String LEVEL_CLASS = "CLASS";    // 纲
+public static final String LEVEL_ORDER = "ORDER";    // 目
+public static final String LEVEL_FAMILY = "FAMILY";  // 科
+public static final String LEVEL_GENUS = "GENUS";    // 属
+public static final String LEVEL_SPECIES = "SPECIES";// 种
+
+// 新增分类常量
+public static final String CATEGORY_CORE = "core";           // 核心菌属
+public static final String CATEGORY_PROBIOTIC = "probiotic"; // 益生菌
+public static final String CATEGORY_HARMFUL = "harmful";     // 有害菌
+public static final String CATEGORY_OTHER = "other";         // 其它重要菌属
+public static final String CATEGORY_PATHOGEN_GENUS = "pathogen_genus";    // 病原菌属
+public static final String CATEGORY_PATHOGEN_DETECTION = "pathogen_detection"; // 病原菌检出
+public static final String CATEGORY_TAXONOMY = "taxonomy";   // 菌群层级
+```
+
+#### Step 2: `ParsedReportPayload.java` — 新增 DTO 字段
+
+**当前**：`gutFlora` (GENUS级别) + `probioticSpecies` (SPECIES级别)
+
+**修改**：新增 5 个 taxonomy 层级 DTO + 2 个病原菌 DTO
+
+```java
+// 新增
+private List<ParsedGutFlora> taxonomyClass;     // 菌纲构成
+private List<ParsedGutFlora> taxonomyOrder;     // 菌目构成
+private List<ParsedGutFlora> taxonomyFamily;    // 菌科构成
+private List<ParsedGutFlora> taxonomyGenus;     // 菌属构成
+private List<ParsedGutFlora> taxonomySpecies;   // 菌种构成
+private List<ParsedGutFlora> pathogenGenus;     // 病原菌属
+private List<ParsedGutFlora> pathogenDetection; // 病原菌检出
+
+// getter/setter 方法
+```
+
+#### Step 3: `HealthReportService.java` — 扩展存储逻辑
+
+**当前**：`buildGutFloraFromPayload()` 只处理 `gutFlora` 和 `probioticSpecies`
+
+**修改**：扩展处理所有新字段
+
+```java
+// 在 buildGutFloraFromPayload() 中增加
+if (payload.getTaxonomyClass() != null) {
+    for (ParsedReportPayload.Flora pf : payload.getTaxonomyClass()) {
+        result.add(convertToGutFlora(pf));
+    }
+}
+// 同理处理 taxonomyOrder/Family/Genus/Species
+// 同理处理 pathogenGenus/pathogenDetection
+```
+
+#### Step 4: `HealthReportController.java` — 扩展 API 返回
+
+**当前**：`/api/health/report/detail` 返回 `report`, `indicators`, `gutFlora`, `probioticSpecies`, `diseaseRisks`, `foods`
+
+**修改**：增加返回 taxonomy 和 pathogen 数据
+
+```java
+// 在 getReportDetail() 中增加
+result.put("taxonomyClass", gutFloraByLevel("CLASS"));
+result.put("taxonomyOrder", gutFloraByLevel("ORDER"));
+result.put("taxonomyFamily", gutFloraByLevel("FAMILY"));
+result.put("taxonomyGenus", gutFloraByLevel("GENUS"));
+result.put("taxonomySpecies", gutFloraByLevel("SPECIES"));
+result.put("pathogenGenus", gutFloraByCategory("pathogen_genus"));
+result.put("pathogenDetection", gutFloraByCategory("pathogen_detection"));
+```
+
+---
+
+### 阶段二：前端 uni-app 修改（3个文件）
+
+#### Step 5: `gut-flora-species-detail.vue` — 修改菌群详情标签页
+
+**当前标签页**：
+```
+核心菌属 | 益生菌 | 有害菌 | 其它菌属 | 病原菌 | 肥胖相关 | 便秘相关 | 抑郁相关 | 过敏相关 | 腹胀相关 | 失眠相关 | 全部
+```
+
+**问题**：
+- "肥胖相关/便秘相关/抑郁相关/过敏相关/腹胀相关/失眠相关" 在 Python 提取中已禁用（已移到知识库）
+- 缺少"病原菌属"和"病原菌检出"标签
+- 缺少"菌纲/菌目/菌科/菌属/菌种"标签
+
+**修改后标签页**：
+```javascript
+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: '全部' }
+]
+```
+
+**数据加载逻辑修改**：
+```javascript
+loadData: function() {
+  getReportDetail(this.reportId).then(function(res) {
+    if (res.code === 200 && res.data) {
+      self.gutFlora = res.data.gutFlora || []
+      self.probioticSpecies = res.data.probioticSpecies || []
+      // 新增：加载 taxonomy 和 pathogen 数据
+      self.taxonomyClass = res.data.taxonomyClass || []
+      self.taxonomyOrder = res.data.taxonomyOrder || []
+      self.taxonomyFamily = res.data.taxonomyFamily || []
+      self.taxonomyGenus = res.data.taxonomyGenus || []
+      self.taxonomySpecies = res.data.taxonomySpecies || []
+      self.pathogenGenus = res.data.pathogenGenus || []
+      self.pathogenDetection = res.data.pathogenDetection || []
+    }
+  })
+}
+```
+
+**filteredFlora 计算属性修改**：
+核心逻辑是按 `selectedTab` 类别返回对应的数据列表：
+- `core` → `gutFlora.filter(category='core')`
+- `probiotic` → `probioticSpecies`
+- `harmful` → `gutFlora.filter(category='harmful')`
+- `other` → `gutFlora.filter(category='other')`
+- `pathogen_genus` → `pathogenGenus`
+- `pathogen_detection` → `pathogenDetection`
+- `taxonomy_class` → `taxonomyClass`
+- 以此类推
+
+#### Step 6: `gut-flora-detail.vue` — 增加功能入口
+
+在快速导航卡区域增加两个新入口：
+
+```html
+<!-- 现有卡片后增加 -->
+<view class="nav-card" @tap="goToPathogen">
+  <text class="nav-icon">🦠</text>
+  <text class="nav-label">病原菌</text>
+  <text class="nav-count">{{ pathogenCount }}项</text>
+</view>
+<view class="nav-card" @tap="goToTaxonomy">
+  <text class="nav-icon">🔬</text>
+  <text class="nav-label">菌群层级</text>
+  <text class="nav-count">{{ taxonomyCount }}级</text>
+</view>
+```
+
+**新增计算方法**：
+
+```javascript
+computed: {
+  pathogenCount: function() {
+    return (this.pathogenGenus || []).length + (this.pathogenDetection || []).length
+  },
+  taxonomyCount: function() {
+    return 5  // 纲/目/科/属/种
+  }
+}
+```
+
+#### Step 7: `gut-flora-detail.vue` — 增加报告解读区域
+
+在报告头部下方，增加报告解读展示区域：
+
+```html
+<!-- 报告解读区域 -->
+<view class="interpretation-section" v-if="reportInterpretation">
+  <view class="section-header">
+    <text class="section-icon">💡</text>
+    <text class="section-title">报告解读</text>
+  </view>
+  <view class="interpretation-card">
+    <text class="interp-text">{{ reportInterpretation.gutAgeAssessment }}</text>
+  </view>
+  <view class="interpretation-card" v-if="reportInterpretation.healthScoreInterpretation">
+    <text class="interp-text">{{ reportInterpretation.healthScoreInterpretation }}</text>
+  </view>
+</view>
+```
+
+---
+
+### 阶段三：数据库迁移（1个文件）
+
+#### Step 8: `DatabaseInitializer.java` — 扩展 level 字段
+
+```java
+// 迁移N: health_gut_flora 表扩展 level 字段长度
+try {
+    jdbcTemplate.execute("ALTER TABLE health_gut_flora MODIFY COLUMN level VARCHAR(20) COMMENT '级别: CLASS/ORDER/FAMILY/GENUS/SPECIES'");
+    log.info("已扩展 health_gut_flora.level 字段长度");
+} catch (Exception e) {
+    // 忽略
+}
+```
+
+---
+
+## 三、实施顺序
+
+| 步骤 | 文件 | 预估工时 | 依赖 |
+|------|------|---------|------|
+| 1 | `HealthGutFlora.java` | 15min | 无 |
+| 2 | `ParsedReportPayload.java` | 30min | 无 |
+| 3 | `HealthReportService.java` | 30min | Step 1, 2 |
+| 4 | `HealthReportController.java` | 20min | Step 3 |
+| 5 | `gut-flora-species-detail.vue` | 60min | Step 4 |
+| 6 | `gut-flora-detail.vue` | 30min | Step 4 |
+| 7 | `gut-flora-detail.vue` (解读区域) | 20min | 无 |
+| 8 | `DatabaseInitializer.java` | 10min | 无 |
+
+**总预估工时**：约 3.5 小时
+
+---
+
+## 四、风险与注意事项
+
+1. **Python 提取脚本 vs Java 后端解析**：当前 Java 后端的 `PdfParseService` 解析 PDF 的逻辑与 Python 脚本不同。Java 端解析的是上传的 PDF 文件，而 Python 脚本是离线处理。两者需要保持一致的字段映射。
+
+2. **前端数据流**：`gut-flora-species-detail.vue` 的 `filteredFlora` 计算属性需要重构以支持新的分类键值。当前使用 `category` 字段匹配，新 taxonomy 数据只需按 `level` 字段匹配。
+
+3. **向后兼容**：现有报告数据在数据库中可能没有 `level` 字段值（旧数据为 NULL）。前端需要处理 `level` 为空的情况，默认显示为 "菌属"。
+
+4. **疾病相关菌标签**：肥胖/便秘/抑郁/过敏/腹胀/失眠 标签在 Python 提取中已禁用，但在前端仍有显示。移除后这些标签后将显示空数据。建议先保留标签但显示"暂无数据"提示，等用户确认后再移除。
+
+5. **个性化解读字段**：`解读` 字段是 JSON 输出新增的，Java 后端当前没有这个字段。如果需要在 App 中展示，需要在 `ParsedIndicator` 和 `ParsedDiseaseRisk` DTO 中增加 `interpretation` 字段。