docs: Plan 3 终审收官——ADR-017 补决策六/七（is_primary first-import-wins、§7.6 事务粒度偏差），移交清单补三点既定事实

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-21 21:27:16 +08:00
parent 6d9f7b6ad7
commit fc36239b35
1 changed files with 8 additions and 0 deletions
@@ -31,3 +31,11 @@

 - **理由**：幂等三态（miss / checksum 同 skip / checksum 异新修订）全部落在数据库唯一约束与不可变触发器之上（Plan 1 的"约束即规格"），应用层零防御性锁；自建 term 与收编语义保证 WXR 文档序不敏感（真实导出序 items 先于 wp:term 是常态而非例外）；串行分派以最小复杂度满足锚点依赖，杜绝并行竞态面。
 - **权衡/陷阱**：① 五列身份解析的 latest-first 口径依赖 source_records 无并发写入方（CLI 单进程成立，REST 化时需重审——与决策四同一重审点）；② auto: 前缀行被后续 wp:term 收编后 source_id 变更——跨快照的 term 幂等以 (site, taxonomy, slug) 域锚定而非 source_id，行为正确但排查时须知两种 source_id 形态并存；③ counts 求和的前提"键前缀互斥"是**约定不是约束**——新写入器复用他家键名会静默相加，JSDoc 键归属声明是唯一防线；④ 24h 回收窗口内崩溃残留的 job 会阻塞同 key 重提交的语义澄清（复用命中非终态 → CLI 警告 + 显式换 --key 重试），这是有意的"不静默重跑"纪律。
+
+## 决策六（终审补记）：content_terms is_primary = first-import-wins
+
+跨快照重导时 content_terms 的 onConflictDoNothing 意味着 is_primary **永不翻转**（首导的 primary 关联固定）——与 schema.ts:168 注释"可在不同关联间翻转"的预期不同。阶段 3 单写方下这是确定性行为；若 Plan 4 主题需渲染"主分类"且源站主分类跨快照变化，需升级为 DO UPDATE SET is_primary 并补跨快照翻转测试。
+
+## 决策七（终审补记）：对 spec §7.6 事务粒度的有意偏差
+
+spec 要求"每 Source Record 的内容/Revision/分类/路由写入使用数据库事务"；实现为按写入器各自事务边界（content 四行创建共事务；term/media/route 单语句原子）。跨域单记录不共事务——由幂等重跑收敛兜底（JSDoc 与 ctx.db 直连约定明示）。REST 化或多写方并发出现时重审。