docs: 添加 H5/MySQL/权限增强设计方案
- H5 移动端适配：响应式 CSS + 底部 Tab 导航 - MySQL 迁移：mysql-connector-python 裸 SQL - 用户权限：非管理员仅能看到自己 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
209
docs/plans/2026-01-23-h5-mysql-permissions-design.md
Normal file
209
docs/plans/2026-01-23-h5-mysql-permissions-design.md
Normal file
@@ -0,0 +1,209 @@
|
|||||||
|
# Vitals 改造设计方案
|
||||||
|
|
||||||
|
> 日期: 2026-01-23
|
||||||
|
> 状态: 已确认
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
本次改造包含三个主要目标：
|
||||||
|
1. **H5 移动端适配** - 所有页面优化为移动端友好
|
||||||
|
2. **MySQL 数据库迁移** - 从 SQLite 迁移到 MySQL
|
||||||
|
3. **用户权限增强** - 非管理员仅能看到自己
|
||||||
|
|
||||||
|
## 一、技术决策
|
||||||
|
|
||||||
|
| 决策项 | 选择 | 理由 |
|
||||||
|
|--------|------|------|
|
||||||
|
| 前端框架 | 保持 Python 渲染 HTML | 改动最小，无需重写前端 |
|
||||||
|
| 数据库驱动 | mysql-connector-python 裸 SQL | 保持现有查询结构 |
|
||||||
|
| CSS 方案 | 响应式 CSS + 媒体查询 | 无需引入新框架 |
|
||||||
|
|
||||||
|
## 二、H5 移动端设计系统
|
||||||
|
|
||||||
|
### 2.1 配色方案
|
||||||
|
|
||||||
|
| 元素 | 色值 | 用途 |
|
||||||
|
|------|------|------|
|
||||||
|
| Primary | `#3B82F6` | 主色调、链接、选中状态 |
|
||||||
|
| Secondary | `#60A5FA` | 辅助色、次要元素 |
|
||||||
|
| CTA | `#F97316` | 主要操作按钮、强调 |
|
||||||
|
| Background | `#F8FAFC` | 页面背景 |
|
||||||
|
| Text | `#1E293B` | 正文文字 |
|
||||||
|
|
||||||
|
### 2.2 字体
|
||||||
|
|
||||||
|
```css
|
||||||
|
@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600;700&family=Fira+Sans:wght@300;400;500;600;700&display=swap');
|
||||||
|
|
||||||
|
--font-heading: 'Fira Sans', sans-serif;
|
||||||
|
--font-body: 'Fira Sans', sans-serif;
|
||||||
|
--font-mono: 'Fira Code', monospace;
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.3 响应式断点
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* 移动优先策略 */
|
||||||
|
默认样式 → 手机 (< 768px)
|
||||||
|
@media (min-width: 768px) → 平板
|
||||||
|
@media (min-width: 1024px) → 桌面
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.4 移动端 UX 规范
|
||||||
|
|
||||||
|
| 规范 | 要求 |
|
||||||
|
|------|------|
|
||||||
|
| 触摸目标 | 最小 44x44px |
|
||||||
|
| 触摸间距 | 元素间至少 8px |
|
||||||
|
| 输入框 | 使用正确的 `inputmode` 属性 |
|
||||||
|
| 点击优化 | `touch-action: manipulation` |
|
||||||
|
| 固定元素 | 使用 `z-index: 50` |
|
||||||
|
| 安全区域 | 底部导航考虑 `safe-area-inset-bottom` |
|
||||||
|
|
||||||
|
### 2.5 导航栏改造
|
||||||
|
|
||||||
|
**桌面端 (≥768px)：** 保持顶部水平导航
|
||||||
|
|
||||||
|
**移动端 (<768px)：** 底部 Tab 栏
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────┐
|
||||||
|
│ 页面内容区域 │
|
||||||
|
│ │
|
||||||
|
├─────────────────────────────────────┤
|
||||||
|
│ 🏠 🏃 🍽️ 😴 ⚙️ │
|
||||||
|
│ 首页 运动 饮食 睡眠 更多 │
|
||||||
|
└─────────────────────────────────────┘
|
||||||
|
|
||||||
|
"更多" 展开菜单：体重、阅读、报告、设置、管理(仅管理员)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.6 页面适配清单
|
||||||
|
|
||||||
|
| 页面 | 适配要点 |
|
||||||
|
|------|----------|
|
||||||
|
| 登录/注册 | 全屏表单，大按钮 |
|
||||||
|
| 首页 Dashboard | 卡片单列堆叠，数据卡片全宽 |
|
||||||
|
| 数据录入页 | 表单全宽，输入框加大 |
|
||||||
|
| 数据列表 | 表格改卡片列表 |
|
||||||
|
| 图表 | 响应式宽度 100% |
|
||||||
|
| 设置/管理 | 单列列表布局 |
|
||||||
|
|
||||||
|
## 三、MySQL 数据库迁移
|
||||||
|
|
||||||
|
### 3.1 SQLite vs MySQL 差异
|
||||||
|
|
||||||
|
| 功能 | SQLite | MySQL |
|
||||||
|
|------|--------|-------|
|
||||||
|
| 占位符 | `?` | `%s` |
|
||||||
|
| 自增 | `AUTOINCREMENT` | `AUTO_INCREMENT` |
|
||||||
|
| 时间函数 | `datetime('now')` | `NOW()` |
|
||||||
|
| 字符串拼接 | `\|\|` | `CONCAT()` |
|
||||||
|
|
||||||
|
### 3.2 配置方式
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 环境变量
|
||||||
|
MYSQL_HOST=localhost
|
||||||
|
MYSQL_PORT=3306
|
||||||
|
MYSQL_USER=vitals
|
||||||
|
MYSQL_PASSWORD=xxx
|
||||||
|
MYSQL_DATABASE=vitals
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 database.py 改动清单
|
||||||
|
|
||||||
|
1. 添加 MySQL 连接池管理
|
||||||
|
2. 所有 `?` 占位符改为 `%s`
|
||||||
|
3. `AUTOINCREMENT` 改为 `AUTO_INCREMENT`
|
||||||
|
4. 时间函数调整
|
||||||
|
5. 字段类型映射 (TEXT → VARCHAR/TEXT)
|
||||||
|
|
||||||
|
### 3.4 表结构映射
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- users 表
|
||||||
|
CREATE TABLE users (
|
||||||
|
id INT PRIMARY KEY AUTO_INCREMENT,
|
||||||
|
name VARCHAR(255) NOT NULL UNIQUE,
|
||||||
|
created_at DATETIME NOT NULL,
|
||||||
|
is_active TINYINT DEFAULT 0,
|
||||||
|
gender VARCHAR(10),
|
||||||
|
height_cm FLOAT,
|
||||||
|
weight_kg FLOAT,
|
||||||
|
age INT,
|
||||||
|
password_hash VARCHAR(255),
|
||||||
|
email VARCHAR(255),
|
||||||
|
is_admin TINYINT DEFAULT 0,
|
||||||
|
is_disabled TINYINT DEFAULT 0
|
||||||
|
);
|
||||||
|
|
||||||
|
-- 其他表类似处理
|
||||||
|
```
|
||||||
|
|
||||||
|
## 四、用户权限增强
|
||||||
|
|
||||||
|
### 4.1 权限模型
|
||||||
|
|
||||||
|
```
|
||||||
|
管理员 (is_admin=1)
|
||||||
|
├── 查看所有用户列表
|
||||||
|
├── 启用/禁用用户
|
||||||
|
├── 删除用户
|
||||||
|
├── 管理邀请码
|
||||||
|
└── 访问 /admin 页面
|
||||||
|
|
||||||
|
普通用户 (is_admin=0)
|
||||||
|
├── 仅能看到自己的用户信息
|
||||||
|
├── 无法访问 /admin 页面
|
||||||
|
└── 无法看到其他用户存在
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 API 接口改动
|
||||||
|
|
||||||
|
| 接口 | 当前行为 | 改动后 |
|
||||||
|
|------|----------|--------|
|
||||||
|
| `GET /api/users` | 返回所有用户 | 非管理员仅返回自己 |
|
||||||
|
| `GET /api/users/{id}` | 返回指定用户 | 非管理员只能查自己，否则 403 |
|
||||||
|
|
||||||
|
### 4.3 页面访问控制
|
||||||
|
|
||||||
|
| 页面 | 管理员 | 普通用户 |
|
||||||
|
|------|--------|----------|
|
||||||
|
| `/admin` | 完整功能 | 重定向到首页 |
|
||||||
|
| `/settings` | 完整功能 | 仅自己信息 |
|
||||||
|
| 导航栏「管理」 | 显示 | 隐藏 |
|
||||||
|
|
||||||
|
## 五、实施阶段
|
||||||
|
|
||||||
|
### 阶段 1: MySQL 迁移
|
||||||
|
- [ ] 改造 database.py 支持 MySQL
|
||||||
|
- [ ] 编写数据迁移脚本
|
||||||
|
- [ ] 测试所有数据库操作
|
||||||
|
|
||||||
|
### 阶段 2: 用户权限
|
||||||
|
- [ ] 修改 /api/users 接口
|
||||||
|
- [ ] 修改 /api/users/{id} 接口
|
||||||
|
- [ ] 隐藏非管理员的管理入口
|
||||||
|
|
||||||
|
### 阶段 3: H5 移动端适配
|
||||||
|
- [ ] 全局样式基础设施（viewport, 字体, 变量）
|
||||||
|
- [ ] 底部导航栏组件
|
||||||
|
- [ ] 逐页适配（11个页面）
|
||||||
|
|
||||||
|
### 阶段 4: 测试验证
|
||||||
|
- [ ] 移动端真机测试
|
||||||
|
- [ ] MySQL 生产环境测试
|
||||||
|
- [ ] 权限功能测试
|
||||||
|
|
||||||
|
## 六、不变的部分
|
||||||
|
|
||||||
|
以下模块保持不变，不在本次改造范围：
|
||||||
|
- `models.py` - 数据模型定义
|
||||||
|
- `auth.py` - 认证逻辑
|
||||||
|
- `vision/` - AI 食物识别
|
||||||
|
- `importers/` - 数据导入
|
||||||
|
- `backup.py` - 备份功能
|
||||||
|
- `export.py` - 导出功能
|
||||||
|
- `report.py` - 报告生成
|
||||||
|
- `calories.py` - 热量计算
|
||||||
|
- API 业务逻辑（仅改数据库层和权限检查）
|
||||||
Reference in New Issue
Block a user