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` - 数据模型
```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 应用 (5500+ 行)

**页面路由：**
| 路由 | 页面 |
|------|------|
| `/` | 首页仪表盘 |
| `/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/sleep` | 添加睡眠记录 |
| POST | `/api/weight` | 添加体重记录 |
| GET | `/api/config` | 获取用户配置 |
| POST | `/api/config` | 更新用户配置 |
| POST | `/api/login` | 用户登录 |
| POST | `/api/register` | 用户注册 |

**前端架构：**
- 纯原生 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)

-- 用户配置
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` | 5500+ | 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+ | 报告生成 |

---

## 最近更新

- **文字 AI 识别功能**：在饮食页面添加"文字AI识别"按钮，支持输入文字描述后自动识别卡路里
  - 前端：`web/app.py` (第 5041 行按钮，第 5166 行函数)
  - 后端：`/api/meal/recognize` 支持 `text` 参数