# Vitals 健康管理应用设计文档

> 生成日期: 2025-01-17

## 概述

Vitals 是一个本地优先的综合健康管理应用，整合运动、饮食、睡眠和体重数据，提供统一的仪表盘和定期报告。

**核心特点：**
- 数据本地存储，隐私有保障
- 支持从佳明手表、咕咚APP导入数据
- 命令行快速记录 + Web 可视化仪表盘
- 智能卡路里计算，支持拍照识别食物
- 周报/月报自动生成

---

## 整体架构

```
┌─────────────────────────────────────────────────────┐
│                    用户交互层                         │
├──────────────────────┬──────────────────────────────┤
│   CLI 命令行工具      │      Web 仪表盘 (本地)        │
│   - 快速记录数据      │      - 数据可视化             │
│   - 导入外部数据      │      - 趋势图表               │
│   - 生成报告         │      - 健康概览               │
└──────────────────────┴──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────┐
│                    核心服务层                         │
│   - 数据标准化处理                                    │
│   - 报告生成引擎                                      │
│   - 数据导入适配器 (Garmin / 咕咚 / CSV)              │
│   - 食物识别与卡路里计算                               │
└─────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────┐
│                    数据存储层                         │
│              SQLite 本地数据库                        │
│   - 运动记录  - 饮食记录  - 睡眠记录  - 体重记录       │
└─────────────────────────────────────────────────────┘
```

**设计原则：**
- 本地优先：所有数据存储在本地 SQLite，不依赖云服务
- 模块解耦：CLI、Web、数据处理各自独立
- 可扩展：通过适配器模式支持新的数据源

---

## 数据模型

### 运动记录 (exercise)
| 字段 | 类型 | 说明 |
|-----|------|-----|
| id | INTEGER | 主键 |
| date | DATE | 日期 |
| type | TEXT | 运动类型（跑步/游泳/力量...） |
| duration | INTEGER | 时长（分钟） |
| calories | INTEGER | 消耗卡路里 |
| distance | FLOAT | 距离（公里，可选） |
| heart_rate_avg | INTEGER | 平均心率（可选） |
| source | TEXT | 数据来源（手动/garmin/codoon） |
| raw_data | JSON | 原始导入数据 |
| notes | TEXT | 备注 |

### 饮食记录 (meal)
| 字段 | 类型 | 说明 |
|-----|------|-----|
| id | INTEGER | 主键 |
| date | DATE | 日期 |
| meal_type | TEXT | 餐次（早/中/晚/加餐） |
| description | TEXT | 食物描述 |
| calories | INTEGER | 总卡路里 |
| protein | FLOAT | 蛋白质（克，可选） |
| carbs | FLOAT | 碳水（克，可选） |
| fat | FLOAT | 脂肪（克，可选） |
| photo_path | TEXT | 照片路径（可选） |
| food_items | JSON | 解析后的食物条目 |

### 睡眠记录 (sleep)
| 字段 | 类型 | 说明 |
|-----|------|-----|
| id | INTEGER | 主键 |
| date | DATE | 日期 |
| bedtime | TIME | 入睡时间 |
| wake_time | TIME | 起床时间 |
| duration | FLOAT | 总时长（小时） |
| quality | INTEGER | 质量评分（1-5） |
| deep_sleep_mins | INTEGER | 深睡时长（可选） |
| source | TEXT | 数据来源 |
| notes | TEXT | 备注 |

### 体重记录 (weight)
| 字段 | 类型 | 说明 |
|-----|------|-----|
| id | INTEGER | 主键 |
| date | DATE | 日期 |
| weight_kg | FLOAT | 体重（公斤） |
| body_fat_pct | FLOAT | 体脂率（可选） |
| muscle_mass | FLOAT | 肌肉量（可选） |
| notes | TEXT | 备注 |

