Files
crawler-plugin/docs/ops/company-multi-tenant-design-2026-10-04.md
T
huangzd1997 80b53695dd docs(多公司): 基线 dump 的位置随出库一起订正
那句"非 Java 通道只有一份基线 dump src/main/resources/db/aiimage.sql"写的还是出库前的路径,
现在照它去找会找不到文件(它已移出仓库、只在本地 gitignored 的 backend-java/data/ 下)。
2026-10-07 11:19:36 +08:00

52 KiB
Raw Blame History

多公司(租户)改造设计

日期:2026-10-04 状态:一期已上线(V143 于 2026-10-04 10:48:54 应用到生产库,jar 双节点同版; V144「摘掉 users.company_id 的列默认值」随下一个 jar 窗口生效) 决策确认:brainstorm 流程(用户逐条拍定) ⚠ 已应用的迁移字节封死:V142 校验和 1152261840、V143 校验和 1539570901 (2026-10-04 11:0x 只读实查 flyway_schema_history)。spring.flyway.validate-on-migrate=true 是硬编码, 原地改这两个文件的任何一个空格 ⇒ 下次启动校验失败、两台 java 都起不来。口径变更只能写下一条迁移, 由 CompanyMigrationV144Test.appliedMigrationBytesAreFrozenAgainstProdChecksum 把守。 适用范围:crawler-plugin/backend-java + crawler-plugin/admin-frontend-vue(后台 admin-vue)+ crawler-plugin/frontend-vue(用户端 app-web) 不修改 app_client(Python 桌面端零改动,见 §2.4) 关联:backend-java/docs/flyway-migration-template.md、backend-java/docs/migration-inventory.md


0. 一句话结论

一期只做账号归属:新建 company 主表、给 users 挂 company_id、现有全部账号归属「厦门米椿花」。 业务表一张不碰、一行不回填——57 张表里 26 张带 user_id,公司维度全部由 user_id → users.company_id 派生。 唯一索引、登录定位、89 个数据过滤出口一律不动,因此一期对线上行为是零变化。


1. 现状取证(每条均可复查)

1.1 现有「公司」字样全是紫鸟语义,不可复用

位置 语义
biz_ziniao_memory_store.company_name(V8__add_company_name_to_ziniao_memory_store.sql) 紫鸟 ERP 侧浏览器配置文件的公司,自由文本、无外键
biz_publish_file.company_name(V77__publish_task.sql:12) 同上,快照字段
ZiniaoProperties.companyId / ClientCredentialProperties.ziniaoCompany 紫鸟自动化账号所属公司

读写点仅 modules/ziniao/memory/service/ZiniaoMemoryStoreService.java:129-151、ZiniaoShopIndexService.java:219/329。 全库无 company / tenant / organization 主表,biz_shop_manage 也没有公司列。新建 company 表不与上述任何字段冲突,但命名上必须避免歧义:新表叫 company,紫鸟那两个字段保持原名不动。

1.2 没有任何框架级租户机制

TenantLineHandler、DataPermissionInterceptor、MetaObjectHandler、@InterceptorIgnore —— 全仓 0 命中。 隔离靠 service 层手写 wrapper:

  • .eq/.in(Entity::getUserId, …) 共 89 处,分布在 34 个文件
  • 构成:userId(方法参数)77 处、request.getUserId() 8 处、集合式(allowedUserIds/uniqueIds/createdById)3 处、createdById 1 处
  • 热点两张表吃掉一半:FileTaskEntity 25 处、FileResultEntity 19 处
  • 另有约 125 处其他归属口径的引用(created_by_id、"user:"+id 字符串、group_id)——这是 grep 命中数,不全是过滤条件,二期逐个接入口时要重新按"是否构成数据范围判定"分类,不能直接当工作量
  • 「admin 看全部 / normal 看自己」的角色判定在 common/security/DeviceSessionPolicy.java:26-36 resolveRole(),经 AdminAuthSupport.java:104-119 暴露;super_admin 分支散在 27 个文件、219 处
  • 唯一的统一工具 modules/permission/support/UserDataScopeSupport.java:33 只服务 3 个模块,且带 FALLBACK_LIMIT = 2000 兜底
  • 并行存在 5 套各自实现的 scope(9 个文件、37 处引用):TaskCenterScopeService、DedupeTotalDataService、ShopDataCrawlAdminTasksService、ShopDataDuplicateCheckQueryService、UserDataScopeSupport

1.3 请求体里的 user_id 不校验归属

validateUserId 只判 > 0,不判是不是登录人本人:

  • modules/patroldelete/service/PatrolDeleteResolveService.java:244-248
  • modules/similarasin/service/SimilarAsinTaskService.java:1679-1683

controller 原样透传 request.getUserId()(patroldelete/pricetrack/productrisk/shopdatacrawl/shopmatch/similarasin/withdraw 七个模块均如此)。

config/AdminApiGuardFilter.java 的 USER_TOOL_PREFIXES 列了 14 个用户态前缀(/api/patrol-delete、/api/price-track、/api/similar-asin、/api/withdraw、/api/shop-match、/api/product-risk-resolve、/api/shop-data-crawl、/api/query-asin、/api/appearance-patent、/api/brand、/api/files、/api/digital-human、/api/collect-data、/api/tasks),受 aiimage.security.user-tool-guard-enabled 控制,默认 false = 匿名可达(AdminApiGuardFilter.java:128)。

客户端确实带 X-Internal-Token(app_client/amazon/tool.py:32 internal_token_or_empty()),但那是共享静态密钥,过滤器注释自己写明「能证明走了内部通道,证明不了这个 user_id 是谁」(AdminApiGuardFilter.java:48)。 → 这 14 个前缀上的公司隔离,在阶段B(设备令牌)落地前无法真正强制。 见 §7.3。

1.4 登录链路按 username 单列定位

  • modules/auth/service/AuthService.java:94 —— selectOne(eq(username)),依赖 users.username 的全局唯一索引
  • AuthService.java:50-78 —— 登录失败锁定 map 的 key 是裸 username
  • LoginResultVo.java:11-23 —— 改造前返回 userId/username/role/isAdmin/deviceId/token/expiresIn/appColumns/adminColumns,无公司(本轮按 §4 加了 companyId:16 / companyName:18)
  • JwtService.issue() claims 只有 subject(userId) / username / deviceId
  • 前端两套登录态机制不同:用户端 frontend-vue 无 Pinia,登录态存 localStorage(shared/auth/ensure-auth.ts 的 AUTH_TOKEN_KEY = 'aiimage_auth_token',uid/username 由 ensureAuth() 与 restoreLoginUser() 两个函数各自回写),shared/api/user.ts 的 getCurrentUserId() 直接读 localStorage.uid;后台 admin-frontend-vue 是 Pinia(src/stores/admin-session.ts 的 defineStore('admin-session')),用户信息走 src/api/session.ts 的 fetchCurrentUser() → /api/admin/current-user
  • /api/admin/current-user 的返回体是 AdminConsoleController.java:70-77 里手搭的 Map<String,Object>(id/username/role/…),不是 VO 类 → 后台顶栏要显示公司名,改的是这个 Map,不是 LoginResultVo

