DDUp/docs/plans/2026-01-19-settings-page-design.md

设置页面设计文档

概述

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

需求

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

---

一、数据模型变更

新增 User 模型

# 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	执行数据清除

清除请求参数

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. 导航更新

   • 在所有页面导航栏添加「设置」入口