WeReadBoard/docs/feature-checklist.md

# 阅间功能目标清单

> 创建日期：2026-09-11。本文先于本轮 Demo 开发建立，是后续实现、验收和追加需求的统一清单。

当前正式看板已接入真实接口；静态 Demo 仅作为历史设计稿保留。

## 使用方式

- 功能编号固定，后续需求追加新编号，不复用或删除旧编号。
- 分别维护「Demo 状态」与「真实接入状态」。假数据交互完成，不等于接口或正式功能完成。
- 状态使用：待实现、进行中、已验证、待接口验证、暂不支持。
- 实现后记录文件和函数或元素位置、验收结果；业务口径变化时同步更新规则与变更记录。
- 当前范围为正式看板接入真实数据；历史 Demo 仅保留交互样例。

## 已确认业务口径

| 编号 | 规则 |
|---|---|
| R01 | 合并阅读概览与阅读统计，统计在概览内展示，不设置重复导航。 |
| R02 | 支持多个阅读目标，每个目标有名称、开始日期、结束日期。结束日期不得早于开始日期。 |
| R03 | 目标可添加具体书籍、一个或多个书单，允许混合选择。 |
| R04 | 同一目标内按书籍 ID 去重；同一本书可属于多个目标。 |
| R05 | 已读完的书直接计为完成，不要求在目标时间范围内读完，不做重读。 |
| R06 | 完成率 = 已读完书籍数 / 去重后目标书籍数。创建目标至少选一本；空目标展示未开始，不除零。 |
| R07 | 时间范围仅安排计划和提示状态，不改变书籍是否读完。全部读完优先显示已完成；否则按未开始、进行中、已到期展示。 |
| R08 | 本版把书单当前成员加入目标并展示来源，保存时提示「加入当前书目」。书单后续变动不自动增删目标书籍；自动跟随属于后续待讨论项。 |
| R09 | Demo 目标保存在当前浏览器，刷新保留；不写回微信读书。现有文档没有目标写回接口。 |
| R10 | 接入时按接口已读完状态判断，不把进度 1 当作完成：书架 finishReading=1；独立进度需要 progress=100 且存在 finishTime。冲突、缺失数据需处理，不伪造已读状态。 |
| R11 | 书架条目数 = books.length + albums.length + (mp 非空 ? 1 : 0)。有声专辑「已完结」不是用户「已读完」。 |
| R12 | 笔记总数 = 划线数 + 想法/点评数 + 书签数。公开点评不计入个人笔记；书签目前仅有数量，无内容。 |
| R13 | 时间戳显示 YYYY-MM-DD；时长按秒转换为小时/分钟；评分按对应接口说明转换，不能混用百分制、五分制。 |
| R14 | 演示数据与真实数据明确区分。无 deepLink 不拼接阅读链接。可选字段缺失不当作 0，也不补造内容。 |

## 功能目标与追踪

以下位置已按本轮实现回填。函数名作为稳定定位依据，行号仅对应本次版本。

