# 微信读书数据看板最终文档

本文档用于替代 `.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/` 继续保留给工具使用即可，但不再视为仓库的正式文档来源。