docs: 更新 README 反映 MySQL 迁移和 H5 适配功能

- 更新快速启动说明,添加 MySQL 环境变量配置
- 更新环境变量表格,添加 MySQL 相关配置项
- 更新技术栈说明(SQLite → MySQL 8.0)
- 更新项目结构,添加迁移脚本说明
- 添加功能清单:MySQL 数据库支持、移动端 H5 适配

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-01-23 18:41:50 +08:00
parent 733d737413
commit 18e0668941

View File

@@ -64,7 +64,14 @@ docker-compose up -d
# 安装依赖
pip install -e .
# 设置环境变量
# 设置 MySQL 环境变量
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=vitals
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=vitals
# 设置应用环境变量
export ADMIN_USERNAME=admin
export ADMIN_PASSWORD=your_password
export JWT_SECRET=$(openssl rand -hex 32)
@@ -273,16 +280,21 @@ pip install -e .
| 变量 | 必填 | 说明 |
|------|------|------|
| `MYSQL_HOST` | 是 | MySQL 服务器地址(默认 `localhost` |
| `MYSQL_PORT` | 否 | MySQL 端口(默认 `3306` |
| `MYSQL_USER` | 是 | MySQL 用户名 |
| `MYSQL_PASSWORD` | 是 | MySQL 密码 |
| `MYSQL_DATABASE` | 是 | MySQL 数据库名(默认 `vitals` |
| `MYSQL_ROOT_PASSWORD` | 是 | MySQL root 密码Docker 部署时需要) |
| `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
- **后端**: Python, FastAPI, MySQL 8.0
- **前端**: HTML, CSS, JavaScript, Chart.js
- **认证**: JWT (PyJWT), bcrypt
- **部署**: Docker, Docker Compose
@@ -309,7 +321,7 @@ vitals/
├── src/vitals/
│ ├── core/
│ │ ├── models.py # 数据模型User, Invite, Exercise, Meal...
│ │ ├── database.py # 数据库操作
│ │ ├── database.py # MySQL 数据库操作(连接池管理)
│ │ ├── auth.py # JWT 认证、密码哈希
│ │ ├── backup.py # 数据库备份
│ │ ├── export.py # 数据导出导入
@@ -322,12 +334,14 @@ vitals/
│ ├── web/
│ │ └── app.py # FastAPI 应用
│ └── cli.py # 命令行工具
├── scripts/
│ └── migrate_sqlite_to_mysql.py # SQLite 到 MySQL 迁移脚本
├── tests/ # 测试文件
├── docs/
│ ├── context/ # 开发上下文
│ └── plans/ # 设计文档
├── Dockerfile # Docker 镜像配置
├── docker-compose.yml # Docker Compose 配置
├── docker-compose.yml # Docker Compose + MySQL 配置
├── .env.example # 环境变量模板
├── pyproject.toml # Python 项目配置
└── README.md
@@ -401,6 +415,14 @@ vitals/
- [x] **Docker 支持** - Dockerfile + docker-compose.yml
- [x] **环境变量配置** - 灵活的配置管理
- [x] **健康检查** - Docker 容器健康检查
- [x] **MySQL 数据库** - MySQL 8.0 连接池,支持数据迁移
#### 移动端 H5 适配
- [x] **响应式布局** - 所有页面适配移动端屏幕768px/400px 断点)
- [x] **底部 Tab 导航** - 移动端专属底部导航栏,支持"更多"菜单
- [x] **触控优化** - 按钮和交互元素符合 44px/48px 触控标准
- [x] **iOS 安全区域** - 支持 iPhone 刘海屏和底部横条
- [x] **全页面适配** - 登录/注册、首页、运动、饮食、睡眠、体重、阅读、报告、设置、管理页面
### 待完善功能 🚧
@@ -413,7 +435,7 @@ vitals/
- [ ] **月度报告** - PDF 报告生成功能(已有框架,需完善)
- [ ] **目标设定** - 运动目标、饮食目标、体重目标的设定和追踪
- [ ] **数据统计增强** - 更丰富的图表和趋势分析
- [ ] **移动端优化** - 响应式设计改进,更好的移动端体验
- [x] **移动端优化** - 响应式设计改进,全部页面已适配移动端
- [ ] **离线支持** - PWA 支持,离线数据缓存
#### 低优先级
@@ -427,11 +449,68 @@ vitals/
### 已知问题 🐛
- [ ] 大量数据时列表加载性能需优化
- [ ] 部分页面在小屏幕上布局需要调整
- [ ] 书籍封面搜索有时无法找到匹配结果
## 数据迁移
### 从 SQLite 迁移到 MySQL
如果你有旧版本的 SQLite 数据需要迁移,可以使用迁移脚本:
```bash
# 1. 确保 MySQL 服务已启动并配置好环境变量
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=vitals
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=vitals
# 2. 运行迁移脚本(默认从 ~/.vitals/vitals.db 读取)
python scripts/migrate_sqlite_to_mysql.py
# 或指定 SQLite 数据库路径
VITALS_DB_PATH=/path/to/old/vitals.db python scripts/migrate_sqlite_to_mysql.py
```
迁移脚本会自动处理:
- 用户数据users
- 运动记录exercise
- 饮食记录meal
- 睡眠记录sleep
- 体重记录weight
- 阅读记录reading
- 邀请码invites
- 配置数据config
## 更新日志
### 2026-01-23
#### 🗄️ MySQL 数据库迁移
- **数据库切换** - 从 SQLite 迁移到 MySQL 8.0
- **连接池支持** - 使用 MySQL 连接池管理,提升性能
- **Docker 集成** - docker-compose 自动配置 MySQL 服务
- **数据迁移脚本** - 提供 SQLite 到 MySQL 的数据迁移工具
- **类型兼容性修复** - 添加 `_parse_datetime``_parse_date``_parse_time` 辅助函数,处理 MySQL 返回原生类型
#### 🔒 用户权限增强
- **API 权限控制** - `/api/users` 非管理员仅返回自己,`/api/users/{id}` 非管理员只能查询自己(否则 403
- **导航栏隐藏** - 非管理员用户隐藏「管理」入口
#### 📱 移动端 H5 全页面适配
- **登录/注册页面** - 移动端布局优化,触摸目标符合标准
- **首页 Dashboard** - 卡片布局适配,底部导航栏
- **运动/饮食页面** - 表格转卡片列表,表单输入增大
- **睡眠/体重/阅读页面** - 响应式布局48px 输入框
- **报告页面** - 按钮触摸目标优化(48px),底部导航
- **设置页面** - 响应式布局,支持手机浏览
- **管理页面** - 表格改为卡片列表(data-label)
- **底部 Tab 导航** - 固定底部导航栏 + "更多"菜单
- **iOS 安全区域** - 支持刘海屏和底部横条
#### 🌐 网络访问
- **绑定地址优化** - 默认绑定 `0.0.0.0`,支持局域网访问和移动端真机测试
### 2026-01-22
#### 🔐 混合认证方案优化