feat: 添加饮食文字AI识别功能与代码文档
- 饮食页面新增"文字AI识别"按钮，支持输入文字描述后自动识别卡路里 - 修复 database.py 中 time 模块导入冲突问题 - 新增 CODEMAPS.md 代码结构文档 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
263
docs/CODEMAPS.md
Normal file
263
docs/CODEMAPS.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# 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/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)
|
||||
|
||||
-- 用户配置
|
||||
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+ | 报告生成 |
|
||||
|
||||
---
|
||||
|
||||
## 最近更新
|
||||
|
||||
- **文字 AI 识别功能**：在饮食页面添加"文字AI识别"按钮，支持输入文字描述后自动识别卡路里
|
||||
- 前端：`web/app.py` (第 5041 行按钮，第 5166 行函数)
|
||||
- 后端：`/api/meal/recognize` 支持 `text` 参数
|
||||
Reference in New Issue
Block a user