panatgithub_AnkiHeadingSync/docs/obsidian-backlink-config-gap-report.md

Obsidian Backlink Config Gap Report

Scope

本报告基于当前仓库真实代码审查，聚焦这五条链路与计划差距：

• settings 默认值、校验、持久化与旧 data.json 兼容
• 普通 QA / Cloze / 语义 QA 的回链渲染入口
• Cloze title/body 合并影响面
• QA Group 12 模板生成与 model drift 更新链路
• renderConfigHash 对已同步卡片的失效机制

Confirmed Gaps

1. 普通卡回链仍硬编码在 ManualCardRenderer

src/domain/manual-sync/services/ManualCardRenderer.ts 当前只在一个分支里决定回链行为：

• addObsidianBacklink = true 时始终向 renderedFields.body 末尾追加 <p><a ...>Open in Obsidian</a></p>
• 没有 label 配置入口
• 没有 placement 配置入口

这意味着普通 QA、Cloze、语义 QA 目前共享同一个“答案末尾 + 固定文案”硬编码。

2. Cloze 兼容点不在 renderer，而在现有字段映射合并逻辑

当前仓库结构里，Cloze 仍然由 renderer 先产出 title / body，再由 note field mapping 把它们合并进主字段。

因此实现时不需要改 Cloze 的字段结构；只要保证 question-last-line 改的是 title，answer-first-line / answer-last-line 改的是 body，现有 title<br><br>body 合并形状就会自然继承新位置。

3. QA Group 12 也仍然硬编码默认回链

src/application/services/QaGroupModelDefinition.ts 当前在模板生成里写死：

• back 模板固定把 <a class="anki-heading-sync-backlink" href="{{Src}}">Open in Obsidian</a> 放在答案容器后
• buildQaGroupModelDefinition() 没有接收 settings 或其他配置参数

src/application/services/QaGroupModelService.ts 的 ensureModel() 也始终调用无参 buildQaGroupModelDefinition()，所以模板漂移更新机制存在，但暂时无法感知用户配置。

4. QA Group note 字段链路已经独立，不需要改字段结构

src/application/services/QaGroupSyncService.ts 当前行为已符合计划的结构约束：

• Src 仍由 buildGroupBacklink() 生成并写入 note fields
• buildQaGroupNoteFields() 仍固定写 Stem / GroupId / Src / S01..S12
• 没有通过普通 note field mapping 去映射 QA Group 字段

因此本轮不需要新增字段，也不需要改变 Src 含义，只需让 model template 生成使用当前 settings。

5. settings 持久化只做默认值合并，没有空 label 归一

src/infrastructure/persistence/DataJsonPluginConfigRepository.ts 当前对 settings 的处理是：

• load 时直接用 DEFAULT_SETTINGS 合并旧 snapshot
• save 时直接校验后原样写回

这能处理“缺字段”，但不能处理：

• 旧 / 异常 data.json 中 obsidianBacklinkLabel 为空字符串或全空格
• UI 保存时把全空格文案写进 settings

计划要求的空 label 归一，需要引入一个显式 normalize 层。

6. renderConfigHash 目前还不感知新配置

src/application/services/RenderConfigService.ts 当前 hash 只包含：

• note model / mapping
• addObsidianBacklink
• convertHighlightsToCloze
• keepPureTagLinesInCardBody

如果只修改 label 或 placement，当前 diff planner 不会把已同步卡片判定为需要更新。

7. settings UI 与 i18n 尚未暴露新配置

src/presentation/settings/PluginSettingTab.ts 当前只在 sync options 区域渲染了 addObsidianBacklink toggle，没有：

• label 文本输入
• placement 下拉

中英文消息文件里也尚未存在这两组设置文案与 placement 校验错误文案。

8. 现有测试覆盖还缺四个关键面

当前仓库已有：

• PluginSettings.test.ts
• PluginSettingTab.test.ts
• ManualCardRenderer.test.ts
• QaGroupModelService.test.ts
• QaGroupSyncService.test.ts

但还缺或不足：

• settings 归一化与 placement 校验
• label / placement 改变引起的 renderConfigHash 变化
• 普通卡三种 placement 的断言
• QA Group 模板三种 placement 与 drift 更新断言

Repository-Compatible Fix Direction

最安全的仓库兼容方案是：

1. 在 settings 层新增集中 normalize 函数，供 load/save/UI 共用。
2. 把普通卡回链渲染收口成共享 helper，并在 ManualCardRenderer 内按 placement 分流到 title 或 body。
3. 让 buildQaGroupModelDefinition() 接收 label/placement，并让 QaGroupModelService.ensureModel() 按 settings 生成模板。
4. 把 label/placement 纳入 RenderConfigService hash。
5. 只扩展现有测试锚点，不改 note 字段结构、不改 Src 语义、不做无关重构。

Out Of Scope

本轮不扩张到：

• 新增 note 字段
• 改写 QA Group field contract
• 修改 Cloze 合并结构
• 新增独立的 QA Group settings 面板
• 调整现有 Obsidian backlink 开关语义