# 知识库 v3.0 + 数据提取重构 设计方案

> 目标：数据与模板分离，个人JSON只存纯数据，知识库存标准内容和解释

---

## 一、知识库结构变更

### 1.1 现有章节扩展：指标调整建议

在现有的每个指标的 `说明` 字段旁，新增两个字段：

```json
{
  "名称": "碳水化合物",
  "说明": "主要能量来源",
  "偏高影响": "碳水化合物偏高可能提示…",
  "偏低影响": "碳水化合物偏低可能导致能量不足…",
  "调整建议": "建议增加全谷物和杂豆摄入…"
}
```

涉及章节：疾病风险评估(20) + 主要营养评估(5) + 氨基酸评估(15) + 维生素评估(10) + 微量元素评估(2) + 抗生素风险评估(9) + 肠道屏障及代谢物(11) + 短链脂肪酸(4) + 神经递质及激素(11) = **~87 项指标**

### 1.2 新增章节：菌属功能库

```json
{
  "菌属功能库": {
    "说明": "所有菌属的功能说明、高低影响、调整方向",
    "菌属": [
      {
        "学名": "Clostridium",
        "中文名": "梭菌属",
        "分组": "核心菌属",
        "功能说明": "产丁酸，参与胆汁酸代谢",
        "偏高影响": "多导致人体炎症，致病，导致菌群失衡；肥胖人群丰度较高",
        "偏低影响": "",
        "调整方向": ""
      }
    ]
  }
}
```

- `学名` 为主键（个人JSON用学名匹配）
- `中文名` 用于展示
- `分组` 对应：核心菌属 / 益生菌 / 有害菌属 / 其它重要菌属 / 病原菌属
- `功能说明` / `偏高影响` / `偏低影响` / `调整方向`

数据来源：从 501999942-某人.json 和 530010234-侯.json 等 5 份报告的菌属 `说明` 字段提取 + 领域知识补齐乱码。

### 1.3 新增章节：食物库

```json
{
  "食物库": {
    "说明": "224种食物的基础营养数据",
    "数据": [
      {
        "名称": "大麦",
        "分类": "主食",
        "能量KJ": "1481",
        "蛋白g": "12",
        "脂肪g": "2",
        "碳水化合物g": "73",
        "总膳食纤维g": "17"
      }
    ]
  }
}
```

直接从现有 personal JSON 的 `个体化食物推荐表.数据` 搬运。注意：个人JSON中的 `推荐指数` 是个人计算结果，不进知识库。

---

## 二、个人JSON输出结构变更（提取脚本重构）

### 2.1 删除的字段

| 字段 | 原因 |
|------|------|
| `正常范围`（各项指标中的字符串） | 知识库有结构化 min/max |
| `解读`（大部分为空） | 改为知识库模板动态拼接 |
| 菌属的 `说明` | 移入知识库 `菌属功能库` |

### 2.2 统一的字段命名

| 当前混乱的命名 | 统一为 |
|---------------|--------|
| `数值` / `评估值` / `丰度` / `丰度%` | `数值` |
| `状态` / `健康状况` | `状态`（保留，方便前端） |
| `致病菌`（主要消化道致病菌） | `名称` |
| `名称: "梭菌属 Clostridium"` | `名称: "Clostridium"`（提取学名部分） |

### 2.3 保留的输出结构示例

```json
{
  "报告概述": {
    "姓名": "某人", "年龄": "53岁", "性别": "男",
    "肠道预测年龄": "55.52岁", "肠型": "普雷沃氏菌型",
    "健康总分": 57, "菌群健康": 76, ...
  },
  "疾病风险评估": [
    {"名称": "炎症性肠炎", "数值": 0.24, "状态": "低风险"},
    ...
  ],
  "菌群检出详细列表": {
    "核心菌属": [
      {"名称": "Clostridium", "数值": 0.2787}
    ],
    "菌纲构成": [
      {"名称": "Bacteroidia", "数值": 76.721}
    ]
  },
  "个体化食物推荐表": [
    {"名称": "大麦", "推荐指数": 17},
    ...
  ]
}
```

### 2.4 名称一致性清洗

提取脚本中新增名称清洗逻辑：
- `"梭菌属 Clostridium"` → `"Clostridium"`
- `"5.1543-18.1656"`（数据污染）→ 跳过或修正
- `"心脑血管疾病风险"` → `"心脑血管疾病"`（与知识库匹配）
- 去重：自动去重因PDF格式导致的重复条目

---

## 三、匹配关系设计

### 3.1 匹配规则

前端（或后端拼接层）按以下规则匹配：

1. **指标类数据**：个人 JSON 的 `名称` ↔ 知识库各章节 `指标[].名称`
   - 例如：`{"名称":"碳水化合物"}` → 知识库 `主要营养评估.指标[名称="碳水化合物"]`

2. **菌属数据**：个人 JSON 的 `名称`(学名) ↔ 知识库 `菌属功能库.菌属[].学名`
   - 例如：`{"名称":"Clostridium"}` → 知识库 `菌属功能库.菌属[学名="Clostridium"]`

3. **食物数据**：个人 JSON 的 `名称` + `推荐指数` ↔ 知识库 `食物库.数据[].名称`
   - 例如：`{"名称":"大麦","推荐指数":17}` → 知识库 `食物库.数据[名称="大麦"]` + 推荐指数

4. **状态判定**：个人 JSON 的 `数值` + 知识库的 `标准范围`/`状态分级` → 可验证或重新计算 `状态`

### 3.2 前端展示流程

```
个人JSON.json（数值）       知识库.json（解释）
     │                            │
     └──────────┬─────────────────┘
                │ 按名称匹配
                ▼
      动态拼接渲染
     ┌─────────────────────┐
     │ 指标名称（知识库）    │
     │ 数值（个人）          │
     │ 状态（个人或动态计算） │
     │ 说明（知识库）        │
     │ 调整建议（知识库）    │
     └─────────────────────┘
```

---

## 四、实施步骤

1. **知识库补充**：在 `报告指标知识库.json` 中增加调整建议、菌属功能库、食物库
2. **提取脚本重构**：修改 `extract_full_report_v5.py` 的输出结构
3. **验证**：用 5 份测试 PDF 重新提取，验证名称匹配率和数据正确性
4. **同步更新**：同步 `schema.sql`（如有表结构变化）
5. **提交**：`git commit -m "feat: knowledge base v3 with flora library, food library, adjustment tips; refactor extraction script"`