mirror of
https://github.com/KingHWJ/WeReadBoard.git
synced 2026-11-03 18:24:58 +08:00
feat: switch to MySQL, add Chinese comments, health check, and technical docs
1. 数据源切换至 MySQL： - app.py 从 SQLite 切换到 PyMySQL，所有 API 读取 MySQL weread_dashboard 数据库 - 新增 db_required 装饰器统一管理数据库连接和异常处理 - 新增 /api/health 健康检查接口，检测 MySQL 连接状态 - MySQL 连接失败时返回 HTTP 503 和告警信息 - 修复 fetched_at 字段 Unix 时间戳到 MySQL TIMESTAMP 的兼容问题 2. 前端数据库连接告警： - 页面加载时优先调用 /api/health 检查 MySQL 连接 - 连接失败时显示固定告警横幅，阻止后续数据加载 - CSS 告警横幅样式（黄色背景、下滑动画） 3. 代码中文注释： - app.py：所有函数、API 接口、工具函数添加完整中文文档注释 - fetch_data.py：所有 SQLite 建表语句添加列级中文注释 - migrate_to_mysql.py：保留已有中文注释 4. 技术文档与元数据文档： - docs/TECHNICAL_DOC.md：项目概述、系统架构、API 设计、部署指南 - docs/METADATA_DOC.md：18 张表完整字段说明、索引、表关系、数据类型规范
This commit is contained in:
admin committed
1 parent
72e9971a69
commit
507b9c5704
8 files changed
+1805
-436
No files matched your search
@@ -0,0 +1,331 @@
|
||||
# 微信读书数据展示网站 - 技术文档
|
||||
|
||||
> 版本：1.2.0 | 更新时间：2026-07-17 | 作者：WorkBuddy
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
### 1.1 项目简介
|
||||
|
||||
本项目是一个个人读书数据展示网站，数据来源于微信读书。通过微信读书 API 拉取用户的阅读数据（书架、阅读统计、笔记等），存入本地数据库，并通过 Web 仪表盘进行可视化展示。
|
||||
|
||||
### 1.2 核心功能
|
||||
|
||||
| 模块 | 功能说明 |
|
||||
|------|----------|
|
||||
| 数据采集 | 从微信读书 API 拉取书架、阅读统计、笔记本数据，存入本地数据库 |
|
||||
| 总览仪表盘 | 累计阅读时长、阅读天数、藏书量、笔记数等核心指标 |
|
||||
| 数据图表 | 年度阅读趋势（柱状图）、24h 时段分布（折线图）、偏好分类（饼图）、偏好作者（条形图） |
|
||||
| 读书排行 | 阅读时长最久的 20 本书卡片展示 |
|
||||
| 书架 | 404 本书的网格展示，支持分类筛选和"仅看已读完" |
|
||||
| 笔记概览 | 有笔记的书籍列表，点击查看划线和想法详情 |
|
||||
| 书籍详情 | 点击书架书籍弹出详情（书名、作者、出版社、ISBN、评分、阅读进度） |
|
||||
| 笔记详情 | 点击笔记书籍查看划线（按章节分组）和想法/点评 |
|
||||
| 推荐页面 | 个性化推荐书籍 + 关键词搜索，数据入库 |
|
||||
|
||||
### 1.3 技术栈
|
||||
|
||||
| 层级 | 技术 | 说明 |
|
||||
|------|------|------|
|
||||
| 前端 | HTML5 + CSS3 + 原生 JavaScript | 无框架依赖，轻量高效 |
|
||||
| 图表 | ECharts 5.5.0 | 年度趋势、时段分布、分类饼图、作者排行 |
|
||||
| 后端 | Python Flask | 轻量级 Web 框架，提供 RESTful API |
|
||||
| 数据库 | MySQL 5.7+（主）/ SQLite（采集） | MySQL 为生产数据库，SQLite 用于数据采集中间存储 |
|
||||
| 数据采集 | 微信读书 Agent Gateway API | 通过 weread-skills 技能提供的 API 接口 |
|
||||
| 版本控制 | Git | dev 分支开发，master 分支发布，遵循 Conventional Commits |
|
||||
|
||||
---
|
||||
|
||||
## 2. 系统架构
|
||||
|
||||
### 2.1 整体架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 用户浏览器（前端） │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ 总览仪表盘│ │ 数据图表 │ │ 书架列表 │ │ 推荐搜索 │ │
|
||||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ └───────────┴─────┬─────┴───────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────▼────────┐ │
|
||||
│ │ 健康检查模块 │ │
|
||||
│ │ (MySQL 连接检测) │ │
|
||||
│ └────────┬────────┘ │
|
||||
└─────────────────────────┼───────────────────────────────┘
|
||||
│ HTTP / RESTful API
|
||||
┌─────────────────────────┼───────────────────────────────┐
|
||||
│ Flask 后端服务 │
|
||||
│ │ │
|
||||
│ ┌──────────────────────▼──────────────────────┐ │
|
||||
│ │ API 路由层 │ │
|
||||
│ │ /api/overview /api/shelf /api/book/detail │ │
|
||||
│ │ /api/recommend /api/search /api/health ... │ │
|
||||
│ └──────────────────────┬──────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────────────────▼──────────────────────┐ │
|
||||
│ │ db_required 装饰器 │ │
|
||||
│ │ (连接管理 + 错误处理 + 503 告警) │ │
|
||||
│ └──────────────────────┬──────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────────────────▼──────────────────────┐ │
|
||||
│ │ PyMySQL 数据访问层 │ │
|
||||
│ └───────────┬──────────────────┬──────────────┘ │
|
||||
│ │ │ │
|
||||
│ ┌───────────▼─────┐ ┌────────▼─────────┐ │
|
||||
│ │ MySQL 数据库 │ │ 微信读书 API 代理 │ │
|
||||
│ │ weread_dashboard│ │ (按需获取+入库) │ │
|
||||
│ └─────────────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────┼───────────────────────────────┐
|
||||
│ 数据采集层（独立运行） │
|
||||
│ ┌──────────────────────▼──────────────────────┐ │
|
||||
│ │ fetch_data.py 采集脚本 │ │
|
||||
│ │ 拉取书架/统计/笔记 → SQLite → migrate_to_mysql│ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 数据流设计
|
||||
|
||||
```
|
||||
微信读书 API
|
||||
│
|
||||
▼
|
||||
fetch_data.py（采集脚本）
|
||||
│
|
||||
▼
|
||||
weread.db（SQLite 中间存储）
|
||||
│
|
||||
▼
|
||||
migrate_to_mysql.py（迁移脚本）
|
||||
│
|
||||
▼
|
||||
MySQL weread_dashboard（生产数据库）
|
||||
│
|
||||
▼
|
||||
Flask app.py（后端服务，端口 8080）
|
||||
│
|
||||
▼
|
||||
前端页面（ECharts 可视化）
|
||||
```
|
||||
|
||||
**按需数据流**（用户点击书籍/笔记时）：
|
||||
|
||||
```
|
||||
用户点击 → Flask API → 微信读书 API（实时获取）→ 入库 MySQL → 返回前端
|
||||
↓（API 失败时）
|
||||
从 MySQL 读取缓存数据 → 返回前端
|
||||
```
|
||||
|
||||
### 2.3 目录结构
|
||||
|
||||
```
|
||||
weread-dashboard/
|
||||
├── app.py # Flask 后端服务（MySQL 数据源）
|
||||
├── fetch_data.py # 数据采集脚本（SQLite）
|
||||
├── migrate_to_mysql.py # SQLite → MySQL 数据迁移脚本
|
||||
├── schema_mysql.sql # MySQL 建表语句（含中文注释）
|
||||
├── requirements.txt # Python 依赖
|
||||
├── weread.db # SQLite 数据库文件（采集中间存储）
|
||||
├── README.md # 项目说明
|
||||
├── docs/ # 文档目录
|
||||
│ ├── TECHNICAL_DOC.md # 技术文档（本文件）
|
||||
│ └── METADATA_DOC.md # 元数据文档
|
||||
├── templates/
|
||||
│ └── index.html # 前端页面
|
||||
└── static/
|
||||
├── css/
|
||||
│ └── style.css # 样式文件
|
||||
└── js/
|
||||
└── app.js # 前端逻辑
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 后端 API 设计
|
||||
|
||||
### 3.1 API 接口列表
|
||||
|
||||
| 接口 | 方法 | 说明 | 数据来源 |
|
||||
|------|------|------|----------|
|
||||
| `/api/health` | GET | 健康检查（MySQL 连接状态） | MySQL |
|
||||
| `/api/overview` | GET | 总览数据（核心指标） | MySQL |
|
||||
| `/api/yearly-trend` | GET | 年度阅读时长时间序列 | MySQL |
|
||||
| `/api/top-books` | GET | 阅读时长排行 TOP 20 | MySQL |
|
||||
| `/api/categories` | GET | 偏好分类 | MySQL |
|
||||
| `/api/authors` | GET | 偏好作者 TOP 20 | MySQL |
|
||||
| `/api/time-distribution` | GET | 24 小时时段分布 | MySQL |
|
||||
| `/api/shelf` | GET | 书架列表（分页） | MySQL |
|
||||
| `/api/notebooks` | GET | 笔记本概览 | MySQL |
|
||||
| `/api/read-stats` | GET | 阅读统计摘要 | MySQL |
|
||||
| `/api/archives` | GET | 书单列表 | MySQL |
|
||||
| `/api/book/detail` | GET | 书籍详情（按需） | 微信读书 API + MySQL |
|
||||
| `/api/book/notes` | GET | 笔记详情（按需） | 微信读书 API + MySQL |
|
||||
| `/api/recommend` | GET | 个性化推荐（按需） | 微信读书 API + MySQL |
|
||||
| `/api/search` | GET | 搜索书籍（按需） | 微信读书 API + MySQL |
|
||||
|
||||
### 3.2 接口详情
|
||||
|
||||
#### 3.2.1 健康检查
|
||||
|
||||
```
|
||||
GET /api/health
|
||||
```
|
||||
|
||||
**响应（正常）**：
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"database": "connected",
|
||||
"message": "MySQL 连接正常"
|
||||
}
|
||||
```
|
||||
|
||||
**响应（异常，HTTP 503）**：
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"database": "disconnected",
|
||||
"message": "MySQL 连接失败: ..."
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.2 总览数据
|
||||
|
||||
```
|
||||
GET /api/overview
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"total_read_time": 1223850,
|
||||
"total_read_time_str": "339小时57分钟",
|
||||
"read_days": 304,
|
||||
"year_read_time": 849029,
|
||||
"year_read_time_str": "235小时50分钟",
|
||||
"year_read_days": 198,
|
||||
"shelf_count": 404,
|
||||
"finished_count": 12,
|
||||
"notebook_count": 32,
|
||||
"total_notes": 1709,
|
||||
"regist_time": "2024-03-15",
|
||||
"last_read_time": "2026-07-17",
|
||||
"fetch_time": "2026-07-17 09:50:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2.3 书架列表（分页）
|
||||
|
||||
```
|
||||
GET /api/shelf?page=1&per_page=60&category=文学&finished=1
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| page | int | 1 | 页码 |
|
||||
| per_page | int | 60 | 每页数量 |
|
||||
| category | string | "" | 分类筛选（模糊匹配） |
|
||||
| finished | string | "0" | "1"=只看已读完 |
|
||||
|
||||
#### 3.2.4 书籍详情（按需）
|
||||
|
||||
```
|
||||
GET /api/book/detail?book_id=34615967
|
||||
```
|
||||
|
||||
实时调用微信读书 `/book/info` + `/book/getprogress` API，入库后返回。API 失败时回退到数据库缓存。
|
||||
|
||||
#### 3.2.5 错误处理
|
||||
|
||||
所有 API 接口在 MySQL 连接失败时统一返回：
|
||||
|
||||
```
|
||||
HTTP 503 Service Unavailable
|
||||
{
|
||||
"error": "数据库连接失败",
|
||||
"detail": "具体错误信息",
|
||||
"alert": "MySQL 数据库无法连接，请检查 MySQL 服务是否已启动。"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 关键设计决策
|
||||
|
||||
### 4.1 数据库选择
|
||||
|
||||
- **生产环境使用 MySQL**：支持并发访问、事务管理、完善的权限体系
|
||||
- **采集层使用 SQLite**：轻量级，无需额外服务，适合单机数据采集
|
||||
- **迁移脚本桥接**：`migrate_to_mysql.py` 负责 SQLite → MySQL 的数据同步
|
||||
|
||||
### 4.2 按需获取策略
|
||||
|
||||
书籍详情、笔记详情、推荐、搜索等数据采用**按需获取**策略：
|
||||
- 用户点击时实时调用微信读书 API
|
||||
- 获取成功后入库 MySQL 缓存
|
||||
- API 调用失败时自动回退到数据库缓存
|
||||
- 避免初始化时大量 API 调用，提升用户体验
|
||||
|
||||
### 4.3 健康检查与告警机制
|
||||
|
||||
- 后端提供 `/api/health` 接口检测 MySQL 连接状态
|
||||
- 前端页面加载时首先调用健康检查
|
||||
- 连接失败时显示固定告警横幅，阻止后续数据加载
|
||||
- 使用 `db_required` 装饰器统一处理数据库连接异常
|
||||
|
||||
### 4.4 Git 分支策略
|
||||
|
||||
- **dev 分支**：日常开发，功能迭代
|
||||
- **master 分支**：稳定发布版本，通过 `--no-ff` 合并 dev
|
||||
- 提交信息遵循 **Conventional Commits** 规范（`feat:` / `fix:` / `merge:`）
|
||||
|
||||
---
|
||||
|
||||
## 5. 部署与运行
|
||||
|
||||
### 5.1 环境要求
|
||||
|
||||
- Python 3.13+
|
||||
- MySQL 5.7+
|
||||
- 微信读书 API Key（通过 `WEREAD_API_KEY` 环境变量配置）
|
||||
|
||||
### 5.2 启动步骤
|
||||
|
||||
```bash
|
||||
# 1. 设置微信读书 API Key
|
||||
export WEREAD_API_KEY=wrk-xxxxxxxx
|
||||
|
||||
# 2. 安装 Python 依赖
|
||||
pip install flask pymysql
|
||||
|
||||
# 3. 启动 MySQL 服务
|
||||
sudo /usr/local/mysql/support-files/mysql.server start
|
||||
|
||||
# 4. 创建数据库并建表
|
||||
mysql -u root -p < schema_mysql.sql
|
||||
|
||||
# 5. 采集数据（首次）
|
||||
python fetch_data.py
|
||||
|
||||
# 6. 迁移数据到 MySQL
|
||||
python migrate_to_mysql.py
|
||||
|
||||
# 7. 启动 Web 服务
|
||||
python app.py
|
||||
# 访问 http://127.0.0.1:8080
|
||||
```
|
||||
|
||||
### 5.3 数据更新
|
||||
|
||||
```bash
|
||||
# 重新采集最新数据
|
||||
python fetch_data.py
|
||||
|
||||
# 同步到 MySQL
|
||||
python migrate_to_mysql.py
|
||||
```
|
||||
Reference in new issue
Block a user