# 身体健康7维模型设计规范

> 建立「身」维度下可量化的7维健康子体系，面向家长用户，以最少的用户输入获取最精准的健康画像。

**版本：** v1.0  
**日期：** 2026-06-25  
**状态：** Draft

---

## 1. 背景与目标

### 1.1 现有维度体系

| 体系 | 维度 | 说明 |
|------|------|------|
| 五维能量 | 身·智·富·行·心 | 平台顶层框架，五行相生相克 |
| 认知（DAN评估） | 注意力/专注力/记忆力/逻辑/感知/空间/加工速度 | 6+1维 |
| 心理（EMI） | 情绪商数/心理韧性/压力应对/自我认知 | 4维 |
| 大五人格 | 开放性/尽责性/外向性/宜人性/神经质 | 5维 |
| 关系 | 亲密/沟通/信任 | 3维 |
| **「身」子维度** | **生长发育/睡眠质量/视力健康/免疫力/营养均衡/肠胃健康/运动活力** | **7维（本文档）** |

### 1.2 核心设计原则

1. **最少用户输入**：拍照/上传 > 语音 > 点选 > 手动输入
2. **渐进式精度**：问卷兜底（Tier 3）→ 拍照AI解析（Tier 2）→ 自动报告（Tier 1），有高精度数据自动替代低精度
3. **常模对标**：每个维度的评分映射到同龄同性别人群百分位
4. **菌群报告优先复用**：已有PDF解析的指标直接映射到对应维度

---

## 2. 7维定义与数据源

### 📈 生长发育

| 项目 | 内容 |
|------|------|
| **用户理解** | 身高体重达标吗，胖瘦合适吗 |
| **Tier 1（拍照/自动）** | ①体脂称照片OCR → 体重/体脂率/肌肉量/骨量 ②菌群报告 → 疾病风险（易胖/超重指标）+ Firmicutes/Bacteroidetes比值 ③体检报告OCR → 身高/体重 |
| **Tier 2（语音）** | "8岁，身高130，体重26" → NLP提取 |
| **Tier 3（手动）** | 输入身高、体重（年龄+性别从用户资料读取） |
| **评分算法** | BMI-for-age百分位（中国WS/T 586-2018）+ 体脂率校正 + 历史趋势（持续增长加分） |
| **常模来源** | 中国儿童生长发育标准曲线（卫健委） |

### 🛌 睡眠质量

| 项目 | 内容 |
|------|------|
| **用户理解** | 睡够了没，睡得好不好 |
| **Tier 1** | ①菌群报告 → 神经递质指标（血清素/GABA水平，category="神经递质"） ②手环/手表睡眠截图OCR → 深睡时长/总时长/醒夜次数 |
| **Tier 2** | "晚上十点睡早上七点起，中间醒一次" |
| **Tier 3** | 点选睡眠时长区间（<6h / 6-8h / 8-10h / >10h）+ 点选质量（好/一般/差） |
| **评分算法** | 时长分（年龄推荐时长±1h内满分）+ 质量调整因子 |
| **常模来源** | 同年龄睡眠需求推荐值（美国国家睡眠基金会/AASM） |

### 👁️ 视力健康

| 项目 | 内容 |
|------|------|
| **用户理解** | 近视了没，度数涨了没 |
| **Tier 1** | ①视力检查单/验光单拍照OCR → 左右眼裸眼视力/矫正视力/屈光度 |
| **Tier 2** | "左眼5.0，右眼4.8" 或 "左眼100度，右眼150度" |
| **Tier 3** | 点选是否戴镜 + 输入视力值 |
| **评分算法** | 裸眼视力值映射分 + 屈光度变化趋势（稳定加分/加深扣分）+ 每日屏幕时间风险因子 |
| **常模来源** | 儿童视力发育标准（各年龄正常视力下限） |

### 🛡️ 免疫力

