docs: 添加设置页面设计文档
包含用户管理和系统管理两个功能模块的完整设计： - 用户档案切换（家庭多用户支持） - 体重录入功能 - 数据清除功能（按时间/类型/全部） Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Rocky
229
docs/plans/2026-01-19-settings-page-design.md
Normal file
229
docs/plans/2026-01-19-settings-page-design.md
Normal file
@@ -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. **导航更新**
|
||||
- 在所有页面导航栏添加「设置」入口
|
||||
Reference in New Issue
Block a user