DDUp/docs/CODEMAPS.md

Vitals 代码结构地图

项目概览

Vitals 是一个本地优先的综合健康管理应用，支持运动、饮食、睡眠、体重、阅读等多维度健康数据记录与分析。

vitals/
├── src/vitals/          # 主要源代码
│   ├── cli.py           # 命令行入口
│   ├── core/            # 核心业务逻辑
│   ├── vision/          # AI视觉识别模块
│   ├── web/             # Web应用 (FastAPI)
│   └── importers/       # 数据导入器
├── tests/               # 测试文件
├── scripts/             # 脚本工具
└── docs/                # 文档

---

核心模块详解

1. CLI 入口 (cli.py)

命令行界面，基于 Typer 构建。

命令	功能
vitals dashboard	启动 Web 仪表盘
vitals log	记录健康数据
vitals show	查看健康数据
vitals config	用户配置
vitals import	导入外部数据
vitals report	生成报告
vitals export	数据导出
vitals backup	数据备份

---

2. 核心业务 (core/)

models.py - 数据模型

@dataclass
class Exercise    # 运动记录
class Meal        # 饮食记录
class Sleep       # 睡眠记录
class Weight      # 体重记录
class Reading     # 阅读记录
class User        # 用户
class UserConfig  # 用户配置
class Invite      # 邀请码

database.py - 数据库操作

• MySQL 连接池管理
• CRUD 操作封装
• 用户隔离支持

主要函数：

init_db()                    # 初始化数据库表
get_connection()             # 获取数据库连接
add_meal() / get_meals()     # 饮食记录
add_exercise() / get_exercises()  # 运动记录
add_sleep() / get_sleeps()   # 睡眠记录
add_weight() / get_weights() # 体重记录
get_api_key() / set_api_key()  # API Key 管理

calories.py - 卡路里计算

• 内置 94 种常见中文食物数据库
• 智能食物描述解析（支持中文数字、多种分隔符）
• 运动卡路里估算（基于 MET 代谢当量）

estimate_meal_calories(description)      # 估算餐食卡路里
estimate_exercise_calories(type, mins)   # 估算运动消耗
parse_food_description(text)             # 解析食物描述

auth.py - 认证模块

• JWT Token 认证
• 密码哈希 (bcrypt)
• 邀请码机制

report.py - 报告生成

• 周报/月报生成
• PDF 导出 (WeasyPrint)
• 数据可视化

export.py - 数据导出

• JSON / CSV 格式导出
• 数据备份与恢复

backup.py - 备份模块

• 自动备份
• 增量备份支持

---

3. AI 视觉识别 (vision/)

analyzer.py - 分析器基类

class FoodAnalyzer:
    def analyze(image_path) -> dict  # 分析食物图片

class ClaudeFoodAnalyzer:            # Claude Vision 实现

providers/qwen.py - 通义千问 VL

class QwenVisionAnalyzer:
    def analyze_image(image_path)    # 图片识别
    def analyze_text(description)    # 文字识别 ← 新增功能

providers/deepseek.py - DeepSeek Vision

class DeepSeekVisionAnalyzer:
    def analyze_image(image_path)
    def analyze_text(description)

---

4. Web 应用 (web/)

app.py - FastAPI 应用 (9700+ 行)

页面路由：

路由	页面
/	首页仪表盘
/exercise	运动记录
/meal	饮食记录
/sleep	睡眠记录
/weight	体重记录
/reading	阅读记录
/report	健康报告
/settings	设置页面
/login	登录页面

API 端点：

方法	路由	功能
POST	/api/meal	添加饮食记录
GET	/api/meals	查询饮食记录
POST	/api/meal/recognize	AI 食物识别 (图片/文字)
GET	/api/meals/nutrition	营养统计
POST	/api/exercise	添加运动记录
GET	/api/exercises	查询运动记录
POST	/api/steps	同步步数（iOS 快捷指令调用）
GET	/api/steps	查询步数记录
GET	/api/steps/today	获取今日步数
POST	/api/sleep	添加睡眠记录
POST	/api/weight	添加体重记录
GET	/api/config	获取用户配置
POST	/api/config	更新用户配置
POST	/api/login	用户登录
POST	/api/register	用户注册
GET	/api/bmi/analysis	BMI 分析（体重/目标/达成预估）
GET	/api/nutrition/recommendations	营养建议（TDEE目标/缺口/配餐）
GET	/api/sleep/assessment	睡眠评估（状态/健康影响/建议）

