Rocky/DDUp

Files

liweiliang0905@gmail.com a279e7b343 docs: 更新 README 添加健康分析模块说明

- 添加 3 个新 API 端点文档
- 更新已完成功能列表
- 添加 2026-01-27 更新日志

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

2026-01-27 16:47:06 +08:00

22 KiB

Raw Blame History

Vitals

本地优先的综合健康管理应用，整合运动、饮食、睡眠、体重和阅读数据。

功能特性

健康数据追踪

运动记录 - 跑步、游泳、骑行、力量训练等，支持时长、距离、心率记录
饮食记录 - 三餐及加餐，支持卡路里、蛋白质、碳水、脂肪追踪，AI 智能识别食物图片和文字
睡眠记录 - 入睡/起床时间、睡眠时长、睡眠质量评分
体重记录 - 体重、体脂率、肌肉量追踪

阅读习惯追踪

阅读记录 - 时长、书名、作者、封面（自动获取）、读后感
心情记录 - 5 种表情选择（😄😊😐😔😢）
我的书库 - 书籍封面网格展示，按书名归类
统计图表 - 阅读时长趋势、心情分布饼图

多用户与认证

用户档案 - 姓名、性别、身高、体重、年龄
BMI 计算 - 自动计算并显示健康状态（偏瘦/正常/偏胖/肥胖）
用户切换 - 支持多用户数据隔离
用户配置隔离 - 每个用户独立的配置数据
数据管理 - 按日期范围或数据类型清除数据
JWT 认证 - HTTPOnly Cookie + Authorization Header 混合认证
记住我 - 可选 1 天或 30 天登录有效期
邀请码注册 - 通过邀请码控制用户注册
管理员面板 - 用户管理、邀请码管理、API Key 管理

数据管理

数据导出 - 支持 JSON/CSV 格式导出
数据导入 - 从 JSON 文件导入数据
自动备份 - 数据写入后自动备份
备份恢复 - 支持从备份文件恢复数据

提醒功能

定时提醒 - 体重、睡眠、运动、饮食提醒
系统通知 - 支持 macOS/Linux/Windows 系统通知

数据可视化

今日概览 - 运动、饮食、睡眠、体重、阅读汇总，深色科技风格仪表盘
本周报告 - 趋势分析和统计图表
详细报告 - 各项数据的深度分析

Apple Health 集成

步数同步 - 自动同步 Apple Health 步数数据到首页仪表盘

快速开始

Docker 部署（推荐）

# 1. 复制环境变量模板
cp .env.example .env

# 2. 编辑 .env 文件，设置 JWT 密钥
vim .env

# 3. 启动服务
docker-compose up -d

# 4. 访问 http://localhost:8888
# 默认管理员账号: admin / admin123

本地开发

# 安装依赖
pip install -e .

# 设置 MySQL 环境变量
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=vitals
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=vitals

# 设置 JWT 密钥
export JWT_SECRET=$(openssl rand -hex 32)

# 启动服务
uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080

访问 http://localhost:8080 即可使用 Web 界面。

注意: 默认管理员账号为 admin / admin123，请在首次登录后及时修改密码。

页面导航

/ - 首页（今日概览）
/login - 登录页面
/register - 注册页面（需邀请码）
/admin - 管理员面板
/exercise - 运动记录
/meal - 饮食记录
/sleep - 睡眠记录
/weight - 体重记录
/reading - 阅读记录
/report - 健康报告
/settings - 设置页面

API 接口

认证

端点	方法	说明
`/api/auth/login`	POST	用户登录，返回 JWT Token + 设置 Cookie
`/api/auth/register`	POST	用户注册（需邀请码）
`/api/auth/logout`	POST	用户登出，清除 Cookie
`/api/auth/me`	GET	获取当前用户信息

管理员

