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
69bfe3ce0e445f0d30fd315e5eecc38826432e65
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

9.1 KiB
Raw Blame History

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

本文档用于替代 .qoder/ 与 .workbuddy/ 中分散的工具生成文档，作为当前仓库内的单一最终说明。内容以仓库现状为准，吸收了工具文档中的架构说明、接口说明、数据库分组、部署信息和迭代记录，同时剔除了已经过期或仅对工具自身有意义的中间信息。

1. 文档与目录约定

  • 本文件是 .qoder/repowiki 与 .workbuddy/memory 的合并结果，也是这两个目录的人工可维护替代品。
  • .qoder/、.workbuddy/ 属于外部工具的中间产物，不参与 Git 管理。
  • 深度技术细节仍保留在仓库原有文档中：

2. 项目定位

这是一个基于微信读书 Agent Gateway API 的个人阅读数据看板。系统将微信读书中的书架、阅读统计、笔记、推荐和搜索能力整合到一个本地运行的网站中，提供可视化图表、分页书架、笔记概览和按需详情查询。

当前实现采用：

  • 后端：Flask + PyMySQL
  • 前端：原生 HTML / CSS / JavaScript + ECharts
  • 缓存与采集：SQLite
  • 在线查询数据源：MySQL
  • 外部能力：微信读书 Agent Gateway API

3. 当前仓库结构

核心文件与职责如下：

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 读取 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

常用命令：

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 为准。

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。

9. 前端实现要点

当前前端是单页标签切换式界面，主要包括：

  • 主题切换：支持明暗主题与本地持久化
  • 图表懒加载：首次进入图表页时才初始化 ECharts
  • 高清封面策略：低清 URL 自动升级为高清版本
  • 书架筛选：关键词、分类、已读完、分页
  • 想法详情页：从弹窗升级为独立页面
  • 刷新同步：按钮触发 /api/sync 后再刷新书架数据

10. 部署与运维要点

  • MySQL 需要先执行 schema_mysql.sql 建库建表。
  • 初次准备数据时，执行：
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. 结论

现在仓库内推荐遵循的文档与资料体系如下：

.qoder/ 与 .workbuddy/ 继续保留给工具使用即可，但不再视为仓库的正式文档来源。

Reference in new issue View Git Blame Copy Permalink