Codex/audit tmp migration

[sallowayma-git]

1. 结构化阅读笔记

旧分支在 tmp/js/bundles/reading-page.bundle.js 中实现了：

• 从原文高亮创建结构化笔记；
• note = { id, title, body, quote, outlineId, order, createdAt, updatedAt }；
• Notes drawer、outline 新建/改名/折叠/删除；
• 笔记拖拽归组与排序；
• 可拖动的笔记编辑器；
• 点击笔记回跳原文锚点；
• highlight 快照携带 noteId。

目标源码：

• js/runtime/unifiedReadingPage.js
• js/runtime/readingHighlightShared.js

2. 草稿与提交后注释持久化

旧分支保存以下阅读上下文：

• answers
• highlights
• noteText
• notes
• noteOutlines
• markedQuestions
• scrollY

并在 pagehide / visibilitychange 时强制 flush。Review 模式会尝试按原记录 id 更新笔记和标注。

该行为值得迁移，但旧实现把草稿和 autosaved record 直接写入 practice_records，不符合当前架构。阅读练习运行在 iframe 内，不能假设其中存在主窗口的 PracticeRecordAPI；迁移后应通过带 window/session token 校验的父子窗口消息分流：

• 未完成草稿：发送 draft/annotation sync 消息，由父窗口写入独立 draft/meta 存储；
• 已完成记录：沿用 PRACTICE_COMPLETE，由父窗口调用 PracticeRecordAPI.saveCompletion；
• Review 纯注释更新：新增受校验的 annotation sync 消息，由父窗口 getById 后合并，并以原 id 调用 saveRecord({ updateStats: false })。

3. 结果题号回跳原文证据

旧分支把结果表题号变为跳转按钮，并根据 explanation locator snippet 或段落标签建立原文定位；无法精确匹配时使用 overlap fallback。

该功能可独立于数据层迁移，但锚点必须在文本或 DOM 改动时无损降级，不能错误绑定到其他段落。

4. 阅读显示控制

旧分支在 header 中动态加入：

• 定位、笔记、高亮显隐；
• 题号导航折叠/展开；
• UI 偏好持久化。

这些属于 settings/UI preference，不应写入练习记录。可继续走当前设置仓库或明确的 UI preference key。

5. 旧分支的补偿逻辑

旧分支还实现了：

• 隐藏 autosaved practice record；
• 按标题、秒级时间、分数等字段对历史记录去重；
• localStorage 与 IndexedDB 的 practice_records 合并迁移。

这些是旧写入模型造成的补偿，不应原样迁移。当前数据层已经集中处理 canonical record 和 id 去重；应修复生产端，不应依赖展示层掩盖重复记录。

数据接口重定向

当前硬规则：practice_records 和 user_stats 只能通过 PracticeRecordAPI 写入。dataRepositories.practice 已不再公开，PracticeCore.store 也是只读 public store，raw storage 与 simpleStorageWrapper 对受保护 key 的写入会抛错。

旧接口或行为	当前目标接口	迁移要求
dataRepositories.practice.list()	PracticeRecordAPI.list() / listSummary()	UI 列表优先 summary
practice.getById(id)	PracticeRecordAPI.getById(id)	直接替换
practice.upsert(record) / PracticeCore.store.savePracticeRecord	PracticeRecordAPI.saveRecord(record, options)	必须含 canonical examId
completion payload 自拼记录再保存	PracticeRecordAPI.saveCompletion(...)	优先让当前 ingestor 建 canonical record
overwrite / raw storage.set('practice_records')	PracticeRecordAPI.replace(...)	导入时控制 updateStats
remove / clear	deleteById、deleteMany、clear	suite 仅在明确场景按 sessionId 删除
raw user_stats 读写	readStats、writeStats、mergeStats、resetStats	不迁旧浅合并算法
旧手写备份接口	BackupAPI	使用当前 normalize/restore 语义
raw 题库配置和 path map 写入	LibraryManager + ResourceCore	保证配置、内存索引、事件和路径同步
raw 词表写入	VocabStore / VocabDataIO	不绕过 active list 与缓存