docs: 更新 README 添加健康分析模块说明

- 添加 3 个新 API 端点文档 - 更新已完成功能列表 - 添加 2026-01-27 更新日志 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 16:47:06 +08:00
parent f120bc16f5
commit a279e7b343
1 changed files with 93 additions and 10 deletions
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@

 ### 健康数据追踪
 - **运动记录** - 跑步、游泳、骑行、力量训练等，支持时长、距离、心率记录
- **饮食记录** - 三餐及加餐，支持卡路里、蛋白质、碳水、脂肪追踪，AI 智能识别食物
+- **饮食记录** - 三餐及加餐，支持卡路里、蛋白质、碳水、脂肪追踪，AI 智能识别食物图片和文字
 - **睡眠记录** - 入睡/起床时间、睡眠时长、睡眠质量评分
 - **体重记录** - 体重、体脂率、肌肉量追踪

@@ -20,11 +20,12 @@
 - **用户档案** - 姓名、性别、身高、体重、年龄
 - **BMI 计算** - 自动计算并显示健康状态（偏瘦/正常/偏胖/肥胖）
 - **用户切换** - 支持多用户数据隔离
+- **用户配置隔离** - 每个用户独立的配置数据
 - **数据管理** - 按日期范围或数据类型清除数据
 - **JWT 认证** - HTTPOnly Cookie + Authorization Header 混合认证
 - **记住我** - 可选 1 天或 30 天登录有效期
 - **邀请码注册** - 通过邀请码控制用户注册
- **管理员面板** - 用户管理、邀请码管理
+- **管理员面板** - 用户管理、邀请码管理、API Key 管理

 ### 数据管理
 - **数据导出** - 支持 JSON/CSV 格式导出
@@ -37,10 +38,13 @@
 - **系统通知** - 支持 macOS/Linux/Windows 系统通知

 ### 数据可视化
- **今日概览** - 运动、饮食、睡眠、体重、阅读汇总
+- **今日概览** - 运动、饮食、睡眠、体重、阅读汇总，深色科技风格仪表盘
 - **本周报告** - 趋势分析和统计图表
 - **详细报告** - 各项数据的深度分析

+### Apple Health 集成
+- **步数同步** - 自动同步 Apple Health 步数数据到首页仪表盘
+
 ## 快速开始

 ### Docker 部署（推荐）
@@ -118,6 +122,10 @@ uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080
 | `/api/admin/invites` | GET | 获取邀请码列表 |
 | `/api/admin/invites` | POST | 创建邀请码 |
 | `/api/admin/invites/{id}` | DELETE | 删除邀请码 |
+| `/api/admin/api-keys` | GET | 获取所有 API Key 状态 |
+| `/api/admin/api-keys/{provider}` | GET | 获取指定 API Key（明文） |
+| `/api/admin/api-keys/{provider}` | PUT | 设置 API Key |
+| `/api/admin/api-keys/{provider}` | DELETE | 删除 API Key |

 ### 用户管理

@@ -146,6 +154,7 @@ uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080
 | `/api/exercise` | POST | 添加运动记录 |
 | `/api/exercise/{id}` | DELETE | 删除单条运动记录 |
 | `/api/exercises/stats` | GET | 运动统计 |
+| `/api/bmi/analysis` | GET | BMI 分析（当前/目标体重、达成预估） |

 ### 饮食

@@ -156,6 +165,7 @@ uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080
 | `/api/meal/{id}` | DELETE | 删除单条饮食记录 |
 | `/api/meals/nutrition` | GET | 营养统计 |
 | `/api/food/recognize` | POST | AI 识别食物 |
+| `/api/nutrition/recommendations` | GET | 营养建议（TDEE目标、缺口分析、配餐建议） |

 ### 睡眠

@@ -164,6 +174,7 @@ uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080
 | `/api/sleep` | GET | 获取睡眠记录 |
 | `/api/sleep` | POST | 添加睡眠记录 |
 | `/api/sleep/{id}` | DELETE | 删除单条睡眠记录 |
+| `/api/sleep/assessment` | GET | 睡眠评估（状态分析、健康影响、建议） |

 ### 体重

