DDUp/docs/plans/2026-01-20-reading-module-design.md

阅读模块设计文档

日期： 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. 测试验证