From 7ad4932bd5e6c9db9f93aebf0094a0ca0149d8f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Sun, 4 Oct 2026 02:29:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E5=A4=9A=E5=85=AC=E5=8F=B8):=20=E4=B8=80?= =?UTF-8?q?=E6=9C=9F=E7=A7=9F=E6=88=B7=E6=94=B9=E9=80=A0=E8=AE=BE=E8=AE=A1?= =?UTF-8?q?=20=E2=80=94=E2=80=94=20company=20=E8=A1=A8=20+=20users.company?= =?UTF-8?q?=5Fid=EF=BC=8C=E4=B8=9A=E5=8A=A1=E8=A1=A8=E9=9B=B6=20DDL?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 现有 company_name 两处均为紫鸟语义不可复用,全库无租户机制(89 处手写 user_id 过滤散在 34 文件),故一期只落账号归属:V143 建 company 主表、 users 挂 company_id 并全量归属厦门米椿花,公司维度由 user_id 派生。 唯一索引切换、登录定位、数据隔离出口一律推迟到第二家公司开通时, 并记录两个必须同批改的点(username 唯一索引 vs 登录 selectOne、 锁定 key 裸 username 造成的跨租户 DoS)与 14 个匿名可达前缀的收口前提。 回滚刻意写成迁移目录外的补丁脚本:放成 V144 会被 Flyway 下次启动 直接执行,等于自动撤销 V143。 --- .../company-multi-tenant-design-2026-10-04.md | 355 ++++++++++++++++++ 1 file changed, 355 insertions(+) create mode 100644 docs/ops/company-multi-tenant-design-2026-10-04.md diff --git a/docs/ops/company-multi-tenant-design-2026-10-04.md b/docs/ops/company-multi-tenant-design-2026-10-04.md new file mode 100644 index 000000000..7a06728fa --- /dev/null +++ b/docs/ops/company-multi-tenant-design-2026-10-04.md @@ -0,0 +1,355 @@ +# 多公司(租户)改造设计 + +> 日期:2026-10-04 状态:**待审** 决策确认:brainstorm 流程(用户逐条拍定) +> 适用范围:`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:10-19` —— 返回 `userId/username/role/isAdmin/deviceId/token/expiresIn/appColumns/adminColumns`,无公司 +- `JwtService.issue()` claims 只有 `subject(userId)` / `username` / `deviceId` +- 前端两套登录态机制不同:**用户端 `frontend-vue` 无 Pinia**,登录态存 localStorage(`shared/auth/ensure-auth.ts:13` `aiimage_auth_token`、`:25-39` `uid`/`username`),`shared/api/user.ts:4-13 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:66-71` 里**手搭的 `Map`**(`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` + 索引 +- **业务表零 DDL** + +### 2.2 建号:公司必选,超管可指定 + +规则与现有 `createdById` 完全同构(`AdminUserService.java:146-168`:超管可指定创建人,非超管强制落自己名下): + +| 操作者 | `companyId` 传了 | 不传 | +|---|---|---| +| `super_admin` | 落指定公司(校验公司存在且启用) | 落自己所属公司 | +| `admin`(公司内) | **只允许等于自己所属公司**,否则 403 | 落自己所属公司 | +| `normal` | 不可建号(现状即如此:`POST /api/admin/user` 需管理员 + `admin_users` 菜单,`AdminUserService.java:60-63`) | — | + +`AdminUserService.create` **永远显式写入** `company_id`,不依赖列 DEFAULT。DEFAULT 只为混合版本窗口存在(§8.2)。 + +移人(改账号所属公司):一期**仅超管**可做,且必须校验不变式——账号的 `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:347-351`)。 + +账号列表(`AdminUserService.adminPage`)一期加 `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` + +```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。 +-- ============================================================= + +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'); +``` + +> 菜单与公司表放同一条迁移,是因为取号存在真实争用风险(V138/V139/V140 已被其他计划占用,见 `migration-inventory.md`),一条迁移少占一个号。 + +**验证 SQL** + +```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'; -- 期望 Null=NO, Default=1 +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 +``` + +同步更新 `backend-java/docs/migration-inventory.md`:文件数 141→142、范围 V1..V142→V1..V143、最新版本行、取号起点 V143→V144。审计测试 `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` | +| `modules/admin/service/AdminUserService.java` | `create` 写 `companyId`(§2.2 规则);`update` 支持超管移人 + 不变式校验;`adminPage` 加 `companyId` 筛选 | +| `modules/admin/model/dto/*` | 建号/改号请求 +`companyId` | +| `modules/auth/model/vo/LoginResultVo.java` | +`companyId` / `companyName`(**用户端** app-web 走这条) | +| `modules/admin/controller/AdminConsoleController.java:66-71` | `current-user` 的手搭 Map +`companyId` / `companyName`(**后台** admin-vue 顶栏走这条,见 §1.4) | +| `modules/auth/service/AuthService.java` | `login` 与 `checkLogin` 回填公司名(**不改** username 定位逻辑) | +| 启动期巡检 | 多公司 + DEFAULT 未摘除 → ERROR 告警(§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') }`——`path` 必须与 V143 里菜单的 `route_path` 逐字一致,`menuKey` 必须与 `column_key` 一致,否则菜单点进去 404 | +| `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` 的返回类型与 `state.user` +`companyId`/`companyName`(该 store 是 Pinia,已有 `isSuperAdmin` getter,同处扩展) | +| `src/types/admin.ts` | `AdminUser` 类型 +`companyId`/`companyName` | +| `src/layout/topbar-model.ts` + `AdminLayout.vue` | 顶栏显示当前公司名 | + +### 5.2 `frontend-vue`(用户端 app-web) + +| 文件 | 改动 | +|---|---| +| `shared/api/user.ts` | `LoginData` +`companyId` / `companyName` | +| `shared/auth/ensure-auth.ts` | localStorage 存 `companyName`;走 `check_login` 恢复登录态时一并写回(该文件现在只恢复 `uid`/`username`,见 `:25-39`) | +| `pages/login/DesktopLoginPage.vue` | 登录成功后写入公司名 | +| 顶栏 / shell 组件 | 显示当前公司名 | + +### 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 公司边界不变式 + +用例:移人后 `created_by_id` 跨公司必须被拒;超管豁免。 +变异自证:删掉校验分支,用例必须红。 + +### 6.3 DEFAULT 摘除告警(防「半套发布」) + +`users.company_id DEFAULT 1` 是**临时**的,只为混合版本窗口存在。第二家公司开通后若不摘除,此后每个不显式传公司的建号都会被静默塞进厦门米椿花。 +启动期巡检:`SELECT COUNT(*) FROM company` > 1 **且** `users.company_id` 仍有 DEFAULT → 打 ERROR(纳入 `_prod_watch.py` 巡检 ALERTS)。用代码执行,不写进注释。 + +### 6.4 迁移自检 + +`MODIFY ... NOT NULL` 本身即闸门(§3);另跑 `MigrationInventoryTest` 确认版本连续、命名合规、历史校验和未变。 + +### 6.5 全量回归 + +`mvn test`(不许 skipTests)+ `scripts/tests`(当前 137 绿)+ `admin-frontend-vue` 的单测与 e2e(`tests/`、`e2e/`)+ 两个前端各自的 `npm run build`(`frontend-vue` 的 build 含 vue-tsc 类型检查)。 +既有红按差分读,不当回归:客户端批量测试有 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.adminPage` 超管分支 +- 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 记录后重启。**不要**手工改 V143 文件内容(校验和会变)。 + +### 8.2 混合版本窗口(这是 DEFAULT 存在的唯一理由) + +发布期间一台已上新 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 + +两台同版后,新代码永远显式写 `company_id`,DEFAULT 变成死重——但必须在第二家公司开通前摘除(§6.3 用代码盯住这件事)。 + +### 8.3 回滚 + +补丁脚本 `backend-java/docs/ops/rollback-V143-company.sql`,**不是一条 V144 迁移**——版本化迁移放进 `src/main/resources/db/` 就会被 Flyway 在下次启动时自动执行,那等于把 V143 静默撤销掉,还会让 `MigrationInventoryTest` 的版本连续性断言跟着变。执行顺序见 §3 头注释第 5 项。 +回滚窗口内已建的账号会连 `company_id` 一起丢,业务数据不受影响(业务表从未加列)。 + +--- + +## 9. 待确认 + +1. `company` 是否需要 `company_code`(英文短码)?二期登录定位用公司名还是短码?一期我按只用 `company_name` 做。 +2. 顶栏显示公司名——§5 目前按**两端都显示**写(后台 `AdminLayout.vue`、用户端 shell)。若只要用户端,删掉 §5.1 最后两行即可。 +3. 账号列表一期是「只显示公司列」还是「同时支持按公司筛选」?(§2.3 按后者写) +4. 公司内 admin 是否应看到本公司其他 admin 名下的账号?现状只能看名下 1 层(`AdminUserService.java:78-86`)。这属二期隔离口径,但会影响一期公司目录页的可见范围。