端点	方法	说明
`/api/admin/users`	GET	获取所有用户列表
`/api/admin/users/{id}/disable`	POST	禁用用户
`/api/admin/users/{id}/enable`	POST	启用用户
`/api/admin/users/{id}`	DELETE	删除用户
`/api/admin/invites`	GET	获取邀请码列表
`/api/admin/invites`	POST	创建邀请码
`/api/admin/invites/{id}`	DELETE	删除邀请码
`/api/admin/api-keys`	GET	获取所有 API Key 状态
`/api/admin/api-keys/{provider}`	GET	获取指定 API Key（明文）
`/api/admin/api-keys/{provider}`	PUT	设置 API Key
`/api/admin/api-keys/{provider}`	DELETE	删除 API Key

用户管理

端点	方法	说明
`/api/users`	GET	获取所有用户
`/api/users`	POST	创建新用户
`/api/users/active`	GET	获取当前活跃用户
`/api/users/{id}`	GET	获取指定用户
`/api/users/{id}`	PUT	更新用户信息
`/api/users/{id}`	DELETE	删除用户
`/api/users/{id}/activate`	POST	设置活跃用户

数据管理

端点	方法	说明
`/api/data/preview-delete`	POST	预览删除数量
`/api/data/clear`	POST	执行数据删除

运动

端点	方法	说明
`/api/exercises`	GET	获取运动记录
`/api/exercise`	POST	添加运动记录
`/api/exercise/{id}`	DELETE	删除单条运动记录
`/api/exercises/stats`	GET	运动统计
`/api/bmi/analysis`	GET	BMI 分析（当前/目标体重、达成预估）

饮食

端点	方法	说明
`/api/meals`	GET	获取饮食记录
`/api/meal`	POST	添加饮食记录
`/api/meal/{id}`	DELETE	删除单条饮食记录
`/api/meals/nutrition`	GET	营养统计
`/api/food/recognize`	POST	AI 识别食物
`/api/nutrition/recommendations`	GET	营养建议（TDEE目标、缺口分析、配餐建议）

睡眠

端点	方法	说明
`/api/sleep`	GET	获取睡眠记录
`/api/sleep`	POST	添加睡眠记录
`/api/sleep/{id}`	DELETE	删除单条睡眠记录
`/api/sleep/assessment`	GET	睡眠评估（状态分析、健康影响、建议）

体重

端点	方法	说明
`/api/weight`	GET	获取体重记录
`/api/weight`	POST	添加体重记录
`/api/weight/{id}`	DELETE	删除单条体重记录

阅读

端点	方法	说明
`/api/reading`	GET	获取阅读记录（支持 ?days=N）
`/api/reading`	POST	添加阅读记录
`/api/reading/{id}`	DELETE	删除阅读记录
`/api/reading/today`	GET	今日阅读摘要
`/api/reading/stats`	GET	阅读统计
`/api/books/search`	GET	搜索书籍封面（OpenLibrary）

汇总

端点	方法	说明
`/api/today`	GET	今日概览
`/api/week`	GET	本周汇总

命令行使用

数据记录

# 记录体重
vitals log weight 72.5 --fat 18.5

# 记录饮食
vitals log meal 午餐 "燕麦+鸡蛋+牛奶"

# 记录睡眠
vitals log sleep 23:30 07:00 --quality 4

# 记录运动
vitals log exercise 跑步 30min --distance 5km

数据查看

# 查看今日概览
vitals show today

# 查看本周汇总
vitals show week

# 设置个人信息
vitals config set --age 28 --gender male --height 175 --weight 72

数据导出与导入

# 导出所有数据为 JSON
vitals export json ~/backup.json

# 导出运动数据为 CSV
vitals export csv --type exercise ~/exercise.csv

# 从 JSON 导入数据
vitals export import-json ~/backup.json

数据库备份

# 创建备份
vitals backup create

# 列出所有备份
vitals backup list

# 恢复备份
vitals backup restore ~/.vitals/backups/vitals_20260122_120000.db

# 清理旧备份（保留最近 7 天）
vitals backup cleanup --days 7

定时提醒

# 设置体重提醒（每天 07:00）
vitals remind set weight --time 07:00

# 列出所有提醒
vitals remind list