| ID | 功能与验收标准 | Demo 状态 | 真实接入状态 | 代码位置 |
|---|---|---|---|---|
| F01 | 五个入口：概览、书架、目标、笔记、发现；暗亮切换及移动适配 | 已验证（示例） | 不涉及接口 | `web-demo/app.js:54` `navigate`; `web-demo/app.js:30` `setTheme` |
| F02 | 概览内切换周/月/年/总计，展示时长、天数、日均、排行、偏好 | 已验证（示例） | 待实现 | `web-demo/app.js:85` `renderOverview` |
| F03 | 多目标列表、名称、时间范围、封面组合、完成率、到期状态 | 已验证（示例） | 本地功能，待正式持久化 | `web-demo/app.js:76` `renderGoals`; `web-demo/app.js:67` `goalMetrics` |
| F04 | 创建与编辑目标，校验日期和非空内容；刷新保留 | 已验证（示例） | 本地功能，待正式持久化 | `web-demo/app.js:122` `openGoalEditor`; `web-demo/app.js:138` `saveGoal` |
| F05 | 目标混合选择单书与书单，去重，已读直接计完成 | 已验证（示例） | 待接真实书籍状态 | `web-demo/app.js:131` `selectedGoalBooks`; `web-demo/app.js:67` `goalMetrics` |
| F06 | 目标详情查看成员、来源、单本进度；编辑移除成员 | 已验证（示例） | 待接真实书籍状态 | `web-demo/app.js:118` `openGoalDetail`; `web-demo/app.js:122` `openGoalEditor` |
| F07 | 我的书架：在读/已读/想读、书单、有声书和文章收藏入口 | 已验证（示例） | 待实现 | `web-demo/app.js:105` `renderShelf` |
| F08 | 我的书单列表与详情；从书单添加目标 | 已验证（示例） | 待实现 | `web-demo/app.js:104` `renderLists`; `web-demo/app.js:113` `openList` |
| F09 | 发现页：书籍/书单搜索、公开书单详情示意、空结果 | 已验证（示例） | 搜索待实现；公开书单成员待接口验证 | `web-demo/app.js:158` `renderDiscover`; `web-demo/app.js:113` `openList` |
| F10 | 书籍详情：信息、阅读进度、目录；加入目标 | 已验证（示例） | 待实现 | `web-demo/app.js:192` `openBook`; `web-demo/app.js:197` `renderBookTab` |
| F11 | 笔记本、划线与个人想法、书签数量、按书过滤、内容导出 | 内容/导出预览已验证；文件下载待验证 | 待实现；书签内容暂不支持 | `web-demo/app.js:177` `renderNotes`; `web-demo/app.js:184` `exportNotes` |
| F12 | 热门划线、章节热度、划线下想法及想法详情 | 已验证（示例） | 待实现 | `web-demo/app.js:197` `renderBookTab`; `web-demo/app.js:208` `openThought` |
| F13 | 公开点评筛选、点评详情，与个人笔记分离 | 已验证（示例） | 待实现 | `web-demo/app.js:197` `renderBookTab`; `web-demo/app.js:208` `openThought` |
| F14 | 个性化推荐和相似书推荐，可查详情和加入目标 | 已验证（示例） | 待实现 | `web-demo/app.js:158` `renderDiscover`; `web-demo/app.js:197` `renderBookTab` |
| F15 | 搜索其余类型：作者、网文、听书、全文、公众号、文章、综合 | 已验证（示例） | 待实现；非书籍回包结构需实测 | `web-demo/app.js:158` `renderDiscover` |
| F16 | 数据状态：加载、空、失败及重试；演示来源常驻 | 已验证（示例） | 待实现 | `web-demo/app.js:158` `renderDiscover` |
| F17 | API Key 仅服务端使用；版本上报、升级中断、错误转换、分页 | 不属于本轮 Demo | 待实现 | 后续核对 `app.py` 和 `fetch_data.py`，复用现有服务端能力 |
| F18 | 可选统计：阅读时段、作者/出版社/版权方、阅读听书比例、好友排行、勋章、年报 | 已验证（示例） | 待实现；按实际返回字段显示 | `web-demo/app.js:85` `renderOverview` |

## 全部文档接口的落点

依据本地 weread-skills 1.0.4 能力文档。未调用实时 `/_list`，因此此表是文档已知能力，不宣称已发现网关所有实际接口。

| 接口 | 使用场景 | 约束与后续接入要求 |
|---|---|---|
| /_list | 接入前核对网关可用接口 | 获取后补齐本清单；不可将未验证能力标完成 |
| /shelf/sync | 书架、我的书单、专辑、文章收藏 | archive 包含名称与 bookIds；mp 仅入口，不是文章内容 |
| /store/search | 综合、电子书、网文、听书、作者、全文、书单、公众号、文章 | 显式 scope；分页看 hasMore/searchIdx；书单成员结构待验证 |
| /book/info | 详情资料与评分 | 按返回字段展示，不补造 ISBN 等信息 |
| /book/chapterinfo | 目录与章节选择 | 使用 chapterUid，保留层级和付费状态 |
| /book/getprogress | 书籍进度、已读状态 | 进度 0–100；时长秒；最近阅读优先加载，避免全书架逐本请求 |
| /readdata/detail | 概览全部阅读统计 | 自然周期；总量用 totalReadTime；日均按自然日；preferTime 从 6 点开始；可选数据缺失时隐藏 |
| /user/notebooks | 笔记本与数量 | count + lastSort 分页；总数含书签 |
| /book/bookmarklist | 划线内容 | 不含书签内容 |
| /review/list/mine | 个人想法与点评 | 与划线合并导出；使用 bookid 参数及 synckey 分页 |
| /book/underlines | 章节划线热度 | 只有人数/位置等统计，不含文本 |
| /book/bestbookmarks | 热门划线 | 固定前 20 条，不支持分页 |
| /book/readreviews | 划线下想法 | 使用返回 range、chapterUid；每个 range 独立分页 |
| /review/single | 想法、点评详情 | 富文本正式接入时需净化后渲染 |
| /review/list | 公开点评及筛选 | 双层 review 包装；20/40/60/80/100 对应 1–5 星 |
| /book/recommend | 为你推荐 | 使用 searchIdx 分页 |
| /book/similar | 相似推荐 | 显式 count/maxIdx；后续携带 sessionId |

