docs: 添加阅读模块设计文档
This commit is contained in:
Rocky
204
docs/plans/2026-01-20-reading-module-design.md
Normal file
204
docs/plans/2026-01-20-reading-module-design.md
Normal file
@@ -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. 测试验证
|
||||
Reference in New Issue
Block a user