1.5 users 表映射了两个实体

common/model/entity/AdminUserEntity.java 与 modules/auth/model/entity/LoginUserEntity.java 都 @TableName("users")。加列必须同步改两处,漏一处就是半边链路读不到公司。


2. 一期范围

2.1 数据模型(V143)

见 §3 迁移全文。要点:

  • company 主表,company_name 唯一
  • users.company_id BIGINT NOT NULL DEFAULT 1 + 索引 —— DEFAULT 1 已由 V144 摘除,列现为 NOT NULL 无默认值(§6.3 / §8.2)
  • 业务表零 DDL

2.2 建号:公司必选,超管可指定

规则与现有 createdById 完全同构(AdminUserService.java:161-175:超管可指定创建人,非超管强制落自己名下):

操作者 companyId 传了 不传
super_admin 落指定公司(校验公司存在且启用) 落自己所属公司
admin(公司内) 只允许等于自己所属公司,否则 403 落自己所属公司
normal 不可建号(现状即如此:POST /api/admin/user 需管理员 + admin_users 菜单,AdminUserService.java:136-140) —

AdminUserService.createUser 永远显式写入 company_id,不依赖列 DEFAULT(resolveTargetCompanyId 在任何分支都返回一个具体值)。 列 DEFAULT 曾只为混合版本窗口的旧 jar 存在(§8.2),现已由 V144 摘除:此后任何绕过 createUser 的写入若不带公司, MySQL 严格模式报 1364 Field 'company_id' doesn't have a default value 炸在日志里,而不是被静默塞进厦门米椿花。

前端比后端严:新后台的建号弹窗对超管必须显式选一家(validateCreateUserForm(form, operator)), 而后端对"不传"仍落操作者自己公司。这不是矛盾——后端那条口径是给尚未升级的旧后台兜底的(§5.3), 超管手里同时有 N 家公司时"静默落我自己那家"是危险默认。别把前端的必选当成冗余逻辑删掉。

移人(改账号所属公司):一期仅超管可做,且必须校验不变式——账号的 created_by_id 必须与自己同公司或为超管,否则拒绝。这条不变式是二期省掉逐个改 77 处过滤点的前提(§7.2)。

2.3 公司目录接口

新建 modules/company/:

方法 路径 权限
GET /api/admin/companies 超管列全部;公司内 admin 只列自己公司
POST /api/admin/companies 仅超管
PUT /api/admin/companies/{id} 仅超管(改名 / 启停)

不做删除:有账号挂着的公司删不掉,用 status=0 停用代替。 菜单权限走现有口径:columns 表插 admin_companies,controller 用 permissionMenuService.hasAnyAdminMenu(operator, List.of("admin_companies"))(同 AdminUserService.java:466-470)。

账号列表(AdminUserService.listUsers)一期加 companyId 可选筛选参数:超管可筛任意公司,admin 只能筛自己公司(传别家公司 → 视为无结果,不报错也不越权)。不传时行为与现状完全一致。若你只要"列表显示公司列"而不要筛选,去掉这个参数即可,其余设计不受影响(见 §9.3)。

2.4 登录态与前端显示公司名

  • LoginResultVo + check_login 返回 companyId / companyName
  • JWT 不加 claim:AdminAuthSupport.requireUser() 每次都 selectById 回库,公司随实体自然带出;加 claim 反而要处理旧 token 无该 claim 的兼容
  • 前端两个部署物都要动(后台建号表单 + 公司目录在 admin-frontend-vue,用户端顶栏显示公司名在 frontend-vue),逐文件清单见 §5
  • app_client 零改动:桌面端窗口直载线上 app-web,前端发布即全端生效,无客户端版本碎片化

2.5 一期明确不做

推迟项 触发条件
users.username 唯一索引 → (company_id, username) 第二家公司开通时
登录定位改造 + 锁定 key 改造 同上(两者必须同批,见 §7.1)
89 个数据过滤出口叠公司边界 同上
14 个用户态前缀的越权收口 阶段B 设备令牌落地
跨公司汇总 / 对比报表 用户已明确一期不要

3. V143 迁移

正文以 backend-java/src/main/resources/db/V143__company_and_users_company_id.sql 为准(已由 CompanyMigrationV143Test 12 例 + 16 条变异自证钉住),本节只记不落进代码就丢失的决策。 语句顺序共六步:建表 → 插初始公司 → 加列与索引 → 回填 → 收 NOT NULL 闸门 → 插后台菜单。

