panatgithub_AnkiHeadingSync/docs/module-5-gap-report.md

Module 5 Gap Report

审查范围

本报告只审查与模块 5 直接相关的实现：

1. deck 配置模型
2. 设置页 deck UI
3. 文件级 deck 解析
4. 文件夹 deck 映射
5. manual-sync 主链路中的最终 deck 解析
6. warning 透传
7. deck 模板插入能力

当前实现与模块 5 计划的主要差距

1. 配置模型缺字段

当前 PluginSettings 只保留了：

1. defaultDeck
2. 范围过滤配置
3. 其他同步与字段映射配置

缺少模块 5 需要的：

1. fileDeckEnabled
2. fileDeckMarker
3. fileDeckTemplate
4. fileDeckInsertLocation
5. folderDeckMode

2. 设置页未实现“显式 deck 模式选择”

当前设置页只有 Default deck 文案增强，但没有：

1. 文件级自定义牌组开关
2. 识别名输入
3. 默认模板输入
4. 插入位置单选
5. 向当前文件插入 deck 模板入口
6. 文件夹映射三态选择与示例说明
7. 最终优先级说明区块

3. 文件级 deck 解析仍然写死

当前 deck 提取实现仍然固定写死：

1. YAML key 固定 targetDeck
2. 正文 marker 固定 TARGET DECK

这与模块 5 要求的“YAML key 与正文 marker 统一使用用户配置的 fileDeckMarker”不一致。

4. 文件级 deck 没有按开关启停

当前 deck 解析总是启用。 模块 5 要求：

1. fileDeckEnabled = false 时不解析 YAML
2. fileDeckEnabled = false 时不解析正文

5. 文件夹映射模式不完整

当前只有一种隐式文件夹映射，等价于“父文件夹映射”。 缺少：

1. off
2. folder
3. folder-and-file

同时当前非法路径片段处理是抛错硬失败，而模块 5 要求：

1. 产出 deck_invalid_folder_segment warning
2. 放弃映射
3. 回退到 defaultDeck

6. 没有 deck 模板插入能力

当前仓库不存在“向当前文件插入 deck 模板”的能力，也没有相关命令或设置页操作入口。

7. 同步链路已有 warning 透传，但未覆盖模块 5 的新模式行为

当前 warning 结果对象已存在，但：

1. 还没有 fileDeck 开关影响解析的测试
2. 还没有 marker 改名后的 YAML / 正文解析测试
3. 还没有 folder-and-file 模式测试
4. 还没有 invalid folder segment 回退 default 的 warning 测试
5. 还没有 deck 模板插入测试

兼容与边界判断

该报告反映的是模块 5 实现前的历史差距。

后续 deck-rule-migration 修复已经把产品语义更新为：普通同步会按最新 deck 规则迁移旧卡；只有 rebuildIndex 继续保持“不迁移 Anki deck”的边界。

本轮修复边界

本轮只补齐模块 5 明确要求：

1. deck 模式配置
2. deck 解析按配置启停
3. 可配置 marker
4. 文件夹映射三态
5. deck 模板插入
6. warning 继续沿 manual-sync 结果透传
7. 与当前 old-card 行为兼容的回归测试

不扩展到：

1. deck 迁移模块
2. 模板 DSL 扩展
3. 标题级 deck override
4. 手工 folder -> deck 映射表