Rocky/DDUp

Files

Rocky b5b2eba6f8 docs: 添加 Vitals 健康管理应用设计文档

- 综合健康管理：运动、饮食、睡眠、体重
- CLI + Web 仪表盘双交互模式
- 支持佳明/咕咚数据导入
- 智能卡路里计算，支持拍照识别食物
- 周报/月报多格式导出（HTML/PDF/PNG）

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-17 22:11:13 +08:00

13 KiB

Raw Blame History

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 命令设计

# ===== 数据记录 =====
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分钟 → 视为重复
保留规则：优先保留数据更完整的记录
冲突提示：发现疑似重复时询问用户处理方式

卡路里管理

食物卡路里推算

文字输入：

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

图片输入：

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（食物识别）

下一步

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

13 KiB Raw Blame History Unescape Escape