feat(多公司): V143 建 company 与 users.company_id,配 12 例迁移护栏

一期只做账号归属:company 主表 + users.company_id,57 张业务表零 DDL、零回填,
公司维度全部由 user_id → users.company_id 派生。存量账号在迁移里归入「厦门米椿花」,
不需要另外拿脚本对着生产库 UPDATE。

两个不落进代码就会丢的判断:

1) 每条语句都写成幂等。MySQL 的 DDL 不进事务,NOT NULL 闸门失败时前面的建表/插数/加列
   已经落库,而 repair + 重启会让 Flyway 从第一条语句重跑整个文件;写成裸 CREATE TABLE /
   裸 INSERT 的话,恢复路径自己撞 1050/1060/1062,"补数据后重启"就变成"必须手工清库"。
2) 回滚是 docs/rollback-V143-company.sql,不是一条 V144 迁移。放进 src/main/resources/db/
   等于让 Flyway 在下次启动时自动执行回滚。这两条口径一并写进 migration-inventory.md 的
   约束段,供后续所有迁移引用。

闸门留 DEFAULT 1 只为混合版本窗口存在(旧 jar 建号不带 company_id),摘除时机改由启动期
巡检盯(下一步实现),不靠人记。

CompanyMigrationV143Test 12 例,断言打在剥掉注释后的可执行 SQL 上(否则"注释里写了这句话"
就算通过);16 条变异全部被抓到。全量 mvn test 3515 例 0 红。

