mirror of
https://github.com/panatgithub/AnkiHeadingSync.git
synced 2026-07-22 06:51:43 +00:00
62 lines
No EOL
2.1 KiB
Markdown
62 lines
No EOL
2.1 KiB
Markdown
# 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. 不新增复杂配置项 |