Files
crawler-plugin/backend-java/docs/migration-inventory.md
T
huangzd1997 07757b9f6d 对平(两条既有台账红): 迁移盘点文档补 V156 一跳、页码台账按拼写分开登记
出包前实测 master 头全量红在这两条上(都不是本批引入,已在干净 HEAD worktree 复跑坐实):

1. docs/migration-inventory.md:磁盘 154 支版本化迁移、整数版本到 V156,文档还停在
   153 / V1..V155,"最新版本"一行也没写 V156 的文件名 ⇒ CompanyMigrationV143Test
   的三条对账(文件数/范围/含最新文件名)红。取号起点 V157 本来就对,没动。
   旧版文件名一个没挤掉(V155/V154/V153/V152 仍在链条里,CompanyDefaultDropV152Test 钉着)。
2. PageDefaultsLedgerTest:同一个断言同时套在 #page_size= 与 #pageSize= 两种拼写上,
   而 camelCase 那族实际只用得到 2 种常量(另外 2 种只以 snake_case 出现)⇒ 恒红,
   红的是写法不是有人新增了默认值。改成逐拼写登记 + 两拼写并集仍只许四种,
   "长出第五种要红"这条保护不降。

用户拍板"对平两条账后整批发",故本笔与外观那两笔同树出包。
2026-10-10 11:47:21 +08:00

12 KiB
Raw Blame History

Flyway 迁移盘点(task-193)

生成方式:src/test/java/com/nanri/aiimage/config/MigrationInventoryTest.java(只读审计,可重复)。 快照日期:2026-10-01;2026-10-03 随 V142 追加时同步过概览数字与取号起点;2026-10-04 随 V143 同步;2026-10-04 随 V144 同步;2026-10-04 15:1x 随 V145 同步;2026-10-05 随 V146 同步;2026-10-05 23:0x 随 V147 同步;2026-10-06 随 V148 同步(并把 V145/V146/V147 从"待发版"挪进"已应用");2026-10-06 随 V149 同步(菜单树按公司一套;V148 仍未上线,故 V149 与它同批);2026-10-06 随 V150/V151 同步,并删掉未上线的 V148(该号就此退役,见下);2026-10-07 随 V152 同步(并把 V149/V150/V151 从"待发版"挪进"已应用"——10-06 17:32 只读实查,success 全 1);2026-10-08 随 V153 同步(分组名收窄到同公司唯一;表侧只 13 行,写侧代码与本版必须同批)。

概览

  • 版本化迁移文件数:154(src/main/resources/db/V*.sql,其中整数版本 153 个 + 小版本 V25_1)
  • 整数版本范围:V1..V156,其中 V132/V133/V148 为已退役空号(见下),其余连续
  • 历史遗留小版本:V25_1__shop_manage_group_bind_user.sql(Flyway 语义 25.1,紧跟在 V25 之后、V26 之前执行,属历史命名,保留)
  • 最新版本:V156__dedupe_total_data_pioneer_backfill.sql(上一版 V155__users_disabled_at.sql,再上一版 V154__biz_dedupe_total_data_company_id_drop_default.sql,其前 V153__shop_manage_group_company_id.sql,再往前 V152__columns_shop_key_company_id_drop_default.sql——概览往下推时旧文件名一个不许挤掉,CompanyDefaultDropV152Test.inventoryDocTracksV152 就是钉这件事的)
  • 待下一次 jar 发版执行:V154、V155(V152、V153 已于 10-09 09:50 随 jar 69d2ebb0 双台同版应用——启动日志实查 "Current version of schema aiimage: 153 / Schema aiimage is up to date. No migration necessary.";V149/V150/V151 已于 10-06 17:32 应用。V153 给分组表加 company_id 并把分组名从"全平台唯一"收窄成"同公司唯一",写侧代码必须同批,两个方向单独发都不行——见 V153 头注释第 6 段;V154 只摘一列的默认值,前提逐条取证见下面的 V154 条目;V155 只给 users 加一列可空 disabled_at,140 行全取 NULL、对旧 jar 零行为差异,但它必须与读这列的代码同版——只发迁移则停用无人执行,只发 jar 则启动期读列即 1054)
  • 已应用:V142(10-03 18:23)、V143(10-04 10:48)、V144(10-04 13:22)、V145__brand_dedupe_company_scope.sql(10-05 13:01)、V146__users_expires_at_admin_expiry.sql(10-05 13:01)、V147__product_category_company_scope.sql(10-06 11:03)、V149__permission_menu_company_tree.sql / V150__shop_key_company_scope.sql / V151__rule_tables_shared_across_companies.sql(三条均为 10-06 17:32)
    • 末段 flyway_schema_history 为 2026-10-07 主机A 只读实查(success 全 1,最大整数版本 151),不是从 jar 版本推的
  • 重复版本:无
  • 迁移命名:全部符合 V<整数>(_<子版本>)?__<描述>.sql,无空格