前端架构：

• 纯原生 HTML/CSS/JavaScript
• Chart.js 图表库
• 响应式设计（PC/移动端适配）

---

5. 数据导入器 (importers/)

模块	功能
base.py	导入器基类
csv_importer.py	CSV 通用导入
garmin.py	Garmin 数据导入
codoon.py	咕咚数据导入

---

6. 测试 (tests/)

文件	测试内容
test_calories.py	卡路里计算测试
test_database.py	数据库操作测试
test_models.py	数据模型测试
test_web.py	Web API 测试
test_report.py	报告生成测试
test_export.py	导出功能测试
test_backup.py	备份功能测试
test_deepseek.py	DeepSeek API 测试

---

数据库设计

主要表结构

-- 用户表
user (id, username, password_hash, email, created_at)

-- 运动记录
exercise (id, user_id, date, exercise_type, duration, calories, distance, notes)

-- 饮食记录
meal (id, user_id, date, meal_type, description, calories, protein, carbs, fat, photo_path, food_items)

-- 睡眠记录
sleep (id, user_id, date, bedtime, wake_time, duration, quality, notes)

-- 体重记录
weight (id, user_id, date, weight, body_fat, notes)

-- 阅读记录
reading (id, user_id, date, book_title, pages, duration, notes)

-- 步数记录
steps (id, user_id, date, steps, distance, calories, source, synced_at)

-- 用户配置
user_config (id, user_id, height, weight, age, gender, activity_level, goal)

-- API Keys
api_keys (id, user_id, provider, api_key, created_at)

-- 邀请码
invite (id, code, created_by, used_by, used_at, expires_at)

---

技术栈

层级	技术
后端框架	FastAPI + Uvicorn
数据库	MySQL 8
CLI	Typer + Rich
AI 识别	Qwen VL / DeepSeek / Claude
PDF 生成	WeasyPrint
前端	原生 HTML/CSS/JS + Chart.js
认证	JWT + bcrypt

---

关键文件行数统计

文件	行数	说明
web/app.py	9700+	Web 应用主体
core/database.py	800+	数据库操作
core/calories.py	333	卡路里计算
core/models.py	327	数据模型
vision/providers/qwen.py	185	通义千问识别
vision/providers/deepseek.py	176	DeepSeek 识别
core/report.py	300+	报告生成

---

最近更新

• 健康模块智能分析 (2026-01-27)：运动、饮食、睡眠三大模块新增智能分析功能

  • BMI 健康分析 (/exercise 页面)
    • API：/api/bmi/analysis 返回 BMI 状态、目标体重、达成预估
    • 前端：BMI 刻度条（偏瘦/正常/偏重/肥胖）+ 目标达成预估卡片
    • 计算：基于 TDEE - 摄入 + 运动 的每日净消耗
  • 营养建议系统 (/meal 页面)
    • API：/api/nutrition/recommendations 返回 TDEE 目标、缺口分析、配餐建议
    • 前端：营养进度条（热量/蛋白质/碳水/脂肪）+ 配餐建议卡片
    • 图表：7 天趋势图增加建议摄入参考线
  • 睡眠健康评估 (/sleep 页面)
    • API：/api/sleep/assessment 返回睡眠状态、健康影响、建议
    • 前端：睡眠刻度条 + 警告/益处卡片（4 类健康影响）
    • 图表：趋势图动态着色（理想区间绿色标记）

• Apple Health 步数同步：支持通过 iOS 快捷指令同步 Apple Health 步数数据

  • 数据库：新增 steps 表存储每日步数
  • API：/api/steps (POST 同步, GET 查询), /api/steps/today (今日步数)
  • 前端：运动页面显示今日步数卡片，设置页面提供 iOS 快捷指令配置说明

• 文字 AI 识别功能：在饮食页面添加"文字AI识别"按钮，支持输入文字描述后自动识别卡路里

  • 前端：web/app.py
  • 后端：/api/meal/recognize 支持 text 参数