release-db-config-sync

release-db-config-sync

发版前算清远端 DB 迁移与 Nacos 配置的差异（apc/01 §2 db-config-sync，收口步 3/4）。这是治 R3（"DB sync 走桩、writes:0 换马甲冒充已同步"）的真机制：它真 spawn scripts/ops/sync-test-migrations.ts --dry-run——真解析凭证、真连库、真算迁移计划——退出码由真脚本决定，绝不注入桩。Nacos 侧对两份 key dump 算真差集。dry-run 永不写库、不写真 Nacos——止于写入边界，真 apply 走审批后的远端路径。

什么时候用：release-preflight 绿之后、release-tag 之前，确认远端 test 环境的迁移账本和配置 key 都对齐了才发版。

承重纪律（先记死）

• 事故红线（memory / apc/01 开头）：prod 曾因 Navicat 结构 diff 绕过迁移账本灌库出事故（丢回填 / 半应用）。一切 DB sync 必须走账本，diff 工具只做审计不做写入。 本 skill 就是账本路径的收口——绝不教你拿 Navicat / 裸 SQL 去改远端。
• 本 skill 只 dry-run：算差异、出计划、停在写入边界。真 apply（把 pending 迁移打进 test RDS、把缺失 key 补进 Nacos）是审批后的远端动作（本机替身口径下 = M5），不由本 skill 执行。
• 别把桩当验过：本机替身下 Nacos fetch 未接线时，key-diff 会诚实标 skipped（真路径 = M5）。看到 skipped 就照实报 ⬜，别写成"配置已核对无差异"。

Anti-pattern（直接判红）

• ❌ 迁移 dry-run 报 blocked（真脚本失败 / 缺凭证）时，改用别的路径灌库绕过去。真脚本 exit 非 0 = 连不上 / 缺 REMOTE_MYSQL_*，是要修的前置，不是要绕的门。
• ❌ 有 pending 迁移（staged）就当没事发版。staged（exit 3）意味着远端账本落后，未审批 apply 前不该 tag。
• ❌ key-diff skipped 说成"已核对"。没给 dump 文件就是没比，别冒充。

工具契约（签名以此为准）

apc 不在 PATH——在仓库根用 npx tsx sdk/apc/bin/apc.ts <sub>。

命令	作用	退出码
npx tsx sdk/apc/bin/apc.ts release db-config-sync [--ref <dump>] [--cur <dump>] [--json]	真跑 sync-test-migrations.ts --dry-run（本机替身指向本地 replica，永不写远端）+ 对两份 Nacos dump 算 key 差集	0 green（无差异）· 3 staged（有 pending / 缺 key）· 1 blocked（真脚本失败 / 缺凭证）

--json 字段（名以此为准）：

• 顶层：{ verb:'db-config-sync', decision, migration, keyDiff, blockers:[], staged:[] }
• migration：{ exitCode, pending:[<sql文件名>], stderr }（exitCode 是真脚本退出码；pending 是真脚本 fs 枚举 ⇄ _migrations 账本比对得出的待同步迁移）
• keyDiff：{ status:'skipped', reason } 或 { status:'computed', missing:[], extra:[], common }（missing = 目标环境缺的 key，需补齐；extra 不阻塞，仅报告）

Workflow

1. 跑迁移 dry-run + key-diff

# 只算迁移（不给 dump 时 key-diff 诚实 skipped）：
npx tsx sdk/apc/bin/apc.ts release db-config-sync --json > /tmp/dbsync.json; D=$?
echo "db-config-sync exit=$D"