### 用户配置 (config)
| 字段 | 类型 | 说明 |
|-----|------|-----|
| age | INTEGER | 年龄 |
| gender | TEXT | 性别 |
| height | FLOAT | 身高（厘米） |
| weight | FLOAT | 当前体重 |
| activity_level | TEXT | 活动水平 |
| goal | TEXT | 目标（减重/维持/增肌） |
| bmr | INTEGER | 基础代谢（自动计算） |
| tdee | INTEGER | 日常总消耗（自动计算） |

---

## CLI 命令设计

```bash
# ===== 数据记录 =====
vitals log weight 72.5                           # 记录体重
vitals log weight 72.5 --fat 18.5                # 带体脂率
vitals log meal 早餐 "燕麦+鸡蛋+牛奶"             # 记录饮食
vitals log meal 午餐 --photo ~/lunch.jpg         # 拍照记录饮食
vitals log sleep 23:30 07:00 --quality 4         # 记录睡眠
vitals log exercise 跑步 30min --distance 5km    # 手动记录运动

# ===== 数据导入 =====
vitals import garmin ~/Downloads/export.zip      # 导入佳明数据
vitals import codoon ~/Downloads/codoon.json     # 导入咕咚数据
vitals import csv ~/data.csv --type weight       # 通用CSV导入

# ===== 数据查看 =====
vitals show today                                # 今日概览
vitals show week                                 # 本周汇总
vitals show weight --days 30                     # 最近30天体重趋势

# ===== 报告生成 =====
vitals report week                               # 生成周报（终端输出）
vitals report week --output report.html          # HTML导出
vitals report week --output report.md            # Markdown导出
vitals report week --output report.pdf           # PDF导出
vitals report week --output report.png           # 图片导出
vitals report month                              # 生成月报

# ===== 个人配置 =====
vitals config set --age 28 --gender male --height 175 --weight 72
vitals config set --activity-level moderate
vitals config set --goal lose

# ===== Web 仪表盘 =====
vitals dashboard                                 # 启动本地Web服务
```

**设计说明：**
- 日期默认今天，可用 `--date 2024-01-15` 覆盖
- 根据文件后缀自动选择导出格式
- 图片导出宽度 1080px，适配手机分享

---

## 数据导入适配器

### Garmin 佳明

**导入方式：**
- 从 Garmin Connect 网站导出数据包 (ZIP格式)
- 或通过 Garmin Connect API（需授权）

**支持数据：**
- 运动记录：跑步、骑行、游泳、力量训练等
- 睡眠数据：入睡/起床时间、深睡/浅睡时长
- 心率数据：静息心率、运动心率
- 体重数据：如使用 Garmin 体重秤

**文件解析：** ZIP 包内含 FIT 文件和 JSON 摘要，优先解析 JSON

### 咕咚 Codoon

**导入方式：** 咕咚APP → 设置 → 数据导出 → 下载 JSON/GPX 文件

**支持数据：**
- 运动记录：跑步、健走、骑行
- 运动轨迹：GPX 格式，可选保留
- 运动统计：配速、心率、卡路里

### 去重策略

- 同一天 + 同一运动类型 + 时间差 <5分钟 → 视为重复
- 保留规则：优先保留数据更完整的记录
- 冲突提示：发现疑似重复时询问用户处理方式

---

## 卡路里管理

### 食物卡路里推算

**文字输入：**
```bash
vitals log meal 午餐 "一碗米饭+红烧肉+炒青菜"
# 系统自动解析:
#   → 米饭(200g): 230卡
#   → 红烧肉(100g): 320卡
#   → 炒青菜(150g): 45卡
#   → 总计: 595卡
```

**图片输入：**
```bash
vitals log meal 午餐 --photo ~/lunch.jpg
# 系统识别:
#   → 检测到: 米饭、红烧排骨、西兰花
#   → 估算热量: 约 680 卡
```

**技术实现：**
- 内置常见食物数据库（约 2000+ 种中国常见食物）
- 支持自然语言描述，智能拆分食物条目
- 图片识别优先使用 Claude Vision API，备选本地模型
- 用户修正后记入个人食物库，提升准确度

