# 阅读模块设计文档 **日期：** 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. 测试验证