panatgithub_AnkiHeadingSync/docs/settings-page-cardization-gap-report.md

设置页卡片化差距审计

本文以本轮“设置页卡片化 + 局部刷新 + 设置驱动卡片识别配置”任务合同为唯一验收基准，对当前仓库做真实实现审计。

1. 当前设置页仍是单入口整页重建

• 设置页入口位于 src/presentation/settings/PluginSettingTab.ts。
• display() 里直接执行 containerEl.empty()，随后把所有设置项重新创建。
• 多个普通交互会再次调用 this.display()，包括：
  • 语义 QA 标记变更
  • note type 切换
  • Anki 字段加载
  • 字段映射保存
  • 文件级 deck 开关
  • 范围模式切换
  • 文件夹树勾选
  • 文件夹树展开/收起
• 这与“稳定卡片外壳 + 卡片内部局部刷新”的任务目标直接冲突，也是当前页面跳动和滚动漂移的根因。

2. 现有 UI 结构与目标 5 卡片结构不一致

• 当前设置页是按顺序平铺的 imperative render，没有稳定分区壳层。
• 不存在折叠卡片，也没有设置页实例级展开状态。
• deck、scope、mapping、semantic preview 等内容都混在一个 display() 流程里。
• 不满足“5 张可折叠卡片、默认展开 1/5、默认折叠 2/3/4”的要求。

3. 第一张卡片的数据模型还没有成为识别真源

• 当前设置模型只保留旧的离散字段：
  • qaHeadingLevel
  • clozeHeadingLevel
  • qaGroupMarker
  • semanticQaMarker
  • qaNoteType
  • clozeNoteType
  • semanticQaNoteType
  • noteFieldMappings
• 运行时识别入口仍是 src/domain/manual-sync/services/CardIndexingService.ts：
  • 先按 qaHeadingLevel/clozeHeadingLevel 把标题判成 basic/cloze
  • 再仅在 basic 分支内部，用 qaGroupMarker/semanticQaMarker 特判 QA Group 与 Semantic QA
• 当前不存在统一的“4 行配置 -> 识别匹配规则 -> 运行时类型”的结构。
• 因此即便只改 UI，也无法让表格真正驱动同步识别。

4. 当前识别规则不足以支持新任务合同

• CardIndexingService 只支持：
  • 一个 QA/basic 标题级别
  • 一个 cloze 标题级别
  • basic 上的两个 marker 分流
• 当前不支持：
  • enabled 控制识别开关
  • 同一标题级别下多行配置的优先级匹配
  • 同级默认行（空 extra marker）回退
  • 保存时检测“同级多个启用默认行”并阻止保存
• 现有 validatePluginSettings() 还显式禁止 qaHeadingLevel === clozeHeadingLevel，这与新合同允许同级依赖 extra marker 分流的方向冲突。

5. 现有字段映射能力可复用，但需要换接入方式

• noteFieldMappings、NoteFieldMappingService、Anki note model 读取接口、字段详情读取接口都已存在，可复用。
• 但当前 UI 采用“每个 section 单独选择 note type、单独读取字段、再单独点保存映射”的流程。
• 这与新的直接编辑表格、自动保存、按需 debounce 保存不一致。
• QA Group 12 已经有独立的托管模型链路：
  • QaGroupModelDefinition
  • QaGroupSyncService
• 这说明 QA Group 行不应该被硬塞进普通 noteFieldMappings 保存流程；该行应显示为托管模型/托管字段。

6. 第二、三、四张卡片已有局部能力基础，但刷新策略不对

• “同步内容”相关设置已经存在，但散落在整页 render 中。
• 范围设置已经具备：
  • scopeMode
  • 文件夹树纯函数
  • lazy load
  • 缓存字段 folderTree / hasLoadedFolderTree / folderTreeLoadPromise
• deck 设置已经具备完整字段和按钮能力。
• 但 scope、deck 的普通交互仍回到整页 display()，所以已有能力还没有被组织成局部刷新架构。

7. 文件夹树缓存已存在，但缺少局部刷新按钮

• 当前文件夹树只在 scopeMode !== all 时触发加载。
• 已有缓存字段能支撑“按展开时加载”和“重复打开不重复遍历”。
• 但没有局部“刷新文件夹列表”入口。
• 加载完成后仍调用整页 display()，不满足“只刷新 card 3 / tree region”的目标。

8. Anki 模板加载路径存在，但还是 section 级旧交互

• 当前已有：
  • listNoteModels()
  • getNoteModelDetails(modelName)
• 但交互仍是：先刷新 note types，再按 section 读取字段。
• 新合同要求 card 1 提供一个统一按钮，一次刷新模板列表，并补齐当前表格已选模板的字段选项。
• 当前状态字段 availableNoteModels、loadedModelDetails、draftMappings 可部分复用，但需要调整成表格行驱动。

9. 迁移链路尚未实现

• mergePluginSettings() 目前只做默认值合并，不会从旧字段构建新识别配置。
• normalizePluginSettings() 当前只处理 backlink label 标准化。
• DataJsonPluginConfigRepository.load() / save() 会依赖 mergePluginSettings() 与 validatePluginSettings()，所以迁移和兼容必须落在设置模型层，而不是仅在 UI 层补丁。

10. 现有测试缺口

• 设置页测试目前主要覆盖：
  • note type / field mapping
  • scope tree 交互
  • deck 开关
• 还没有覆盖：
  • 5 卡片结构
  • 默认展开状态
  • 表格直编 + debounce 自动保存
  • 普通交互不触发整页重建
  • 新识别规则与冲突阻止保存
  • 旧设置迁移到新识别结构后行为保持不变

11. 可复用与必须替换

可复用：

• noteFieldMappings 与 NoteFieldMappingService
• listNoteModels() / getNoteModelDetails()
• QA Group 托管模型链路
• scope tree 纯函数与缓存字段
• deck 设置字段与插入模板能力
• PluginSettingTab 现有各段业务渲染逻辑中的具体设置项语义

必须替换或重组：

• PluginSettingTab.display() 的整页重建模式
• 运行时基于旧离散字段的识别分派方式
• 设置模型里缺失的新识别配置与迁移逻辑
• 设置页测试夹具中无法表达“局部清空/局部重绘”的部分

12. 结论

当前仓库具备完成本任务的大部分业务能力，但缺少三个关键骨架：

1. 稳定卡片壳层与局部 render 机制
2. 新的卡片识别配置模型及其向旧字段的兼容迁移
3. 让运行时识别直接消费新配置的匹配逻辑

因此本轮实现应聚焦于：

• 先在设置模型层建立新配置与迁移
• 再改运行时识别入口
• 最后将设置页重组为 5 张稳定卡片并接入局部刷新