| 项目 | 内容 |
|------|------|
| **用户理解** | 老不老实生病 |
| **Tier 1** | ①菌群报告 → 肠道屏障指标 + 抗生素耐药指标 + 有益菌水平 ②血常规照片OCR → 白细胞/中性粒细胞/淋巴细胞/免疫球蛋白 |
| **Tier 2** | "今年感冒了3次，没得过肺炎" |
| **Tier 3** | 点选半年生病次数（0次/1-2次/3-5次/6次以上）+ 点选严重程度（从未住院/住院1次/住院多次） |
| **评分算法** | 基础分=年龄常模基线 → 生病频率调整（越多越低）→ 菌群屏障加成 → 血常规校正 |
| **常模来源** | 各年龄段年患病次数参考值 |

### 🥗 营养均衡

| 项目 | 内容 |
|------|------|
| **用户理解** | 偏不偏食，缺不缺营养 |
| **Tier 1** | ①菌群报告 → 营养均衡分 + 微量指标（维生素D/铁/锌/钙等）+ 营养缺乏记录 ②饭菜拍照 → AI识别菜品 → 膳食多样性评分 |
| **Tier 2** | "不爱吃青菜，肉还行，牛奶每天喝" |
| **Tier 3** | 3题快速选择：挑食程度（不挑/挑几样/严重挑食）+ 每周食材种类数 + 补充剂使用 |
| **评分算法** | 菌群微营养指标得分 × 0.6 + 膳食多样性得分 × 0.4（仅有问卷时=问卷分×0.8+基线×0.2） |
| **常模来源** | 各年龄段推荐营养素摄入量（DRIs） |

### 🌿 肠胃健康

| 项目 | 内容 |
|------|------|
| **用户理解** | 肠胃舒服吗，拉得好吗 |
| **Tier 1** | ①菌群报告 → **最完整覆盖**：健康度/平衡分/多样性/有益菌/有害菌/核心菌属/SCFA/肠型/肠道年龄 ②舌诊照片 → AI分析舌苔厚薄/舌色/齿痕 → 消化功能状态 |
| **Tier 2** | "最近大便偏稀，一周拉4次，偶尔肚子疼" |
| **Tier 3** | 点选消化舒适度（好/一般/差，含解释emoji辅助） |
| **评分算法** | 菌群综合分（多指标加权）+ 舌诊校正因子 |
| **常模来源** | 菌群报告自带 populationLevel + detectionRate（人群百分位） |

### 🏃 运动活力

| 项目 | 内容 |
|------|------|
| **用户理解** | 运动够不够，体能怎么样 |
| **Tier 1** | ①微信运动授权 → 日均步数 ②学校体测报告拍照OCR → 跳绳/50米跑/坐位体前屈等成绩（对照国家学生体质健康标准） |
| **Tier 2** | "每周两节体育课，周末踢一小时球" |
| **Tier 3** | 点选运动频率（几乎不/每周1-2次/3-5次/每天）+ 点选运动强度（轻度/中等/剧烈） |
| **评分算法** | 运动量（MET-min/周）映射分 + 国家体测标准分（如有） |
| **常模来源** | 国家学生体质健康标准（2023版）+ 各年龄推荐运动量（WHO） |

---

## 3. 数据源优先级与映射规则

### 3.1 全局规则

```
IF 存在 Tier 1 数据 THEN 使用 Tier 1 替代所有低层数据
IF 仅有 Tier 2 数据 THEN 使用 NLP 提取值，置信度低于0.6时降级为 Tier 3
IF 无 Tier 1/2 数据 THEN 使用 Tier 3（问卷/手动），标注"快速评估"标识
```

### 3.2 菌群报告 → 7维映射矩阵

| 菌群报告字段 | 生长发育 | 睡眠质量 | 视力健康 | 免疫力 | 营养均衡 | 肠胃健康 | 运动活力 |
|-------------|:-------:|:-------:|:-------:|:-----:|:-------:|:-------:|:-------:|
| gutHealthScore | | | | ✅ | | ✅ | |
| balanceScore | | | | | | ✅ | |
| diversityScore | | | | ✅ | | ✅ | |
| nutritionScore | | | | | ✅ | | |
| chronicDiseaseScore | ✅ | | | | ✅ | | |
| beneficialBacteriaScore | | | | ✅ | | ✅ | |
| harmfulBacteriaScore | | | | ✅ | | ✅ | |
| coreGenusScore | | | | | | ✅ | |
| gutAge | | ✅ | | | | ✅ | |
| gutBalanceScore | | | | | | ✅ | |
| gutDiversityScore | | | | ✅ | | ✅ | |
| 神经递质(indicators) | | ✅ | | | | | |
| 肠道屏障(indicators) | | | | ✅ | | ✅ | |
| 短链脂肪酸(indicators) | | | | | ✅ | ✅ | |
| 疾病风险(diseaseRisks) | ✅ | | | ✅ | | | |
| 菌种丰度(populationLevel) | ✅ | | | ✅ | ✅ | ✅ | |
| 微量指标(维生素/矿物质) | | | | | ✅ | | |
| 抗生素耐药 | | | | ✅ | | | |

