docs(backend-java): 恢复 flyway 迁移模板/演练/盘点文档（原来只在未合入的并行分支上，master 的 MigrationInventory/FlywayTemplate 契约测试一直红）

2026-09-13 13:03:33 +08:00
parent 8cd8390d95
commit 4bc4969e5a
3 changed files with 111 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Flyway 迁移演练 runbook（task-201）
+
+> 目的：在**副本库**上验证新增迁移可干净执行、验证 SQL 通过、可回滚、可幂等重跑，且全程不动历史迁移。
+> 本文档为演练步骤与检查清单；on-DB 执行需运维在有副本库的机器按步骤进行（本地/CI 无库时不执行 migrate）。
+
+## 前置
+
+- 副本库：与生产同版本（MySQL 8.4），已执行到当前最大版本 V108（与生产一致）。
+- 拿到待演练的新迁移：`src/main/resources/db/V{N+1}__*.sql`，头注释引用 `docs/flyway-migration-template.md`（task-192）六项必填齐全。
+
+## 演练步骤
+
+1. **基线核对**：`flyway -url=<副本> info` 确认版本、描述、checksum 与生产一致；`git log` 确认历史 V1..V108 未被改动。
+2. **validate**：`flyway validate` —— 校验历史迁移 checksum，任何历史文件被改动会立刻失败（违规红线）。
+3. **干净迁移**：把待演练迁移放入后 `flyway migrate`；记录成功版本、耗时。
+4. **验证 SQL**：执行迁移头注释第 4 项的验证 SQL（行数/索引/SHOW INDEX），确认结果符合预期。
+5. **回滚验证**：按头注释第 5 项回滚脚本回滚新迁移（若无回滚脚本，验证迁移可幂等重跑替代）。
+6. **幂等重跑**：回滚后再 `flyway migrate` 一次，确认可重复、无残留副作用。
+7. **锁窗口评估**：索引类迁移记录执行耗时与是否 ONLINE，结合表数据量估算生产锁窗口。
+8. **收尾**：记录结论到本清单；生产窗口按 template 第 6 项执行。
+
+## 离线静态检查（本仓库 JUnit 已覆盖）
+
+- 迁移文件整数版本 1..N 连续、无重复（`MigrationInventoryTest`，task-193）。
+- 迁移校验和可复算稳定（同一文件两次读 SHA-256 一致，`MigrationInventoryTest`）。
+- 新迁移命名合规、模板六字段可引用（`FlywayMigrationTemplateDocTest`，task-192）。
+
+## 完成检查
+
+- [ ] 副本库 `flyway migrate` 干净执行（版本升至目标）
+- [ ] 验证 SQL 通过
+- [ ] 回滚验证通过 / 幂等重跑通过
+- [ ] 锁窗口已按表量估算并记录
+- [ ] 历史迁移未被改动（`flyway validate` 通过）
+
+> 注：CI/本地无数据库环境时，本 runbook 的第 3-7 步需在带副本库的机器执行；仓库内以静态检查 + 本清单兜底。