## 验收记录

2026-09-11 在本地浏览器实测，结果如下。均为假数据 Demo 验证，不代表真实接口验收。

| 场景 | 输入或操作 | 实际结果 |
|---|---|---|
| 导航合并 | 查看侧边栏 | 共 5 个入口，无独立阅读统计 |
| 日期校验 | 开始 2026-09-12，结束 2026-09-01 | 原生表单阻止保存，提示结束日期过早 |
| 非空校验 | 只填写名称与日期，未选择书籍 | 提示至少选择一本书或一个书单 |
| 混合去重 | 单独选《活着》，再加入含它的三本书单 | 已选 3 本，1 本已读完，保存显示 33% |
| 保存刷新 | 保存“周末慢读清单”后刷新 | 名称、日期、3 本书与进度保留 |
| 编辑移除 | 从上述目标移除《人生海海》 | 剩余 2 本，1 本完成，显示 50% |
| 已有目标去重 | 重复加入“心理学，向内走一程”书单 | 原目标仍为 3 本，1 本完成 |
| 书单查询 | 发现页选择书单，输入“心理学” | 仅显示匹配书单，详情可加入已有目标 |
| 书籍内容 | 三体 → 目录 → 示例章节 2 → 划线想法 → 详情 | 展示对应入口及示例内容 |
| 点评筛选 | 读者点评选择“一般” | 仅显示三星的一般点评示例 |
| 相似推荐 | 在书籍详情选择相似推荐 | 展示其他 4 本书，可进入详情 |
| 笔记边界 | 全部笔记 → 书签数量 | 总数 10，划线 2、想法 2、书签 6；不显示书签内容 |
| 导出预览 | 导出全部笔记 | 生成 4 条内容：2 条划线、2 条想法，包含演示声明 |
| 文件下载 | 等待浏览器下载事件 | 事件超时，未确认落盘；保留可复制预览和下载链接，后续实测下载 |
| 搜索类型 | 推荐、作者、网文、听书、全文、公众号、文章、综合 | 均切换为对应类型示意 |
| 失败重试 | 预览状态选失败，再点击重试 | 显示失败状态，重试恢复结果 |
| 统计周期 | 切换月、年、总计、周 | 图表与总量切换；年度最终核对为 128小时42分钟 |
| 书架边界 | 我的书单、有声书、文章收藏 | 展示书单、有声信息和收藏入口边界说明 |
| 主题与响应式 | 1440px 桌面、390px 手机，暗亮切换 | 桌面双列目标；手机单列且编辑弹窗可滚动，无横向溢出 |
| 静态检查 | Node 语法检查 app.js 和 demo-data.js | 均通过 |

可重复手工验收：新建空内容目标检查提示；选择《活着》和文学书单验证 1/3；刷新验证保存；移除一本验证 1/2。不要把验收用目标写入未来真实账号。

## 变更记录

| 日期 | 变更 | 依据 |
|---|---|---|
| 2026-09-11 | 建立清单；确认多目标、日期范围、单书与书单混合、已读直接完成 | 本任务用户需求 |
| 2026-09-11 | 完成第二版 Demo，回填代码位置与验收；真实接口接入保留待实现 | 本轮浏览器实测 |

## 后续追加模板

复制下面一行到功能目标表，分配下一个编号，并在完成时同步验收记录。

| ID | 功能与验收标准 | Demo 状态 | 真实接入状态 | 代码位置 |
|---|---|---|---|---|
| F19 | 待填写；涉及新规则时追加 R 编号 | 待实现 | 待实现 | 实现后填写文件、函数和行号 |

后续开发顺序：核对实时 `/_list` 与公开书单成员能力 → 服务端鉴权及只读接口 → 替换 Demo 数据 → 校验分页与字段口径 → 正式目标持久化。每次只将已实际验收的范围标为完成。