2026-06-26-health-dimensions-design-spec.md 24 KB
身体健康7维模型设计规范
建立「身」维度下可量化的7维健康子体系，面向家长用户，以最少的用户输入获取最精准的健康画像。
版本： v1.0
日期： 2026-06-25
状态： Draft
1. 背景与目标
1.1 现有维度体系
| 体系 | 维度 | 说明 |
|---|---|---|
| 五维能量 | 身·智·富·行·心 | 平台顶层框架，五行相生相克 |
| 认知（DAN评估） | 注意力/专注力/记忆力/逻辑/感知/空间/加工速度 | 6+1维 |
| 心理（EMI） | 情绪商数/心理韧性/压力应对/自我认知 | 4维 |
| 大五人格 | 开放性/尽责性/外向性/宜人性/神经质 | 5维 |
| 关系 | 亲密/沟通/信任 | 3维 |
| 「身」子维度 | 生长发育/睡眠质量/视力健康/免疫力/营养均衡/肠胃健康/运动活力 | 7维（本文档） |
1.2 核心设计原则
- 最少用户输入：拍照/上传 > 语音 > 点选 > 手动输入
- 渐进式精度：问卷兜底（Tier 3）→ 拍照AI解析（Tier 2）→ 自动报告（Tier 1），有高精度数据自动替代低精度
- 常模对标：每个维度的评分映射到同龄同性别人群百分位
- 菌群报告优先复用：已有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
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
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 常模数据结构
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 常模优先级
- 中国官方标准（BMI-for-age WS/T 586、学生体质健康标准、血压百分位）
- 菌群报告人群数据（已有 populationLevel → 平台积累后直接复用）
- 国际权威标准（WHO生长曲线、睡眠时长推荐）
- 平台自建常模（运营一段后基于用户数据建立自有百分位）
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百分位表是硬编码在代码中还是做成可配置表
- 商品能量触发：当前 ProductOrder 支付成功后未调用 awardEnergy，需在 ProductOrderService 中新增能量发放逻辑（见 8.2 改进方案）
- Dify 推荐落地：
product_dimension_config.difyDatasetId为空，需填充实际数据集 ID 并完成 DifySyncService 调用链路
10. 附录：7维与五维能量「身」的衔接
五维「身」能量值 = Σ(7维子维度分 × 权重)
其中权重可配置（默认等权 1/7）
衔接逻辑：
- 用户首次进入 → 引导上传菌群报告/拍照 → 自动生成7维+「身」能量
- 已有旧数据 → 历史迁移：菌群报告现有字段直接映射，缺的维度走问卷
- 实时联动 → 任一子维度更新 → 自动重算「身」能量（已有 EnergyService）