生产已执行核对

生产 flyway_schema_history 末段:V125..V131 之后直接是 V134__publish_item_free_text_columns、V135__dedupe_total_data_wide_columns(两条 installed_on 均为 2026-09-25 20:46:16),库内没有 132/133 记录。

空号的来历(V132/V133/V148)

本地曾存在 V132__web_config_add_is_latest.sql、V133__hide_redundant_indexes_invisible.sql,与另一分支已在生产落库的 V134/V135 冲突。因 Flyway 未开启 out-of-order,把任何迁移编到 132/133 会在启动期报 "resolved migration not applied";因此这两条改为 V136/V137,132/133 永久退役,不可回填。

V148__product_category_builtin_owned_by_company.sql(把 18 行内置类目的归属从共享哨兵 0 改成厦门米椿花 1)从未上线,2026-10-06 控制方点名「商品类目做成共享的,不区分」⇒ 它的口径被 V151 整体推翻,文件连同 ProductCategoryMigrationV148Test、docs/rollback-V148-product-category-builtin-shared.sql 一起删除。它与 132/133 的区别要写清:把新迁移编号写回 148 在 Flyway 语义上是可行的(生产最大值仍是 147,不存在 out-of-order),这里禁它是共树并发的护栏——148 与 149/150 是同一工作区里另一路会话此刻正在引用的号,被删的 V148 文件可能被再次写出,而同号两个文件会让 Flyway 启动期报 "Found more than one migration with version 148" ⇒ 两台 java 同时起不来。宁可让 integerVersionsSequentialFromOne 的红字出现在测试里,也不把撞号留到运行期发现。因此这三个号都在 MigrationInventoryTest.RETIRED_HOLES 里登记。

后续新增迁移从 V157 起取号(V156 已被 dedupe_total_data_pioneer_backfill 占用:把组 33/uid=1188「先锋」名下账号已删的 1452 行 company_id 从兜底 1 回填到 3,配套读侧按行 company_id 收窄的 JAR 同批上线,回滚见 docs/rollback-V156-dedupe-pioneer-backfill.sql;V155 已被 users_disabled_at 占用:给 users 加一列可空停用时刻,回滚见 docs/rollback-V155-users-disabled-at.sql;V154 已被 biz_dedupe_total_data_company_id_drop_default 占用:只摘一列的默认值,回滚见 docs/rollback-V154-dedupe-company-id-drop-default.sql。只认"当前最大值 + 1",不要为还没写出来的迁移预留号段——预留会在 1..max 里留洞,integerVersionsSequentialFromOne 会红;也不要回填上面那三个洞)。原先挂在 V149 名下的"摘 DEFAULT"待办,columns 那条已与 biz_shop_key 合并成 V152 发出(V150 头注释第 6 段要求"合并成一版发出";发布前的只读取证:columns 154 行按公司 52/51/51、biz_shop_key 16 行全 company_id=1 且无 NULL,两列 COLUMN_DEFAULT 都是 1)。摘 DEFAULT 这一族到此摘完,最后一条是 V154:

  • ALTER TABLE biz_dedupe_total_data ALTER COLUMN company_id DROP DEFAULT; —— 已作为 V154 发出。V152 当年把它留在门外的前提是"先修写侧、上线并验证真实导入之后才谈摘",2026-10-09 只读探针(运维仓 scripts/_probe_dedupe_default.py,主机A,零写入)逐条对上:哨兵四张表里只剩这张仍带 DEFAULT 1(users / biz_shop_key / columns 的 COLUMN_DEFAULT 均为空);归属分布 company_id=1 共 546,344 行、=3 共 8,125 行,没有 0 也没有 NULL;孤儿归属 0 行;写侧显式落值那版上线后真实导入 29,555 行(2026-10-07 09:48:38 → 2026-10-08 23:57:51)。⚠ 本表批量导入走 INSERT IGNORE:在生产 sql_mode(实查含 STRICT_TRANS_TABLES)下省略该列不会撞 1364,而是被降级成 warning 并落成隐式默认 0——0 不属于任何公司,行插得进去但对所有公司隐形,比"静默归第 1 家"更难发现。⇒ 顺序必须是先上带 Java 闸门的 jar,再让本迁移随同一版生效;闸门=DedupeTotalDataService.requireCompanyAttribution(接在 create 与 insertImportBatch 两条写通道上),用例 DedupeTotalDataWriteAttributionTest 4 例,其中接线钉按行首语句数调用点==2(避开 javadoc 同名提及那个坑)。

