panatgithub_AnkiHeadingSync/docs/id-noteid-mainline-gap-report.md

ID NoteId Mainline Gap Report

Scope

本报告只针对当前 manual-sync 主链，审查它与本轮契约之间的偏差：

• 主链 durable identity 切换为 <!--ID: noteId-->
• 满足当前标题级别规则的旧卡支持按 ID marker 重接进
• 认领成功后按当前 renderer 重渲染更新
• plugin state / writeback / execution 全部切到 noteId 主身份

Executive Summary

当前实现与本轮契约的偏差是系统性的，不是局部修补能解决的小问题。

当前 manual-sync 主链仍然围绕以下假设建立：

• Markdown marker 协议是 <!-- AHS:card=... note=... -->
• cardId 是 durable identity
• PluginState.cards 以 cardId 作为 key
• pendingWriteBack 以 cardId 追踪
• 一次运行内与持久化状态共用同一身份键

而本轮契约要求：

• <!--ID: noteId--> 成为唯一主链 marker 协议
• noteId 成为 durable identity
• syncKey 只作为单次运行内的相关键
• 旧 ID marker 卡片可以在满足当前标题规则时被认领并重渲染

结论：当前主链必须做一次贯穿 marker、index、plan、execute、state、writeback 的统一重构。

Gap Inventory

1. Marker protocol is wrong

文件：src/domain/manual-sync/services/CardMarkerService.ts

现状：

• 候选 marker 只看 <!-- AHS:
• 合法 marker 只接受 <!-- AHS:card=... note=... -->
• create/writeback 也只会生成 AHS marker
• service 内还负责生成新的 cardId

与契约冲突：

• 主链 marker 必须切为 <!--ID: noteId-->
• 合法 marker 只能接受正整数 noteId
• 非法 trailing <!--ID: ...--> 候选也要剥离并占用 marker 槽位
• 主链不再以 marker 生成 durable cardId

影响：

• 当前主链无法识别旧卡 marker
• 当前 writeback 永远不会写出正确协议

2. IndexedCard schema still treats cardId as durable identity

文件：src/domain/manual-sync/entities/IndexedCard.ts

现状：

• IndexedCard 仍持有 cardId
• 仍使用 markerState = "missing" | "card-only" | "card-and-note"
• 没有 syncKey
• 没有 idMarkerState
• 没有 noteIdSource

与契约冲突：

• durable cardId 应从主链 index 结果中移除
• 需要新增运行内 syncKey
• 需要区分 marker 是否存在且是否合法
• 需要显式记录 noteId 来源是 marker / state recovery / pending writeback

影响：

• 后续 planning / execution 无法按契约判断“认领”“恢复”“重写 marker”

3. Persisted state schema is still cardId-centric

文件：src/domain/manual-sync/entities/PluginState.ts

现状：

• FileState.cardIds 仍然存在
• CardState.cardId 仍然存在
• CardState.noteId 仍是可选
• PendingWriteBackState 用 cardId 追踪
• PluginState.cards 的 key 仍隐含为 cardId

与契约冲突：

• PluginState.cards 必须改为 String(noteId) 键控
• FileState.cardIds 必须改为 noteIds
• CardState.noteId 必须是必填
• pendingWriteBack 必须改成按块身份追踪

影响：

• 当前 persisted state 不能作为 noteId 主身份的真相源

4. State repository has no schema migration

文件：src/infrastructure/persistence/DataJsonPluginStateRepository.ts

现状：

• load() 只是直接返回 snapshot.pluginState
• 不迁移旧 cards[cardId]
• 不迁移 files[].cardIds
• 不丢弃旧 pending writeback

与契约冲突：

• 需要在 load 阶段显式升级旧 schema
• 旧 pendingWriteBack 要直接丢弃

影响：

• 主链切协议后，旧状态无法安全进入新主链

5. Indexing still resolves identity by cardId

文件：src/domain/manual-sync/services/CardIndexingService.ts

现状：

• marker extraction 只识别 AHS marker
• resolveIdentity() 顺序是：marker cardId -> pending by cardId -> knownCards by rawBlockHash -> 生成新 cardId
• usedCardIds 用于去重
• rawBlockHash 当前只会剥除 AHS marker，不会剥除旧 ID marker

与契约冲突：