@@ -288,8 +299,11 @@ pip install -e .
 | `MYSQL_DATABASE` | 是 | MySQL 数据库名（默认 `vitals`） |
 | `MYSQL_ROOT_PASSWORD` | 是 | MySQL root 密码（Docker 部署时需要） |
 | `JWT_SECRET` | 是 | JWT 签名密钥（建议用 `openssl rand -hex 32` 生成） |
-| `DASHSCOPE_API_KEY` | 否 | 阿里云通义千问 API Key，用于 AI 食物识别 |
-| `DEEPSEEK_API_KEY` | 否 | DeepSeek API Key，用于 AI 食物识别 |
+| `DASHSCOPE_API_KEY` | 否 | 阿里云通义千问 API Key（可通过 Web 管理界面配置） |
+| `DEEPSEEK_API_KEY` | 否 | DeepSeek API Key（可通过 Web 管理界面配置） |
+| `ANTHROPIC_API_KEY` | 否 | Anthropic API Key（可通过 Web 管理界面配置） |
+
+> **API Key 管理**: AI 相关的 API Key 支持通过 Web 管理界面配置（管理员设置页），数据库配置优先于环境变量。

 **默认管理员账号**: `admin` / `admin123`（请在首次登录后修改）

@@ -304,6 +318,21 @@ pip install -e .

 ## 设计系统

+### 首页仪表盘（深色科技风格）
+
+| 元素 | 值 |
+|------|------|
+| Background | `#0a0a0f` (深空黑) |
+| Card Background | `rgba(255,255,255,0.03)` (玻璃态) |
+| Primary Accent | `#00d4ff` (科技青) |
+| Secondary Accent | `#7c3aed` (霓虹紫) |
+| Text Primary | `#ffffff` |
+| Text Secondary | `rgba(255,255,255,0.6)` |
+| Border | `rgba(255,255,255,0.1)` |
+| Glow Effect | `0 0 20px rgba(0,212,255,0.3)` |
+
+### 其他页面
+
 | 元素 | 值 |
 |------|------|
 | Primary | `#3B82F6` |
@@ -322,12 +351,12 @@ vitals/
 ├── src/vitals/
 │   ├── core/
 │   │   ├── models.py      # 数据模型（User, Invite, Exercise, Meal...）
-│   │   ├── database.py    # MySQL 数据库操作（连接池管理）
+│   │   ├── database.py    # MySQL 数据库操作（连接池管理、API Key 管理）
 │   │   ├── auth.py        # JWT 认证、密码哈希
 │   │   ├── backup.py      # 数据库备份
 │   │   ├── export.py      # 数据导出导入
 │   │   ├── report.py      # 健康报告生成
-│   │   └── calories.py    # 卡路里计算
+│   │   └── calories.py    # 卡路里计算（本地数据库 + AI 智能识别）
 │   ├── vision/
 │   │   ├── analyzer.py    # 食物识别分析器
 │   │   └── providers/     # AI 提供商（通义千问、DeepSeek）
@@ -375,8 +404,9 @@ vitals/
 - [x] **JWT 认证** - 服务端认证 + Cookie，支持 1 天/30 天过期
 - [x] **密码安全** - bcrypt 哈希加密
 - [x] **多用户支持** - 用户档案、数据隔离、用户切换
+- [x] **用户配置隔离** - 每个用户独立的配置数据（身高、体重、目标等）
 - [x] **邀请码注册** - 控制用户注册，支持有效期设置
- [x] **管理员面板** - 用户管理（启用/禁用/删除）、邀请码管理
+- [x] **管理员面板** - 用户管理（启用/禁用/删除）、邀请码管理、API Key 管理

 #### Web 应用
 - [x] **完整页面** - 登录、注册、管理员、首页、运动、饮食、睡眠、体重、阅读、报告、设置
@@ -392,8 +422,10 @@ vitals/
 - [x] **数据清理** - 按日期范围或数据类型删除，支持预览

 #### AI 集成
- [x] **食物识别** - 阿里通义千问(Qwen VL)、DeepSeek Vision、Claude Vision
+- [x] **食物图片识别** - 阿里通义千问(Qwen VL)、DeepSeek Vision、Claude Vision
+- [x] **食物文字智能识别** - 本地数据库优先匹配，识别失败自动调用 AI 标准化
 - [x] **卡路里估算** - 基于食物描述的营养值计算