### 3.3 维度分数聚合

```
纬度最终分 = Σ(各数据源分 × 权重) × 年龄段常模校正因子

权重说明：
- 有菌群报告时：菌群指标权重占 0.4-0.7，其他数据源占 0.3-0.6
- 无菌群报告时：问卷/语音权重占 0.7-1.0，基线常模占 0-0.3

常模校正：
- 原始分 → 查同性别同年龄百分位 → 输出 1-100 分（50 = 人群中位）
- 百分位≥85 → 优秀（绿色）
- 百分位50-84 → 良好（蓝色）
- 百分位15-49 → 一般（黄色）
- 百分位<15 → 关注（橙色/红色）
```

---

## 4. 架构设计

### 4.1 模块划分

```
┌─────────────────────────────────────────────────────────────┐
│                    Controller 层                              │
│  HealthDimensionController                                    │
│  POST /api/health/dimensions/{memberId} — 获取7维评分        │
│  POST /api/health/dimensions/{memberId}/upload — 上传数据源  │
│     body: { type: "report"|"photo"|"voice", file/data }     │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                   Service 层                                 │
│                                                              │
│  DimensionScoreService     ← 核心聚合器                       │
│  ├─ getDimensions(memberId) → 7维评分 + 常模百分位            │
│  ├─ refresh(memberId, dataSource) → 监听到新数据，重算        │
│  └─ compareTrend(memberId, months) → 历史趋势                 │
│                                                              │
│  ┌────────────┬───────────┬───────────┬──────────────────┐   │
│  │ GrowScore  │ SleepScore│ VisionScore│ ImmunityScore   │   │
│  │ Service    │ Service   │ Service   │ Service          │   │
│  ├────────────┼───────────┼───────────┼──────────────────┤   │
│  │ Nutrition  │ GutScore  │ Exercise  │                  │   │
│  │ ScoreSvc   │ Service   │ ScoreSvc  │                  │   │
│  └────────────┴───────────┴───────────┴──────────────────┘   │
│                                                              │
│  外部依赖 Service:                                            │
│  ├─ HealthReportService  (菌群报告)                          │
│  ├─ OcrService           (照片OCR)                           │
│  ├─ VoiceInputService    (语音→NLP)                          │
│  ├─ TongueDiagnosisService (舌诊AI)                          │
│  └─ WechatStepService    (微信运动)                          │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                  Entity / Mapper 层                           │
│                                                              │
│  HealthDimensionScore ← 核心实体                              │
│  ├─ id, memberId, dimension (code), score (0-100)            │
│  ├─ percentile (0-100), dataSource (枚举: REPORT/PHOTO/...)  │
│  ├─ tier (1/2/3), assessDate, expireDate                     │
│  └─ rawData (JSON) — 保留原始输入用于追溯                     │
│                                                              │
│  DataSourceRecord ← 数据源记录                                │
│  ├─ id, memberId, sourceType (PDF/PHOTO/VOICE/MANUAL)        │
│  ├─ dimensionCodes (影响的维度列表)                           │
│  └─ parsedResult (JSON) — OCR/解析后的结构化结果              │
└─────────────────────────────────────────────────────────────┘
```

### 4.2 核心实体设计

#### HealthDimensionScore

