# 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 业务逻辑（仅改数据库层和权限检查）