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":新增数量}

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

{"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，失败时回滚整个批次。迁移与验证方式见 技术指南。

阅读数据字段

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