mirror of
https://github.com/KingHWJ/WeReadBoard.git
synced 2026-11-03 18:24:58 +08:00
110 lines
3.9 KiB
Markdown
110 lines
3.9 KiB
Markdown
# 微信读书数据展示网站
|
||
|
||
基于微信读书 API 的个人读书数据展示网站。
|
||
|
||
- **「阅间」看板（当前默认前端）**：沿用设计稿的视觉与交互，数据来自 `/api/reading/*` 实时聚合接口，见 `docs/API.md`。
|
||
- **旧版仪表盘（已归档）**：原 ECharts 单页仪表盘，完整备份在 `legacy/classic/`。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── fetch_data.py # 数据采集脚本（从微信读书 API 拉取数据到 SQLite）
|
||
├── app.py # Flask 后端服务（旧接口 + 注册当前看板接口）
|
||
├── reading_api.py # 当前数据接口层（/api/reading/*，供「阅间」前端使用）
|
||
├── start_dashboard.sh # 启动脚本（端口可用 PORT 覆盖）
|
||
├── legacy/classic/ # 旧版前端备份（index.html / style.css / app.js）
|
||
├── weread.db # SQLite 数据库（运行 fetch_data.py 后生成）
|
||
├── requirements.txt # Python 依赖
|
||
├── docs/troubleshooting.md # 日常维护与故障排查
|
||
├── templates/
|
||
│ └── index.html # 「阅间」前端页面
|
||
└── static/
|
||
├── css/styles.css # 当前样式（设计稿原样）
|
||
├── css/style.css # 旧版样式（保留）
|
||
└── js/
|
||
├── weapi.js # 当前数据层（封装 /api/reading/*）
|
||
└── app.js # 当前交互逻辑
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 设置环境变量
|
||
|
||
```bash
|
||
export WEREAD_API_KEY=wrk-xxxxxxxx # 你的微信读书 API Key
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 采集数据
|
||
|
||
```bash
|
||
python fetch_data.py
|
||
```
|
||
|
||
将拉取书架、阅读统计、笔记等数据并存入 `weread.db`。
|
||
|
||
### 4. 启动网站
|
||
|
||
```bash
|
||
./start_dashboard.sh # 默认 8770 端口
|
||
PORT=8080 ./start_dashboard.sh # 或指定端口
|
||
```
|
||
|
||
也可以直接 `python app.py`（默认 8080，可用环境变量 `PORT` 覆盖），
|
||
然后访问 http://127.0.0.1:8770 查看「阅间」看板。
|
||
|
||
> 当前看板的书架、统计、推荐、搜索等数据实时来自微信读书接口；
|
||
> 未运行 `fetch_data.py` 时也能使用，只有进度/笔记等局部数据会缺少缓存加速。
|
||
|
||
## 自动部署
|
||
|
||
服务器部署使用根目录的 `deploy.sh`，由 GitHub Webhook 通知服务器触发：
|
||
|
||
```bash
|
||
DEPLOY_BRANCH=master ./deploy.sh
|
||
```
|
||
|
||
脚本只允许拉取 `master` 分支，随后自动创建 `.venv`、安装 `requirements.txt`、执行数据库迁移并重启 `weread.service`。GitHub Actions 只做代码验证，不再通过 SSH 登录服务器；详细配置见 [master 自动部署](docs/deploy-master.md)。
|
||
|
||
运行端口、Python 环境、HTTPS 证书和接口故障的诊断方法见 [日常维护与故障排查](docs/troubleshooting.md)。
|
||
|
||
当前应用版本保存在根目录 `VERSION`，网页底部和登录页会显示该版本号。
|
||
|
||
## 功能模块
|
||
|
||
| 模块 | 说明 |
|
||
|------|------|
|
||
| 总览仪表盘 | 累计阅读时长、阅读天数、书架藏书数、笔记总数 |
|
||
| 年度趋势图 | 各年度阅读时长柱状图 |
|
||
| 时段分布 | 24 小时阅读时段分布折线图 |
|
||
| 偏好分类 | 阅读分类占比饼图 |
|
||
| 偏好作者 | 阅读最多的作者排行 |
|
||
| 读书排行 | 阅读时长最久的书籍 TOP 20 |
|
||
| 书架 | 每页 48 本，底部页码分页，支持按最近阅读、书名或作者排序 |
|
||
| 笔记概览 | 有笔记的书籍及划线/想法/书签统计 |
|
||
|
||
## 数据库表结构
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| books | 书架书籍信息 |
|
||
| reading_stats | 阅读统计概要（overall/annually） |
|
||
| read_times | 阅读时长时间序列 |
|
||
| read_longest | 阅读时长最久的书籍 |
|
||
| prefer_categories | 偏好分类 |
|
||
| prefer_authors | 偏好作者 |
|
||
| prefer_time | 24 小时阅读时段分布 |
|
||
| notebooks | 笔记本概览 |
|
||
| read_stat_items | 阅读统计摘要项 |
|
||
| archives | 书单/归档 |
|
||
|
||
## 更新数据
|
||
|
||
随时重新运行 `python fetch_data.py` 即可刷新本地数据。
|