决策 为什么
初始公司 id 显式钉为 1 V143 出厂时 users.company_id 的 DEFAULT 只能是字面量(MySQL 不允许 DEFAULT 子查询),存量回填也写死 = 1。id 交给 AUTO_INCREMENT,这两处就会指向一个不存在的公司。V144 摘掉 DEFAULT 后,"回填写死 1"这一处仍然依赖它
加列 → 回填 → 再 MODIFY NOT NULL,不是一步建成 NOT NULL MODIFY ... NOT NULL 本身就是自检闸门:回填漏任何一行就抛 ER_INVALID_USE_OF_NULL 让迁移失败,而不是留一堆 NULL 静默通过(NULL = 该账号在公司维度整体失明)
闸门留 DEFAULT 1 只为混合版本窗口存在,见 §8.2;摘除不能原地改这条迁移(10:48:54 已落库),只能前向写成 V144
每条语句都写成幂等(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' 真正的跨产物契约是 column_key 必须在 admin-frontend-vue/src/router/routes.ts 登记为 menuKey:侧边栏跳转、面包屑与路由门禁都按 key 关联,且 menu-route-map.ts 会用注册表算出的规范路径覆盖库里的 route_path——所以 route_path 写错并不会 404,没登记 menuKey 才会。两边都按现有值保持一致,由 admin-frontend-vue/tests/company-menu-route.test.ts 逐条核对;columns.column_key 上有 uk_column_key,非幂等插入会直接报错
回滚是 backend-java/docs/rollback-V143-company.sql,不是一条版本化迁移 见 §8.3。(实际的 V144 是前向修复——摘 DEFAULT,不是撤销 V143;两者别混)

条件 DDL 的写法照 V142(本仓首例),幂等插菜单照 V103/V106。

菜单与公司表放同一条迁移,是因为取号存在真实争用风险(V138/V139/V140 已被其他计划占用,见 migration-inventory.md),一条迁移少占一个号。

验证 SQL

SELECT COUNT(*) AS company_rows FROM company;                        -- 期望 1
SELECT id, company_name, status FROM company;                        -- 期望 1 | 厦门米椿花 | 1
SELECT COUNT(*) AS users_total,
       SUM(company_id IS NULL) AS null_company,
       SUM(company_id = 1)     AS in_xiamen_michunghua
FROM users;                                                          -- 期望 null_company=0 且 users_total=in_xiamen_michunghua
SHOW COLUMNS FROM users LIKE 'company_id';                           -- V143 出厂期望 Default=1;V144 上线后期望 Default=NULL
SHOW INDEX FROM users WHERE Key_name = 'idx_users_company_id';       -- 期望 1 行
SELECT c.id, c.name, c.column_key, c.route_path, c.sort_order, p.column_key AS parent_key
FROM columns c LEFT JOIN columns p ON p.id = c.parent_id
WHERE c.column_key = 'admin_companies';                              -- 期望 1 行,parent_key=admin_group_account

生产实跑读数(2026-10-04 11:3x,只读,主机A 业务库)

查的 读到的 判读
flyway_schema_history 末三行 143 / 1539570901 / 10:48:54、142 / 1152261840 / 10-03 18:23:22、141 / -117620083 / 10-03 12:52:31 两个校验和就是冻结护栏里的常量,非记忆值
information_schema.COLUMNS 的 company_id IS_NULLABLE=NO、COLUMN_DEFAULT=1 回填与闸门都落上了;DEFAULT 仍在 ⇒ V144 有明确对象,尚未生效
users 归属分布 139 / null=0 / =1 的 139 一行不漏,全部落在厦门米椿花
company 行数 1 初始公司只一家
idx_users_company_id 索引行数 1 列与索引都在
菜单 admin_companies id=109、route_path=account/companies、父级 admin_group_account 与前端 routes.ts 逐字一致
两台 jar 同版 dd89997732dd1f9118aaeae96daca89e(137,416,959 B;B 10:48:36、A 11:01:21) 混合版本窗口闭合
两台启动 Flyway 行 B:validated 143 → 142 → 143 applied;A:validated 143 + Current version: 143 校验通过,A 只是没东西可补
哨兵 COMPANY_DEFAULT_STILL_PRESENT 两台近 6h 各 0 次 与 §6.3 一致:1 家公司时本来就不该喊,摘没摘只能看上面那行 COLUMN_DEFAULT
admin-vue(主机B) 当前包 20261004-110528,含 assets/companies-*.js,account/companies 命中 1、admin_companies 命中 2 公司管理页已随包出厂
app-web(主机B) 当前包 20261003-130306,companyName 命中 29 用户端带得到公司身份
两台 ERROR 行(近 2h) 各 0 这次迁移没带来新报错

更正一条我早先的读数:11:04 那次探到 admin-vue 公司页 HITS=0,不是 grep 姿势错,是当时软链还指向 01:45 的包(20261004-014530,公司页未随那版发)。11:05 切包后为 1/2 命中。

同步更新 backend-java/docs/migration-inventory.md:V144 落盘后文件数 142→143、范围 V1..V143→V1..V144、取号起点 V144→V145,并把 142/143 的生产校验和记进「已应用迁移的存量校验和」表。审计测试 MigrationInventoryTest 会校验整数版本从 1 连续到最大值(RETIRED_HOLES = {132,133} 除外)。


4. 后端改动清单

文件 改动
common/model/entity/AdminUserEntity.java +companyId
modules/auth/model/entity/LoginUserEntity.java +companyId(§1.5:两个实体都映射 users,必须同改)
modules/company/(新建) CompanyEntity / CompanyMapper / CompanyService / CompanyController;CompanyService 除目录读写外还有三条只读口径:requireActive(准入)、namesByIds(批量显示名,不做权限判定)、nameOrEmpty(单条显示名,查不到回空串)
modules/admin/service/AdminUserService.java createUser 写 companyId(§2.2 规则);update 支持超管移人 + 不变式校验;listUsers 加 companyId 可选筛选 + 批量取公司名
modules/admin/controller/AdminUserController.java GET /api/admin/users +@RequestParam(name = "company_id")
modules/admin/model/vo/AdminUserItemVo.java +company_id / company_name(前端账号列的数据源,snake_case 与其余字段同规则)
modules/admin/model/dto/* 建号/改号请求 +companyId
modules/auth/model/vo/LoginResultVo.java +companyId / companyName(用户端 app-web 走这条)
modules/admin/controller/AdminConsoleController.java:76-77 current-user 的手搭 Map +companyId / companyName(后台 admin-vue 顶栏走这条,见 §1.4)
modules/auth/service/AuthService.java login 与 checkLogin 回填公司名(不改 username 定位逻辑)
启动期巡检 modules/company/service/CompanyDefaultGuard.java(新建):company 表 >1 行 且 users.company_id 仍带 DEFAULT → log.error 带 ASCII 标记 COMPANY_DEFAULT_STILL_PRESENT,探针自身失败降级为 COMPANY_DEFAULT_PROBE_FAILED 的 WARN(不许静默当成"查过了")。scripts/_prod_watch.py 的 SIGNATURES 收第一条并计入 ALERTS(§6.3)

5. 前端改动清单

两个前端是两个独立部署物,别混:后台是 admin-frontend-vue(部署为 admin-vue),用户端是 frontend-vue(构建到 new_web_source/,部署为 app-web,桌面客户端窗口直载它)。建号表单和公司目录在后台,"用户登录后看到公司名"在用户端。

5.1 admin-frontend-vue(后台)

文件 改动
src/router/routes.ts 注册 { path: 'account/companies', menuKey: 'admin_companies', title: '公司管理', load: () => import('@/pages/account/CompaniesPage.vue') }——menuKey 必须与菜单的 column_key 一致(否则菜单点进去 404,见 §3),path 与库里 route_path 保持一致
src/pages/account/CompaniesPage.vue(新建) 公司列表 + 新建 + 改名/启停
src/api/companies.ts(新建,配 -dto.ts/-model.ts) 按 src/api/users.ts 的现有 DTO/model 分层写,不另发明一套
src/pages/account/UsersPage.vue 建号表单加公司下拉(必选,超管可选任意公司、admin 锁死自己公司);列表加公司列与筛选
src/api/users-dto.ts / users-model.ts / users.ts +companyId / companyName
src/api/session.ts + src/stores/admin-session.ts 不改:fetchCurrentUser 直接把 /api/admin/current-user 的 item 当 AdminUser 用(session.ts:6),不经解析器,所以 companyId/companyName 自动落到对象上;顶栏 AdminLayout.vue:35 的 topbarUserOf(session.user) 读它即可
src/types/admin.ts AdminUser 类型 +companyId/companyName
src/layout/topbar-model.ts + AdminLayout.vue 顶栏显示当前公司名

5.2 frontend-vue(用户端 app-web)

文件 改动
src/shared/api/user.ts LoginData +companyId / companyName
src/shared/auth/company-identity.ts(新建) 公司名的 localStorage 读写:后端没带 companyName 就删键,避免换账号后残留上一个账号的公司
src/shared/auth/ensure-auth.ts check_login 恢复登录态时一并回写公司名(该文件原本只恢复 uid/username,见 :25-39)
src/pages/login/DesktopLoginPage.vue 登录成功后写入公司名;?logout=1 / ?switch=1 那段清登录态时连 company_name 一起清(原本只清 token/uid/username)
src/shared/auth/kick-handler.ts 被顶下线(handleKicked)时连 company_name 一起清,与 uid/username 同一批
src/pages/amazon/components/AmazonTopBar.vue 顶栏用户名左侧显示公司名;为空则整段不渲染

5.3 发布耦合

admin-frontend-vue 与后端 jar 不必同批——因为 §2.2 把 companyId 做成"缺省 = 操作者所属公司",旧后台建号仍然可用(落操作者自己公司)。这是刻意的设计,目的就是消掉 §8.2 那个混合版本窗口。 frontend-vue 同理可独立发布:后端未返回 companyName 时顶栏不显示该段即可,不要写成 undefined。


6. 护栏与验收

6.1 建号必写 company_id

用例:建号后断言落库行的 company_id 等于期望值(超管指定 / admin 落自己公司 / admin 指定他司被拒)。 变异自证:把 entity.setCompanyId(...) 删掉,用例必须红——若仍绿说明用例在验 DEFAULT 而不是验代码,等于没验。

6.2 公司边界不变式

AdminUserMoveCompanyTest 8 例(建号那批用例见 §6.1;移人写进 AdminUserService.updateUser):

用例 钉住的行为
movingAloneIsAValidEdit 只传 companyId、不改密码/角色/权限,也是合法编辑(原代码的"请提供要修改的内容"会把这种请求打回)
moveIsRefusedWhenTheCreatorLivesInAnotherCompany 创建人在第三家公司 ⇒ 403 且一条 UPDATE 都不发
creatorSuperAdminIsExemptFromTheCompanyMatch 创建人是超管 ⇒ 不受同公司约束
onlySuperAdminMayMoveAccounts 公司内 admin 传别家公司 ⇒ 403,不静默改写
namingTheCurrentCompanyIsNotAMove 传的正好是账号现属公司按"没动"处理,照常改密码(幂等请求不该被判越权)
destinationCompanyMustExistAndBeActive 目标公司先 requireActive 再落库
danglingCreatorBlocksTheMove created_by_id 悬空(创建人已删)⇒ 无法确认同公司,不移
nullCreatedByIdMovesWithoutComplaint created_by_id 本来就空 ⇒ 没有冲突可校验,照移

不变式内容:账号被移进 X 公司后,它的 created_by_id 要么仍是 X 公司的人,要么是超管。 这条是 §7.2 里"77 处 eq(getUserId, userId) 无需逐个改"的前提,破口就得回到逐出口补边界那条路。

一期没做移人的前端入口:账号列表只有公司列 + 超管筛选(§5.1),移人是后台手工动作, 接口 PUT /api/admin/user 的 companyId 字段已就绪,UI 留给二期和公司目录一起出。

踩过的坑(写下一条同类用例前先看):LambdaUpdateWrapper.getSqlSegment() 只含 WHERE, SET 子句在 getSqlSet() 里。最初四条断言打在 getSqlSegment() 上,实际拿到的是 (id = #{ew.paramNameValuePairs.MPGENVAL2})——"改了哪一列"这一整组断言恒假红, 而"没移人不许带 company_id"那条恒绿。断"这次真的写了哪一列"只能取 getSqlSet()。

6.3 DEFAULT 摘除告警(防「半套发布」)

users.company_id DEFAULT 1 是临时的,只为混合版本窗口存在。V144 已经把它摘掉(MODIFY COLUMN company_id bigint NOT NULL,不带 DEFAULT), 所以本节现在盯的是「回潮」:半套发布、老 dump 重建、手工 SET DEFAULT 都会让库里又出现一个默认值—— 此后每个不显式传公司的建号被静默塞进那一家。 启动期巡检:SELECT COUNT(*) FROM company > 1 且 users.company_id 仍有 DEFAULT → 打 ERROR(纳入 _prod_watch.py 巡检 ALERTS)。用代码执行,不写进注释。

哨兵不能当 V144 的验收项:singleCompanyKeepsQuiet 故意让"只有一家公司"时闭嘴(一期就是这个状态,否则每次重启都白喊)。 而 V144 上线时库里恰好只有 1 家公司 ⇒ 摘没摘成功,哨兵一律不响。唯一复核手段是 SHOW COLUMNS FROM users LIKE 'company_id' 看 Default 是否为 NULL——这就是 V144 头注释必须自带验证 SQL 的理由(§3、CompanyMigrationV144Test.v144ShipsPostDeployVerificationSql)。

CompanyDefaultGuard(@EventListener(ApplicationReadyEvent.class))8 例:

用例 钉住的行为
secondCompanyWithDefaultStillOnShoutsError 2 家公司 + DEFAULT="1" ⇒ ERROR 带 COMPANY_DEFAULT_STILL_PRESENT 与公司数
singleCompanyKeepsQuiet 只有一家公司时 DEFAULT 是发布期故意留的(§8.2),不许喊
droppedDefaultKeepsQuiet COLUMN_DEFAULT 为 null ⇒ 已摘除,一声不响
blankDefaultCountsAsDropped 空串/空白也按"已摘除"处理
noCompanyAtAllKeepsQuiet 0 家公司时连列都不去查(短路顺序也是断言对象)
probeFailureIsAnnouncedNotSwallowed 探针抛错 ⇒ WARN 带 COMPANY_DEFAULT_PROBE_FAILED,不许静默读成"检查过了"
probeReadsTheRightColumn 捕获真实 SQL,必须探 information_schema.COLUMNS 的 'users' / 'company_id'(表名列名写错等于没探)
guardRunsWhenTheApplicationIsReady 反射断 checkOnStartup 上挂着 @EventListener(ApplicationReadyEvent.class)——漏注解这哨兵永远不跑

两个标记串故意用 ASCII:巡检是靠 docker logs | grep -aiE 匹配的,中文一旦在容器里变了编码整条签名静默失效。 scripts/_prod_watch.py 的 SIGNATURES 增 ('公司DEFAULT未摘', 'COMPANY_DEFAULT_STILL_PRESENT', True)(第 12 条,实跑 scripts/tests 全绿)。 COMPANY_DEFAULT_PROBE_FAILED 故意不进 ALERTS:生产 MySQL 账号本就缺 information_schema 读权限(见运维要点),把它做成告警只会变成常驻噪声;它出现在 WARN 里,人工核查时看得到。

6.4 迁移自检

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 确认版本连续、命名合规、历史校验和未变。

V144 与前向修复契约(CompanyMigrationV144Test 8 例 + 7 条变异自证,全部被咬死):

用例 钉住的行为
appliedMigrationBytesAreFrozenAgainstProdChecksum 按 Flyway 的 CRC32(逐 readLine() 的 UTF-8 字节、行尾不入 CRC)复算 V142/V143,必须等于生产 flyway_schema_history.checksum。这是本次差点踩的地雷:V143 已在 10:48:54 落库,原地把它的 DEFAULT 1 改掉,下一次启动就会校验失败、两台 java 都起不来
migrationIsVersionedOneFourFour 摘 DEFAULT 只能是 V144(当前最大版本),不能回填已应用的号
v144DropsTheColumnDefault MODIFY COLUMN company_id 子句里不许再出现 DEFAULT,且头注释要写清 1364 的取舍与 V143 的来源
v144TouchesOnlyUsersCompanyIdAndIsRerunnable 只 ALTER users;不许 CREATE TABLE / DROP TABLE·COLUMN·INDEX / ADD COLUMN —— 它是前向修复,不是回滚
v144HeaderCarriesTemplateFieldsAndWhyItExists 模板六项 + 「已应用」+「校验和」,让评审一眼看出这是追加而非补漏
v144ShipsPostDeployVerificationSql 自带 SHOW COLUMNS ... LIKE 'company_id' 且期望写成 Default = NULL(§6.3:哨兵在单公司时不响,这是唯一验收面)
defaultSentinelStillShipsAndWired V144 上线后 CompanyDefaultGuard 不许被当历史包袱删掉
inventoryDocTracksV144 盘点文档要记录 V144 文件名与 1539570901,否则下一个人无从知道 V143 不能碰

变异清单(M1–M7,backend-java/target/mut_v144.py + mut_v144.sh):把 DEFAULT 1 加回 MODIFY 子句、整条 ALTER 删掉、MODIFY COLUMN 改成 ADD COLUMN、验证段期望 Default = NULL 改成 = 1、头注释不再点名哨兵签名、删掉「已应用」口径、原地改 V143 摘掉 DEFAULT。 最后一条是给冻结护栏本身做的红证:8136eea9… 注入后红的不是一堆用例,而恰好是 appliedMigrationBytesAreFrozenAgainstProdChecksum 一条。

同一轮里 CompanyMigrationV143Test#migrationIsVersionedOneFourThree 里那句"V143 必须是当前最大版本"被删掉了 —— V144 落盘后它是假前提(V143 已封死,不可能再是最大号)。号段连续性与撞号仍由 MigrationInventoryTest 把守,不是没人管了。

6.5 公司目录:读写收窄与出厂一致性(§2.3)

后端 4 个测试类共 26 例(mvn -o test -Dtest="Company*Test"):

测试类 例数 钉住的行为
CompanyServiceDirectoryTest 17 超管列全部(不带任何查询条件)、公司内 admin 只列自己公司、无角色与无公司归属一律 403、admin_companies 菜单闸门、写接口仅超管、名称 trim + 唯一(改名校验排除自身)+ 不超列宽、备注不超列宽、状态只能是 0/1
CompanyControllerEndpointTest 5 每个 handler 先 requireAdminOrInternal 再碰目录(InOrder 断言调用次序)、路由与后台前端逐字一致、不暴露 DELETE、列表返回 VO 而非实体、写接口回保存后的公司
CompanyVoTest 1 过真 ObjectMapper 序列化,键名恰好 id/company_name/status/remark/created_at/updated_at,日期 yyyy-MM-dd HH:mm、空日期出 ""
CompanyServiceRequireActiveTest 3 requireActive(§2.2 那批用例):本轮只把构造器补到 3 参,断言未动

前端 2 个文件共 15 例:tests/company-user-list.test.ts(7,含一条反向排他——解析器读到 camelCase companyId/companyName 必须忽略,防止前后端各猜一套)、tests/company-user-create.test.ts(8)。

实跑证据(2026-10-04 04:45–05:11;日志文件属 target/ 产物,收尾已删,下面的数字取自当轮回显): baseline: 26 例全绿 → 16 条变异 16/16 KILLED(每条都打印了它红的那一例)→ restore check: all files byte-identical to pre-injection(三个文件还原后 sha1 与注入前逐字节一致)→ SURVIVORS/PROBLEMS: 0、PY_RC=0。

16 条变异自证(脚本注入缺陷 → 指定的那几例必须红 → 用注入前读进内存的字节还原,不许 git checkout): admin-directory-loses-own-company-filter、super-admin-directory-also-filtered、admin-without-company-falls-back-to-all、 menu-gate-removed、role-gate-removed、super-admin-write-gate-removed、company-name-not-trimmed、 duplicate-name-check-removed、duplicate-check-includes-self、status-range-check-removed、name-length-check-removed、 remark-length-check-removed、vo-loses-snake-case-name、controller-create-skips-auth、 controller-gets-a-delete-endpoint、controller-route-typo。

两条踩过的坑,留给后续同类用例:

  • 断言要打在"有没有带值的条件"上,不是打在列名上。company 表压根没有 company_id 列,最初写的 getSqlSegment()).contains("company_id") 一条恒假、配套的"超管不带条件"一条恒真,两条一起绿等于没断言。 改成 getParamNameValuePairs()).isEmpty()(超管)对 containsValue(2L)(公司内 admin)。 另两个 API 坑:Wrapper 不暴露 getParamNameValuePairs(),捕获类型必须是 LambdaQueryWrapper; 且要先碰一次 getSqlSegment() 参数才会被铺出来。MP 3.5.7 的 insert/updateById 有 Collection 重载, any() 有歧义,必须写 any(CompanyEntity.class)。
  • 变异脚本每轮开跑前要把所有被注入的文件写回 pristine(实测两批都栽了)。第一版只在 finally 里统一还原, 于是每轮只重写"本轮那个文件":第 13 轮改 CompanyVo 时,第 12 轮改 CompanyService 的缺陷还留在盘上, 红名单里混进上一轮的用例 ⇒ 日志里"红名单共 N 例"这个数字整批失真。 16 条 KILLED 本身仍可采信,因为每条变异期望红的那一例都只在自己那一轮出现(已按用例名做过归因矩阵); 但要是两轮期望的用例同名,就会被静默假判 KILLED。脚本已补上"逐轮回写 pristine"。
  • 变异脚本的锚点在 Windows 上要先对齐行尾。源码是 CRLF,decode("utf-8") 不转换行尾,锚串里的 \n 会 0 命中 ⇒ 注入静默失败 ⇒ 那一轮"没红"会被误读成"变异存活"。脚本因此加了 align() 和 --check-anchors 预检(16 条锚点全部 hits=1 才开跑)。

6.6 第二批变异自证:登录态、移人、启动哨兵、列表公司列

覆盖 §2.4(登录/current-user 带出公司身份)、§6.2(移人不变式)、§6.3(DEFAULT 哨兵)、§2.3(列表公司列与筛选), 被注入的 7 个类共 39 例(首轮 37 例,补进 2 例后 39 例)。脚本 target/mutation_company_phase2.py,表内 29 条变异 (条目数由 AST 数出,不是手数),开跑前 anchor pre-check: 29/29 锚点各命中 1 次。

首轮实跑(2026-10-04 06:02–06:47,日志 target/mutation_phase2.log):

baseline: 37 例全绿(报告 7 份,rc=0)
SUMMARY: 25/28 KILLED, SURVIVED=2 ['names-by-ids-loses-dedupe', 'move-gate-for-company-admin-removed'],
         INCONCLUSIVE=1 ['move-only-request-rejected-as-empty-edit'], restore_ok=True
PY_RC=1

三条问题全部是用例侧/脚本侧的洞,不是实现有缺陷(实现一行没改):

  • names-by-ids-loses-dedupe 存活:AdminUserListCompanyTest 把 CompanyService 整个 mock 掉了, 捕获的是调用方传出去的参数,永远摸不到 namesByIds 内部的去重。全仓 grep 证明没有任何用例用真实对象 调过这个方法 ⇒ 这条被注释宣称的护栏从未被证明过。修法:CompanyServiceNameLookupTest(真实 CompanyService
    • mock mapper)补 2 例——重复 id 折成一次查询且 IN 参数每家公司只出现一遍(用 in(col, coll) 每元素一个 MPGENVAL 参数来钉去重)、空列表与 null 一条 SQL 都不发。
  • move-gate-for-company-admin-removed 存活:断言写的是 contains("公司"),而"移人闸门"与"创建人同公司不变式" 两条 403 文案都含"公司"——删掉闸门后仍由后者抛 403,用例"因为错的原因过"。修法:两条断言各钉自己的文案 (contains("超级管理员") / contains("创建人"))。
  • move-only-request-rejected-as-empty-edit INCONCLUSIVE:变异串本身不是合法 Java(整行替换成 ) 丢了 { ⇒ 花括号失衡 ⇒ 编译失败 ⇒ 压根没有报告)。4 次尝试全 rc=1 且无 TEST-*.xml 即为此症。修法:替换串保留花括号。

修补后只复跑受影响的 4 条(06:53–07:00,target/mutation_phase2b.log,--only 过滤后"表内 29 条,本轮跳过 25 条"):

baseline: 39 例全绿(报告 7 份,rc=0)
[04] names-by-ids-loses-dedupe                 KILLED  red=1/39  期望红=命中=batchLookupSendsEachCompanyIdOnce
[05] names-by-ids-queries-on-empty-input       KILLED  red=1/39  期望红=命中=batchLookupOnEmptyInputSkipsTheTable
[11] move-only-request-rejected-as-empty-edit  KILLED  red=5/39  期望红=命中=movingAloneIsAValidEdit
[13] move-gate-for-company-admin-removed       KILLED  red=1/39  期望红=命中=onlySuperAdminMayMoveAccounts
SUMMARY: 4/4 KILLED, SURVIVED=0, INCONCLUSIVE=0, restore_ok=True(表内 29 条,本轮跳过 25 条)
PY_RC=0

两个 7 文件的还原读数(首轮与复跑一致,sha256 前 12 位与注入前逐项相同):CompanyService.java 93513896eb9a、AuthService.java d35d7715b509、AdminConsoleController.java 9102c2967947、 AdminUserService.java cf1d200c49ee、CompanyDefaultGuard.java 2900ed07c35c、AdminUserItemVo.java 8ee2c28e9c9f、AdminUserController.java 5849f9b48b39,全部 byte-identical。 复跑后 13 那轮的红名单恰好只有 onlySuperAdminMayMoveAccounts 一例——这本身就是"断言收紧后只咬它自己那条闸门"的证据。

29 条变异清单:name-or-empty-queries-on-null-id、name-or-empty-throws-when-company-missing、 name-or-empty-hides-disabled-company、names-by-ids-loses-dedupe、names-by-ids-queries-on-empty-input、 login-loses-company-name、login-loses-company-id、login-gates-on-company-active、 current-user-company-key-snake-cased、current-user-drops-company-identity、 move-only-request-rejected-as-empty-edit、same-company-naming-treated-as-a-move、 move-gate-for-company-admin-removed、move-target-company-existence-unchecked、creator-invariant-check-removed、 super-admin-creator-not-exempted、null-creator-blocks-the-move、move-does-not-write-the-column、 admin-cross-company-filter-falls-through、super-admin-filter-adds-no-condition、 unknown-company-row-crashes-the-item、empty-page-still-asks-for-names、item-vo-company-name-loses-snake-case、 company-filter-param-becomes-required、guard-threshold-off-by-one、guard-treats-blank-default-as-dropped、 guard-probe-failure-is-swallowed、guard-never-runs-on-startup、guard-probes-the-wrong-column。

新增一条规矩(第一条就栽过):变异点落在被 mock 掉的依赖内部,用例必然咬不住。判存活时先怀疑 mock 边界, 再怀疑脚本;这类护栏要用真实对象另建一组用例,注释里写"已覆盖"不作数。

6.7 全量回归

mvn test(不许 skipTests、主树禁 clean):2026-10-04 07:09 全量实跑 Tests run: 3589, Failures: 0, Errors: 0, Skipped: 7,BUILD SUCCESS,耗时 04:52(日志 target/mvn_full.log,收尾已删)。

  • scripts/tests(2026-10-04 06:12 实跑 155 passed,设计文档早前写的 137 已过期)+ admin-frontend-vue 的 npm test(06:25 复跑 1678/1678,RC=0)+ frontend-vue 的 npm test(06:20 复跑 672/672,RC=0,含本轮新增的下线清键 1 例)+ 两个前端各自的 npm run build(build 脚本自带 vue-tsc --noEmit,frontend-vue 06:21 RC=0,admin-frontend-vue 06:35 RC=0)。 这一轮全量绿是在「本批公司改动 + 另一批未提交的 task-center 改动」的同一棵工作区树上跑出来的,提交只含前者。 两者互不依赖已逐个取证:task-center 那 8 个改动/新增的 java 文件里 compan 关键词逐个文件命中 0 行(逐文件 grep -ci,不是全树一次过),本批改动的文件零引用 taskcenter; 本批唯一改签名的方法 AdminUserService.listUsers(加 companyIdFilter 形参)在 HEAD 与工作区都只有 AdminUserController 一个调用方,而它就在同一笔提交里;其余改动是纯增字段。 提交子集已在干净 worktree(detached @ 27859af8,补了 gitignore 的三处文档与 application-local.yml)单独跑过一遍全量,见下面的「V144 轮」。 本批 V144 这一轮补做了那条「更硬的证据」:27859af8 检出到干净 worktree(git worktree add --detach,工作区 0 脏件)全量实跑 Tests run: 3597, Failures: 1, Errors: 0(比 07:09 那轮多 8 例 = CompanyMigrationV144Test 的 8 例)。 唯一一条红是 TxDurationBenchmarkTest#measurementRepeatableWithinTolerance(两次测量偏差过大: 500 vs 1900,容差 upper <= lower*3), 已归因为计时假红、不是回归:同一台机器上把 BASE(c4a35c64,无 V144)与 GATE(27859af8,含 V144)各放一个干净 worktree, mvn -o -B test -Dtest=TxDurationBenchmarkTest 隔离单跑两轮,四跑全绿——BASE 8/0(16.79s / 29.18s)、GATE 8/0(15.24s / 30.47s),逐轮 MVN_RC=0。 这条用例在全量套件里跑=和 3590 例抢 CPU,本来就脆(与「门禁不要与 Nuitka 打包并行」同源)。 顺带一条读数坑:主树并发跑门禁时另一路会话同树 mvn 会换掉 target/classes,那一轮读到 3592 例 / 12 errors、 NoClassDefFoundError: TaskEntityLocalCache$Entry——隔离复跑同类 16 例全绿,所以那不是回归,是并发污染。 e2e 没跑:admin-frontend-vue 的 Playwright 用例(e2e/*.spec.ts,npm run test:browser)要起着前端与后端才成立,本轮未起服务,公司目录页也没有对应 spec——这一条是缺口,不是已通过项。 SFC 那一行清键(DesktopLoginPage.vue 的登出/切号分支)没有自动化用例覆盖:handleKicked 那条有,另一条靠人肉读代码确认。 既有红按差分读,不当回归:客户端批量测试有 8 例既有红、task_220 有 3 例既有红(已用干净 HEAD worktree 证实)。 门禁不要与 Nuitka 打包并行跑(计时用例会假红)。

7. 二/三期路线(已定案的口径,防止丢失)

7.1 唯一索引与登录(必须同批)

users.username 唯一索引 → UNIQUE (company_id, username)。一旦允许跨公司同名:

  1. AuthService.java:94 的 selectOne(eq(username)) 会抛 TooManyResultsException,登录全站挂 → 改为按 username 查列表,命中 1 条放行、多条要求指定公司(LoginRequest 加 company)。缺省不带公司时行为与现状完全一致。
  2. AuthService.java:50-78 锁定 key 从裸 username 改为 companyId|username。否则新公司建个同名账号反复错密码,就能把厦门米椿花的真人锁在门外——跨租户 DoS,不是可选优化。

这两条与索引切换必须同一次发版,任何一条滞后都是线上事故。

7.2 数据隔离(方案②:中央 scope + 逐出口接入 + 护栏)

  • CompanyScopeSupport:currentCompanyId(user) / memberUserIds(companyId) / assertSameCompany(...);role=super_admin 豁免(按 role 判,不按 company_id 判)
  • 需要叠公司边界的是范围大于一人的出口:5 套并行 scope(9 文件 37 处)、27 文件 219 处 super_admin 分支中「看全部」的部分、3 处集合式过滤、AdminUserService.listUsers 超管分支
  • 77 处 eq(getUserId, userId) 由 §2.2 的 created_by_id 同公司不变式覆盖,无需逐个改
  • 护栏:AST/正则扫描——对公司归属表的 getUserId 过滤若未走 scope 即红;变异自证(把 in 改回 eq、删掉超管豁免,必须被抓到)
  • 不给业务表冗余 company_id:与「数据按账号归属、公司维度跟着账号走」的定案相反。若日后 IN (成员列表) 在热表上撑不住,再单独议是否给那两三张表冗余

7.3 14 个用户态前缀的越权收口

user-tool-guard-enabled 默认 false(§1.3)。打开前必须先逐端点审计客户端是否带令牌,漏审一个就是线上集采/跟价全线 401——这正是当初把开关默认设成 false 的原因。 且共享静态内部令牌证明不了 user_id 是谁,所以真正的公司隔离要等阶段B 设备令牌。建议与阶段B 绑成同一张工单。


8. 风险与回滚

8.1 迁移失败

MODIFY ... NOT NULL 抛错 → Flyway 标记该版本 failed,应用启动失败。恢复:补齐漏掉的行,flyway repair 清 failed 记录后重启。 不要手工改已应用迁移的文件内容——spring.flyway.validate-on-migrate=true 是硬编码(/app/java/application-server.yml 没 pin 过它), 改一个字节 ⇒ 下次启动 DbValidate 报校验和不匹配,两台都起不来。这条不再是口头纪律: CompanyMigrationV144Test.appliedMigrationBytesAreFrozenAgainstProdChecksum 会按 Flyway 的 CRC32 复算 V142/V143 并与生产存量校验和(1152261840 / 1539570901)比对,原地改就在 mvn test 阶段红。

这条恢复路径成立的前提是 V143 每条语句都可重跑:DDL 失败时前面的语句已经落库,repair 后 Flyway 会从文件第一条重新执行。所以建表带 IF NOT EXISTS、种子行 INSERT IGNORE、ADD COLUMN 先查 information_schema 再 PREPARE(§3)。若写成裸语句,重启会在恢复路上撞 1050/1060/1062,只剩"手工清库"一条路——这也是 CompanyMigrationV143Test.migrationIsRerunnableAfterPartialFailure 存在的理由。

8.2 混合版本窗口(DEFAULT 曾为此存在,现已由 V144 摘除)

发布期间一台已上新 jar、另一台仍是旧 jar,而 /api 经主机 B 的 clb 打到两台。旧 jar 的 AdminUserService.create 不给 company_id 赋值:

  • 列若为 NOT NULL 无 DEFAULT → 严格模式报 Field 'company_id' doesn't have a default value,打到旧节点的建号请求全失败(约一半)
  • 列有 DEFAULT 1 → 旧节点建号成功并落厦门米椿花。一期只有一家公司,这个结果是正确的,不是 bug

两台同版后 DEFAULT 就成了死重,而且是有害的死重:任何绕过 createUser 的写入(手工 SQL、将来漏改的入口、回滚到带 company 模块之前的 jar)都会被静默塞进厦门米椿花。 所以定案是宁可撞 1364 炸在日志里,也不要静默归错公司 ⇒ 写成 V144 前向修复摘掉它。 摘完之后这条窗口的代价反过来:如果哪台退回到不带 company 模块的 jar,它的建号会报 1364 而不是悄悄归到公司 1——那是响着失败,不是静默失真,符合定案。 users 表除 AdminUserService 之外还有没有写入口,见 §10 的枚举结论。

8.3 回滚

补丁脚本 backend-java/docs/rollback-V143-company.sql,不是一条版本化迁移——版本化迁移放进 src/main/resources/db/ 就会被 Flyway 在下次启动时自动执行,那等于把 V143 静默撤销掉,还会让 MigrationInventoryTest 的版本连续性断言跟着变。执行顺序(停两台应用 → 跑脚本 → 删 flyway_schema_history 的 143 行 → 回退 jar → 起应用)写在脚本头部;漏掉删历史那步,将来重装带 V143 的 jar 时 Flyway 判定"已应用"直接跳过,表和列都不会重建,而 Java 侧实体照常读写 company_id ⇒ 运行期 unknown column。 回滚窗口内已建的账号会连 company_id 一起丢,业务数据不受影响(业务表从未加列)。 要区分两种"下一条迁移":V144 是口径前向修复(摘 DEFAULT,库往更严格的方向走),回滚是撤销已应用的那一笔——只有前者可以做成版本化迁移,后者永远只能人工按顺序执行。回滚 V144 同样不进扫描路径:重设 DEFAULT 1 + 删历史里 version='144' 那一行,步骤写在 V144 头注释第 5 项。 这条"回滚不进 Flyway 扫描路径"的口径连同上一条"迁移必须可重跑",一并写进了 backend-java/docs/migration-inventory.md 的「约束」段,供后续所有迁移引用。


9. 待确认(一期按下列默认口径已实现,若要改请在此推翻)

  1. 不加 company_code。一期没有任何消费点:目录页、建号下拉、顶栏显示全都用 company_name。 二期登录定位若真遇到跨公司同名账号,让用户在"先选公司"的下拉里挑比记短码更直观,短码只会多一处唯一索引 + 录入校验。
  2. 两端都显示公司名——后台 AdminLayout.vue 用户名下方一行、用户端 AmazonTopBar.vue 用户名左侧,均已在做(§5.1/§5.2)。 两处都是"后端没带 companyName 就整段不渲染",不显示 undefined。
  3. 既显示列,也支持筛选(§2.3 口径已实现)。筛选下拉仅超管可见:公司内 admin 的读接口已被后端收窄到本公司, 给它一个只能选到自己公司的筛选框是假功能。
  4. 公司内 admin 一期仍只看自己名下 1 层账号(AdminUserService.java:92-102 现状不变:列表的非超管分支只放行「自己」或「自己创建的 normal」)。 一期定案是"业务代码零改动",把可见范围放宽与 89 处数据出口叠公司边界放到同一批(§7.2); 因此公司目录页对 admin 只显示自己这一家,不承诺"看见本公司全部账号"。

10. users 写入口枚举(V144 摘 DEFAULT 的影响面)

列默认值只在 INSERT 省略该列时生效——UPDATE / DELETE 与它无关。所以"摘掉 DEFAULT 会不会把线上写挂"这个问题 只需要数清 users 的 INSERT 有几条。取证口径:@TableName("users") 的两个实体(AdminUserEntity、LoginUserEntity) → 两张 BaseMapper → 全部写调用;再排除同名前缀的别的表(user_notification、user_column_permission、user_api_secret 都与 users 无关)。

位置 操作 摘掉 DEFAULT 之后
AdminUserService.java:186 adminUserMapper.insert(entity) 唯一的 INSERT 不受影响::184 恒调 resolveTargetCompanyId(...),任何分支都返回一个具体值并写进实体(超管不传 → 落自己公司;公司内 admin → 落自己公司或 403)
AdminUserService.java:323 adminUserMapper.update(...) 改账号(移公司 / 改密码 / 改角色) UPDATE,与默认值无关;company_id 只在"真的要移人"时才进 SET 子句
AdminUserService.java:391 adminUserMapper.deleteById(uid) 删号 无关
AuthService.java:109 loginUserMapper.update(...) 登录链路写回 无关
  • 没有任何 SQL 层的写路径:src/main/resources 下不存在 MyBatis XML mapper(整棵 resources 只有 logback-spring.xml 一支 xml),两个 Mapper 接口是空的 BaseMapper 子接口、注解 SQL(@Insert/@Update/@Delete)命中 0 处。 ⇒ users 的写只能来自这两个实体的 BaseMapper 调用,上表就是全集,不是"grep 没搜到所以没有"。
  • 非 Java 通道只有一份基线 dump(原 src/main/resources/db/aiimage.sql,2026-10-07 已移出仓库,现只在本地 gitignored 的 backend-java/data/aiimage.sql)——INSERT INTO users VALUES (...),全列显式、且早于 V143 所以不带这一列。用它重建库时列由 V143 加、默认值由 V144 摘,顺序上成立。 ⚠ 顺带记一笔:这份 dump 含全体账号的 pbkdf2:sha256:1000000$... 口令散列,已在 git 里(非本次引入),将来要动 users 相关的对外交付时得把它算进暴露面。

结论:Java 侧不会因为 V144 新增任何 1364。剩下的暴露面全部在应用之外——手工 SQL、别的进程直连库、dump 重建—— 而那些正是我们希望它们报错的路径(§8.2)。