liweiliang0905@gmail.com
02426e0a59
UI 改造: - 首页采用深色科技风格 (Dark Tech) - Tailwind CSS + Glass Morphism 毛玻璃效果 - 左侧边栏导航 (PC端) / 底部导航 (移动端) - Material Symbols 图标 + Space Grotesk 字体 - Chart.js 深色主题适配 新功能: - Apple Health 步数同步 API (/api/steps) - 设置页面添加 iOS 快捷指令配置说明 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
275 lines
7.3 KiB
Markdown
275 lines
7.3 KiB
Markdown
# Vitals 代码结构地图
|
||
|
||
## 项目概览
|
||
|
||
Vitals 是一个本地优先的综合健康管理应用，支持运动、饮食、睡眠、体重、阅读等多维度健康数据记录与分析。
|
||
|
||
```
|
||
vitals/
|
||
├── src/vitals/ # 主要源代码
|
||
│ ├── cli.py # 命令行入口
|
||
│ ├── core/ # 核心业务逻辑
|
||
│ ├── vision/ # AI视觉识别模块
|
||
│ ├── web/ # Web应用 (FastAPI)
|
||
│ └── importers/ # 数据导入器
|
||
├── tests/ # 测试文件
|
||
├── scripts/ # 脚本工具
|
||
└── docs/ # 文档
|
||
```
|
||
|
||
---
|
||
|
||
## 核心模块详解
|
||
|
||
### 1. CLI 入口 (`cli.py`)
|
||
|
||
命令行界面，基于 Typer 构建。
|
||
|
||
| 命令 | 功能 |
|
||
|------|------|
|
||
| `vitals dashboard` | 启动 Web 仪表盘 |
|
||
| `vitals log` | 记录健康数据 |
|
||
| `vitals show` | 查看健康数据 |
|
||
| `vitals config` | 用户配置 |
|
||
| `vitals import` | 导入外部数据 |
|
||
| `vitals report` | 生成报告 |
|
||
| `vitals export` | 数据导出 |
|
||
| `vitals backup` | 数据备份 |
|
||
|
||
---
|
||
|
||
### 2. 核心业务 (`core/`)
|
||
|
||
#### `models.py` - 数据模型
|
||
```python
|
||
@dataclass
|
||
class Exercise # 运动记录
|
||
class Meal # 饮食记录
|
||
class Sleep # 睡眠记录
|
||
class Weight # 体重记录
|
||
class Reading # 阅读记录
|
||
class User # 用户
|
||
class UserConfig # 用户配置
|
||
class Invite # 邀请码
|
||
```
|
||
|
||
#### `database.py` - 数据库操作
|
||
- MySQL 连接池管理
|
||
- CRUD 操作封装
|
||
- 用户隔离支持
|
||
|
||
主要函数：
|
||
```python
|
||
init_db() # 初始化数据库表
|
||
get_connection() # 获取数据库连接
|
||
add_meal() / get_meals() # 饮食记录
|
||
add_exercise() / get_exercises() # 运动记录
|
||
add_sleep() / get_sleeps() # 睡眠记录
|
||
add_weight() / get_weights() # 体重记录
|
||
get_api_key() / set_api_key() # API Key 管理
|
||
```
|
||
|
||
#### `calories.py` - 卡路里计算
|
||
- 内置 94 种常见中文食物数据库
|
||
- 智能食物描述解析（支持中文数字、多种分隔符）
|
||
- 运动卡路里估算（基于 MET 代谢当量）
|
||
|
||
```python
|
||
estimate_meal_calories(description) # 估算餐食卡路里
|
||
estimate_exercise_calories(type, mins) # 估算运动消耗
|
||
parse_food_description(text) # 解析食物描述
|
||
```
|
||
|
||
#### `auth.py` - 认证模块
|
||
- JWT Token 认证
|
||
- 密码哈希 (bcrypt)
|
||
- 邀请码机制
|
||
|
||
#### `report.py` - 报告生成
|
||
- 周报/月报生成
|
||
- PDF 导出 (WeasyPrint)
|
||
- 数据可视化
|
||
|
||
#### `export.py` - 数据导出
|
||
- JSON / CSV 格式导出
|
||
- 数据备份与恢复
|
||
|
||
#### `backup.py` - 备份模块
|
||
- 自动备份
|
||
- 增量备份支持
|
||
|
||
---
|
||
|
||
### 3. AI 视觉识别 (`vision/`)
|
||
|
||
#### `analyzer.py` - 分析器基类
|
||
```python
|
||
class FoodAnalyzer:
|
||
def analyze(image_path) -> dict # 分析食物图片
|
||
|
||
class ClaudeFoodAnalyzer: # Claude Vision 实现
|
||
```
|
||
|
||
#### `providers/qwen.py` - 通义千问 VL
|
||
```python
|
||
class QwenVisionAnalyzer:
|
||
def analyze_image(image_path) # 图片识别
|
||
def analyze_text(description) # 文字识别 ← 新增功能
|
||
```
|
||
|
||
#### `providers/deepseek.py` - DeepSeek Vision
|
||
```python
|
||
class DeepSeekVisionAnalyzer:
|
||
def analyze_image(image_path)
|
||
def analyze_text(description)
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Web 应用 (`web/`)
|
||
|
||
#### `app.py` - FastAPI 应用 (5500+ 行)
|
||
|
||
**页面路由：**
|
||
| 路由 | 页面 |
|
||
|------|------|
|
||
| `/` | 首页仪表盘 |
|
||
| `/exercise` | 运动记录 |
|
||
| `/meal` | 饮食记录 |
|
||
| `/sleep` | 睡眠记录 |
|
||
| `/weight` | 体重记录 |
|
||
| `/reading` | 阅读记录 |
|
||
| `/report` | 健康报告 |
|
||
| `/settings` | 设置页面 |
|
||
| `/login` | 登录页面 |
|
||
|
||
**API 端点：**
|
||
|
||
| 方法 | 路由 | 功能 |
|
||
|------|------|------|
|
||
| POST | `/api/meal` | 添加饮食记录 |
|
||
| GET | `/api/meals` | 查询饮食记录 |
|
||
| POST | `/api/meal/recognize` | AI 食物识别 (图片/文字) |
|
||
| GET | `/api/meals/nutrition` | 营养统计 |
|
||
| POST | `/api/exercise` | 添加运动记录 |
|
||
| GET | `/api/exercises` | 查询运动记录 |
|
||
| POST | `/api/steps` | 同步步数（iOS 快捷指令调用） |
|
||
| GET | `/api/steps` | 查询步数记录 |
|
||
| GET | `/api/steps/today` | 获取今日步数 |
|
||
| POST | `/api/sleep` | 添加睡眠记录 |
|
||
| POST | `/api/weight` | 添加体重记录 |
|
||
| GET | `/api/config` | 获取用户配置 |
|
||
| POST | `/api/config` | 更新用户配置 |
|
||
| POST | `/api/login` | 用户登录 |
|
||
| POST | `/api/register` | 用户注册 |
|
||
|
||
**前端架构：**
|
||
- 纯原生 HTML/CSS/JavaScript
|
||
- Chart.js 图表库
|
||
- 响应式设计（PC/移动端适配）
|
||
|
||
---
|
||
|
||
### 5. 数据导入器 (`importers/`)
|
||
|
||
| 模块 | 功能 |
|
||
|------|------|
|
||
| `base.py` | 导入器基类 |
|
||
| `csv_importer.py` | CSV 通用导入 |
|
||
| `garmin.py` | Garmin 数据导入 |
|
||
| `codoon.py` | 咕咚数据导入 |
|
||
|
||
---
|
||
|
||
### 6. 测试 (`tests/`)
|
||
|
||
| 文件 | 测试内容 |
|
||
|------|----------|
|
||
| `test_calories.py` | 卡路里计算测试 |
|
||
| `test_database.py` | 数据库操作测试 |
|
||
| `test_models.py` | 数据模型测试 |
|
||
| `test_web.py` | Web API 测试 |
|
||
| `test_report.py` | 报告生成测试 |
|
||
| `test_export.py` | 导出功能测试 |
|
||
| `test_backup.py` | 备份功能测试 |
|
||
| `test_deepseek.py` | DeepSeek API 测试 |
|
||
|
||
---
|
||
|
||
## 数据库设计
|
||
|
||
### 主要表结构
|
||
|
||
```sql
|
||
-- 用户表
|
||
user (id, username, password_hash, email, created_at)
|
||
|
||
-- 运动记录
|
||
exercise (id, user_id, date, exercise_type, duration, calories, distance, notes)
|
||
|
||
-- 饮食记录
|
||
meal (id, user_id, date, meal_type, description, calories, protein, carbs, fat, photo_path, food_items)
|
||
|
||
-- 睡眠记录
|
||
sleep (id, user_id, date, bedtime, wake_time, duration, quality, notes)
|
||
|
||
-- 体重记录
|
||
weight (id, user_id, date, weight, body_fat, notes)
|
||
|
||
-- 阅读记录
|
||
reading (id, user_id, date, book_title, pages, duration, notes)
|
||
|
||
-- 步数记录
|
||
steps (id, user_id, date, steps, distance, calories, source, synced_at)
|
||
|
||
-- 用户配置
|
||
user_config (id, user_id, height, weight, age, gender, activity_level, goal)
|
||
|
||
-- API Keys
|
||
api_keys (id, user_id, provider, api_key, created_at)
|
||
|
||
-- 邀请码
|
||
invite (id, code, created_by, used_by, used_at, expires_at)
|
||
```
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 后端框架 | FastAPI + Uvicorn |
|
||
| 数据库 | MySQL 8 |
|
||
| CLI | Typer + Rich |
|
||
| AI 识别 | Qwen VL / DeepSeek / Claude |
|
||
| PDF 生成 | WeasyPrint |
|
||
| 前端 | 原生 HTML/CSS/JS + Chart.js |
|
||
| 认证 | JWT + bcrypt |
|
||
|
||
---
|
||
|
||
## 关键文件行数统计
|
||
|
||
| 文件 | 行数 | 说明 |
|
||
|------|------|------|
|
||
| `web/app.py` | 5500+ | Web 应用主体 |
|
||
| `core/database.py` | 800+ | 数据库操作 |
|
||
| `core/calories.py` | 333 | 卡路里计算 |
|
||
| `core/models.py` | 327 | 数据模型 |
|
||
| `vision/providers/qwen.py` | 185 | 通义千问识别 |
|
||
| `vision/providers/deepseek.py` | 176 | DeepSeek 识别 |
|
||
| `core/report.py` | 300+ | 报告生成 |
|
||
|
||
---
|
||
|
||
## 最近更新
|
||
|
||
- **Apple Health 步数同步**：支持通过 iOS 快捷指令同步 Apple Health 步数数据
|
||
- 数据库：新增 `steps` 表存储每日步数
|
||
- API：`/api/steps` (POST 同步, GET 查询), `/api/steps/today` (今日步数)
|
||
- 前端：运动页面显示今日步数卡片，设置页面提供 iOS 快捷指令配置说明
|
||
|
||
- **文字 AI 识别功能**：在饮食页面添加"文字AI识别"按钮，支持输入文字描述后自动识别卡路里
|
||
- 前端：`web/app.py` (第 5041 行按钮，第 5166 行函数)
|
||
- 后端：`/api/meal/recognize` 支持 `text` 参数
|