```sql
CREATE TABLE health_dimension_scores (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    member_id       BIGINT       NOT NULL COMMENT '家庭成员ID',
    dimension       VARCHAR(20)  NOT NULL COMMENT '维度: growth/sleep/vision/immunity/nutrition/gut/exercise',
    score           INT          NOT NULL COMMENT '0-100分',
    percentile      INT          COMMENT '人群百分位 0-100',
    data_source     VARCHAR(20)  NOT NULL COMMENT '数据源: REPORT/PHOTO/VOICE/MANUAL',
    tier            TINYINT      NOT NULL DEFAULT 3 COMMENT '数据层级: 1自动/2语音/3手动',
    raw_data        JSON         COMMENT '原始数据快照',
    assess_date     DATE         NOT NULL COMMENT '评估日期',
    expire_date     DATE         COMMENT '数据过期日（Tier1长/Tier3短）',
    created_at      DATETIME,
    updated_at      DATETIME,
    UNIQUE KEY uk_member_dim_date (member_id, dimension, assess_date)
);
```

#### DataSourceRecord

```sql
CREATE TABLE health_data_sources (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    member_id       BIGINT       NOT NULL,
    source_type     VARCHAR(20)  NOT NULL COMMENT 'PDF/PHOTO/VOICE/MANUAL/WEIXIN_STEP',
    dimension_codes JSON         NOT NULL COMMENT '影响的维度列表',
    parsed_result   JSON         COMMENT '解析结果全量',
    file_url        VARCHAR(500) COMMENT '原始文件URL',
    confidence      DECIMAL(3,2) COMMENT 'AI解析置信度 0-1',
    created_at      DATETIME,
    INDEX idx_member_source (member_id, source_type)
);
```

### 4.3 维度分数生命周期

```
用户上传数据源
     │
     ▼
解析层（OcrService / PdfParseService / VoiceInputService / TongueDiagnosisService）
     │
     ▼ 返回结构化原始数据
DimensionScoreService.refresh(memberId, dataSource)
     │
     ├─ 读取该dataSource影响的所有维度
     ├─ 对每个维度：读取所有活跃数据源
     ├─ 按Tier优先级合并（Tier1覆盖Tier2/3）
     ├─ 计算加权得分
     ├─ 查常模表得到百分位
     └─ 写入/更新 health_dimension_scores

用户查看7维面板
     │
     ▼
POST /api/health/dimensions/{memberId}
     │
     ├─ 取各维度最新 assess_date 的记录
     ├─ 有expire_date且未过期 → 直接返回
     ├─ 有过期 → 提示用户补充数据，同时返回过期数据（标注）
     └─ 无数据 → 进入Tier 3（问卷流程）
```

---

## 5. 常模系统

### 5.1 常模数据结构

```sql
CREATE TABLE health_norm_reference (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    dimension       VARCHAR(20)  NOT NULL COMMENT '维度',
    gender          VARCHAR(10)  NOT NULL COMMENT 'male/female/all',
    age_min         INT          NOT NULL COMMENT '年龄下限(月)',
    age_max         INT          NOT NULL COMMENT '年龄上限(月)',
    percentile_5    INT,
    percentile_15   INT,
    percentile_25   INT,
    percentile_50   INT  COMMENT '中位值',
    percentile_75   INT,
    percentile_85   INT,
    percentile_95   INT,
    source          VARCHAR(50)  COMMENT '常模来源: WHO/卫健委/平台自建',
    UNIQUE KEY uk_dim_gender_age (dimension, gender, age_min, age_max)
);
```

### 5.2 常模优先级

1. **中国官方标准**（BMI-for-age WS/T 586、学生体质健康标准、血压百分位）
2. **菌群报告人群数据**（已有 populationLevel → 平台积累后直接复用）
3. **国际权威标准**（WHO生长曲线、睡眠时长推荐）
4. **平台自建常模**（运营一段后基于用户数据建立自有百分位）

### 5.3 菌群报告已有常模数据的利用

`HealthGutFlora.populationLevel` 字段（如 "35%"）和 `detectionRate`（如 "98.56%"）已经是现成的常模数据。可直接用于：
- 肠胃健康维度的评分校准
- 免疫力维度的部分指标校准
- 营养均衡维度的微营养指标参考

策略：菌群报告解析时，populationLevel 直接作为该指标在人群中的百分位使用，无需二次查表。

---

## 6. 分期实现计划

### Phase 1 — 核心框架 + 问卷兜底（MVP）

**目标：7维全部可评估，所有用户可使用**

