2026-01-22 12:57:26 +08:00
|
|
|
|
# Vitals
|
|
|
|
|
|
|
|
|
|
|
|
本地优先的综合健康管理应用,整合运动、饮食、睡眠、体重和阅读数据。
|
|
|
|
|
|
|
|
|
|
|
|
## 功能特性
|
|
|
|
|
|
|
|
|
|
|
|
### 健康数据追踪
|
|
|
|
|
|
- **运动记录** - 跑步、游泳、骑行、力量训练等,支持时长、距离、心率记录
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- **饮食记录** - 三餐及加餐,支持卡路里、蛋白质、碳水、脂肪追踪,AI 智能识别食物图片和文字
|
2026-01-22 12:57:26 +08:00
|
|
|
|
- **睡眠记录** - 入睡/起床时间、睡眠时长、睡眠质量评分
|
|
|
|
|
|
- **体重记录** - 体重、体脂率、肌肉量追踪
|
|
|
|
|
|
|
|
|
|
|
|
### 阅读习惯追踪
|
|
|
|
|
|
- **阅读记录** - 时长、书名、作者、封面(自动获取)、读后感
|
|
|
|
|
|
- **心情记录** - 5 种表情选择(😄😊😐😔😢)
|
|
|
|
|
|
- **我的书库** - 书籍封面网格展示,按书名归类
|
|
|
|
|
|
- **统计图表** - 阅读时长趋势、心情分布饼图
|
|
|
|
|
|
|
|
|
|
|
|
### 多用户与认证
|
|
|
|
|
|
- **用户档案** - 姓名、性别、身高、体重、年龄
|
|
|
|
|
|
- **BMI 计算** - 自动计算并显示健康状态(偏瘦/正常/偏胖/肥胖)
|
|
|
|
|
|
- **用户切换** - 支持多用户数据隔离
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- **用户配置隔离** - 每个用户独立的配置数据
|
2026-01-22 12:57:26 +08:00
|
|
|
|
- **数据管理** - 按日期范围或数据类型清除数据
|
2026-01-22 15:17:09 +08:00
|
|
|
|
- **JWT 认证** - HTTPOnly Cookie + Authorization Header 混合认证
|
|
|
|
|
|
- **记住我** - 可选 1 天或 30 天登录有效期
|
2026-01-22 12:57:26 +08:00
|
|
|
|
- **邀请码注册** - 通过邀请码控制用户注册
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- **管理员面板** - 用户管理、邀请码管理、API Key 管理
|
2026-01-22 12:57:26 +08:00
|
|
|
|
|
|
|
|
|
|
### 数据管理
|
|
|
|
|
|
- **数据导出** - 支持 JSON/CSV 格式导出
|
|
|
|
|
|
- **数据导入** - 从 JSON 文件导入数据
|
|
|
|
|
|
- **自动备份** - 数据写入后自动备份
|
|
|
|
|
|
- **备份恢复** - 支持从备份文件恢复数据
|
|
|
|
|
|
|
|
|
|
|
|
### 提醒功能
|
|
|
|
|
|
- **定时提醒** - 体重、睡眠、运动、饮食提醒
|
|
|
|
|
|
- **系统通知** - 支持 macOS/Linux/Windows 系统通知
|
|
|
|
|
|
|
|
|
|
|
|
### 数据可视化
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- **今日概览** - 运动、饮食、睡眠、体重、阅读汇总,深色科技风格仪表盘
|
2026-01-22 12:57:26 +08:00
|
|
|
|
- **本周报告** - 趋势分析和统计图表
|
|
|
|
|
|
- **详细报告** - 各项数据的深度分析
|
|
|
|
|
|
|
2026-01-27 16:47:06 +08:00
|
|
|
|
### Apple Health 集成
|
|
|
|
|
|
- **步数同步** - 自动同步 Apple Health 步数数据到首页仪表盘
|
|
|
|
|
|
|
2026-01-22 12:57:26 +08:00
|
|
|
|
## 快速开始
|
|
|
|
|
|
|
|
|
|
|
|
### Docker 部署(推荐)
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 1. 复制环境变量模板
|
|
|
|
|
|
cp .env.example .env
|
|
|
|
|
|
|
2026-01-23 21:16:32 +08:00
|
|
|
|
# 2. 编辑 .env 文件,设置 JWT 密钥
|
2026-01-22 12:57:26 +08:00
|
|
|
|
vim .env
|
|
|
|
|
|
|
|
|
|
|
|
# 3. 启动服务
|
|
|
|
|
|
docker-compose up -d
|
|
|
|
|
|
|
2026-01-23 21:16:32 +08:00
|
|
|
|
# 4. 访问 http://localhost:8888
|
|
|
|
|
|
# 默认管理员账号: admin / admin123
|
2026-01-22 12:57:26 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 本地开发
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 安装依赖
|
|
|
|
|
|
pip install -e .
|
|
|
|
|
|
|
2026-01-23 18:41:50 +08:00
|
|
|
|
# 设置 MySQL 环境变量
|
|
|
|
|
|
export MYSQL_HOST=localhost
|
|
|
|
|
|
export MYSQL_PORT=3306
|
|
|
|
|
|
export MYSQL_USER=vitals
|
|
|
|
|
|
export MYSQL_PASSWORD=your_password
|
|
|
|
|
|
export MYSQL_DATABASE=vitals
|
|
|
|
|
|
|
2026-01-23 21:16:32 +08:00
|
|
|
|
# 设置 JWT 密钥
|
2026-01-22 12:57:26 +08:00
|
|
|
|
export JWT_SECRET=$(openssl rand -hex 32)
|
|
|
|
|
|
|
|
|
|
|
|
# 启动服务
|
|
|
|
|
|
uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
访问 `http://localhost:8080` 即可使用 Web 界面。
|
|
|
|
|
|
|
2026-01-23 21:16:32 +08:00
|
|
|
|
> **注意**: 默认管理员账号为 `admin` / `admin123`,请在首次登录后及时修改密码。
|
|
|
|
|
|
|
2026-01-22 12:57:26 +08:00
|
|
|
|
### 页面导航
|
|
|
|
|
|
- `/` - 首页(今日概览)
|
|
|
|
|
|
- `/login` - 登录页面
|
|
|
|
|
|
- `/register` - 注册页面(需邀请码)
|
|
|
|
|
|
- `/admin` - 管理员面板
|
|
|
|
|
|
- `/exercise` - 运动记录
|
|
|
|
|
|
- `/meal` - 饮食记录
|
|
|
|
|
|
- `/sleep` - 睡眠记录
|
|
|
|
|
|
- `/weight` - 体重记录
|
|
|
|
|
|
- `/reading` - 阅读记录
|
|
|
|
|
|
- `/report` - 健康报告
|
|
|
|
|
|
- `/settings` - 设置页面
|
|
|
|
|
|
|
|
|
|
|
|
## API 接口
|
|
|
|
|
|
|
|
|
|
|
|
### 认证
|
|
|
|
|
|
|
|
|
|
|
|
| 端点 | 方法 | 说明 |
|
|
|
|
|
|
|------|------|------|
|
2026-01-22 15:17:09 +08:00
|
|
|
|
| `/api/auth/login` | POST | 用户登录,返回 JWT Token + 设置 Cookie |
|
2026-01-22 12:57:26 +08:00
|
|
|
|
| `/api/auth/register` | POST | 用户注册(需邀请码) |
|
2026-01-22 15:17:09 +08:00
|
|
|
|
| `/api/auth/logout` | POST | 用户登出,清除 Cookie |
|
2026-01-22 12:57:26 +08:00
|
|
|
|
| `/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 | 删除邀请码 |
|
2026-01-27 16:47:06 +08:00
|
|
|
|
| `/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 |
|
2026-01-22 12:57:26 +08:00
|
|
|
|
|
|
|
|
|
|
### 用户管理
|
|
|
|
|
|
|
|
|
|
|
|
| 端点 | 方法 | 说明 |
|
|
|
|
|
|
|------|------|------|
|
|
|
|
|
|
| `/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 | 运动统计 |
|
2026-01-27 16:47:06 +08:00
|
|
|
|
| `/api/bmi/analysis` | GET | BMI 分析(当前/目标体重、达成预估) |
|
2026-01-22 12:57:26 +08:00
|
|
|
|
|
|
|
|
|
|
### 饮食
|
|
|
|
|
|
|
|
|
|
|
|
| 端点 | 方法 | 说明 |
|
|
|
|
|
|
|------|------|------|
|
|
|
|
|
|
| `/api/meals` | GET | 获取饮食记录 |
|
|
|
|
|
|
| `/api/meal` | POST | 添加饮食记录 |
|
|
|
|
|
|
| `/api/meal/{id}` | DELETE | 删除单条饮食记录 |
|
|
|
|
|
|
| `/api/meals/nutrition` | GET | 营养统计 |
|
|
|
|
|
|
| `/api/food/recognize` | POST | AI 识别食物 |
|
2026-01-27 16:47:06 +08:00
|
|
|
|
| `/api/nutrition/recommendations` | GET | 营养建议(TDEE目标、缺口分析、配餐建议) |
|
2026-01-22 12:57:26 +08:00
|
|
|
|
|
|
|
|
|
|
### 睡眠
|
|
|
|
|
|
|
|
|
|
|
|
| 端点 | 方法 | 说明 |
|
|
|
|
|
|
|------|------|------|
|
|
|
|
|
|
| `/api/sleep` | GET | 获取睡眠记录 |
|
|
|
|
|
|
| `/api/sleep` | POST | 添加睡眠记录 |
|
|
|
|
|
|
| `/api/sleep/{id}` | DELETE | 删除单条睡眠记录 |
|
2026-01-27 16:47:06 +08:00
|
|
|
|
| `/api/sleep/assessment` | GET | 睡眠评估(状态分析、健康影响、建议) |
|
2026-01-22 12:57:26 +08:00
|
|
|
|
|
|
|
|
|
|
### 体重
|
|
|
|
|
|
|
|
|
|
|
|
| 端点 | 方法 | 说明 |
|
|
|
|
|
|
|------|------|------|
|
|
|
|
|
|
| `/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 | 本周汇总 |
|
|
|
|
|
|
|
|
|
|
|
|
## 命令行使用
|
|
|
|
|
|
|
|
|
|
|
|
### 数据记录
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 记录体重
|
|
|
|
|
|
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
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 数据查看
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 查看今日概览
|
|
|
|
|
|
vitals show today
|
|
|
|
|
|
|
|
|
|
|
|
# 查看本周汇总
|
|
|
|
|
|
vitals show week
|
|
|
|
|
|
|
|
|
|
|
|
# 设置个人信息
|
|
|
|
|
|
vitals config set --age 28 --gender male --height 175 --weight 72
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 数据导出与导入
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 导出所有数据为 JSON
|
|
|
|
|
|
vitals export json ~/backup.json
|
|
|
|
|
|
|
|
|
|
|
|
# 导出运动数据为 CSV
|
|
|
|
|
|
vitals export csv --type exercise ~/exercise.csv
|
|
|
|
|
|
|
|
|
|
|
|
# 从 JSON 导入数据
|
|
|
|
|
|
vitals export import-json ~/backup.json
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 数据库备份
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 创建备份
|
|
|
|
|
|
vitals backup create
|
|
|
|
|
|
|
|
|
|
|
|
# 列出所有备份
|
|
|
|
|
|
vitals backup list
|
|
|
|
|
|
|
|
|
|
|
|
# 恢复备份
|
|
|
|
|
|
vitals backup restore ~/.vitals/backups/vitals_20260122_120000.db
|
|
|
|
|
|
|
|
|
|
|
|
# 清理旧备份(保留最近 7 天)
|
|
|
|
|
|
vitals backup cleanup --days 7
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 定时提醒
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 设置体重提醒(每天 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
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 安装
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pip install -e .
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 环境变量
|
|
|
|
|
|
|
|
|
|
|
|
| 变量 | 必填 | 说明 |
|
|
|
|
|
|
|------|------|------|
|
2026-01-23 18:41:50 +08:00
|
|
|
|
| `MYSQL_HOST` | 是 | MySQL 服务器地址(默认 `localhost`) |
|
|
|
|
|
|
| `MYSQL_PORT` | 否 | MySQL 端口(默认 `3306`) |
|
|
|
|
|
|
| `MYSQL_USER` | 是 | MySQL 用户名 |
|
|
|
|
|
|
| `MYSQL_PASSWORD` | 是 | MySQL 密码 |
|
|
|
|
|
|
| `MYSQL_DATABASE` | 是 | MySQL 数据库名(默认 `vitals`) |
|
|
|
|
|
|
| `MYSQL_ROOT_PASSWORD` | 是 | MySQL root 密码(Docker 部署时需要) |
|
2026-01-22 12:57:26 +08:00
|
|
|
|
| `JWT_SECRET` | 是 | JWT 签名密钥(建议用 `openssl rand -hex 32` 生成) |
|
2026-01-27 16:47:06 +08:00
|
|
|
|
| `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 管理界面配置(管理员设置页),数据库配置优先于环境变量。
|
2026-01-22 12:57:26 +08:00
|
|
|
|
|
2026-01-23 21:16:32 +08:00
|
|
|
|
**默认管理员账号**: `admin` / `admin123`(请在首次登录后修改)
|
|
|
|
|
|
|
2026-01-22 12:57:26 +08:00
|
|
|
|
## 技术栈
|
|
|
|
|
|
|
2026-01-23 18:41:50 +08:00
|
|
|
|
- **后端**: Python, FastAPI, MySQL 8.0
|
2026-01-22 12:57:26 +08:00
|
|
|
|
- **前端**: HTML, CSS, JavaScript, Chart.js
|
|
|
|
|
|
- **认证**: JWT (PyJWT), bcrypt
|
|
|
|
|
|
- **部署**: Docker, Docker Compose
|
|
|
|
|
|
- **AI**: 阿里云通义千问 / DeepSeek (食物识别)
|
|
|
|
|
|
- **外部 API**: OpenLibrary (书籍封面搜索)
|
|
|
|
|
|
|
|
|
|
|
|
## 设计系统
|
|
|
|
|
|
|
2026-01-27 16:47:06 +08:00
|
|
|
|
### 首页仪表盘(深色科技风格)
|
|
|
|
|
|
|
|
|
|
|
|
| 元素 | 值 |
|
|
|
|
|
|
|------|------|
|
|
|
|
|
|
| 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)` |
|
|
|
|
|
|
|
|
|
|
|
|
### 其他页面
|
|
|
|
|
|
|
2026-01-22 12:57:26 +08:00
|
|
|
|
| 元素 | 值 |
|
|
|
|
|
|
|------|------|
|
|
|
|
|
|
| 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...)
|
2026-01-27 16:47:06 +08:00
|
|
|
|
│ │ ├── database.py # MySQL 数据库操作(连接池管理、API Key 管理)
|
2026-01-22 12:57:26 +08:00
|
|
|
|
│ │ ├── auth.py # JWT 认证、密码哈希
|
|
|
|
|
|
│ │ ├── backup.py # 数据库备份
|
|
|
|
|
|
│ │ ├── export.py # 数据导出导入
|
|
|
|
|
|
│ │ ├── report.py # 健康报告生成
|
2026-01-27 16:47:06 +08:00
|
|
|
|
│ │ └── calories.py # 卡路里计算(本地数据库 + AI 智能识别)
|
2026-01-22 12:57:26 +08:00
|
|
|
|
│ ├── vision/
|
|
|
|
|
|
│ │ ├── analyzer.py # 食物识别分析器
|
|
|
|
|
|
│ │ └── providers/ # AI 提供商(通义千问、DeepSeek)
|
|
|
|
|
|
│ ├── importers/ # 数据导入器(Garmin、Codoon、CSV)
|
|
|
|
|
|
│ ├── web/
|
|
|
|
|
|
│ │ └── app.py # FastAPI 应用
|
|
|
|
|
|
│ └── cli.py # 命令行工具
|
2026-01-23 18:41:50 +08:00
|
|
|
|
├── scripts/
|
|
|
|
|
|
│ └── migrate_sqlite_to_mysql.py # SQLite 到 MySQL 迁移脚本
|
2026-01-22 12:57:26 +08:00
|
|
|
|
├── tests/ # 测试文件
|
|
|
|
|
|
├── docs/
|
|
|
|
|
|
│ ├── context/ # 开发上下文
|
|
|
|
|
|
│ └── plans/ # 设计文档
|
|
|
|
|
|
├── Dockerfile # Docker 镜像配置
|
2026-01-23 18:41:50 +08:00
|
|
|
|
├── docker-compose.yml # Docker Compose + MySQL 配置
|
2026-01-22 12:57:26 +08:00
|
|
|
|
├── .env.example # 环境变量模板
|
|
|
|
|
|
├── pyproject.toml # Python 项目配置
|
|
|
|
|
|
└── README.md
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 文档
|
|
|
|
|
|
|
|
|
|
|
|
### 部署文档
|
|
|
|
|
|
- [云服务器部署指南](docs/deployment-guide.md) - 详细的公网部署步骤
|
|
|
|
|
|
|
|
|
|
|
|
### 设计文档
|
|
|
|
|
|
- [Vitals 设计文档](docs/plans/2025-01-17-vitals-design.md)
|
|
|
|
|
|
- [设置页面实现计划](docs/plans/2026-01-19-settings-page-implementation.md)
|
|
|
|
|
|
- [阅读模块设计文档](docs/plans/2026-01-20-reading-module-design.md)
|
|
|
|
|
|
- [公网部署设计文档](docs/plans/2026-01-20-public-deployment-design.md)
|
|
|
|
|
|
- [开发任务清单](docs/plans/task.md)
|
|
|
|
|
|
|
|
|
|
|
|
## 开发进度
|
|
|
|
|
|
|
2026-01-22 15:03:01 +08:00
|
|
|
|
### 已完成功能 ✅
|
|
|
|
|
|
|
|
|
|
|
|
#### 核心数据追踪
|
|
|
|
|
|
- [x] **运动记录** - 类型、时长、距离、卡路里、心率追踪,支持 Garmin/Codoon/CSV 导入
|
|
|
|
|
|
- [x] **饮食记录** - 三餐+加餐,营养数据(卡路里/蛋白质/碳水/脂肪),照片上传
|
|
|
|
|
|
- [x] **睡眠记录** - 入睡/起床时间、时长、质量评分(1-5)、深睡时长
|
|
|
|
|
|
- [x] **体重记录** - 体重(kg)、体脂率(%)、肌肉量,趋势分析
|
|
|
|
|
|
- [x] **阅读记录** - 书名、作者、封面(自动获取)、时长、心情(5种表情)、读后感
|
|
|
|
|
|
|
|
|
|
|
|
#### 用户认证与管理
|
|
|
|
|
|
- [x] **JWT 认证** - 服务端认证 + Cookie,支持 1 天/30 天过期
|
|
|
|
|
|
- [x] **密码安全** - bcrypt 哈希加密
|
|
|
|
|
|
- [x] **多用户支持** - 用户档案、数据隔离、用户切换
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- [x] **用户配置隔离** - 每个用户独立的配置数据(身高、体重、目标等)
|
2026-01-22 15:03:01 +08:00
|
|
|
|
- [x] **邀请码注册** - 控制用户注册,支持有效期设置
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- [x] **管理员面板** - 用户管理(启用/禁用/删除)、邀请码管理、API Key 管理
|
2026-01-22 15:03:01 +08:00
|
|
|
|
|
|
|
|
|
|
#### Web 应用
|
|
|
|
|
|
- [x] **完整页面** - 登录、注册、管理员、首页、运动、饮食、睡眠、体重、阅读、报告、设置
|
|
|
|
|
|
- [x] **认证中间件** - 保护所有页面(登录/注册除外)
|
|
|
|
|
|
- [x] **REST API** - 40+ 个接口,完整的 CRUD 操作
|
|
|
|
|
|
- [x] **照片管理** - 饮食照片上传和静态文件服务
|
|
|
|
|
|
|
|
|
|
|
|
#### 数据管理
|
|
|
|
|
|
- [x] **数据导出** - JSON 和 CSV 格式
|
|
|
|
|
|
- [x] **数据导入** - JSON 文件导入(带验证)
|
|
|
|
|
|
- [x] **自动备份** - 数据写入后自动备份,7 天保留策略
|
|
|
|
|
|
- [x] **备份恢复** - 从备份文件恢复数据
|
|
|
|
|
|
- [x] **数据清理** - 按日期范围或数据类型删除,支持预览
|
|
|
|
|
|
|
|
|
|
|
|
#### AI 集成
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- [x] **食物图片识别** - 阿里通义千问(Qwen VL)、DeepSeek Vision、Claude Vision
|
|
|
|
|
|
- [x] **食物文字智能识别** - 本地数据库优先匹配,识别失败自动调用 AI 标准化
|
2026-01-22 15:03:01 +08:00
|
|
|
|
- [x] **卡路里估算** - 基于食物描述的营养值计算
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- [x] **API Key 管理** - Web 界面管理 AI API Key,数据库存储优先于环境变量
|
2026-01-22 15:03:01 +08:00
|
|
|
|
|
|
|
|
|
|
#### 数据导入器
|
|
|
|
|
|
- [x] **Garmin 导入** - 从 Garmin 设备导入运动数据
|
|
|
|
|
|
- [x] **Codoon 导入** - 支持咔豆运动数据导入
|
|
|
|
|
|
- [x] **CSV 导入** - 通用 CSV 导入(运动/饮食/睡眠/体重)
|
|
|
|
|
|
|
|
|
|
|
|
#### 报告与分析
|
|
|
|
|
|
- [x] **今日概览** - 所有健康指标汇总
|
|
|
|
|
|
- [x] **本周汇总** - 7 天趋势分析
|
|
|
|
|
|
- [x] **阅读统计** - 时长趋势、心情分布、书库展示
|
|
|
|
|
|
- [x] **图表展示** - 运动趋势、营养统计、睡眠热力图
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- [x] **BMI 健康分析** - BMI 刻度条、目标体重达成预估
|
|
|
|
|
|
- [x] **营养建议系统** - TDEE 目标计算、缺口分析、配餐建议
|
|
|
|
|
|
- [x] **睡眠健康评估** - 状态评估、健康影响警告/益处提示
|
2026-01-22 15:03:01 +08:00
|
|
|
|
|
|
|
|
|
|
#### CLI 工具
|
|
|
|
|
|
- [x] **数据记录** - `vitals log` 记录各类数据
|
|
|
|
|
|
- [x] **数据查看** - `vitals show` 显示汇总
|
|
|
|
|
|
- [x] **数据导出** - `vitals export` 导出 JSON/CSV
|
|
|
|
|
|
- [x] **数据备份** - `vitals backup` 管理备份
|
|
|
|
|
|
|
|
|
|
|
|
#### 部署
|
|
|
|
|
|
- [x] **Docker 支持** - Dockerfile + docker-compose.yml
|
|
|
|
|
|
- [x] **环境变量配置** - 灵活的配置管理
|
|
|
|
|
|
- [x] **健康检查** - Docker 容器健康检查
|
2026-01-23 18:41:50 +08:00
|
|
|
|
- [x] **MySQL 数据库** - MySQL 8.0 连接池,支持数据迁移
|
|
|
|
|
|
|
|
|
|
|
|
#### 移动端 H5 适配
|
|
|
|
|
|
- [x] **响应式布局** - 所有页面适配移动端屏幕(768px/400px 断点)
|
|
|
|
|
|
- [x] **底部 Tab 导航** - 移动端专属底部导航栏,支持"更多"菜单
|
|
|
|
|
|
- [x] **触控优化** - 按钮和交互元素符合 44px/48px 触控标准
|
|
|
|
|
|
- [x] **iOS 安全区域** - 支持 iPhone 刘海屏和底部横条
|
|
|
|
|
|
- [x] **全页面适配** - 登录/注册、首页、运动、饮食、睡眠、体重、阅读、报告、设置、管理页面
|
2026-01-22 15:03:01 +08:00
|
|
|
|
|
|
|
|
|
|
### 待完善功能 🚧
|
|
|
|
|
|
|
|
|
|
|
|
#### 高优先级
|
|
|
|
|
|
- [ ] **提醒系统完善** - 定时提醒功能已有框架,但系统集成需要完善
|
|
|
|
|
|
- [ ] **数据编辑功能** - 目前仅支持删除,需要添加编辑已有记录的功能
|
|
|
|
|
|
- [ ] **错误处理优化** - 前端错误提示和异常处理需要更友好
|
|
|
|
|
|
|
|
|
|
|
|
#### 中优先级
|
|
|
|
|
|
- [ ] **月度报告** - PDF 报告生成功能(已有框架,需完善)
|
|
|
|
|
|
- [ ] **目标设定** - 运动目标、饮食目标、体重目标的设定和追踪
|
|
|
|
|
|
- [ ] **数据统计增强** - 更丰富的图表和趋势分析
|
2026-01-23 18:41:50 +08:00
|
|
|
|
- [x] **移动端优化** - 响应式设计改进,全部页面已适配移动端
|
2026-01-22 15:03:01 +08:00
|
|
|
|
- [ ] **离线支持** - PWA 支持,离线数据缓存
|
|
|
|
|
|
|
|
|
|
|
|
#### 低优先级
|
|
|
|
|
|
- [ ] **国际化(i18n)** - 多语言支持
|
|
|
|
|
|
- [ ] **云同步** - 跨设备数据同步
|
|
|
|
|
|
- [ ] **社交功能** - 数据分享、好友挑战
|
|
|
|
|
|
- [ ] **智能建议** - 基于数据的个性化健康建议
|
2026-01-27 16:47:06 +08:00
|
|
|
|
- [x] **Apple Health 集成** - 步数数据同步到首页仪表盘
|
2026-01-22 15:03:01 +08:00
|
|
|
|
- [ ] **深色模式** - UI 深色主题支持
|
|
|
|
|
|
|
|
|
|
|
|
### 已知问题 🐛
|
|
|
|
|
|
|
|
|
|
|
|
- [ ] 大量数据时列表加载性能需优化
|
|
|
|
|
|
- [ ] 书籍封面搜索有时无法找到匹配结果
|
2026-01-22 12:57:26 +08:00
|
|
|
|
|
2026-01-23 18:41:50 +08:00
|
|
|
|
## 数据迁移
|
|
|
|
|
|
|
|
|
|
|
|
### 从 SQLite 迁移到 MySQL
|
|
|
|
|
|
|
|
|
|
|
|
如果你有旧版本的 SQLite 数据需要迁移,可以使用迁移脚本:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 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-22 15:17:09 +08:00
|
|
|
|
## 更新日志
|
|
|
|
|
|
|
2026-01-27 16:47:06 +08:00
|
|
|
|
### 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 18:41:50 +08:00
|
|
|
|
### 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 15:17:09 +08:00
|
|
|
|
### 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** - 第一版发布(核心健康追踪功能)
|
|
|
|
|
|
|
2026-01-22 12:57:26 +08:00
|
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
|
|
MIT
|