web/WeReadBoard
1
0 Fork 0
mirror of https://github.com/KingHWJ/WeReadBoard.git synced 2026-11-03 18:24:58 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
61d39519052d165e4e8293d837c23e07ade5a241
WeReadBoard/docs/PROJECT_FINAL_DOC.md
T
admin 92a48d14cd feat: 添加配置读取工具，支持从环境变量和 .env 文件加载 WEREAD_API_KEY 
fix: 修复启动脚本中的 Python 解释器路径识别
style: 更新样式以支持按钮最小宽度和灵活布局
docs: 添加项目最终文档，整合各类信息与说明
2026-07-17 22:11:27 +08:00

287 lines
9.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 微信读书数据看板最终文档
本文档用于替代 `.qoder/` 与 `.workbuddy/` 中分散的工具生成文档，作为当前仓库内的单一最终说明。内容以仓库现状为准，吸收了工具文档中的架构说明、接口说明、数据库分组、部署信息和迭代记录，同时剔除了已经过期或仅对工具自身有意义的中间信息。
## 1. 文档与目录约定
- 本文件是 `.qoder/repowiki` 与 `.workbuddy/memory` 的合并结果，也是这两个目录的人工可维护替代品。
- `.qoder/`、`.workbuddy/` 属于外部工具的中间产物，不参与 Git 管理。
- 深度技术细节仍保留在仓库原有文档中：
- [TECHNICAL_DOC.md](/Users/kinghwj/Codes/WeReadBoard/docs/TECHNICAL_DOC.md)
- [METADATA_DOC.md](/Users/kinghwj/Codes/WeReadBoard/docs/METADATA_DOC.md)
## 2. 项目定位
这是一个基于微信读书 Agent Gateway API 的个人阅读数据看板。系统将微信读书中的书架、阅读统计、笔记、推荐和搜索能力整合到一个本地运行的网站中，提供可视化图表、分页书架、笔记概览和按需详情查询。
当前实现采用：
- 后端：Flask + PyMySQL
- 前端：原生 HTML / CSS / JavaScript + ECharts
- 缓存与采集：SQLite
- 在线查询数据源：MySQL
- 外部能力：微信读书 Agent Gateway API
## 3. 当前仓库结构
核心文件与职责如下：
- [app.py](/Users/kinghwj/Codes/WeReadBoard/app.py)：Flask 后端服务，提供页面和 `/api/*` 接口。
- [fetch_data.py](/Users/kinghwj/Codes/WeReadBoard/fetch_data.py)：全量采集脚本，将微信读书数据写入 SQLite。
- [migrate_to_mysql.py](/Users/kinghwj/Codes/WeReadBoard/migrate_to_mysql.py)：将 SQLite 数据迁移到 MySQL。
- [schema_mysql.sql](/Users/kinghwj/Codes/WeReadBoard/schema_mysql.sql)：MySQL 31 张表建表语句。
- [config_utils.py](/Users/kinghwj/Codes/WeReadBoard/config_utils.py)：运行时配置读取工具。
- [start_server.sh](/Users/kinghwj/Codes/WeReadBoard/start_server.sh)：本地服务生命周期脚本。
- [templates/index.html](/Users/kinghwj/Codes/WeReadBoard/templates/index.html)：页面骨架。
- [static/js/app.js](/Users/kinghwj/Codes/WeReadBoard/static/js/app.js)：前端交互逻辑。
- [static/css/style.css](/Users/kinghwj/Codes/WeReadBoard/static/css/style.css)：主题、布局和组件样式。
## 4. 系统架构
系统采用“采集 -> 迁移 -> 展示 -> 按需回填”的模式：
1. `fetch_data.py` 从微信读书 API 拉取全量数据，落入本地 `weread.db`。
2. `migrate_to_mysql.py` 将 SQLite 中的数据按表迁移到 MySQL `weread_dashboard`。
3. `app.py` 从 MySQL 读取基础数据，向前端提供 REST API。
4. 部分详情型接口会在用户点击时再去调用微信读书 API，并把结果缓存回 MySQL。
5. 前端点击“刷新”时会调用 `/api/sync`，串行执行全量采集与迁移。
## 5. 运行时配置
### 5.1 微信读书 API Key
当前代码通过 [config_utils.py](/Users/kinghwj/Codes/WeReadBoard/config_utils.py) 读取 `WEREAD_API_KEY`，优先级如下：
1. 当前进程环境变量
2. 项目根目录 `.env`
3. 项目根目录 `.env.local`
4. 用户 shell 配置文件，如 `~/.zshrc`、`~/.zprofile`、`~/.bash_profile`
这层逻辑的目的，是避免“终端里已经 export，但服务进程没有继承”导致的误报。
### 5.2 MySQL 配置
当前 MySQL 连接配置仍写在代码中，`app.py` 与 `migrate_to_mysql.py` 各维护一份：
- host: `127.0.0.1`
- port: `3306`
- user: `root`
- password: `258963`
- database: `weread_dashboard`
这部分目前能工作，但仍属于后续值得继续抽离的技术债。
### 5.3 端口与启动
- 默认端口：`8080`
- 可选环境变量：`WEREAD_PORT`
- 启动脚本使用当前机器上可用的 `python3` 或 `python`
常用命令：
```bash
pip install -r requirements.txt
python3 app.py
./start_server.sh daemon
./start_server.sh stop
./start_server.sh status
```
## 6. 主要功能
### 6.1 概览与图表
- 总阅读时长、阅读天数、书架数量、笔记总数
- 年度阅读趋势
- 24 小时时段分布
- 偏好分类
- 偏好作者
- 阅读时长排行
### 6.2 书架
- 关键词搜索书名 / 作者
- 分类筛选与父子分类树
- 仅看已读完
- 分页浏览
- 一键刷新同步微信读书数据
### 6.3 笔记与想法
- 笔记本概览
- 点击书籍查看按章节整理的划线、想法和点评
- 想法详情页按类型筛选
### 6.4 发现能力
- 为你推荐
- 搜索书籍
- 推荐 / 搜索结果写回本地缓存
## 7. API 总览
当前后端接口主要分为四类：
### 7.1 系统接口
- `GET /api/health`：数据库健康检查
- `POST /api/sync`：执行全量采集与迁移
### 7.2 基础统计接口
- `GET /api/overview`
- `GET /api/yearly-trend`
- `GET /api/top-books`
- `GET /api/categories`
- `GET /api/authors`
- `GET /api/time-distribution`
- `GET /api/read-stats`
- `GET /api/archives`
### 7.3 书架与笔记接口
- `GET /api/shelf`
- `GET /api/notebooks`
### 7.4 按需详情 / 发现接口
- `GET /api/book/detail`
- `GET /api/book/notes`
- `GET /api/recommend`
- `GET /api/search`
接口返回格式、参数细节和字段说明，仍以 [TECHNICAL_DOC.md](/Users/kinghwj/Codes/WeReadBoard/docs/TECHNICAL_DOC.md) 为准。
## 8. 数据模型分组
当前 MySQL 使用 31 张表，按职责分为以下几组：
### 8.1 书架
- `books`
- `shelf_albums`
- `shelf_meta`
- `archives`
### 8.2 阅读统计
- `reading_stats`
- `read_times`
- `read_longest`
- `read_stat_items`
- `prefer_categories`
- `prefer_authors`
- `prefer_publishers`
- `prefer_cps`
- `prefer_books`
- `prefer_time`
- `read_rank`
- `medals`
- `year_reports`
### 8.3 笔记与书籍内容
- `notebooks`
- `book_highlights`
- `book_chapters`
- `book_reviews`
- `book_best_bookmarks`
- `book_underlines`
- `public_reviews`
### 8.4 书籍详情与进度
- `book_details`
- `book_progress`
### 8.5 推荐与搜索
- `recommended_books`
- `similar_books`
- `search_sessions`
- `search_results`
### 8.6 系统元信息
- `fetch_meta`
设计特征：
- MySQL 统一使用 `utf8mb4` + `InnoDB`
- 大多数时间字段采用“整型时间戳 + `_dt` 可读时间列”的双列模式
- 每张表统一维护 `created_at` 与 `updated_at`
完整字段说明见 [METADATA_DOC.md](/Users/kinghwj/Codes/WeReadBoard/docs/METADATA_DOC.md)。
## 9. 前端实现要点
当前前端是单页标签切换式界面，主要包括：
- 主题切换：支持明暗主题与本地持久化
- 图表懒加载：首次进入图表页时才初始化 ECharts
- 高清封面策略：低清 URL 自动升级为高清版本
- 书架筛选：关键词、分类、已读完、分页
- 想法详情页：从弹窗升级为独立页面
- 刷新同步：按钮触发 `/api/sync` 后再刷新书架数据
## 10. 部署与运维要点
- MySQL 需要先执行 [schema_mysql.sql](/Users/kinghwj/Codes/WeReadBoard/schema_mysql.sql) 建库建表。
- 初次准备数据时，执行：
```bash
python3 fetch_data.py
python3 migrate_to_mysql.py
```
- 日常使用可直接启动 Web 服务，前端点“刷新”会自动触发同步。
- 若样式或静态资源修改后页面无变化，优先检查：
- 服务是否使用了旧进程
- 浏览器是否使用了缓存
## 11. 合并后的迭代记录
以下内容来自 `.workbuddy/memory/2026-07-17.md`，但已按主题重整并去掉工具内部流程描述。
### 11.1 数据层演进
- 项目由 SQLite 展示切换为 MySQL 展示。
- 建表从 18 张表扩展到 31 张表，对齐官方接口字段。
- 迁移脚本重写，支持全量导入与时间字段转换。
### 11.2 后端演进
- 新增 `db_required` 装饰器统一管理数据库连接。
- 新增 `/api/health` 用于前端健康检查。
- 新增 `/api/sync`，打通“采集 -> 迁移 -> 展示”的刷新流程。
- 新增按需详情接口，失败时可回退本地缓存。
### 11.3 前端演进
- 新增明暗主题切换和图表配色适配。
- 阅读排行从卡片改为列表。
- 想法详情从弹窗改为独立页面。
- 新增顶部搜索框、书架分类树、推荐与搜索页。
- 书架增加刷新按钮，并在后续多次修复其加载态抖动问题。
### 11.4 启动与配置演进
- `start_server.sh` 从硬编码路径改为动态识别项目目录与解释器。
- `WEREAD_API_KEY` 从单纯依赖当前 shell 环境，演进为支持 `.env` 和 shell 配置回退读取。
## 12. 当前已知技术债
- MySQL 连接配置仍硬编码在 `app.py` 和 `migrate_to_mysql.py`，存在重复维护。
- `README.md` 仍保留较早期的 SQLite 描述，后续可与当前架构再对齐。
- 当前仍以本地脚本为主，未引入更正式的进程管理和自动化部署方案。
## 13. 结论
现在仓库内推荐遵循的文档与资料体系如下：
- 最终总说明：本文件 [PROJECT_FINAL_DOC.md](/Users/kinghwj/Codes/WeReadBoard/docs/PROJECT_FINAL_DOC.md)
- 技术展开说明：[TECHNICAL_DOC.md](/Users/kinghwj/Codes/WeReadBoard/docs/TECHNICAL_DOC.md)
- 表结构与字段说明：[METADATA_DOC.md](/Users/kinghwj/Codes/WeReadBoard/docs/METADATA_DOC.md)
`.qoder/` 与 `.workbuddy/` 继续保留给工具使用即可，但不再视为仓库的正式文档来源。
Reference in new issue View Git Blame Copy Permalink