- 创建 `HealthDimensionScore` / `DataSourceRecord` / `health_norm_reference` 表
- `DimensionScoreService` 聚合逻辑（Tier 3 问卷兜底）
- `HealthDimensionController` — 获取7维 / 手动输入问卷
- 前端：7维雷达图页面 + 每个维度的简单问卷（3-5题点选）
- 已有菌群报告数据直接映射（`PdfParseService` 解析结果 → 对应维度）
- 部署常模种子数据（BMI/体测等国家标准）

### Phase 2 — 拍照OCR

**目标：替代手动输入，减少用户操作**

- `OcrService` 通用引擎（支持体检报告/体测单/血常规拍照）
- 体脂称照片OCR（显示屏幕 → 数字识别）
- 舌诊照片AI分析（舌色/舌苔/齿痕 → 肠胃/免疫/睡眠推论）
- `VoiceInputService`（语音→ASR→NLP指标提取）
- 后端整合Tier1/2→覆盖Tier3

### Phase 3 — 自动接入

**目标：最低用户操作**

- 微信运动授权接入（步数→运动活力）
- 手环截图自动识别
- 历史数据趋势图（各维度3/6/12个月变化）
- 健康建议引擎（各维度低分→个性化改善建议，关联商城营养品）

---

## 7. 用户界面示意（文字描述）

### 7.1 7维健康雷达图

主页面显示一个7边形雷达图，每个顶点标注维度名称和分数（0-100），中心为常模中位线（50分）。

颜色编码：
- ≥85 分深绿 — 🟢 优秀
- 60-84 分浅绿 — 良好
- 40-59 分黄色 — ⚠️ 一般
- <40 分橙色/红 — 🔴 关注

### 7.2 数据源提示

每个维度下方显示当前数据源等级图标：
- 📄 菌群报告 / 🏥 体检报告（Tier 1 自动）
- 📷 照片识别（Tier 2 拍照）
- 🎤 语音输入（Tier 2 语音）
- ✏️ 手动填写（Tier 3 手动）
- 点击可查看原始数据和到期时间

### 7.3 数据补充引导

当某维度数据过期或从未采集时：
- 入口文案："拍张体检单，自动获取{维度名}评估"
- 或语音按钮："说句话，AI帮你记录"
- 或点选入口：3-5题快速问卷

---

## 8. 商品与维度的联动设计

### 8.1 现有代码调研结论

经过对后端/前端代码的全面探索，以下是当前商品模块的实际实现状态：

#### 商品列表（已实现）

| 层级 | 文件 | 说明 |
|------|------|------|
| 后端 | `ProductController.java` (`/api/product/*`) | 商品 CRUD、上下架、审核 |
| 后端 | `ProductService.java` | 商品管理核心逻辑 |
| 后端 | `ProductCategoryService.java` | 两级分类管理 |
| 前端 | `pages/body/index.vue` → `loadDimensionProducts()` | 身体 Tab 调用 `getProductsByDomain('body', page, size)` |
| 前端 | `DimensionProducts.vue` | 通用维度商品展示组件（2列卡片网格） |
| 前端 | `pages/shop/index.vue` | 完整商城页（两级分类 + 分页加载） |
| 前端 | `pages/discover/index.vue` | 发现页热门推荐（按 productType 筛选） |

**数据结构**：`products` 表（status: pending/on_shelf/off_shelf/approved/rejected）+ `product_categories` 表（parent-child 自关联）

#### AI 商品推荐（部分实现，待完善）

| 组件 | 文件 | 现状 |
|------|------|------|
| 推荐引擎 | `RecommendationService.java` | 基于 `nutritionTags` 模糊搜索 `name`/`description`，非真正 AI 推荐 |
| Dify 集成 | `DifySyncService.java` | 有 TODO 注释，实际未完成：`// 根据 dimensionCode 查找 product_dimension_config 中的 dify_dataset_id` |
| 配置表 | `product_dimension_config` | 有 `difyDatasetId` 字段，但数据为空 |
| 前端 | `pages/discover/product-detail/` | 有商品详情页，未接入 AI 推荐 |

**推荐流程（当前）**：用户营养标签 → `RecommendationService.search()` → LIKE 模糊匹配商品 name/description → 返回 `RecommendationResult`（product/activity/article 三类）

#### 购买后能量变化（**未实现**）

