WeReadBoard/docs/V2_API.md

# v2 数据接口（/api/v2/*）

「阅间」新版前端的数据来源。实现在 `api_v2.py`（Flask Blueprint，注册于 `app.py`），
v1 的 `/api/*` 接口保持不变，两套接口可同时使用。

## 数据来源与优先级

| 数据 | 来源 | 说明 |
|------|------|------|
| 书架、书目 | 微信读书 `/shelf/sync`（实时，进程内缓存 10 分钟） | 字段含书名、作者、分类、封面、读完标记、最近阅读时间 |
| 阅读统计（周/月/年/总） | 微信读书 `/readdata/detail`（实时，缓存 5 分钟） | 时长趋势、阅读天数、读得最多、偏好分类/作者/出版社/时段/勋章/好友排行 |
| 阅读进度 | 本地 `notebooks` / `book_progress` 缓存优先，缺失时并发调用 `/book/getprogress` 补齐（缓存 10 分钟） | 用于书架卡片与详情页进度 |
| 笔记本与笔记 | 本地 `notebooks` 表 + 实时 `/book/bookmarklist`、`/review/list/mine` | 划线与想法正文实时获取 |
| 书籍详情 | 实时 `/book/info`、`/book/getprogress`、`/book/chapterinfo`、`/book/bestbookmarks`、`/review/list`、`/book/similar` | 逐项降级，单项失败不影响整页 |
| 搜索 / 推荐 | 实时 `/store/search`（按 scope 切换类型）、`/book/recommend` | |
| 阅读目标 | MySQL `reading_goals` / `reading_goal_books` | 数据库持久化；旧浏览器目标可手动导入 |

MySQL 不可用时，阅读数据接口仍可降级运行（返回 `degraded: true`）。阅读目标必须持久化，其接口返回 503，不退回浏览器保存。

## 接口清单

| 方法 | 路径 | 参数 | 说明 |
|------|------|------|------|
| GET | `/api/v2/status` | — | 连接状态、书架规模、数据快照时间 |
| GET | `/api/v2/shelf` | `tab=all\|reading\|done\|wish`、`keyword`、`limit`、`offset`、`progress=1` | 书架列表 + 书单 + 有声书 + 文章收藏入口（`progress=1` 为首屏书籍实时补拉进度） |
| GET | `/api/v2/dashboard` | `period=week\|month\|year\|overall` | 整页概览：趋势柱状图、四张统计卡、读得最多、偏好方向、时段分布、阅读画像、年度小结 |
| GET | `/api/v2/notebooks` | — | 笔记本概览（有笔记的书 + 划线/想法/书签数量） |
| GET | `/api/v2/notes` | `book_id`（`all` 表示聚合笔记最多的前 N 本）、`limit` | 划线与想法正文，按时间倒序 |
| GET | `/api/v2/book/<book_id>` | — | 书籍详情聚合：简介 + 进度 + 目录 + 我的笔记 + 热门划线 + 点评 + 相似推荐 |
| GET | `/api/v2/book/<book_id>/reviews` | `type=0\|1\|2\|3\|4`（全部/推荐/不行/最新/一般）、`count` | 公开点评（按类型筛选） |
| GET | `/api/v2/book/<book_id>/highlights` | `chapter_uid`（0=全书） | 热门划线（人数、章节、位置、跳转链接） |
| GET | `/api/v2/book/<book_id>/underline-thoughts` | `chapter_uid`、`range` | 某条划线下的他人想法 |
| GET | `/api/v2/thought/<review_id>` | — | 单条想法详情：正文、划线原文、点赞、评论 |
| GET | `/api/v2/archives` | — | 书架书单及成员书籍 |
| GET | `/api/v2/recommend` | `maxIdx` | 个性化推荐 |
| GET | `/api/v2/search` | `keyword`、`scope=all\|books\|author\|lists\|audio\|fulltext\|novel\|account\|article` | 书城检索（按分组归一为书籍/作者/书单） |
| POST | `/api/sync` | — | v1 已有：重新采集数据并迁移到 MySQL |

## 与微信读书接口的字段口径

### 阅读目标接口

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/v2/goals` | 返回 `{"goals":[...]}`，成员按书籍 ID 排序 |
| POST | `/api/v2/goals` | 新建，成功返回 201 和 `{"goal":{...}}` |
| PUT | `/api/v2/goals/<id>` | 整体替换目标和书目，返回 `{"goal":{...}}` |
| DELETE | `/api/v2/goals/<id>` | 删除目标及其成员，返回 `{"ok":true}` |
| POST | `/api/v2/goals/import` | 请求 `{"goals":[...]}`，返回 `{"imported":新增数量}` |

新建、编辑和导入中的目标字段一致：

```json
{"id":"goal-example","name":"秋季阅读","start":"2026-09-01","end":"2026-09-30","ids":["123","456"],"sources":["文学书单"]}
```

ID 和书籍 ID 为 1 至 64 字符的字符串；名称去除首尾空格后为 1 至 60 字符。日期必须为有效的 `YYYY-MM-DD`，年份为 1000 至 9999，结束日期不早于开始日期。`ids` 为非空字符串数组；`sources` 为字符串数组，省略时默认为空。PUT 请求体 ID 必须与路径一致。

书籍和来源去重，未知书籍 ID 仍保留。错误返回 `{"error":"中文说明"}`：400 参数非法、404 目标不存在、409 新建 ID 冲突、503 数据库不可用。导入不覆盖已有 ID，失败时回滚整个批次。迁移与验证方式见 [技术指南](technical-guide.md)。

### 阅读数据字段

- 评分：接口 `newRating` 为 0~1000，接口层换算成 `score = newRating / 100`（前端按设计稿公式展示为 `评分 XX/100`），详情页展示 `rating = newRating / 10`。
- 封面：设计稿使用 4 种示意底色（`c1`~`c4`），由 `book_id` 哈希稳定映射；真实封面 URL 保留在 `cover_url`。
- 进度：统一到 0~100 整数；`status` 口径为「读完=done、有最近阅读=reading、从未读过=wish」。
- 周/月维度的统计接口不回偏好画像字段，接口层用「总计」口径补齐，并在 `preference_source` 中标注来源。
- 「文章收藏」按接口规范计为 1 个书架条目（`books + albums + mp`）。