From 49f786f30fd2de6d698cf81615ce67896f183bba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Fri, 9 Oct 2026 14:30:57 +0800 Subject: [PATCH] =?UTF-8?q?feat(=E5=81=9C=E7=94=A8):=20V155=20=E7=BB=99=20?= =?UTF-8?q?users=20=E5=8A=A0=20disabled=5Fat=E2=80=94=E2=80=94=E5=81=9C?= =?UTF-8?q?=E7=94=A8=E7=AC=AC=E4=B8=80=E6=AC=A1=E6=9C=89=E8=B4=A6=E5=8F=B7?= =?UTF-8?q?=E7=BA=A7=E8=BD=BD=E4=BD=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 生产 users 只有 11 列、无任何状态列,expires_at 140 行全 NULL,所以停用既无字段可落、 也不能借 machine(那是测试号签名 + 互踢判定在用)。不复用 expires_at 塞哨兵:取消停用 会把收费到期日一起抹掉。两张 users 实体同批改,少一张就有一条鉴权路径读不到。 台账同步:文件数 153、范围 V1..V155、取号起点推到 V156 --- backend-java/docs/migration-inventory.md | 10 +-- .../docs/rollback-V155-users-disabled-at.sql | 15 +++++ .../common/model/entity/AdminUserEntity.java | 6 ++ .../auth/model/entity/LoginUserEntity.java | 6 ++ .../resources/db/V155__users_disabled_at.sql | 63 +++++++++++++++++++ .../security/UserDisabledAtShapeTest.java | 24 +++++++ 6 files changed, 119 insertions(+), 5 deletions(-) create mode 100644 backend-java/docs/rollback-V155-users-disabled-at.sql create mode 100644 backend-java/src/main/resources/db/V155__users_disabled_at.sql create mode 100644 backend-java/src/test/java/com/nanri/aiimage/common/security/UserDisabledAtShapeTest.java diff --git a/backend-java/docs/migration-inventory.md b/backend-java/docs/migration-inventory.md index 7c50bd4ea..decec1a65 100644 --- a/backend-java/docs/migration-inventory.md +++ b/backend-java/docs/migration-inventory.md @@ -5,11 +5,11 @@ ## 概览 -- 版本化迁移文件数:**152**(`src/main/resources/db/V*.sql`,其中整数版本 151 个 + 小版本 V25_1) -- 整数版本范围:**V1..V154**,其中 V132/V133/V148 为已退役空号(见下),其余连续 +- 版本化迁移文件数:**153**(`src/main/resources/db/V*.sql`,其中整数版本 152 个 + 小版本 V25_1) +- 整数版本范围:**V1..V155**,其中 V132/V133/V148 为已退役空号(见下),其余连续 - 历史遗留小版本:**V25_1__shop_manage_group_bind_user.sql**(Flyway 语义 25.1,紧跟在 V25 之后、V26 之前执行,属历史命名,保留) -- 最新版本:**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**) -- 待下一次 jar 发版执行:**V154**(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.sql**(上一版 **V154__biz_dedupe_total_data_company_id_drop_default.sql**,再上一版 **V153__shop_manage_group_company_id.sql**) +- 待下一次 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 版本推的 - 重复版本:无 @@ -25,7 +25,7 @@ `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` 里登记。 -后续新增迁移从 **V155** 起取号(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**: +后续新增迁移从 **V156** 起取号(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 同名提及那个坑)。 diff --git a/backend-java/docs/rollback-V155-users-disabled-at.sql b/backend-java/docs/rollback-V155-users-disabled-at.sql new file mode 100644 index 000000000..a8a27f8b2 --- /dev/null +++ b/backend-java/docs/rollback-V155-users-disabled-at.sql @@ -0,0 +1,15 @@ +-- 回滚 V155(users.disabled_at)——人工执行,放在 Flyway 扫描路径之外。 +-- 理由:把回滚也做成版本化迁移,等于让"决定回滚"这件事自己发生(V150/V152/V154 同款处置)。 +-- +-- 只在"这列不该加"时才跑。仅仅回滚 jar 不需要它:旧 jar 不认识 disabled_at,留着 NULL 列零影响。 +-- +-- 顺序:停两台 java → 跑本文件 → 删 flyway_schema_history 的 version='155' 行 → 回滚 jar → 起 java。 +-- +-- ⚠ 跑之前先确认没有非 NULL 的停用行,否则 DROP COLUMN 会把停用记录一起抹掉、事后无从追认: +-- SELECT COUNT(*) FROM `users` WHERE `disabled_at` IS NOT NULL; -- 期望 0 + +ALTER TABLE `users` DROP COLUMN `disabled_at`; + +-- 复核: +-- SHOW COLUMNS FROM `users` LIKE 'disabled_at'; -- 期望 Empty set +-- DELETE FROM flyway_schema_history WHERE version = '155'; diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/model/entity/AdminUserEntity.java b/backend-java/src/main/java/com/nanri/aiimage/common/model/entity/AdminUserEntity.java index 72bf13fcd..9f63dfe2e 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/common/model/entity/AdminUserEntity.java +++ b/backend-java/src/main/java/com/nanri/aiimage/common/model/entity/AdminUserEntity.java @@ -32,6 +32,12 @@ public class AdminUserEntity { */ @TableField("expires_at") private LocalDateTime expiresAt; + /** + * 管理员停用时刻;非 NULL 即停用——同时挡重新登录与已发令牌。 + * 与 expires_at(V146 收费到期)分列:复用后者会在取消停用时抹掉原到期日。 + */ + @TableField("disabled_at") + private LocalDateTime disabledAt; @TableField("created_at") private LocalDateTime createdAt; /** diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/auth/model/entity/LoginUserEntity.java b/backend-java/src/main/java/com/nanri/aiimage/modules/auth/model/entity/LoginUserEntity.java index 15c3aa755..6efda7993 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/auth/model/entity/LoginUserEntity.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/auth/model/entity/LoginUserEntity.java @@ -37,4 +37,10 @@ public class LoginUserEntity { */ @TableField("expires_at") private LocalDateTime expiresAt; + /** + * 管理员停用时刻;非 NULL 即停用——同时挡重新登录与已发令牌。 + * 与 expires_at(V146 收费到期)分列:复用后者会在取消停用时抹掉原到期日。 + */ + @TableField("disabled_at") + private LocalDateTime disabledAt; } diff --git a/backend-java/src/main/resources/db/V155__users_disabled_at.sql b/backend-java/src/main/resources/db/V155__users_disabled_at.sql new file mode 100644 index 000000000..1c3c399de --- /dev/null +++ b/backend-java/src/main/resources/db/V155__users_disabled_at.sql @@ -0,0 +1,63 @@ +-- ============================================================= +-- 迁移 V155__users_disabled_at +-- 模板:docs/flyway-migration-template.md +-- 需求:会话容忍设计 docs/superpowers/specs/2026-10-09-session-tolerance-while-task-running-design.md §5 停点 3 +-- +-- 1. 变更目的:给 `users` 加一列可空 `disabled_at`,让"管理员停用账号"在数据上第一次有位置。 +-- 今天做不到的事:生产 `users` 只有 11 列(users/id/username/password_hash/is_admin/created_at/ +-- updated_at/machine/role/created_by_id/company_id/expires_at),没有任何状态列;"停用"只能靠 +-- 删除账号(硬删、无外键、无审计)表达,而删除是不可逆的、且会留下孤儿业务行。 +-- 为什么不复用 `expires_at` 塞哨兵值:那是收费到期字段。用哨兵表达停用,取消停用时原到期日 +-- 就被抹掉了——这类损失上线当天没人看见,对账那天才炸。分列之后,停用与到期可以并存, +-- 取消停用后原到期日仍然生效。 +-- +-- 2. 前提取证(2026-10-09 只读探针 scripts/_probe_notif_anomaly_scan.py,主机A,零写入): +-- · `users` 共 140 行、3 家公司; +-- · `expires_at` 140 行【全为 NULL】⇒ 到期级联(AccountExpiryService,V146)今天一条都不生效, +-- 所以"停用"没有任何现成载体可以借用; +-- · `machine` 非空但被当测试号签名使用(claude-*/e2e-*),不能拿来表达停用——它会与互踢判定 +-- (DeviceSessionPolicy.assertSameDevice)抢同一个字段。 +-- +-- 3. 影响表与数据量:只加一列,不写数据、不加索引、不删列、不碰其他任何表。 +-- 加列后 140 行全部取 NULL(=未停用),行为与加列前逐字一致。 +-- +-- 4. 锁表风险:极低。MySQL 8.4 的 ADD COLUMN NULL 走 INSTANT 算法(只改元数据,不重建表、不扫行)。 +-- 【禁写成 ADD COLUMN NOT NULL DEFAULT ...】——那会改变列的物化方式,且本列语义上必须有 +-- "未停用"与"停用时刻"两种状态,NULL 就是前者。 +-- +-- 5. 验证 SQL(迁移后跑,不许只看启动日志的 Successfully applied): +-- SHOW COLUMNS FROM `users` LIKE 'disabled_at'; +-- -> 期望 Null = YES,Default = NULL +-- SELECT COUNT(*) AS total, SUM(disabled_at IS NOT NULL) AS disabled FROM `users`; +-- -> 期望 total = 140、disabled = 0(本迁移只加列,不回填任何停用值) +-- 应用侧确认两条闸都读到了该列:AccountExpiryServiceTest + AccountDisabledGateTest 全绿 +-- (只挡请求不挡登录 = 被停用的人重新登录一次就把吊销冲掉,两用例分别钉一头)。 +-- +-- 6. 上线窗口:随 jar 双节点同窗口发布。加列对旧 jar 无影响(旧代码不认识新列), +-- 混合版本窗口零行为差异;新代码读该列前 Flyway 已保证列存在。 +-- 本列必须与"读它的代码"同版:只发迁移不发 jar,停用无人执行;只发 jar 不发迁移,启动期 +-- 读列即 1054 Unknown column(V146 同款结论)。 +-- +-- 【可重跑性】加列前先查 information_schema(照 V146 的条件 DDL 惯例):迁移中途失败时 +-- flyway repair + 重启会让 Flyway 从第一条语句重跑整个文件,裸 ADD COLUMN 会撞 1060。 +-- ============================================================= + +SET @col_exists := ( + SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'users' + AND COLUMN_NAME = 'disabled_at' +); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE `users` ADD COLUMN `disabled_at` datetime NULL COMMENT ''管理员停用时刻(NULL=未停用)。非 NULL 即挡重新登录、并让已发令牌立刻失效;与 expires_at(收费到期)分列,取消停用后原到期日仍生效''', + 'SELECT ''users.disabled_at already exists, skipped'' AS note'); +PREPARE stmt FROM @ddl; +EXECUTE stmt; +DEALLOCATE PREPARE stmt; + +-- ============================================================= +-- 回滚:人工补丁 docs/rollback-V155-users-disabled-at.sql(在 Flyway 扫描路径之外) +-- 触发场景是"这列不该加"。顺序:停两台应用 → 跑补丁(DROP COLUMN) +-- → 删 flyway_schema_history 的 version='155' 行 → 回滚 jar → 起应用。 +-- 仅仅回滚 jar(代码问题、与列无关)不需要 DROP:旧 jar 不认识该列,NULL 列留着零影响。 +-- ============================================================= diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/security/UserDisabledAtShapeTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/security/UserDisabledAtShapeTest.java new file mode 100644 index 000000000..c73ff6682 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/security/UserDisabledAtShapeTest.java @@ -0,0 +1,24 @@ +package com.nanri.aiimage.common.security; + +import com.nanri.aiimage.common.model.entity.AdminUserEntity; +import com.nanri.aiimage.modules.auth.model.entity.LoginUserEntity; +import org.junit.jupiter.api.Test; + +import java.time.LocalDateTime; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * 停用需要账号级载体,而 {@code users} 今天只有 11 列、没有任何状态列。 + * 鉴权链上两张 {@code users} 的实体必须同时拿到该字段:只加一张,另一条路径就读不到停用。 + */ +class UserDisabledAtShapeTest { + + @Test + void bothUserEntitiesExposeDisabledAt() throws Exception { + assertThat(AdminUserEntity.class.getDeclaredMethod("getDisabledAt").getReturnType()) + .isEqualTo(LocalDateTime.class); + assertThat(LoginUserEntity.class.getDeclaredMethod("getDisabledAt").getReturnType()) + .isEqualTo(LocalDateTime.class); + } +}