# 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` - 数据模型
```python
@dataclass
class Exercise    # 运动记录
class Meal        # 饮食记录
class Sleep       # 睡眠记录
class Weight      # 体重记录
class Reading     # 阅读记录
class User        # 用户
class UserConfig  # 用户配置
class Invite      # 邀请码
```

#### `database.py` - 数据库操作
- MySQL 连接池管理
- CRUD 操作封装
- 用户隔离支持

主要函数：
```python
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 代谢当量）

```python
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` - 分析器基类
```python
class FoodAnalyzer:
    def analyze(image_path) -> dict  # 分析食物图片

class ClaudeFoodAnalyzer:            # Claude Vision 实现
```

#### `providers/qwen.py` - 通义千问 VL
```python
class QwenVisionAnalyzer:
    def analyze_image(image_path)    # 图片识别
    def analyze_text(description)    # 文字识别 ← 新增功能
```

#### `providers/deepseek.py` - DeepSeek Vision
```python
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 测试 |

---

## 数据库设计

### 主要表结构

```sql
-- 用户表
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` 参数