**图片存储：**
- 原图保存至 `~/.vitals/photos/YYYY/MM/DD-meal_type.jpg`
- 可选压缩存储节省空间

### 每日卡路里收支

```
┌─────────────────────────────────────────────────┐
│  今日卡路里收支                                  │
├─────────────────────────────────────────────────┤
│  基础代谢 (BMR)           1,650 卡              │
│  + 日常活动消耗             330 卡              │
│  + 运动消耗                 420 卡              │
│  ─────────────────────────────────             │
│  = 今日总消耗             2,400 卡              │
│                                                 │
│  - 早餐                     470 卡              │
│  - 午餐                     595 卡              │
│  - 晚餐                     680 卡              │
│  ─────────────────────────────────             │
│  = 今日摄入               1,745 卡              │
│                                                 │
│  差值: -655 卡 (热量缺口，有助于减重)            │
└─────────────────────────────────────────────────┘
```

---

## Web 仪表盘

**技术选型：**
- 后端：FastAPI
- 前端：HTML + Chart.js
- 运行：`vitals dashboard` 启动，访问 http://localhost:8080

**页面结构：**
- 首页：今日概览 + 卡路里收支 + 趋势图表
- 运动页：运动历史列表 + 统计图表
- 饮食页：饮食记录日历视图 + 图片回顾
- 睡眠页：睡眠质量趋势
- 体重页：体重变化曲线 + 目标线
- 报告页：生成和下载周报/月报

---

## 报告生成

### 输出格式

| 格式 | 说明 |
|-----|------|
| 终端 | 彩色文本，直接查看 |
| HTML | 精美排版，浏览器打开 |
| Markdown | 方便存档 |
| PDF | 正式文档 |
| PNG | 适合分享到微信/朋友圈，宽度 1080px |

### 周报内容

- 本周概览：运动次数、总时长、消耗卡路里
- 睡眠统计：平均时长、质量评分
- 体重变化：起止体重、变化量
- 卡路里收支：平均每日摄入 vs 消耗
- 运动详情：每日运动记录
- 趋势洞察：与上周对比、进展评估

### 月报额外内容

- 月度目标完成情况
- 与上月同期对比
- 本月最佳/最差记录
- 长期趋势分析

---

## 项目结构

```
vitals/
├── pyproject.toml              # 项目配置
├── README.md
│
├── src/vitals/
│   ├── __init__.py
│   ├── cli.py                  # CLI 入口
│   │
│   ├── core/
│   │   ├── models.py           # 数据模型
│   │   ├── database.py         # SQLite 操作
│   │   ├── calories.py         # 卡路里计算
│   │   └── report.py           # 报告生成
│   │
│   ├── importers/
│   │   ├── base.py             # 适配器基类
│   │   ├── garmin.py           # 佳明导入
│   │   ├── codoon.py           # 咕咚导入
│   │   └── csv.py              # CSV导入
│   │
│   ├── vision/
│   │   ├── analyzer.py         # 食物识别
│   │   └── providers/
│   │       ├── claude.py       # Claude Vision
│   │       └── local.py        # 本地模型
│   │
│   ├── web/
│   │   ├── app.py              # FastAPI
│   │   ├── static/
│   │   └── templates/
│   │
│   └── data/
│       └── food_database.json  # 食物热量库
│
├── tests/
└── docs/
```

---

## 技术依赖

| 库 | 用途 |
|---|------|
| typer | CLI 框架 |
| sqlite3 | 数据库（内置） |
| fastapi | Web 框架 |
| uvicorn | ASGI 服务器 |
| chart.js | 前端图表 |
| weasyprint | PDF 导出 |
| playwright / html2image | 图片导出 |
| anthropic | Claude API（食物识别） |

---

## 下一步

1. 初始化项目结构
2. 实现核心数据模型和数据库
3. 实现 CLI 基础命令
4. 实现数据导入适配器
5. 实现卡路里计算和食物识别
6. 实现 Web 仪表盘
7. 实现报告生成