# 禁用/启用提醒
vitals remind disable weight
vitals remind enable weight

# 测试系统通知
vitals remind test

# 设置定时任务（macOS）
vitals remind setup

安装

pip install -e .

环境变量

变量	必填	说明
`MYSQL_HOST`	是	MySQL 服务器地址（默认 `localhost`）
`MYSQL_PORT`	否	MySQL 端口（默认 `3306`）
`MYSQL_USER`	是	MySQL 用户名
`MYSQL_PASSWORD`	是	MySQL 密码
`MYSQL_DATABASE`	是	MySQL 数据库名（默认 `vitals`）
`MYSQL_ROOT_PASSWORD`	是	MySQL root 密码（Docker 部署时需要）
`JWT_SECRET`	是	JWT 签名密钥（建议用 `openssl rand -hex 32` 生成）
`DASHSCOPE_API_KEY`	否	阿里云通义千问 API Key（可通过 Web 管理界面配置）
`DEEPSEEK_API_KEY`	否	DeepSeek API Key（可通过 Web 管理界面配置）
`ANTHROPIC_API_KEY`	否	Anthropic API Key（可通过 Web 管理界面配置）

API Key 管理: AI 相关的 API Key 支持通过 Web 管理界面配置（管理员设置页），数据库配置优先于环境变量。

默认管理员账号: admin / admin123（请在首次登录后修改）

技术栈

后端: Python, FastAPI, MySQL 8.0
前端: HTML, CSS, JavaScript, Chart.js
认证: JWT (PyJWT), bcrypt
部署: Docker, Docker Compose
AI: 阿里云通义千问 / DeepSeek (食物识别)
外部 API: OpenLibrary (书籍封面搜索)

设计系统

首页仪表盘（深色科技风格）

元素	值
Background	`#0a0a0f` (深空黑)
Card Background	`rgba(255,255,255,0.03)` (玻璃态)
Primary Accent	`#00d4ff` (科技青)
Secondary Accent	`#7c3aed` (霓虹紫)
Text Primary	`#ffffff`
Text Secondary	`rgba(255,255,255,0.6)`
Border	`rgba(255,255,255,0.1)`
Glow Effect	`0 0 20px rgba(0,212,255,0.3)`

其他页面

元素	值
Primary	`#3B82F6`
Secondary	`#60A5FA`
CTA	`#F97316`
Background	`#F8FAFC`
Text	`#1E293B`
Headings	Lora
Body	Raleway
Style	Vibrant & Block-based

项目结构

vitals/
├── src/vitals/
│   ├── core/
│   │   ├── models.py      # 数据模型（User, Invite, Exercise, Meal...）
│   │   ├── database.py    # MySQL 数据库操作（连接池管理、API Key 管理）
│   │   ├── auth.py        # JWT 认证、密码哈希
│   │   ├── backup.py      # 数据库备份
│   │   ├── export.py      # 数据导出导入
│   │   ├── report.py      # 健康报告生成
│   │   └── calories.py    # 卡路里计算（本地数据库 + AI 智能识别）
│   ├── vision/
│   │   ├── analyzer.py    # 食物识别分析器
│   │   └── providers/     # AI 提供商（通义千问、DeepSeek）
│   ├── importers/         # 数据导入器（Garmin、Codoon、CSV）
│   ├── web/
│   │   └── app.py         # FastAPI 应用
│   └── cli.py             # 命令行工具
├── scripts/
│   └── migrate_sqlite_to_mysql.py  # SQLite 到 MySQL 迁移脚本
├── tests/                 # 测试文件
├── docs/
│   ├── context/           # 开发上下文
│   └── plans/             # 设计文档
├── Dockerfile             # Docker 镜像配置
├── docker-compose.yml     # Docker Compose + MySQL 配置
├── .env.example           # 环境变量模板
├── pyproject.toml         # Python 项目配置
└── README.md

文档

部署文档

云服务器部署指南 - 详细的公网部署步骤

设计文档

开发进度

