阅读器重构优化：统一评论模型，数据全部改走宿主回调（TB-199）

[hehetoshang]

主题

阅读器重构优化。本 PR 是三个仓库联动改造中的阅读器部分：

仓库	PR	内容
candle-reader	本 PR	阅读器界面与宿主回调契约
talebook	talebook/talebook#1079	阅读页注入回调，笔记接口补齐回复、赞踩、分页
book-review-server	talebook/book-review-server#7	接收 Talebook 同步的回复、修改、删除与赞踩

背景

旧阅读器有两套互不相通的数据：

• 划线 / 笔记：走宿主回调或本机存储；
• 章评 / 书评：阅读器直接请求 BRS，登录、用户中心也直连 BRS。

结果是两套界面、两套数据。Talebook 宿主页面还得拦截旧请求，自己另画一套选字工具栏和笔记侧栏。

这次重构确定了一条边界：阅读器只负责交互，不直接请求任何后端。评论、读者身份、权限和听书数据，全部通过宿主注入的回调获取。

关键改动

统一评论模型

• 划线、文字评论、整书评论是同一种记录；「本段 / 本章 / 全书 / 我的」是查看范围，不是类型。
• 跨段选区可以写评论，归属最后一段；真实选区另存。
• 删除旧的直连 BRS 评论面板、登录框、用户中心和 $backend 请求插件。

新界面

• 评论抽屉：移动端占 90% 高，桌面端为右侧侧边栏；默认显示本章评论，自己的在前，滚动到底自动分页。
• 完整评论页：「本章 / 全书 / 我的」三个标签；「我的」里含私密划线和私密评论。
• 评论详情页：点单条评论进入。第一层回复不缩进，之后统一缩进一级；可回复、修改、删除，删除主评论连同回复。
• 其他交互：
  • 赞踩用图标显示，互斥、可取消，失败时恢复原状；
  • 游客浏览时，互动会引导登录；宿主要求登录才能看评论时，显示「登录后查看评论」；
  • 完整页和详情页都支持浏览器返回；
  • 点正文里的划线或段尾气泡，打开该段落的本段评论；
  • 私密记录在右下角标「私密」，自己记录的修改、删除也放在右下角；
  • 桌面端目录、评论、设置侧边栏带分隔条，可拖动调整宽度并记住。
• 设置：只保留「显示全部划线和评论」「选中文字后显示工具栏」两个独立开关，去掉总开关；旧设置自动迁移。

宿主回调

• annotation_callbacks：user / login / load / list / summary / get / replies / save / remove / vote。
• audiobook_callbacks：manifest / timeline / start_session / report_progress / end_session，有声书不再直接请求接口。
• 完整契约、职责边界和扩展指引见新增的 DESIGN.md；README 给出接入示例。

修复与体验

• 划线底色错位：切换「显示全部划线和评论」后，划线底色会错开原文。原因是段尾评论气泡挤动了段落文字；现在气泡挂在零宽锚点上，不再参与正文排版。
• 评论气泡：数字不居中、夜灰和纯黑主题下没有轮廓，都已修复。
• iOS Safari：
  • 左右翻页时整页不再随手指上下拖动；
  • 选中文字后点别处只取消选中，不翻页；
  • 触屏上工具栏放在选区下方，避开系统菜单；
  • 关闭工具栏时不再自绘选区底色。
• 桌面端：快速拖选、双击选词不再误触翻页。
• 章节识别：一个正文文件里有多章（目录项带锚点）时，能识别出当前章节；一屏跨多章时每一章的标记和气泡都会读取。
• 加载：超过 60 秒才提示「加载较慢」，且不中断加载，加载完成后自动关闭提示。

演示

• make dev 后打开 /demo.html：《西游记》＋纯内存宿主（demo/memory-host.js，完整实现回调契约），可体验全部功能。
• make dist 生成可部署的 dist/demo.html 和介绍页 dist/index.html。
• 新增 .github/workflows/pages.yml：合并进 main 后自动发布到 https://talebook.github.io/candle-reader/ （仓库 Settings → Pages 的 Source 需设为 GitHub Actions）。
• 皮肤图片改为按打包脚本自己的地址解析，部署在子路径（Pages 的 /candle-reader/、Talebook 的 /static/candle-reader/）下也能加载。修复前在子路径下切到竹林皮肤，请求 /themes/skins/zhulin-portrait.svg 返回 404；修复后请求 /candle-reader/themes/skins/zhulin-portrait.svg 返回 200（本地用 make dist 产物挂在 /candle-reader/ 下实测）。

测试结果

• npm run test:e2e：81 passed。e2e 用 tests/e2e/fixtures/mock-host.js 模拟宿主，覆盖：
  • 抽屉、完整页、详情页；
  • 分页、范围切换时迟到的响应不混入；
  • 赞踩与失败回滚；
  • 回复与缩进规则、修改、级联删除；
  • 私密只读、游客引导登录、需登录才能查看；
  • 桌面侧边栏与分隔条拖动；
  • 有声书回调；
  • 气泡不参与排版的回归用例：去掉修复后会失败。
• npm run build、npm run lint：通过。
• 真实 Talebook 页面：配合 talebook#1079，在本地容器里启动 Talebook，用 Playwright 实测。
  • 登录读者 10 项全部通过：写评论、正文标记、段尾气泡、点赞、回复、「我的」、删除、刷新等。
  • 游客显示登录提示，点「去登录」跳到 /login?next=…。
• iPhone Safari 实测（反馈轮中确认）：
  • 拖动不再带动整页；
  • 可以选中多个字。

未验证 / 已知限制

• iPhone 上以下几项已修复，但还没在真机上复测：
  • 选中后点别处只取消选中、不翻页；
  • 工具栏关闭时不再保留自绘选区；
  • 开启工具栏后，系统「拷贝」菜单能否被关掉（取决于 iOS 对 -webkit-touch-callout 的支持）。
• 听书只在 e2e 中验证，没有在真实页面上播放。
• Pages 工作流要等合并进 main 后才会首次运行，目前没有在 GitHub 上跑过。

兼容性

• 构造参数废弃：server、audiobook_edition_id、audiobook_manifest_url 已废弃，传入会被忽略。宿主需改为注入回调（talebook#1079 已改）。
• 本机兜底：不注入 annotation_callbacks 时，评论存本机 localStorage，公开范围不对他人生效。
• 旧社区数据：旧版直连 BRS 的章评、书评界面已移除，Talebook 侧的处理见 talebook#1079。

方案

talebook/talebook 仓库的 design/webserver/20261007-reader-unified-comments.active.html（ACTIVE）：

• GitHub
• 单文件预览

本 PR 早期轮次（统一划线笔记、主从设置、面板焦点恢复）对应 Talebook 方案 design/app/20260904-candle-reader-annotations.active.html。其中的总开关和直连 BRS 的章评、书评已被本次重构取代。

🤖 Generated with Claude Code

https://claude.ai/code/session_01QTiGPhysXXAWy3buws8b7g