# 微信读书数据展示网站

基于微信读书 API 的个人读书数据展示网站。

- **v2「阅间」看板（当前默认前端）**：沿用设计稿的视觉与交互，数据来自 `/api/v2/*` 实时聚合接口，见 `docs/V2_API.md`。
- **v1 仪表盘（已归档）**：原 ECharts 单页仪表盘，完整备份在 `legacy/v1/`。

## 项目结构

```
.
├── fetch_data.py          # 数据采集脚本（从微信读书 API 拉取数据到 SQLite）
├── app.py                 # Flask 后端服务（v1 接口 + 注册 v2 Blueprint）
├── api_v2.py              # v2 数据接口层（/api/v2/*，供「阅间」前端使用）
├── start_dashboard.sh     # 启动脚本（端口可用 PORT 覆盖）
├── legacy/v1/             # v1 前端备份（index.html / style.css / app.js）
├── weread.db              # SQLite 数据库（运行 fetch_data.py 后生成）
├── requirements.txt       # Python 依赖
├── templates/
│   └── index.html         # 「阅间」前端页面（v2 设计稿）
└── static/
    ├── css/styles.css     # v2 样式（设计稿原样）
    ├── css/style.css      # v1 样式（保留）
    └── js/
        ├── weapi.js       # v2 数据层（封装 /api/v2/*）
        └── app.js         # v2 交互逻辑
```

## 快速开始

### 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 查看「阅间」看板。

> v2 的书架、统计、推荐、搜索等数据实时来自微信读书接口；
> 未运行 `fetch_data.py` 时也能使用，只有进度/笔记等局部数据会缺少缓存加速。

## 自动部署

服务器部署使用根目录的 `deploy.sh`：

```bash
DEPLOY_BRANCH=dev ./deploy.sh
```

脚本会拉取指定分支，自动创建 `.venv`，安装 `requirements.txt`，执行数据库迁移，然后重启 `weread.service`。GitHub Actions 配置在 `.github/workflows/deploy.yml`，默认监听 `dev` 分支。

## 功能模块

| 模块 | 说明 |
|------|------|
| 总览仪表盘 | 累计阅读时长、阅读天数、书架藏书数、笔记总数 |
| 年度趋势图 | 各年度阅读时长柱状图 |
| 时段分布 | 24 小时阅读时段分布折线图 |
| 偏好分类 | 阅读分类占比饼图 |
| 偏好作者 | 阅读最多的作者排行 |
| 读书排行 | 阅读时长最久的书籍 TOP 20 |
| 书架 | 全部书架书籍展示，支持分类筛选和已读完筛选 |
| 笔记概览 | 有笔记的书籍及划线/想法/书签统计 |

## 数据库表结构

| 表名 | 说明 |
|------|------|
| 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` 即可刷新本地数据。