panatgithub_AnkiHeadingSync/docs/deck-resolution-decisions.md

Deck Resolution Decisions

1. 实现入口

本轮继续以 manual-sync 主链路为实现入口：

1. CardIndexingService 负责文件级显式 deck 提取
2. RenderConfigService 通过新的 deck resolution 服务解析最终 deck
3. DiffPlannerService 聚合结构化 warnings，并保持 update 判定不受 deck 变化影响
4. AnkiBatchExecutor 只在 add 路径使用 resolved deck，update 路径不做 changeDeck
5. ManualSyncService 将 warnings 放入最终 ManualSyncResult

2. 数据语义

1. manual-sync 里的 deckHint 继续表示“文件级显式 deck hint”，不混入 folder / default 结果
2. 最终用于同步的 deck 只存在于 RenderPlan.deck / PlannedCard.deck / RenderedSyncCard.deck
3. 文件级 deck warnings 暂挂在 indexed card / state 上，最终在计划阶段去重汇总

3. 服务拆分

新增 4 个 deck 相关服务：

1. DeckNormalizationService
2. DeckExtractionService
3. FolderDeckMappingService
4. DeckResolutionService

其中：

1. DeckExtractionService 负责 YAML / 正文显式 deck 的提取与冲突 warning
2. DeckResolutionService 负责优先级决策：显式 deck > folder deck > default deck

4. 同步语义

1. 新卡 add 必须使用 resolved deck
2. 普通同步中，旧卡若 resolved deck 变化则执行 changeDeck
3. renderConfigHash 不包含 deck，deck 迁移由独立计划集合承载
4. rebuildIndex 仍不触发 changeDeck

5. 校验与错误

1. deck normalization 输出空字符串时直接报错
2. folder mapping 命中包含 :: 的文件夹名时按计划走硬失败，不静默回退
3. YAML / 正文冲突不阻断同步，按 YAML 为准并产生 warning
4. 多个正文声明不阻断同步，只取第一个并产生 warning

6. 结果透传

ManualSyncResult 新增结构化 warnings，用于：

1. deck 冲突
2. multiple body declarations
3. fallback 到 default deck

UI 层可以再把这些 warning 转成 notice，但 notice 不是唯一载体。

7. UI 最小改动

设置页只做最小文案修正：

1. 默认 deck 说明补充优先级语义
2. 不新增复杂配置项