diff --git a/docs/plans/2026-01-20-reading-module-design.md b/docs/plans/2026-01-20-reading-module-design.md new file mode 100644 index 0000000..6d92242 --- /dev/null +++ b/docs/plans/2026-01-20-reading-module-design.md @@ -0,0 +1,204 @@ +# 阅读模块设计文档 + +**日期：** 2026-01-20 +**状态：** 已确认，待实现 + +--- + +## 概述 + +为 Vitals 健康管理应用添加阅读习惯追踪功能，作为精神健康的一部分。用户可以记录阅读时长、书籍信息、读后感和心情，并在首页汇总展示。 + +--- + +## 功能需求 + +### 记录内容 +- **时长**：阅读分钟数 +- **书名**：输入书名，自动搜索封面 +- **封面**：通过 OpenLibrary API 自动获取（中文书为主） +- **作者**：自动获取或手动输入（可选） +- **心情**：5 个表情选择（😄😊😐😔😢） +- **读后感**：文字记录（可选） + +### 页面展示 +- **阅读页面**：书库视图，按书名归类展示 +- **首页汇总**：今日阅读时长、书名、心情 + +### 统计图表 +- 阅读时长趋势图（近 30 天） +- 心情分布饼图 +- 我的书库（封面网格） + +--- + +## 数据模型 + +### 阅读记录表 (reading) + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | INTEGER | 主键，自增 | +| user_id | INTEGER | 用户 ID | +| date | DATE | 阅读日期 | +| title | TEXT | 书名 | +| author | TEXT | 作者（可选） | +| cover_url | TEXT | 封面 URL | +| duration | INTEGER | 时长（分钟） | +| mood | TEXT | 心情（😄😊😐😔😢） | +| notes | TEXT | 读后感（可选） | + +--- + +## 页面设计 + +### 阅读页面布局 (/reading) + +``` +┌─────────────────────────────────────┐ +│ 导航栏（首页/运动/饮食/睡眠/...） │ +├─────────────────────────────────────┤ +│ 📚 我的阅读 │ +│ 本月已读 12.5 小时 · 3 本书在读 │ +├─────────────────────────────────────┤ +│ 阅读统计（图表区） │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ 时长趋势图 │ │ 心情分布 │ │ +│ │ (近30天) │ │ (饼图) │ │ +│ └─────────────┘ └─────────────┘ │ +├─────────────────────────────────────┤ +│ 我的书库 │ +│ ┌──────┐ ┌──────┐ ┌──────┐ │ +│ │ 封面 │ │ 封面 │ │ 封面 │ │ +│ │书名 │ │书名 │ │书名 │ │ +│ │5.2h │ │3.1h │ │4.2h │ │ +│ └──────┘ └──────┘ └──────┘ │ +├─────────────────────────────────────┤ +│ ＋ 记录阅读（按钮） │ +└─────────────────────────────────────┘ +``` + +### 记录阅读模态框 + +``` +┌─────────────────────────────────────┐ +│ 记录阅读 ✕ │ +├─────────────────────────────────────┤ +│ 书名 * │ +│ ┌─────────────────────────────┐ │ +│ │ 输入书名，自动搜索封面 │ │ +│ └─────────────────────────────┘ │ +│ ┌──────┐ │ +│ │ 封面 │ ← 自动获取 │ +│ └──────┘ │ +│ │ +│ 阅读时长 * 阅读日期 │ +│ ┌──────────┐ ┌──────────┐ │ +│ │ 30 分钟 │ │ 今天 │ │ +│ └──────────┘ └──────────┘ │ +│ │ +│ 今天的阅读心情 │ +│ 😄 😊 😐 😔 😢 │ +│ ○ ● ○ ○ ○ │ +│ │ +│ 读后感（选填） │ +│ ┌─────────────────────────────┐ │ +│ │ │ │ +│ └─────────────────────────────┘ │ +│ │ +│ [ 保存记录 ] │ +└─────────────────────────────────────┘ +``` + +### 首页汇总集成 + +``` +┌─────────────────────────────────────┐ +│ 📊 今日概览 │ +├─────────────────────────────────────┤ +│ 🏃 运动 🍽️ 饮食 😴 睡眠 │ +│ 45分钟 1280卡 7.5小时 │ +├─────────────────────────────────────┤ +│ ⚖️ 体重 📚 阅读 │ +│ 70.0kg 45分钟 😊 │ +│ 《三体》 │ +└─────────────────────────────────────┘ +``` + +--- + +## API 设计 + +### 新增端点 + +| 端点 | 方法 | 说明 | +|------|------|------| +| `/api/reading` | GET | 获取阅读记录（支持 ?days=N） | +| `/api/reading` | POST | 添加阅读记录 | +| `/api/reading/{id}` | DELETE | 删除记录 | +| `/api/reading/today` | GET | 今日阅读摘要 | +| `/api/reading/stats` | GET | 阅读统计（时长趋势、心情分布） | +| `/api/books/search` | GET | 搜索书籍封面（OpenLibrary） | +| `/reading` | GET | 阅读页面 HTML | + +### 首页改动 + +- 仅修改首页前端 HTML，新增调用 `/api/reading/today` +- **不修改** `/api/today`、`/api/week` 接口 + +--- + +## 技术实现 + +### 文件改动 + +| 文件 | 改动 | +|------|------| +| `src/vitals/core/models.py` | 新增 `Reading` dataclass | +| `src/vitals/core/database.py` | 新增 `reading` 表 + CRUD 函数 | +| `src/vitals/web/app.py` | 新增 API 端点 + 阅读页面 HTML + 导航更新 | + +### 书籍封面获取 + +- **数据源**：OpenLibrary API（免费、无需 Key） +- **搜索接口**：`https://openlibrary.org/search.json?q={书名}` +- **封面接口**：`https://covers.openlibrary.org/b/id/{cover_id}-M.jpg` +- **防抖处理**：输入 500ms 后触发搜索 +- **本地优先**：已记录过的书名优先从本地匹配 + +### 交互细节 + +- 点击书籍封面展开该书的阅读历史 +- 心情选择使用表情图标点选 +- 时长输入支持快捷选择（15/30/45/60 分钟） + +--- + +## 设计系统 + +沿用 Vitals 现有设计系统： + +| 元素 | 值 | +|------|------| +| Primary | `#3B82F6` | +| Secondary | `#60A5FA` | +| CTA | `#F97316` | +| Background | `#F8FAFC` | +| Text | `#1E293B` | +| Headings | Lora | +| Body | Raleway | +| Style | Vibrant & Block-based | + +--- + +## 实现步骤 + +1. 新增 `Reading` 数据模型 +2. 新增 `reading` 数据库表和 CRUD 函数 +3. 新增阅读相关 API 端点 +4. 新增书籍搜索 API（OpenLibrary） +5. 创建阅读页面 HTML（书库视图 + 统计图表） +6. 创建记录阅读模态框 +7. 更新所有页面导航栏添加「阅读」链接 +8. 更新首页前端获取阅读摘要 +9. 测试验证