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
F19	单管理员登录保护所有页面/API；首次初始化需一次性口令；密码哈希存 MySQL；会话固定 5 天	不适用	已实现，真实 MySQL 初始化待部署验证	auth.py、migrations/002_site_auth.sql、templates/login.html

全部文档接口的落点

依据本地 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 状态	真实接入状态	代码位置
F20	待填写；涉及新规则时追加 R 编号	待实现	待实现	实现后填写文件、函数和行号

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