feat(停用): V155 给 users 加 disabled_at——停用第一次有账号级载体

生产 users 只有 11 列、无任何状态列,expires_at 140 行全 NULL,所以停用既无字段可落、
也不能借 machine(那是测试号签名 + 互踢判定在用)。不复用 expires_at 塞哨兵:取消停用
会把收费到期日一起抹掉。两张 users 实体同批改,少一张就有一条鉴权路径读不到。

台账同步:文件数 153、范围 V1..V155、取号起点推到 V156
This commit is contained in:
2026-10-09 14:30:57 +08:00
parent b4b2fe2aa5
commit 49f786f30f
6 changed files with 119 additions and 5 deletions
@@ -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 列留着零影响。
-- =============================================================