biz_product_category.company_id 的 DEFAULT 由"待摘"改成"必须保留"(这一条与 V151 同批生效):V151 之后新 jar 的 INSERT 列清单不含 company_id,而该列是 NOT NULL,全靠 DEFAULT 1 满足——此时执行 DROP DEFAULT 会让每一次新建类目报 1364。biz_invalid_asin_data.company_id 同理(品牌库那条写入失败还会被 CollectDataInvalidAsinBatchWriter 吞成 log.warn ⇒ 接口返回成功而黑名单静默少一批)。所以这两张表已从 CompanyDefaultGuard.WATCHED_TABLES 与探针 SQL 的 IN 列表里同时摘掉(清单与 SQL 由 CompanyDefaultGuardTest 双向钉同源),否则哨兵会在每次启动时对着一列"没人读、摘了会炸"的默认值喊 COMPANY_DEFAULT_STILL_PRESENT,而巡检把那条签名计进 ALERTS。 它们真正消失的时点是下一版(两台同版之后):

  • ALTER TABLE biz_invalid_asin_data DROP COLUMN company_id;
  • ALTER TABLE biz_product_category DROP COLUMN company_id;

摘除 DEFAULT 的动作在这两条里"顺带完成"(列没了,默认值随之消失),仍然禁写成 MODIFY COLUMN ... NOT NULL(重建表会按当时的列默认值物化历史行)。biz_shop_key 已在 V152 摘掉 DEFAULT,biz_dedupe_total_data 已在 V154 摘掉——两张的哨兵清单都原样保留:哪天默认值被 dump 重建或手滑装回,启动期还能再喊出来。

原先挂在待办里的"V137 冗余索引 DROP"迁移计划取 V139,该号已被 V139__asin_result_cache.sql 占用,顺延到 V140;V140 已被品牌补测队列表 V140__collectdata_brand_recheck.sql 落用。

已应用迁移的存量校验和(2026-10-04 与 2026-10-07 从生产 flyway_schema_history 只读实查)

版本 文件 校验和 installed_on
142 V142__web_config_sha256.sql 1152261840 2026-10-03 18:23:22
143 V143__company_and_users_company_id.sql 1539570901 2026-10-04 10:48:54
144 V144__users_company_id_drop_default.sql 1833593804 2026-10-04 13:22:00
149 V149__permission_menu_company_tree.sql 593432281 2026-10-06 17:32:29
150 V150__shop_key_company_scope.sql 2113095084 2026-10-06 17:32:29
151 V151__rule_tables_shared_across_companies.sql 613473408 2026-10-06 17:32:30

上表各行的字节就此封死。校验和算法是 Flyway 的 CRC32 逐 BufferedReader.readLine() 的 UTF-8 字节累加(行尾不入 CRC,所以 CRLF 工作树与 LF 工作树算出同一个值);142/143/144 三个值被 CompanyMigrationV144Test#appliedMigrationBytesAreFrozenAgainstProdChecksum 用工作树字节复算比对,149/150/151 被 CompanyDefaultDropV152Test#appliedV149V150V151BytesAreFrozenAgainstProdChecksum 复算比对(10-07 本机复算三值全中)。

真事:10-04 上午有人(我)把"摘掉 users.company_id 的 DEFAULT"直接改成原地编辑 V143,取证才发现 V143 已在 10:48 落库——那样发出去的 jar 会让下次启动 Flyway 校验失败、两台 java 都起不来。口径变更因此写成 V144 前向修复,并把"已应用不许原地改"从注释升级成上面那条用例。

约束

  • 审计测试断言:整数版本从 1 到当前最大值连续(RETIRED_HOLES = {132, 133} 内的号段除外)、无重复文件名、命名正则合规、历史文件校验和可复算稳定。
  • 修改任何已部署历史迁移会破坏 Flyway checksum,属违规;由本盘点测试 + code review 把关(git 层是否改动由 CI/review 校验)。
  • 回滚不得写成版本化迁移。 本目录是 Flyway 扫描路径,任何 V*.sql 都会在应用下次启动时自动执行;把回滚编成 V{N+1}__rollback_*.sql 等于让"决定回滚"这件事在没有人工执行的情况下自己发生。回滚一律是本目录之外的人工补丁脚本(首例:docs/rollback-V143-company.sql),并要按"停应用 → 跑脚本 → 删 flyway_schema_history 对应版本行 → 回滚 jar"的顺序做,漏掉删历史那步会让将来重装时 Flyway 判定"已应用"而跳过重建。
  • 迁移必须可重跑。 MySQL 的 DDL 不进事务:迁移中途失败时前面的语句已经落库,而 flyway repair + 重启会让 Flyway 从第一条语句重跑整个文件。所以建表用 IF NOT EXISTS、插种子行用 INSERT IGNORE 或 WHERE NOT EXISTS、ADD COLUMN/INDEX 先查 information_schema 再 PREPARE(首例:V142 的条件 DDL、V143 全文件)。写成裸 CREATE TABLE / 裸 INSERT ... VALUES 的迁移,恢复路径本身会撞 1050/1060/1062,把"补数据后重启"变成"必须手工清库"。