Skip to content

refactor(annotations): unify matching and resumable sync - #150

Merged
finlater merged 1 commit into
mainfrom
codex/unified-chapter-annotations
Sep 5, 2026
Merged

refactor(annotations): unify matching and resumable sync#150
finlater merged 1 commit into
mainfrom
codex/unified-chapter-annotations

Conversation

@finlater

@finlater finlater commented Sep 5, 2026

Copy link
Copy Markdown
Owner

变更说明

统一微信读书下载书籍与本地导入书籍的划线和想法流程,解决两套匹配逻辑并存、整书同步中断后重复处理的问题。

  • 下载书籍只保存正文;阅读时通过同一入口关联书目、选择章节并匹配划线和想法。
  • 微信下载书籍自动建立书目关联;单章、选章合集和全书共享按书保存的注释源数据,各文件只保存自己的 XPointer 定位结果。
  • 每次下载并匹配一章,按章节、请求批次和匹配位置保存进度;暂停、关书、断网或失败后可继续。
  • 吸收 feat(annotations): add on-demand single-chapter sync #138 的章节文本索引与快速定位思路,并补齐嵌套目录、UTF-8 标题、重叠划线、边界校验、过期结果和累计统计等场景。
  • 统一菜单和快捷动作;划线改为较淡的短虚线;下一章划线预下载为全局选项且默认关闭。

Fixes #124

承接并替代 #138 的单章同步与定位优化方案。

类型

  • Bugfix
  • Feature
  • Refactor
  • Documentation
  • Other

Bugfix 要求

不适用;本 PR 为 #124 的流程重构。

Feature 要求

  • 新增能力:逐章匹配和断点续传;同一本书在单章、选章合集和全书之间复用注释源数据;自动预下载章节可选择是否同时准备划线和想法。
  • 典型场景:只下载一章或几章的用户可以只处理当前文件实际包含的章节;中断后继续时不会重拉已完成章节和批次。
  • UI/交互:本地书与微信下载书共用“划线和想法管理”;提供“继续匹配”“选择章节匹配”“清理划线和想法”;显示/隐藏动作已注册为快捷菜单。

测试

  • 已在 KOReader 中手动测试
  • 已运行 bash scripts/run_lua_specs.sh
  • 已运行 bash scripts/check_lua_namespace.sh
  • 已运行 luacheck main.lua _meta.lua weread spec
  • 如涉及插件加载/KOReader 兼容性,已运行或触发 KOReader integration
  • 不适用,仅文档或注释变更

测试说明:

- 58 个 Lua spec 全部通过。
- Lua namespace 检查通过。
- Luacheck:130 个文件,0 warning / 0 error。
- git diff --check 通过;提交差异未发现 API key、Cookie、Token 或私人书籍内容。
- Kindle 实机使用设备自带 LuaJIT 检查 72 个 Lua 文件,全部可加载。
- Kindle 实机验证了微信下载书自动关联、逐章继续匹配、条数进度、菜单与显示状态;关键文件与本地构建 SHA-256 一致。
- 已定位现有“自动预下载下一章”会在 UI 线程执行正文下载和 EPUB 处理;划线预下载默认关闭,正文预下载的异步化另行处理。

非公开 WeRead API

  • 不涉及非公开 WeRead API
  • 已新增或更新可复现的 Python 验证脚本

脚本路径:

scripts/

复现命令与脱敏结果:

N/A — 复用现有划线和想法接口,未新增或修改非公开 Web API 的请求协议。

模块结构

新增模块均位于项目命名空间:

  • weread/lib/annotation_chapters.lua
  • weread/lib/annotation_source.lua
  • weread/lib/annotation_store.lua
  • weread/lib/annotation_sync.lua
  • weread/ui/annotation_sync_controller.lua

截图

已完成 Kindle 实机交互验证,暂未附截图;菜单结构和实机测试步骤见 README.mddocs/annotation-refactor-device-test.md

Checklist

  • 我已经说明这个 PR 解决的问题或新增的特性。
  • 如果是 bugfix,我已经提供复现步骤或关联 issue。(非 bugfix,N/A)
  • 如果是新增 UI/交互特性,我已经提供截图或录屏。(已实机验证,暂未附截图)
  • 我没有提交 KOReader settings/weread.lua、API key、cookie、token、x-wrpa-* 或私人书籍内容。
  • 新增或移动的项目 Lua 模块遵循 weread/lib/weread/ui/ 命名空间规范。
  • 新增或修复的逻辑包含对应回归测试;若无法自动化,已在测试说明中解释原因。
  • 如果修改了用户可见文本,我已经更新 weread/lib/i18n.lua
  • 如果修改了菜单结构,我已经同步更新 README 菜单结构。
  • 如果涉及非公开 WeRead Web API,我已经在 scripts/ 中提交可独立运行、可复现的 Python 验证脚本,并填写了复现命令和脱敏结果。(N/A)

@finlater
finlater merged commit 0dff2fb into main Sep 5, 2026
1 check passed
@finlater

finlater commented Sep 5, 2026

Copy link
Copy Markdown
Owner Author

Ref #147

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] 统一划线和想法的本地书籍匹配流程,支持微信书籍断点续传

1 participant