# 设置页面设计文档

## 概述

为 Vitals 健康管理应用添加设置页面，包含用户管理和系统管理两个功能模块。

### 需求

1. **用户管理** - 简单档案切换，支持多用户（如家庭成员）
2. **系统管理** - 体重录入和历史数据清除

---

## 一、数据模型变更

### 新增 User 模型

```python
# src/vitals/core/models.py

class User(BaseModel):
    id: int | None = None
    name: str                    # 用户名称，如"爸爸"、"妈妈"
    avatar: str | None = None    # 头像（可选，用于区分）
    created_at: datetime
    is_active: bool = True       # 当前激活的用户
```

### 数据库变更

1. **新增 `users` 表**：存储用户档案
2. **现有表添加 `user_id` 字段**：exercise、meal、sleep、weight、config 表都需要关联到具体用户
3. **默认用户迁移**：首次升级时，自动创建一个"默认用户"，将现有数据关联到该用户

### 数据隔离

- 切换用户后，所有页面只显示当前用户的数据
- 通过 Cookie 记录当前用户 ID
- API 请求自动根据当前用户过滤数据

---

## 二、页面 UI 结构

### 页面布局 (`/settings`)

```
┌─────────────────────────────────────────────────────┐
│  导航栏  [首页] [运动] [饮食] [睡眠] [体重] [报告] [⚙设置]  │
├─────────────────────────────────────────────────────┤
│                                                     │
│   [👤 用户管理]    [🔧 系统管理]    ← 标签页切换      │
│   ─────────────────────────────────────────────     │
│                                                     │
│   （标签页内容区域）                                  │
│                                                     │
└─────────────────────────────────────────────────────┘
```

### 用户管理标签页

```
┌─────────────────────────────────────────────────────┐
│  当前用户: [小明 ✓]                                  │
├─────────────────────────────────────────────────────┤
│  用户列表:                                          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │  👤     │ │  👤     │ │  👤     │ │   ＋    │   │
│  │  小明   │ │  小红   │ │  爸爸   │ │  添加   │   │
│  │ [切换]  │ │ [切换]  │ │ [切换]  │ │  用户   │   │
│  │ [编辑]  │ │ [编辑]  │ │ [编辑]  │ │         │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────────┘│
└─────────────────────────────────────────────────────┘
```

**交互说明**：
- 点击用户卡片的「切换」按钮，切换到该用户
- 当前激活用户显示勾选标记
- 「添加用户」打开弹窗创建新档案
- 「编辑」可修改名称或删除用户（删除需二次确认）

### 添加/编辑用户弹窗

```
┌──────────────────────────┐
│ 用户名称: [________]     │
│ [取消]  [保存]  [删除]   │
└──────────────────────────┘
```

---

## 三、系统管理标签页

### 布局

```
┌─────────────────────────────────────────────────────┐
│  [👤 用户管理]    [🔧 系统管理]                       │
│  ─────────────────────────────────────────────      │
│                                                     │
│  ┌─ 体重录入 ─────────────────────────────────────┐ │
│  │  当前用户: 小明                                 │ │
│  │  日期: [2026-01-19 ▼]  体重: [__] kg           │ │
│  │  体脂率: [__] % (选填)  备注: [________]       │ │
│  │                              [录入体重]        │ │
│  └───────────────────────────────────────────────┘ │
│                                                     │
│  ┌─ 数据清除 ─────────────────────────────────────┐ │
│  │  ⚠️ 警告：删除的数据无法恢复，请谨慎操作         │ │
│  │                                                │ │
│  │  清除方式:                                     │ │
│  │  ○ 按时间范围                                  │ │
│  │    从 [2026-01-01] 到 [2026-01-19]            │ │
│  │                                                │ │
│  │  ○ 按数据类型                                  │ │
│  │    □ 运动记录  □ 饮食记录  □ 睡眠记录  □ 体重  │ │
│  │                                                │ │
│  │  ○ 清除全部数据                                │ │
│  │                                                │ │
│  │                    [清除数据]  ← 红色警示按钮   │ │
│  └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```

### 删除确认弹窗

```
┌──────────────────────────────────────┐
│  ⚠️ 确认删除                          │
│                                      │
│  即将删除以下数据：                    │
│  • 用户：小明                         │
│  • 范围：2026-01-01 至 2026-01-19    │
│  • 类型：运动记录、饮食记录            │
│  • 共 45 条记录                       │
│                                      │
│  此操作不可撤销！                      │
│                                      │
│  请输入 "确认删除" 以继续：            │
│  [____________]                      │
│                                      │
│        [取消]    [删除]               │
└──────────────────────────────────────┘
```

**安全措施**：
- 删除前显示将被删除的记录数量
- 需要输入「确认删除」文字才能执行
- 删除按钮为红色警示样式

---

## 四、API 接口设计

### 用户管理 API

| 方法 | 路径 | 功能 |
|------|------|------|
| `GET` | `/api/users` | 获取所有用户列表 |
| `GET` | `/api/users/current` | 获取当前激活用户 |
| `POST` | `/api/users` | 创建新用户 |
| `PUT` | `/api/users/{id}` | 更新用户信息 |
| `DELETE` | `/api/users/{id}` | 删除用户（含其所有数据） |
| `POST` | `/api/users/{id}/switch` | 切换到指定用户 |

### 数据清除 API

| 方法 | 路径 | 功能 |
|------|------|------|
| `POST` | `/api/data/preview-delete` | 预览将删除的数据量 |
| `DELETE` | `/api/data/clear` | 执行数据清除 |

### 清除请求参数

```python
class DataClearRequest(BaseModel):
    user_id: int                          # 目标用户
    mode: str                             # "range" | "type" | "all"
    date_from: date | None = None         # 按时间范围
    date_to: date | None = None
    data_types: list[str] | None = None   # ["exercise", "meal", "sleep", "weight"]
    confirm_text: str                     # 必须为 "确认删除"
```

### 用户状态存储

使用 Cookie 存储当前用户 ID：
```
Cookie: vitals_current_user=1
```

- 所有现有 API 自动根据 Cookie 中的用户 ID 过滤数据
- 未设置 Cookie 时，使用默认用户（ID=1）

---

## 五、实现文件清单

### 需要修改的文件

| 文件 | 修改内容 |
|------|----------|
| `src/vitals/core/models.py` | 新增 `User` 模型和 `DataClearRequest` 模型 |
| `src/vitals/core/database.py` | 新增用户表、添加 `user_id` 字段、数据迁移、清除函数 |
| `src/vitals/web/app.py` | 新增 `/settings` 页面、用户管理 API、数据清除 API、修改现有 API 支持多用户 |

### 实现步骤

1. **数据库层**
   - 创建 `users` 表
   - 为 exercise/meal/sleep/weight/config 表添加 `user_id` 字段
   - 编写数据迁移逻辑（现有数据归属默认用户）
   - 实现用户 CRUD 函数
   - 实现数据清除函数

2. **API 层**
   - 实现用户管理接口
   - 实现数据清除接口
   - 修改现有接口支持 `user_id` 过滤

3. **前端页面**
   - 创建设置页面 HTML/CSS/JS
   - 实现标签页切换
   - 实现用户管理交互
   - 实现数据清除交互（含确认弹窗）

4. **导航更新**
   - 在所有页面导航栏添加「设置」入口