diff --git a/docs/plans/2026-01-19-settings-page-design.md b/docs/plans/2026-01-19-settings-page-design.md new file mode 100644 index 0000000..51bb941 --- /dev/null +++ b/docs/plans/2026-01-19-settings-page-design.md @@ -0,0 +1,229 @@ +# 设置页面设计文档 + +## 概述 + +为 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. **导航更新** + - 在所有页面导航栏添加「设置」入口