Rocky/DDUp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b8f55f97a68687dab8bb4e9af373b87fc26481d6
DDUp/README.md
liweiliang0905@gmail.com 5de6cfc9de feat: 设置页面添加管理后台入口 
- 在账户区域添加"进入管理后台"按钮（仅管理员可见）
- 使用 localStorage 缓存用户信息确保显示正确

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-22 15:17:09 +08:00

466 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
Reference in New Issue View Git Blame Copy Permalink