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,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 校验）。