后端 modules/company、两端前端、DEFAULT 摘除巡检尚未开始。
This commit is contained in:
2026-10-04 03:27:27 +08:00
parent 4ffd407c53
commit f81d89bae1
5 changed files with 637 additions and 74 deletions
@@ -128,76 +128,23 @@ controller 原样透传 `request.getUserId()`(`patroldelete`/`pricetrack`/`pro
---
## 3. V143 迁移全文
## 3. V143 迁移
`backend-java/src/main/resources/db/V143__company_and_users_company_id.sql`
**正文以 `backend-java/src/main/resources/db/V143__company_and_users_company_id.sql` 为准**(已由
`CompanyMigrationV143Test` 12 例 + 16 条变异自证钉住),本节只记不落进代码就丢失的决策。
语句顺序共六步:建表 → 插初始公司 → 加列与索引 → 回填 → 收 NOT NULL 闸门 → 插后台菜单。
```sql
-- =============================================================
-- 迁移 V143__company_and_users_company_id
-- 模板:docs/flyway-migration-template.md(task-192)
--
-- 1. 变更目的:为多公司场景引入租户主表 company,给 users 挂 company_id,
-- 并把现有全部账号归属「厦门米椿花」;同时插入后台「公司管理」菜单。
-- 业务表不加列——公司维度由 user_id 派生。
-- 2. 影响表与数据量:company(新建,1 行);users(全表 UPDATE 一次,行数以生产实查为准——
-- aiimage.sql 快照的 AUTO_INCREMENT=106 且 id 有跳号,不等于行数);columns(+1 行菜单)。
-- 三张表都是百行量级,业务表 0 张受影响。
-- 3. 锁表风险:低。users 约百行;MySQL 8 的 ADD COLUMN 为 INSTANT,
-- MODIFY ... NOT NULL 触发 COPY 重建但数据量极小(毫秒级),ADD INDEX 为 INPLACE。
-- 不涉及 biz_task_file_job 等锁热点表。
-- 4. 验证 SQL:见文件末尾「验证」段。
-- 5. 回滚步骤:补丁脚本 backend-java/docs/ops/rollback-V143-company.sql(**刻意放在
-- src/main/resources/db/ 之外**:放成 V144 会被 Flyway 下次启动直接执行,等于自动回滚掉本迁移)。
-- 内容为 ALTER TABLE users DROP INDEX idx_users_company_id, DROP COLUMN company_id;
-- DROP TABLE IF EXISTS company; 并删除 admin_companies 菜单行。可完全回退。
-- 真要回滚时:先停两台应用 → 手工执行该脚本 → 在 flyway_schema_history 删掉 V143 行 → 回退 jar。
-- 6. 上线窗口:随 jar 双节点滚动发布,Flyway 在应用启动期执行,
-- 第二节点见到已应用会跳过。建议业务低峰 02:00-06:00。
-- =============================================================
| 决策 | 为什么 |
|---|---|
| 初始公司 `id` 显式钉为 1 | `users.company_id` 的 DEFAULT 只能是字面量(MySQL 不允许 DEFAULT 子查询),回填也写死 `= 1`。id 交给 AUTO_INCREMENT,这两处就会指向一个不存在的公司 |
| 加列 → 回填 → 再 `MODIFY NOT NULL`,不是一步建成 NOT NULL | `MODIFY ... NOT NULL` 本身就是自检闸门:回填漏任何一行就抛 `ER_INVALID_USE_OF_NULL` 让迁移失败,而不是留一堆 NULL 静默通过(NULL = 该账号在公司维度整体失明) |
| 闸门留 `DEFAULT 1` | 只为混合版本窗口存在,见 §8.2;摘除时机由 §6.3 的启动期巡检盯,不在迁移里处理 |
| 每条语句都写成幂等(`IF NOT EXISTS` / `INSERT IGNORE` / 查 `information_schema` 后 `PREPARE` / `WHERE` 限定 / `NOT EXISTS` 守卫) | MySQL 的 DDL 不进事务。迁移中途失败时前面的语句已落库,而 §8.1 的恢复步骤(补数据 → `flyway repair` → 重启)会让 Flyway **从第一条语句重跑整个文件**;写成裸 `CREATE TABLE` / 裸 `INSERT ... VALUES`,恢复路径自己会撞 1050/1060/1062,把"补数据后重启"变成"必须手工清库" |
| 菜单 `sort_order` 按同级 `MAX+5` 自算 | 现有子菜单的 sort_order 来自初始数据、从未被任何迁移设定过,写字面量等于猜 |
| 菜单 `route_path = 'account/companies'`、`column_key = 'admin_companies'` | 必须与 `admin-frontend-vue/src/router/routes.ts` 逐字一致,否则菜单点进去 404;`columns.column_key` 上有 `uk_column_key`,非幂等插入会直接报错 |
| 回滚是 `backend-java/docs/rollback-V143-company.sql`,**不是一条 V144 迁移** | 见 §8.3 |
CREATE TABLE `company` (
`id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
`company_name` varchar(128) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '公司名称',
`status` tinyint NOT NULL DEFAULT 1 COMMENT '1=启用 0=停用',
`remark` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NULL DEFAULT NULL COMMENT '备注',
`created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
PRIMARY KEY (`id`) USING BTREE,
UNIQUE INDEX `uk_company_name`(`company_name` ASC) USING BTREE,
INDEX `idx_company_status`(`status` ASC) USING BTREE
) ENGINE = InnoDB AUTO_INCREMENT = 2 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = '公司(租户)主表' ROW_FORMAT = Dynamic;
-- id 显式钉为 1:users.company_id 的 DEFAULT 必须是字面量(MySQL 不允许 DEFAULT 子查询),
-- 而混合版本窗口里旧 jar 建号不带 company_id,靠这个 DEFAULT 才不会失败(见设计 §8.2)。
INSERT INTO `company` (`id`, `company_name`, `status`, `remark`)
VALUES (1, '厦门米椿花', 1, '初始公司:现有全部账号与数据归属');
ALTER TABLE `users`
ADD COLUMN `company_id` bigint NULL DEFAULT NULL COMMENT '所属公司(company.id)' AFTER `created_by_id`,
ADD INDEX `idx_users_company_id`(`company_id` ASC) USING BTREE;
UPDATE `users` SET `company_id` = 1 WHERE `company_id` IS NULL;
-- 自检闸门:上一句若漏掉任何一行,这里抛 ER_INVALID_USE_OF_NULL 让迁移失败,
-- 而不是留一堆 NULL 静默通过。
ALTER TABLE `users`
MODIFY COLUMN `company_id` bigint NOT NULL DEFAULT 1 COMMENT '所属公司(company.id)';
-- 后台「公司管理」菜单,挂在「账号与权限」分组(admin_group_account,V103 建)下,
-- 与 admin_users→account/users、admin_group_manage→account/groups 同一命名口径(V109)。
-- 幂等写法照 V106;sort_order 按同级最大值 +5 自算——现有子菜单的 sort_order 来自初始数据、
-- 从未被任何迁移设定,写字面量等于猜。
INSERT INTO `columns` (`name`, `column_key`, `menu_type`, `route_path`, `sort_order`, `parent_id`)
SELECT '公司管理', 'admin_companies', 'admin', 'account/companies',
(SELECT COALESCE(MAX(sib.sort_order), 0) + 5
FROM `columns` sib
WHERE sib.parent_id = parent.id),
parent.id
FROM `columns` parent
WHERE parent.`column_key` = 'admin_group_account'
AND NOT EXISTS (SELECT 1 FROM `columns` x WHERE x.`column_key` = 'admin_companies');
```
条件 DDL 的写法照 V142(本仓首例),幂等插菜单照 V103/V106。
> 菜单与公司表放同一条迁移,是因为取号存在真实争用风险(V138/V139/V140 已被其他计划占用,见 `migration-inventory.md`),一条迁移少占一个号。
@@ -289,7 +236,18 @@ WHERE c.column_key = 'admin_companies'; -- 期望 1
### 6.4 迁移自检
`MODIFY ... NOT NULL` 本身即闸门(§3);另跑 `MigrationInventoryTest` 确认版本连续、命名合规、历史校验和未变。
`MODIFY ... NOT NULL` 本身即闸门(§3)。
文件层护栏落在 `backend-java/src/test/java/com/nanri/aiimage/config/CompanyMigrationV143Test.java`
(12 例,逐条标注它防的是哪个破坏点;断言打在**剥掉注释后的可执行 SQL** 上,避免"注释里写了这句话就算通过"):
版本号与撞号、头注释六项、`uk_company_name` 唯一、初始公司 id 钉死为 1、只允许 ALTER `users` 一张表、
回填与闸门的先后、DEFAULT 仍在、菜单幂等与 `route_path`/父级、可重跑性、回滚在扫描路径之外、
盘点文档三个数字与取号起点。变异自证 16 条(脚本注入缺陷 → 指定期望用例必须红 → 用注入前读进内存的字节还原)。
变异清单:去 `IF NOT EXISTS`、去 `IGNORE`、把 `IF(@col_exists=0)` 改成无条件执行、初始公司 id 改 7、
去掉 INSERT 的 `id` 列、删掉回填 UPDATE、把 NOT NULL 闸门提到回填之前、去掉闸门的 `DEFAULT 1`、
`uk_company_name` 降级成普通索引、去掉菜单的 `NOT EXISTS`、`route_path` 改错、父级分组改错、
给 `biz_shop_manage` 也加 `company_id`、把回滚写成 `V144__rollback_company.sql` 放进 `src/main/resources/db/`、
盘点文档取号起点不跟着改、盘点文档文件数不跟着改。
另跑 `MigrationInventoryTest` 确认版本连续、命名合规、历史校验和未变。
### 6.5 全量回归
@@ -331,6 +289,8 @@ WHERE c.column_key = 'admin_companies'; -- 期望 1
`MODIFY ... NOT NULL` 抛错 → Flyway 标记该版本 failed,应用启动失败。恢复:补齐漏掉的行,`flyway repair` 清 failed 记录后重启。**不要**手工改 V143 文件内容(校验和会变)。
这条恢复路径成立的前提是 **V143 每条语句都可重跑**:DDL 失败时前面的语句已经落库,repair 后 Flyway 会从文件第一条重新执行。所以建表带 `IF NOT EXISTS`、种子行 `INSERT IGNORE`、`ADD COLUMN` 先查 `information_schema` 再 `PREPARE`(§3)。若写成裸语句,重启会在恢复路上撞 1050/1060/1062,只剩"手工清库"一条路——这也是 `CompanyMigrationV143Test.migrationIsRerunnableAfterPartialFailure` 存在的理由。
### 8.2 混合版本窗口(这是 DEFAULT 存在的唯一理由)
发布期间一台已上新 jar、另一台仍是旧 jar,而 `/api` 经主机 B 的 clb 打到两台。旧 jar 的 `AdminUserService.create` 不给 `company_id` 赋值:
@@ -342,8 +302,9 @@ WHERE c.column_key = 'admin_companies'; -- 期望 1
### 8.3 回滚
补丁脚本 `backend-java/docs/ops/rollback-V143-company.sql`,**不是一条 V144 迁移**——版本化迁移放进 `src/main/resources/db/` 就会被 Flyway 在下次启动时自动执行,那等于把 V143 静默撤销掉,还会让 `MigrationInventoryTest` 的版本连续性断言跟着变。执行顺序见 §3 头注释第 5 项。
补丁脚本 `backend-java/docs/rollback-V143-company.sql`,**不是一条 V144 迁移**——版本化迁移放进 `src/main/resources/db/` 就会被 Flyway 在下次启动时自动执行,那等于把 V143 静默撤销掉,还会让 `MigrationInventoryTest` 的版本连续性断言跟着变。执行顺序(停两台应用 → 跑脚本 → 删 `flyway_schema_history` 的 143 行 → 回退 jar → 起应用)写在脚本头部;漏掉删历史那步,将来重装带 V143 的 jar 时 Flyway 判定"已应用"直接跳过,表和列都不会重建,而 Java 侧实体照常读写 `company_id` ⇒ 运行期 unknown column。
回滚窗口内已建的账号会连 `company_id` 一起丢,业务数据不受影响(业务表从未加列)。
这条"回滚不进 Flyway 扫描路径"的口径连同上一条"迁移必须可重跑",一并写进了 `backend-java/docs/migration-inventory.md` 的「约束」段,供后续所有迁移引用。
---