已完成功能 ✅

核心数据追踪

运动记录 - 类型、时长、距离、卡路里、心率追踪，支持 Garmin/Codoon/CSV 导入
饮食记录 - 三餐+加餐，营养数据（卡路里/蛋白质/碳水/脂肪），照片上传
睡眠记录 - 入睡/起床时间、时长、质量评分(1-5)、深睡时长
体重记录 - 体重(kg)、体脂率(%)、肌肉量，趋势分析
阅读记录 - 书名、作者、封面(自动获取)、时长、心情(5种表情)、读后感

用户认证与管理

JWT 认证 - 服务端认证 + Cookie，支持 1 天/30 天过期
密码安全 - bcrypt 哈希加密
多用户支持 - 用户档案、数据隔离、用户切换
用户配置隔离 - 每个用户独立的配置数据（身高、体重、目标等）
邀请码注册 - 控制用户注册，支持有效期设置
管理员面板 - 用户管理（启用/禁用/删除）、邀请码管理、API Key 管理

Web 应用

完整页面 - 登录、注册、管理员、首页、运动、饮食、睡眠、体重、阅读、报告、设置
认证中间件 - 保护所有页面（登录/注册除外）
REST API - 40+ 个接口，完整的 CRUD 操作
照片管理 - 饮食照片上传和静态文件服务

数据管理

数据导出 - JSON 和 CSV 格式
数据导入 - JSON 文件导入（带验证）
自动备份 - 数据写入后自动备份，7 天保留策略
备份恢复 - 从备份文件恢复数据
数据清理 - 按日期范围或数据类型删除，支持预览

AI 集成

食物图片识别 - 阿里通义千问(Qwen VL)、DeepSeek Vision、Claude Vision
食物文字智能识别 - 本地数据库优先匹配，识别失败自动调用 AI 标准化
卡路里估算 - 基于食物描述的营养值计算
API Key 管理 - Web 界面管理 AI API Key，数据库存储优先于环境变量

数据导入器

Garmin 导入 - 从 Garmin 设备导入运动数据
Codoon 导入 - 支持咔豆运动数据导入
CSV 导入 - 通用 CSV 导入（运动/饮食/睡眠/体重）

报告与分析

今日概览 - 所有健康指标汇总
本周汇总 - 7 天趋势分析
阅读统计 - 时长趋势、心情分布、书库展示
图表展示 - 运动趋势、营养统计、睡眠热力图
BMI 健康分析 - BMI 刻度条、目标体重达成预估
营养建议系统 - TDEE 目标计算、缺口分析、配餐建议
睡眠健康评估 - 状态评估、健康影响警告/益处提示

CLI 工具

数据记录 - vitals log 记录各类数据
数据查看 - vitals show 显示汇总
数据导出 - vitals export 导出 JSON/CSV
数据备份 - vitals backup 管理备份

部署

Docker 支持 - Dockerfile + docker-compose.yml
环境变量配置 - 灵活的配置管理
健康检查 - Docker 容器健康检查
MySQL 数据库 - MySQL 8.0 连接池，支持数据迁移

移动端 H5 适配

响应式布局 - 所有页面适配移动端屏幕（768px/400px 断点）
底部 Tab 导航 - 移动端专属底部导航栏，支持"更多"菜单
触控优化 - 按钮和交互元素符合 44px/48px 触控标准
iOS 安全区域 - 支持 iPhone 刘海屏和底部横条
全页面适配 - 登录/注册、首页、运动、饮食、睡眠、体重、阅读、报告、设置、管理页面

待完善功能 🚧

高优先级

提醒系统完善 - 定时提醒功能已有框架，但系统集成需要完善
数据编辑功能 - 目前仅支持删除，需要添加编辑已有记录的功能
错误处理优化 - 前端错误提示和异常处理需要更友好

中优先级

月度报告 - PDF 报告生成功能（已有框架，需完善）
目标设定 - 运动目标、饮食目标、体重目标的设定和追踪
数据统计增强 - 更丰富的图表和趋势分析
移动端优化 - 响应式设计改进，全部页面已适配移动端
离线支持 - PWA 支持，离线数据缓存