| 数据模型 | 现状 |
|----------|------|
| `EnergyLog.sourceType` | 注释支持 "product" 类型，但代码中无触发路径 |
| `EnergySourceConfig` | 表设计支持 `sourceType=product` + ratio 比例分配，需管理员预配置 |
| `ProductDimensionConfig` | 有 `dimensionCode` + `dimensionType`，但无商品绑定数据 |

**当前已实现的能量来源**：task、emotion_checkin、health_checkin、streak、game、article、appointment、activity、checkin

**缺失**：商品支付成功后**未调用** `energyService.awardEnergy()`，能量系统对商品购买无感知。

### 8.2 设计改进方案

#### 改进1：商品购买后自动发放能量

```
用户支付成功（ProductOrder status: pending → paid）
        │
        ▼
ProductOrderService.handlePaymentSuccess() / pay()
        │
        ├─ 检查 energy_source_config 中是否存在 sourceType=product, sourceId={商品ID} 的配置
        ├─ 如有：按 ratio 比例分配能量至各维度
        └─ 如无：使用商品默认能量值（由 ProductDimensionConfig.dimensionCode 决定基础维度）
```

**新增接口**：
- `POST /api/energy/award-from-product` — 手动触发商品能量发放（用于补偿漏发场景）
- `POST /api/admin/energy-source-config` — 管理员配置商品-维度-能量映射

**Product 实体扩展**（可选）：
- 新增 `energyAmount` 字段：购买该商品赠送的能量值
- 新增 `primaryDimension` 字段：主维度的 dimensionCode

#### 改进2：Dify AI 商品推荐落地

```
用户进入身体 Tab → 加载7维健康数据
        │
        ▼
获取营养缺乏标签（NutritionDeficiencyRecord）
        │
        ▼
调用 Dify API（datasetId 来自 product_dimension_config）
        │
        ▼
返回推荐的商品列表（排序：相关度 × 维度匹配度）
        │
        ▼
前端 DimensionProducts 组件展示
```

**前提条件**：
- `product_dimension_config` 表填充 `difyDatasetId`（目前为空）
- Dify 中建立商品知识库，包含商品维度标签（growth/sleep/vision/immunity/nutrition/gut/exercise）

### 8.3 现有代码文件索引

| 功能 | 后端关键文件 | 前端关键文件 |
|------|------------|------------|
| 商品列表/分类 | `ProductController.java`, `ProductService.java`, `ProductMapper.java`, `ProductCategoryService.java` | `pages/shop/index.vue`, `pages/body/index.vue`, `DimensionProducts.vue` |
| AI 推荐 | `RecommendationService.java`（推荐引擎）, `DifySyncService.java`（Dify 集成） | `pages/discover/index.vue`, `pages/discover/product-detail/` |
| 能量变化 | `EnergySourceConfig.java`（配置表）, `ProductDimensionConfig.java`（维度配置）, `EnergyLog.java`（流水） | 暂无前端入口 |

---

## 9. 待确认问题

- [ ] 舌诊AI方案：自研基于颜色/纹理分类 vs 接入第三方API（如百度AI舌诊）
- [ ] 体脂称：支持哪些品牌的屏幕布局，是否需要通用OCR适配层
- [ ] 语音模型：用微信内置语音识别还是自建ASR
- [ ] 常模数据：BMI百分位表是硬编码在代码中还是做成可配置表
- [x] **商品能量触发**：当前 ProductOrder 支付成功后**未调用** awardEnergy，需在 ProductOrderService 中新增能量发放逻辑（见 8.2 改进方案）
- [ ] **Dify 推荐落地**：`product_dimension_config.difyDatasetId` 为空，需填充实际数据集 ID 并完成 DifySyncService 调用链路

---

## 10. 附录：7维与五维能量「身」的衔接

```
五维「身」能量值 = Σ(7维子维度分 × 权重)
                    其中权重可配置（默认等权 1/7）

衔接逻辑：
- 用户首次进入 → 引导上传菌群报告/拍照 → 自动生成7维+「身」能量
- 已有旧数据 → 历史迁移：菌群报告现有字段直接映射，缺的维度走问卷
- 实时联动 → 任一子维度更新 → 自动重算「身」能量（已有 EnergyService）
```