diff --git a/docs/plans/2026-01-27-health-module-enhancement-design.md b/docs/plans/2026-01-27-health-module-enhancement-design.md new file mode 100644 index 0000000..4e2eef8 --- /dev/null +++ b/docs/plans/2026-01-27-health-module-enhancement-design.md @@ -0,0 +1,258 @@ +# 健康模块增强设计方案 + +> 日期: 2026-01-27 +> 状态: 待实现 + +## 概述 + +本设计方案涵盖三个健康模块的功能增强： + +1. **运动模块** - BMI 分析与目标达成预估 +2. **饮食模块** - 营养建议区间与配餐推荐 +3. **睡眠模块** - 睡眠预警与健康提示 + +## 设计决策 + +| 决策点 | 选择 | 理由 | +|-------|------|------| +| 目标设定方式 | 目标体重 | 用户更容易理解，系统反推 BMI | +| 达成预估计算 | 综合运动+饮食数据 | TDEE - 摄入 + 运动消耗，最精准 | +| 营养建议基准 | 基于用户 TDEE 动态计算 | 个性化推荐 | +| 睡眠预警阈值 | 固定阈值 | < 6h 不足，7-9h 理想 | +| 预警展示方式 | 卡片式提示 | 颜色区分状态，不打扰用户 | +| 配餐推荐范围 | 简单文字建议 | 根据营养缺口给出提示 | + +## 设计风格 + +基于现有深色科技风格 + Dark Mode (OLED) 设计语言： + +- **背景**: 深色渐变 `#0A0E27` → `#121212` +- **卡片**: `rgba(255,255,255,0.05)` 玻璃质感 + 微发光边框 +- **字体**: Fira Code / Fira Sans（数据仪表盘风格） +- **强调色**: + - 健康绿 `#10B981` + - 警告橙 `#F59E0B` + - 危险红 `#EF4444` + - 信息蓝 `#3B82F6` + +--- + +## 一、运动模块 - BMI 分析卡片 + +### 位置 + +运动概览页面统计卡片区域下方 + +### UI 结构 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ BMI 健康分析 [设置目标 →] │ +├──────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ 当前体重 │ │ 当前 BMI │ │ BMI 状态 │ │ +│ │ 75.0 │ │ 24.5 │ │ ● 偏重 │ │ +│ │ kg │ │ │ │ (24-27.9) │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ +│ ─────────────── BMI 刻度条 ─────────────── │ +│ [偏瘦 ][正常 ][偏重 ▲][肥胖 ] │ +│ <18.5 18.5-24 24-28 >28 │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ 目标达成预估 │ │ +│ │ ───────────────────────────────────────────────── │ │ +│ │ 目标体重: 70.0 kg → 目标 BMI: 22.9 (正常) │ │ +│ │ 距离目标: -5.0 kg │ │ +│ │ │ │ +│ │ 预估达成: 约 50 天 │ │ +│ │ ──────────────────────────────────────────── │ │ +│ │ 计算依据: 近30天平均每日净消耗 350 卡 │ │ +│ │ (TDEE 1800 - 摄入 1650 + 运动 200 = 350 卡/天) │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ 提示: 健康减重建议每周 0.5-1 kg │ +└──────────────────────────────────────────────────────────────┘ +``` + +### BMI 状态颜色映射 + +| BMI 范围 | 状态 | 颜色 | CSS Class | +|---------|------|------|-----------| +| < 18.5 | 偏瘦 | 蓝色 | `text-blue-400` / `#60A5FA` | +| 18.5-24 | 正常 | 绿色 | `text-emerald-400` / `#34D399` | +| 24-28 | 偏重 | 橙色 | `text-amber-400` / `#FBBF24` | +| > 28 | 肥胖 | 红色 | `text-red-400` / `#F87171` | + +### 计算逻辑 + +```python +# 每日净消耗 +daily_deficit = TDEE - daily_intake + exercise_calories + +# 预估天数 (7700 卡 ≈ 1 kg 脂肪) +estimated_days = (current_weight - target_weight) * 7700 / avg_daily_deficit +``` + +### 数据不足降级显示 + +当缺少必要数据时，显示引导用户完善信息的提示卡片。 + +--- + +## 二、饮食模块 - 营养建议区间 + +### 增强点 + +1. 营养成分分布图 - 添加 TDEE 推荐比例参考环 +2. 餐次分布图 - 添加理想餐次比例参考 +3. 近7天摄入趋势 - 添加每日建议摄入参考线 +4. 新增营养差距卡片 - 显示今日缺口 + 配餐建议 + +### 1. 营养成分分布图（双环饼图） + +``` +外环: 用户实际摄入比例（实心） +内环: TDEE 计算的建议比例（虚线边框） + +偏差提示: +- 绿色 = 达标 +- 橙色 = 偏低/偏高 +``` + +### 2. 餐次分布建议比例 + +| 餐次 | 建议比例 | +|-----|---------| +| 早餐 | 25-30% | +| 午餐 | 35-40% | +| 晚餐 | 25-30% | +| 加餐 | 0-10% | + +### 3. 摄入趋势图参考线 + +``` +虚线: 建议摄入上限（TDEE） +实线: 目标摄入（根据减重/增重目标调整） +绿色区域: 健康摄入区间 +``` + +### 4. 营养差距与配餐建议卡片 + +``` +┌────────────────────────────────────────────────────────────┐ +│ 今日营养状况 │ +├────────────────────────────────────────────────────────────┤ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 热量 │ │ 蛋白质 │ │ 碳水 │ │ 脂肪 │ │ +│ │ 1420 │ │ 45g │ │ 180g │ │ 52g │ │ +│ │ /1800卡 │ │ /90g │ │ /200g │ │ /60g │ │ +│ │ ████░░ │ │ ███░░░ │ │ █████░ │ │ █████░ │ │ +│ │ 79% │ │ 50% │ │ 90% │ │ 87% │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ 晚餐建议 │ │ +│ │ 蛋白质缺口较大 (-45g)，建议晚餐增加: │ │ +│ │ • 鸡胸肉 150g (+46g 蛋白质, 165 卡) │ │ +│ │ • 或 鸡蛋 3 个 (+18g 蛋白质, 210 卡) │ │ +│ │ • 或 豆腐 200g (+16g 蛋白质, 160 卡) │ │ +│ └──────────────────────────────────────────────────────┘ │ +└────────────────────────────────────────────────────────────┘ +``` + +### TDEE 营养素计算公式 + +| 营养素 | 建议比例 | 计算方式 | +|-------|---------|---------| +| 蛋白质 | 20-30% | TDEE × 0.25 ÷ 4 (每克4卡) | +| 碳水 | 45-55% | TDEE × 0.50 ÷ 4 (每克4卡) | +| 脂肪 | 20-30% | TDEE × 0.25 ÷ 9 (每克9卡) | + +--- + +## 三、睡眠模块 - 预警与提示 + +### 增强点 + +1. 睡眠状态评估卡片 - 根据近期睡眠时长显示健康状态 +2. 睡眠不足警告 - 红色警示卡片，列出对身体的危害 +3. 睡眠充足益处 - 绿色激励卡片，列出健康益处 +4. 趋势图增强 - 添加健康睡眠区间参考带 + +### 状态阈值定义 + +| 睡眠时长 | 状态 | 颜色 | 显示卡片 | +|---------|------|------|---------| +| < 5h | 严重不足 | `#EF4444` 红色 | 警告卡片（强调） | +| 5-6h | 不足 | `#F59E0B` 橙色 | 警告卡片 | +| 7-9h | 理想 | `#10B981` 绿色 | 益处卡片 | +| > 9h | 过多 | `#3B82F6` 蓝色 | 提示卡片 | + +### 1. 睡眠状态评估卡片 + +位于统计卡片下方，显示： +- 近 7 天平均睡眠时长 +- BMI 式刻度条（偏少/不足/理想/过多） +- 当前状态与距理想的差距 + +### 2. 睡眠不足警告卡片 + +背景色: `#7F1D1D20`（深红半透明） + +危害分类： +- **认知能力**: 注意力下降 40%、记忆力减退、决策能力受损 +- **身体健康**: 免疫力下降、肥胖风险增加 33%、心血管疾病风险上升 +- **情绪状态**: 焦虑抑郁风险增加、情绪波动大、压力耐受力降低 +- **运动表现**: 反应速度下降、肌肉恢复减慢、受伤风险增加 + +### 3. 睡眠充足益处卡片 + +背景色: `#065F4620`（深绿半透明） + +益处分类： +- **认知提升**: 记忆巩固增强、专注力提高、创造力活跃 +- **身体修复**: 免疫系统强化、肌肉组织修复、激素分泌平衡 +- **情绪稳定**: 情绪调节能力增强、压力抵抗力提升、心态积极 +- **运动增益**: 运动表现提升 15%、恢复速度加快、耐力增强 + +### 4. 趋势图增强 + +- 绿色半透明带：7-9 小时理想睡眠区间 +- 理想区间内的点用绿色，区间外用橙色/红色 +- 底部增加统计：理想天数/不足天数占比 + +--- + +## 技术实现要点 + +### 前端修改文件 + +- `src/vitals/web/app.py` - 运动/饮食/睡眠页面 HTML 模板 + +### 后端新增 API + +| API | 功能 | +|-----|------| +| `GET /api/bmi/analysis` | 获取 BMI 分析数据 | +| `GET /api/nutrition/recommendations` | 获取营养建议 | +| `GET /api/sleep/assessment` | 获取睡眠评估 | + +### 数据依赖 + +- 用户配置：身高、体重、年龄、性别、活动水平、目标体重 +- 运动记录：近 30 天运动消耗 +- 饮食记录：近 30 天摄入数据 +- 睡眠记录：近 7/30 天睡眠时长 + +--- + +## 预交付检查清单 + +- [ ] 无 emoji 作为图标（使用 SVG: Heroicons/Lucide） +- [ ] 所有可点击元素添加 `cursor-pointer` +- [ ] Hover 状态使用平滑过渡（150-300ms） +- [ ] 深色模式文字对比度 4.5:1 以上 +- [ ] 键盘导航焦点状态可见 +- [ ] 响应式适配：375px, 768px, 1024px, 1440px