低优先级

国际化(i18n) - 多语言支持
云同步 - 跨设备数据同步
社交功能 - 数据分享、好友挑战
智能建议 - 基于数据的个性化健康建议
Apple Health 集成 - 步数数据同步到首页仪表盘
深色模式 - UI 深色主题支持

已知问题 🐛

大量数据时列表加载性能需优化
书籍封面搜索有时无法找到匹配结果

数据迁移

从 SQLite 迁移到 MySQL

如果你有旧版本的 SQLite 数据需要迁移，可以使用迁移脚本：

# 1. 确保 MySQL 服务已启动并配置好环境变量
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=vitals
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=vitals

# 2. 运行迁移脚本（默认从 ~/.vitals/vitals.db 读取）
python scripts/migrate_sqlite_to_mysql.py

# 或指定 SQLite 数据库路径
VITALS_DB_PATH=/path/to/old/vitals.db python scripts/migrate_sqlite_to_mysql.py

迁移脚本会自动处理：

用户数据（users）
运动记录（exercise）
饮食记录（meal）
睡眠记录（sleep）
体重记录（weight）
阅读记录（reading）
邀请码（invites）
配置数据（config）

更新日志

2026-01-27

📊 健康模块智能分析增强

BMI 健康分析 - 运动页面新增 BMI 分析卡片
- BMI 状态刻度条（偏瘦/正常/偏重/肥胖）
- 目标体重设定与达成预估
- 基于 TDEE-摄入+运动的智能计算
营养建议系统 - 饮食页面新增营养状况卡片
- 每日营养进度条（热量/蛋白质/碳水/脂肪）
- 基于 TDEE 的个性化目标计算
- 营养缺口分析与配餐建议
- 7 天趋势图增加建议摄入参考线
睡眠健康评估 - 睡眠页面新增健康评估卡片
- 睡眠状态刻度条（偏少/不足/理想/过多）
- 睡眠不足警告卡片（认知/身体/情绪/运动影响）
- 睡眠充足益处卡片（健康益处提示）
- 趋势图动态着色（理想区间绿色标记）

2026-01-26

🎨 首页仪表盘深色科技风格改造