+- [x] **API Key 管理** - Web 界面管理 AI API Key，数据库存储优先于环境变量

 #### 数据导入器
 - [x] **Garmin 导入** - 从 Garmin 设备导入运动数据
@@ -405,6 +437,9 @@ vitals/
 - [x] **本周汇总** - 7 天趋势分析
 - [x] **阅读统计** - 时长趋势、心情分布、书库展示
 - [x] **图表展示** - 运动趋势、营养统计、睡眠热力图
+- [x] **BMI 健康分析** - BMI 刻度条、目标体重达成预估
+- [x] **营养建议系统** - TDEE 目标计算、缺口分析、配餐建议
+- [x] **睡眠健康评估** - 状态评估、健康影响警告/益处提示

 #### CLI 工具
 - [x] **数据记录** - `vitals log` 记录各类数据
@@ -444,7 +479,7 @@ vitals/
 - [ ] **云同步** - 跨设备数据同步
 - [ ] **社交功能** - 数据分享、好友挑战
 - [ ] **智能建议** - 基于数据的个性化健康建议
- [ ] **Apple Health 集成** - 与 Apple Health 数据同步
+- [x] **Apple Health 集成** - 步数数据同步到首页仪表盘
 - [ ] **深色模式** - UI 深色主题支持

 ### 已知问题 🐛
@@ -485,6 +520,54 @@ VITALS_DB_PATH=/path/to/old/vitals.db python scripts/migrate_sqlite_to_mysql.py

 ## 更新日志

+### 2026-01-27
+
+#### 📊 健康模块智能分析增强
+- **BMI 健康分析** - 运动页面新增 BMI 分析卡片
+  - BMI 状态刻度条（偏瘦/正常/偏重/肥胖）
+  - 目标体重设定与达成预估
+  - 基于 TDEE-摄入+运动 的智能计算
+- **营养建议系统** - 饮食页面新增营养状况卡片
+  - 每日营养进度条（热量/蛋白质/碳水/脂肪）
+  - 基于 TDEE 的个性化目标计算
+  - 营养缺口分析与配餐建议
+  - 7 天趋势图增加建议摄入参考线
+- **睡眠健康评估** - 睡眠页面新增健康评估卡片
+  - 睡眠状态刻度条（偏少/不足/理想/过多）
+  - 睡眠不足警告卡片（认知/身体/情绪/运动影响）
+  - 睡眠充足益处卡片（健康益处提示）
+  - 趋势图动态着色（理想区间绿色标记）
+
+### 2026-01-26
+
+#### 🎨 首页仪表盘深色科技风格改造
+- **全新视觉风格** - 深空黑背景 + 玻璃态卡片 + 霓虹光效
+- **科技感配色** - 科技青(#00d4ff) + 霓虹紫(#7c3aed) 双色调
+- **动态效果** - 卡片悬停光晕、数据呼吸动画、渐变边框
+- **信息密度优化** - 紧凑布局，一屏展示更多健康数据
+
+#### 🍎 Apple Health 步数同步
+- **步数数据集成** - 首页仪表盘展示 Apple Health 同步的步数
+- **自动同步** - 支持从 Apple Health 导入每日步数数据
+
+### 2026-01-24
+
+#### 🔑 API Key 数据库管理
+- **集中存储** - AI API Key（通义千问、DeepSeek、Anthropic）存储在数据库
+- **Web 管理界面** - 管理员可在设置页面配置 API Key
+- **优先级机制** - 数据库配置优先于环境变量
+- **安全显示** - API Key 列表仅显示掩码，支持查看/编辑/删除
+
+#### 👤 用户配置隔离
+- **Config 表迁移** - 添加 user_id 字段，复合主键 (user_id, key)
+- **数据归属** - 现有配置数据归属 ID=1 用户
+- **完全隔离** - 每个用户独立的配置数据，新用户不再看到其他用户信息
+
+#### 🍽️ 食物文字智能识别
+- **本地优先** - 使用内置食物数据库快速匹配（~100 种常见食物）
+- **AI 增强** - 本地无法识别时自动调用通义千问 AI 标准化食物描述
+- **智能回退** - 无 API Key 时仅使用本地估算，不影响基本功能
+
 ### 2026-01-23

 #### 🗄️ MySQL 数据库迁移