# Vitals

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

## 功能特性

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

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

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

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

#### 用户认证与管理
- [x] **JWT 认证** - 服务端认证 + Cookie，支持 1 天/30 天过期
- [x] **密码安全** - bcrypt 哈希加密
- [x] **多用户支持** - 用户档案、数据隔离、用户切换
- [x] **邀请码注册** - 控制用户注册，支持有效期设置
- [x] **管理员面板** - 用户管理（启用/禁用/删除）、邀请码管理

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

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

#### AI 集成
- [x] **食物识别** - 阿里通义千问(Qwen VL)、DeepSeek Vision、Claude Vision
- [x] **卡路里估算** - 基于食物描述的营养值计算

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

#### 报告与分析
- [x] **今日概览** - 所有健康指标汇总
- [x] **本周汇总** - 7 天趋势分析
- [x] **阅读统计** - 时长趋势、心情分布、书库展示
- [x] **图表展示** - 运动趋势、营养统计、睡眠热力图

#### CLI 工具
- [x] **数据记录** - `vitals log` 记录各类数据
- [x] **数据查看** - `vitals show` 显示汇总
- [x] **数据导出** - `vitals export` 导出 JSON/CSV
- [x] **数据备份** - `vitals backup` 管理备份

#### 部署
- [x] **Docker 支持** - Dockerfile + docker-compose.yml
- [x] **环境变量配置** - 灵活的配置管理
- [x] **健康检查** - Docker 容器健康检查

### 待完善功能 🚧

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

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

#### 低优先级
- [ ] **国际化(i18n)** - 多语言支持
- [ ] **云同步** - 跨设备数据同步
- [ ] **社交功能** - 数据分享、好友挑战
- [ ] **智能建议** - 基于数据的个性化健康建议
- [ ] **Apple Health 集成** - 与 Apple Health 数据同步
- [ ] **深色模式** - UI 深色主题支持

### 已知问题 🐛

- [ ] 大量数据时列表加载性能需优化
- [ ] 部分页面在小屏幕上布局需要调整
- [ ] 书籍封面搜索有时无法找到匹配结果

## 更新日志

### 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