363 lines
10 KiB
Markdown
363 lines
10 KiB
Markdown
# Vitals
|
||
|
||
本地优先的综合健康管理应用，整合运动、饮食、睡眠、体重和阅读数据。
|
||
|
||
## 功能特性
|
||
|
||
### 健康数据追踪
|
||
- **运动记录** - 跑步、游泳、骑行、力量训练等，支持时长、距离、心率记录
|
||
- **饮食记录** - 三餐及加餐，支持卡路里、蛋白质、碳水、脂肪追踪，AI 智能识别食物
|
||
- **睡眠记录** - 入睡/起床时间、睡眠时长、睡眠质量评分
|
||
- **体重记录** - 体重、体脂率、肌肉量追踪
|
||
|
||
### 阅读习惯追踪
|
||
- **阅读记录** - 时长、书名、作者、封面（自动获取）、读后感
|
||
- **心情记录** - 5 种表情选择（😄😊😐😔😢）
|
||
- **我的书库** - 书籍封面网格展示，按书名归类
|
||
- **统计图表** - 阅读时长趋势、心情分布饼图
|
||
|
||
### 多用户与认证
|
||
- **用户档案** - 姓名、性别、身高、体重、年龄
|
||
- **BMI 计算** - 自动计算并显示健康状态（偏瘦/正常/偏胖/肥胖）
|
||
- **用户切换** - 支持多用户数据隔离
|
||
- **数据管理** - 按日期范围或数据类型清除数据
|
||
- **JWT 认证** - 安全的 Token 认证机制
|
||
- **邀请码注册** - 通过邀请码控制用户注册
|
||
- **管理员面板** - 用户管理、邀请码管理
|
||
|
||
### 数据管理
|
||
- **数据导出** - 支持 JSON/CSV 格式导出
|
||
- **数据导入** - 从 JSON 文件导入数据
|
||
- **自动备份** - 数据写入后自动备份
|
||
- **备份恢复** - 支持从备份文件恢复数据
|
||
|
||
### 提醒功能
|
||
- **定时提醒** - 体重、睡眠、运动、饮食提醒
|
||
- **系统通知** - 支持 macOS/Linux/Windows 系统通知
|
||
|
||
### 数据可视化
|
||
- **今日概览** - 运动、饮食、睡眠、体重、阅读汇总
|
||
- **本周报告** - 趋势分析和统计图表
|
||
- **详细报告** - 各项数据的深度分析
|
||
|
||
## 快速开始
|
||
|
||
### Docker 部署（推荐）
|
||
|
||
```bash
|
||
# 1. 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 2. 编辑 .env 文件，设置管理员密码和 JWT 密钥
|
||
vim .env
|
||
|
||
# 3. 启动服务
|
||
docker-compose up -d
|
||
|
||
# 4. 访问 http://localhost:8080
|
||
```
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -e .
|
||
|
||
# 设置环境变量
|
||
export ADMIN_USERNAME=admin
|
||
export ADMIN_PASSWORD=your_password
|
||
export JWT_SECRET=$(openssl rand -hex 32)
|
||
|
||
# 启动服务
|
||
uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080
|
||
```
|
||
|
||
访问 `http://localhost:8080` 即可使用 Web 界面。
|
||
|
||
### 页面导航
|
||
- `/` - 首页（今日概览）
|
||
- `/login` - 登录页面
|
||
- `/register` - 注册页面（需邀请码）
|
||
- `/admin` - 管理员面板
|
||
- `/exercise` - 运动记录
|
||
- `/meal` - 饮食记录
|
||
- `/sleep` - 睡眠记录
|
||
- `/weight` - 体重记录
|
||
- `/reading` - 阅读记录
|
||
- `/report` - 健康报告
|
||
- `/settings` - 设置页面
|
||
|
||
## API 接口
|
||
|
||
### 认证
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/auth/login` | POST | 用户登录，返回 JWT Token |
|
||
| `/api/auth/register` | POST | 用户注册（需邀请码） |
|
||
| `/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/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/meals` | GET | 获取饮食记录 |
|
||
| `/api/meal` | POST | 添加饮食记录 |
|
||
| `/api/meal/{id}` | DELETE | 删除单条饮食记录 |
|
||
| `/api/meals/nutrition` | GET | 营养统计 |
|
||
| `/api/food/recognize` | POST | AI 识别食物 |
|
||
|
||
### 睡眠
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/sleep` | GET | 获取睡眠记录 |
|
||
| `/api/sleep` | POST | 添加睡眠记录 |
|
||
| `/api/sleep/{id}` | DELETE | 删除单条睡眠记录 |
|
||
|
||
### 体重
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/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 .
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `ADMIN_USERNAME` | 是 | 管理员用户名（首次启动时创建） |
|
||
| `ADMIN_PASSWORD` | 是 | 管理员密码 |
|
||
| `JWT_SECRET` | 是 | JWT 签名密钥（建议用 `openssl rand -hex 32` 生成） |
|
||
| `VITALS_DB_PATH` | 否 | 数据库路径（默认 `~/.vitals/vitals.db`） |
|
||
| `DASHSCOPE_API_KEY` | 否 | 阿里云通义千问 API Key，用于 AI 食物识别 |
|
||
| `DEEPSEEK_API_KEY` | 否 | DeepSeek API Key，用于 AI 食物识别 |
|
||
|
||
## 技术栈
|
||
|
||
- **后端**: Python, FastAPI, SQLite
|
||
- **前端**: HTML, CSS, JavaScript, Chart.js
|
||
- **认证**: JWT (PyJWT), bcrypt
|
||
- **部署**: Docker, Docker Compose
|
||
- **AI**: 阿里云通义千问 / DeepSeek (食物识别)
|
||
- **外部 API**: OpenLibrary (书籍封面搜索)
|
||
|
||
## 设计系统
|
||
|
||
| 元素 | 值 |
|
||
|------|------|
|
||
| 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 # 数据库操作
|
||
│ │ ├── auth.py # JWT 认证、密码哈希
|
||
│ │ ├── backup.py # 数据库备份
|
||
│ │ ├── export.py # 数据导出导入
|
||
│ │ ├── report.py # 健康报告生成
|
||
│ │ └── calories.py # 卡路里计算
|
||
│ ├── vision/
|
||
│ │ ├── analyzer.py # 食物识别分析器
|
||
│ │ └── providers/ # AI 提供商（通义千问、DeepSeek）
|
||
│ ├── importers/ # 数据导入器（Garmin、Codoon、CSV）
|
||
│ ├── web/
|
||
│ │ └── app.py # FastAPI 应用
|
||
│ └── cli.py # 命令行工具
|
||
├── tests/ # 测试文件
|
||
├── docs/
|
||
│ ├── context/ # 开发上下文
|
||
│ └── plans/ # 设计文档
|
||
├── Dockerfile # Docker 镜像配置
|
||
├── docker-compose.yml # Docker Compose 配置
|
||
├── .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)
|
||
|
||
## 开发进度
|
||
|
||
### 已完成功能
|
||
|
||
- [x] **P1-1** 运动页面 - 运动记录列表、统计图表、数据录入
|
||
- [x] **P1-2** 饮食页面 - 饮食记录、营养统计、日历视图
|
||
- [x] **P1-3** 睡眠/体重页面 - 睡眠趋势、体重曲线、BMI 计算
|
||
- [x] **P1-4** Web 数据录入 - 所有数据类型的表单录入
|
||
- [x] **P1-5** AI 智能识别 - 通义千问/DeepSeek 食物识别
|
||
- [x] **P2-1** 数据导出 - JSON/CSV 格式导出
|
||
- [x] **P2-2** 自动备份 - 数据库备份与恢复
|
||
- [x] **P3-1** 定时提醒 - 系统通知、定时任务
|
||
- [x] **公网部署** - JWT 认证、邀请码注册、管理员面板、Docker 部署
|
||
|
||
## License
|
||
|
||
MIT
|