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
阅读目标	浏览器 localStorage（key weread-goals-v2）	与设计稿一致，不落库

MySQL 不可用时接口仍可用（返回 degraded: true），依赖本地缓存的字段会退化为实时接口结果。

接口清单

方法	路径	参数	说明
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

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

• 评分：接口 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）。