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 步需在带副本库的机器执行；仓库内以静态检查 + 本清单兜底。
@@ -0,0 +1,53 @@
+# Flyway 迁移规范模板（task-192）
+
+> 新增数据库迁移一律在本仓库 `src/main/resources/db/` 追加 `V{N+1}__*.sql`（版本号在现有最大版本之上加 1），
+> 每个迁移文件头必须引用本模板并补齐六项必填。**只追加，绝不修改已部署的历史迁移**（会破坏 Flyway 校验和）。
+
+复制以下头注释到新迁移文件顶部并逐项填写：
+
+```sql
+-- =============================================================
+-- 迁移 V{N+1}__<短横线描述>
+-- 模板：docs/flyway-migration-template.md（task-192）
+--
+-- 1. 变更目的：<一句话说明要解决什么问题 / 为何变更>
+-- 2. 影响表与数据量：<表名：预计行数 / 全表或增量；例如 biz_file_result ~50w 全表>
+-- 3. 锁表风险：<是否 ONLINE / 是否加锁 / 大表索引类需 ALGORITHM=INPLACE 评估；风险高则拆批或窗口执行>
+-- 4. 验证 SQL：<迁移后用于核对的行数 / 抽样语句，见下方示例>
+-- 5. 回滚步骤：<V{N}__<desc>.sql 或补丁脚本路径；无回滚写明原因>
+-- 6. 上线窗口：<建议窗口，例如 业务低峰 02:00-06:00；双节点滚动>
+-- =============================================================
+
+-- 迁移语句（DDL/DML）…
+
+-- 可选验证（与头注释第 4 项对应）
+-- SELECT COUNT(*) FROM <table>;
+```
+
+## 六项必填说明
+
+| # | 字段 | 要求 | 反例 |
+|---|------|------|------|
+| 1 | 变更目的 | 一句话，写清"为什么" | 留空 / 只写表名 |
+| 2 | 影响表与数据量 | 每张被改表名 + 预计行数量级 | "涉及多表" 不含表名 |
+| 3 | 锁表风险 | 指出 DDL 是否 INPLACE/排他、大表评估 | "无风险" 不说明依据 |
+| 4 | 验证 SQL | 迁移后可跑的核对语句 | 缺失 |
+| 5 | 回滚步骤 | 回滚脚本路径或明确不可回滚原因 | 缺失 |
+| 6 | 上线窗口 | 建议时段 + 是否滚动 | 缺失 |
+
+## 示例验证 SQL（供第 4 项复制）
+
+```sql
+-- 迁移后行数与迁移前基线对比
+SELECT COUNT(*) FROM biz_file_result;
+-- 新索引是否生效（用于索引类迁移）
+SHOW INDEX FROM biz_file_result WHERE Key_name = 'idx_task_module';
+-- 抽样数据
+SELECT id, task_id, status, updated_at FROM biz_file_task ORDER BY id DESC LIMIT 5;
+```
+
+## 使用约束
+
+- 版本号在 `src/main/resources/db/` 最大现有版本上加 1（当前 ≥ V109），不抢号、不重复。
+- 不修改、不删除任何已执行过的历史迁移文件。
+- 上线走双节点滚动 + 生产库先 `flyway validate`，失败即停。
@@ -0,0 +1,22 @@
+# Flyway 迁移盘点（task-193）
+
+> 生成方式：`src/test/java/com/nanri/aiimage/config/MigrationInventoryTest.java`（只读审计，可重复）。
+> 快照日期：2026-09-05。
+
+## 概览
+
+- 版本化迁移文件数：**110**（`src/main/resources/db/V*.sql`）
+- 整数版本范围：**V1..V109 连续**
+- 历史遗留小版本：**V25_1__shop_manage_group_bind_user.sql**（Flyway 语义 25.1，紧跟在 V25 之后、V26 之前执行，属历史命名，保留）
+- 最新版本：**V109__admin_menu_frontend_routes.sql**
+- 重复版本：无
+- 迁移命名：全部符合 `V<整数>(_<子版本>)?__<描述>.sql`，无空格
+
+## 生产已执行核对
+
+生产 Flyway 已执行到 ≥ V108；本次新增迁移使用 V109（迁移只追加，不回滚历史）；新增迁移一律在 V108 之上取 `V109__*`，头注释引用 `docs/flyway-migration-template.md`（task-192）。
+
+## 约束
+
+- 审计测试断言：整数版本从 1 到当前最大值连续、无重复文件名、命名正则合规、历史文件校验和可复算稳定。
+- 修改任何已部署历史迁移会破坏 Flyway checksum，属违规；由本盘点测试的 `no_legacy_modified` 类约束 + code review 把关（git 层是否改动由 CI/review 校验）。