• 先识别“当前标题规则命中的块”，再处理 ID marker
• identity resolution 必须变成：marker noteId -> unique same-file rawBlockHash state recovery -> pending writeback -> undefined
• 去重必须基于 noteId，而不是 cardId
• rawBlockHash 必须基于剥除合法/非法 trailing ID marker 后的内容计算

影响：

• 旧 <!--ID: ...--> 卡会被当成正文内容
• 会错误走新建分支

6. Planner still assumes cardId + markerNoteId semantics

文件：src/domain/manual-sync/services/DiffPlannerService.ts

现状：

• 使用 cardsById 按 card.cardId 去重
• 读取 state.cards[card.cardId]
• pendingWriteBack 按 cardId 命中
• toRewriteMarker 依赖 markerState = missing/card-only
• orphan 识别依赖 card.cardId

与契约冲突：

• 规划必须以最终 noteId 和运行内 syncKey 为中心
• recovered noteId、invalid marker、新创建 note 都要触发 rewrite marker
• blocks with existing noteId but no state 也能正常进入 update path

影响：

• 当前 planner 无法正确表达“旧卡重接进 + 重写 ID marker”

7. Executor still uses cardId as the main run-time correlation key

文件：src/application/services/AnkiBatchExecutor.ts

现状：

• resolvedNoteIds 按 card.cardId 保存
• touchedCardIds 按 card.cardId 保存
• markerWriteMap 按 card.cardId 保存
• rendered cards map 也依赖 card.cardId

与契约冲突：

• durable identity 不能再依赖 cardId
• 运行内相关键应切为 syncKey
• note existence check 失败时应降级到 create flow，并最终写回真实 <!--ID: newNoteId-->

影响：

• 即便 planner 修好，executor 仍会把旧身份流重新扭回 cardId 模式

8. Markdown writeback still writes by cardId

文件：src/application/services/MarkdownWriteBackService.ts

现状：

• 结果结构返回 writtenCardIds
• 写回请求包含 cardId
• pending entry 保存 cardId
• target marker 仍通过 AHS marker service 生成

与契约冲突：

• 写回必须统一输出 <!--ID: noteId-->
• pending writeback 要按 (filePath, blockStartLine, rawBlockHash) 追踪
• 结果结构也应转向 noteId/syncKey 语义

影响：

• 当前 writeback 不能支撑新 marker 协议和新 pending shape

9. Tests are still asserting the old contract

主要文件：

• src/domain/manual-sync/services/CardMarkerService.test.ts
• src/domain/manual-sync/services/CardIndexingService.test.ts
• src/domain/manual-sync/services/DiffPlannerService.test.ts

现状：

• 测试名称和断言大量依赖 cardId
• 大量断言使用 AHS marker 字面值
• 缺少“invalid ID marker but valid block”“not matching heading rules -> ignore marker”“schema migration”这类契约要求

影响：

• 即使代码完成重构，现有测试也会大面积误报失败
• 当前测试对本轮目标没有形成足够保护

Architecture Notes

Good existing structure worth preserving

• ManualSyncService -> FileIndexerService -> DiffPlannerService -> AnkiBatchExecutor -> MarkdownWriteBackService 这条主链分层是合理的
• 当前 rendering boundary 仍然干净，可以直接复用在旧卡重接进后的重渲染更新
• DeckResolution 和 deck migration 相关逻辑与本轮冲突较少，应尽量少动

Mainline drift that must be removed

• main sync durable identity 仍与 module 3/4 的 AHS assumptions 紧耦合
• cardId 同时承担 persisted identity 和 in-run correlation key，两类职责未分离

Required Repair Direction

必须完成的主修复方向：

1. marker 协议切换到 <!--ID: noteId-->
2. noteId 成为持久主身份，syncKey 成为运行内相关键
3. state schema 与 repository load 做显式迁移
4. index / plan / execute / writeback 全链去掉 durable cardId 依赖
5. 增加对“满足当前标题规则且带旧 ID marker”的重接进与重渲染支持
6. 重写对应测试，补足 integration 覆盖

Out Of Scope

根据契约，本轮明确不做：

• 继续支持 <!-- AHS:card=... note=... --> 文件
• 双 marker 并读
• 旧 HTML 保留模式
• 不匹配标题规则的 ID marker 清理工具
• legacy heading compatibility mode