全新视觉风格 - 深空黑背景 + 玻璃态卡片 + 霓虹光效
科技感配色 - 科技青(#00d4ff) + 霓虹紫(#7c3aed) 双色调
动态效果 - 卡片悬停光晕、数据呼吸动画、渐变边框
信息密度优化 - 紧凑布局，一屏展示更多健康数据

🍎 Apple Health 步数同步

步数数据集成 - 首页仪表盘展示 Apple Health 同步的步数
自动同步 - 支持从 Apple Health 导入每日步数数据

2026-01-24

🔑 API Key 数据库管理

集中存储 - AI API Key（通义千问、DeepSeek、Anthropic）存储在数据库
Web 管理界面 - 管理员可在设置页面配置 API Key
优先级机制 - 数据库配置优先于环境变量
安全显示 - API Key 列表仅显示掩码，支持查看/编辑/删除

👤 用户配置隔离

Config 表迁移 - 添加 user_id 字段，复合主键 (user_id, key)
数据归属 - 现有配置数据归属 ID=1 用户
完全隔离 - 每个用户独立的配置数据，新用户不再看到其他用户信息

🍽️ 食物文字智能识别

本地优先 - 使用内置食物数据库快速匹配（~100 种常见食物）
AI 增强 - 本地无法识别时自动调用通义千问 AI 标准化食物描述
智能回退 - 无 API Key 时仅使用本地估算，不影响基本功能

2026-01-23

🗄️ MySQL 数据库迁移

数据库切换 - 从 SQLite 迁移到 MySQL 8.0
连接池支持 - 使用 MySQL 连接池管理，提升性能
Docker 集成 - docker-compose 自动配置 MySQL 服务
数据迁移脚本 - 提供 SQLite 到 MySQL 的数据迁移工具
类型兼容性修复 - 添加 _parse_datetime、_parse_date、_parse_time 辅助函数，处理 MySQL 返回原生类型

🔒 用户权限增强

API 权限控制 - /api/users 非管理员仅返回自己，/api/users/{id} 非管理员只能查询自己（否则 403）
导航栏隐藏 - 非管理员用户隐藏「管理」入口

📱 移动端 H5 全页面适配

登录/注册页面 - 移动端布局优化，触摸目标符合标准
首页 Dashboard - 卡片布局适配，底部导航栏
运动/饮食页面 - 表格转卡片列表，表单输入增大
睡眠/体重/阅读页面 - 响应式布局，48px 输入框
报告页面 - 按钮触摸目标优化(48px)，底部导航
设置页面 - 响应式布局，支持手机浏览
管理页面 - 表格改为卡片列表(data-label)
底部 Tab 导航 - 固定底部导航栏 + "更多"菜单
iOS 安全区域 - 支持刘海屏和底部横条

🌐 网络访问

绑定地址优化 - 默认绑定 0.0.0.0，支持局域网访问和移动端真机测试

2026-01-22

🔐 混合认证方案优化

修改 login/register API 使用 JSONResponse 正确设置 Cookie
添加 path="/" 确保 Cookie 在所有路径可用
前端同时使用 localStorage token 进行 API 认证
修复登录后闪屏返回登录页的问题

✨ 登录功能全面升级

服务端认证中间件 - 未登录用户自动重定向到登录页
HTTPOnly Cookie - 使用 HTTPOnly Cookie 存储 token（比 localStorage 更安全）
"记住我"功能 - 勾选：30 天有效期，不勾选：1 天有效期
登出 API - 新增 /api/auth/logout 接口
登录后重定向 - 支持登录后返回原访问页面

🎨 登录/注册页面 UI 升级

采用 Neumorphism（新拟态） 设计风格
健康主题配色（青色 + 绿色渐变）
Lora + Raleway 字体组合
柔和阴影效果，提升视觉体验

历史版本

2026-01-20 - 阅读模块上线（书库、心情追踪、统计图表）
2026-01-19 - 设置页面重构（用户档案、数据管理）
2026-01-17 - 公网部署支持（JWT 认证、邀请码、管理员面板）
2026-01-15 - 第一版发布（核心健康追踪功能）

License

MIT

22 KiB Raw Blame History Unescape Escape

Vitals

功能特性

健康数据追踪

阅读习惯追踪

多用户与认证

数据管理

提醒功能

数据可视化

Apple Health 集成

快速开始

Docker 部署（推荐）

本地开发

页面导航

API 接口

认证

管理员

用户管理

数据管理

运动

饮食

睡眠

体重

阅读

汇总

命令行使用

数据记录

数据查看

数据导出与导入

数据库备份

定时提醒

安装

环境变量

技术栈

设计系统

首页仪表盘（深色科技风格）

其他页面

项目结构

文档

部署文档

设计文档

开发进度

已完成功能 ✅

核心数据追踪

用户认证与管理

Web 应用

数据管理

AI 集成

数据导入器

报告与分析

CLI 工具

部署

移动端 H5 适配

待完善功能 🚧

高优先级

中优先级

低优先级

已知问题 🐛

数据迁移

从 SQLite 迁移到 MySQL

更新日志

2026-01-27

📊 健康模块智能分析增强

2026-01-26

🎨 首页仪表盘深色科技风格改造

🍎 Apple Health 步数同步

2026-01-24

🔑 API Key 数据库管理

👤 用户配置隔离

🍽️ 食物文字智能识别

2026-01-23

🗄️ MySQL 数据库迁移

🔒 用户权限增强

📱 移动端 H5 全页面适配

🌐 网络访问

2026-01-22

🔐 混合认证方案优化

✨ 登录功能全面升级

🎨 登录/注册页面 UI 升级

历史版本

22 KiB

Raw Blame History