Files
crawler-plugin/docs/ops/company-tab-design-2026-10-04.md
T
huangzd1997 764ac21d30 test(公司tab): Task 13 变异自证收尾——前端 11/11、后端 15/15 全杀,并记下这份台账没证明的东西
BG3-a 首轮存活(不是注入没跑到):adminPassingForeignCompanyGetsEmptyNot403 从没桩
memberUserIds(2L),而 Mockito 对未桩、返回 List 的方法默认交空表 ⇒「删掉 foreign 分支、
按本公司重算」这条注入交出的也是空集,isEmpty() 会因为错误的理由通过。本公司两列都桩成
非空后复跑:R0 先绿(tests=63 rc=0,DataReadScopeTest=7/0/0)⇒ BG3-a KILLED ⇒ BG3-b 仍 KILLED。

新增 G1 守卫「发送口的第二实参」(1b ④):task-center 五处 http.get 必须把 query 交给带
params 的第二实参——G1 原来按文件文本查 company_id = companyId,看不见"参数收下却没发出去、
接口照样 200"这一形。

backend-java/docs/mutation-company-tab.md:26 支注入(前端 11 + 后端 15)、被作废的那一整轮
(15 支全 tests=None=解析没抓到本轮 XML,而控制轮照样报 GREEN)、1b⑤ 的 @Test↔surefire 逐类
对平(2+7+7+3+9+3+13+19=63=分母),以及这份台账明确没证明的东西(另一路的第二道门 readCompanyId
的变异、八条人工实跑、live E2E)。

设计文档补一段线上现状:8e80dfc2..HEAD 唯一未上线的功能提交是 965e9690(看板五端点按公司筛,
2 支 src/main),区间新增迁移 0 支 ⇒ 下一版 jar 不动 Flyway 版本。

门禁:后端全量 3760 例 / 0 失败 / 0 错误 / 7 skipped、BUILD SUCCESS(450 个本轮 surefire XML
独立复算同数);admin-frontend-vue 1739/1739/0、vue-tsc rc=0。

本笔刻意**不含** DataReadScopeTest 里那 3 支 readCompanyId 用例——它们要的实现在另一路的未提交
改动里,一起提交会让别人 checkout 到这支提交时编译不过。
2026-10-06 00:15:58 +08:00

246 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 公司 tab(超管按公司看数据)+ 公司配置读写只超管 —— 设计
日期:2026-10-04
状态:**批次 0-1 已实施**(计划 `docs/plans/19-company-tab.md` Task 1-12 出厂,Task 13 变异自证见 `backend-java/docs/mutation-company-tab.md`;人工实跑清单与上线命令另计)。**批次 2/3 由另一路会话在实施**(去重库/品牌库/查询ASIN/最低价ASIN/商品类目 + `V147`),本文件不替它写任务。
关于 V145(§12 第 1 条当时留的那个决定):**它不是本批带的**——V145 早在 10-05 18:3x 那版 jar(出包树 `a9c74b9a`)之前就随历史进入生产,生产 Flyway 现 146;也就是"两张规则库表补 `company_id` + 唯一键改每公司一套"已落地,而它的消费侧正是上面那路批次 2/3。跨公司串扰的窗口因此由那一路收口,不由本批。
线上现状(`git diff a9c74b9a..HEAD` 逐文件核过,10-06 00:0x):**批次 0-1 的大部分已经在这版线上 jar/构建里**——`DataReadScope`、日志管理与店铺管理两页的接线、以及前端 `src/layout/CompanyTabs.vue`(`AdminLayout.vue` 已挂载它,两处引用)都在出包树 `a9c74b9a` 中。**还没上线的只有一支功能提交** `3654d022`(任务看板五个端点按公司筛:`AdminTaskCenterController` + `TaskCenterScopeService`);其余 `a9c74b9a..HEAD` 的后端 `src/main` 改动(共 8 支,另 6 支为角色叫法/文案与按需注册修复)来自另一路会话。这一段区间**新增迁移 0 支**(`git diff --name-only a9c74b9a..HEAD -- backend-java/src/main/resources/db` 为空)⇒ 下一版 jar 不会动 Flyway 版本;`V147__product_category_company_scope.sql` 属批次 2/3,此刻仍未跟踪,一旦提交进区间,上线口径要重算。
需求来源:用户三句话,逐字记录
1. 「公司管理和创建用户选公司只能超管才能看到」
2. 「除了超管都不能操作公司配置 读写都不行」
3. 「前端改一下 超管通过tab看不同公司的数据,其他菜单也是这样(去重数据库之外的菜单)」(附「去重数据汇总」页截图,面包屑那一行画了四个空红框 = tab 位置)
已定的两个口径(用户选的,不是我推荐的):
- 范围:**一次铺完 16 页**,分 3 批发布(我推荐的 5 页首批被否)。
- 默认:**默认选中第一家,不允许「全部」**(我推荐的"默认全部"被否)。
配套文档:一期 `company-multi-tenant-design-2026-10-04.md`;二期(品牌库/去重库)`brand-dedupe-company-isolation-design-2026-10-04.md`。本方案**不依赖**二期落地,但批次 3 的两页要用二期的物化列。
---
## 1. 先更正一条我上一轮说错的事实
我说过"生产 `company` 表只有 1 行 ⇒ tab 上线只有一个标签"。**这句是错的**,来源是我的 13:5x 记忆快照,而 V145 头部记的是 15:0x 实查:
> `company` 表今天有两行(1=厦门米椿花、2 于 10-04 14:55 开通),第 2 家只有 1 个管理员账号(`users.id=1193`)、0 个任务、0 行去重数据。
两个后果,都比"tab 好不好看"更要紧:
- tab 今天就有真实内容,不是空壳演示。
- **二期的 `company_id DEFAULT 1` 摘除倒计时已经触发**(V145 头部自己写的:「第二家公司已于 10-04 14:55 开通 ⇒ 本次发布之后 DEFAULT 的每一分钟都是风险」)。而且 14:55 到批次 1 上线之间,第 2 家公司的**品牌库自动导入行无法追回**(`biz_invalid_asin_data` 今天连账号列都没有)。这条不在本方案范围内,但它决定了本方案什么时候能开工——见 §12 待确认第 1 条。
## 2. 需求拆成两件事,它们必须分开做
| | 是什么 | 判据 | 落点 |
|---|---|---|---|
| **A. 公司配置的读写只超管** | 页面/接口**可见性闸门** | 角色内在(`role == super_admin`),**不查菜单授权** | `CompanyService` + `PermissionMenuService` 三处出口 + 前端注册表 `superAdminOnly` |
| **B. 超管按公司看数据** | 读路径的**数据过滤** | 超管 = tab 选中的公司;非超管 = 恒锁自己公司 | 各页接口 + tab store + 统一的范围解析入口 |
为什么 A 必须是"角色内在"而不是"菜单授权"——这正是 **10-04 12:3x 生产事故的形状**:`listVisible` 挂上 `admin_companies` 菜单闸门,而该菜单授权笔数为 0 ⇒ 15 个管理员账号一开「用户管理」就 403,被踢回登录页,报成"登录闪退"(见 `CompanyService.java:80` 那段注释记录的教训)。所以:
- 用 `role` 判,不用菜单授权判。菜单授权可以被人改坏,角色不能。
- A 做完后,`admin_companies` 这个菜单行**仍然留在 `columns` 表里**(否则历史授权数据无处安放),只是从"可授予集合"里摘出来,让超管也没法把它授给别人。
## 3. 16 页归属普查(逐页取证,不是估的)
分母来源:`admin-frontend-vue/src/router/routes.ts:17-38` 共 22 页。扣掉 6 页非数据页——`account/users`(已有公司筛选,见 §3.1)、`account/companies`(A 类闸门,不做 tab)、`account/menus`(平台字典)、`records/software-version` / `records/tutorial` / `records/digital-human-version`(平台发布物,全公司共享)——**剩 16 页,与用户说的"16 页"对得上**。
| 类 | 判据 | 页 | 归属列证据 |
|---|---|---|---|
| **A(9)** | 表上有账号列,一条 `user_id IN (成员)` 就够 | 数据权限分组、密钥管理、密钥用量统计、店铺管理、生成记录、日志管理、视频任务记录、客户端任务管理、数据去重总数据 | `biz_shop_manage_group.user_id/created_by_id`、`biz_user_api_secret.user_id`、`biz_user_secret_usage_daily.user_id`、`biz_shop_manage.created_by_id`、`image_history.user_id`、`device_log_file.uid`、`biz_image_video_async_task.user_id`(`ImageVideoAdminTaskMapper.java:37` 已有 `<if test="userId != null"> AND t.user_id = #{userId}</if>`)、`biz_task.user_id`(`TaskCenterQueryMapper.java:93-95` 已有 `USER_SCOPE_T/USER_SCOPE_B` 的 `IN` 片段)、`biz_dedupe_total_data.uploader_user_id` |
| **B(3)** | 只有 `group_id`,没有账号列 | 不符合ASIN数据(品牌库)、查询ASIN、最低价ASIN | `InvalidAsinDataEntity.java:20`、`QueryAsinEntity.java:20`、`SkipPriceAsinEntity.java:21` 都只有 `groupId`(品牌库二期 V145 后会多出 `company_id`) |
| **C(2)** | **零归属列**,本质是全平台共享 | 商品类目、店铺密钥管理 | `ProductCategoryEntity.java:15-23`(`parentId/name/categoryKey/sortOrder/isBuiltin`,无归属);`ShopKeyEntity.java:17-32`(紫鸟 token 池 `ziniaoToken/proxyUrl/ipWhitelist*`,无归属) |
| **D(2)** | 快照无归属列,可见性靠"店铺名集合"裁剪 | 店铺撞款监控、店铺数据记录 | `ShopDataDuplicateCheckQueryService.java:78-89 resolveVisibleShopKeys` + `cropShops/cropItems`;底层 `shop_data_duplicate_scan` 只有 `status/summary_json/payload_json`(`ShopDataDuplicateScanEntity.java:16-22`),**全局一份快照**;裁剪链靠 `ShopDuplicateCheckSourceMapper.java:87-97 selectManagedShopNames(operatorId)`(`biz_shop_manage.group_id IN (自己带的分组)`) |
### 3.1 参照实现已经有了:`用户管理`
`AdminUserController.java:43` 的 `@RequestParam(name="company_id", required=false)` 是**全仓唯一**一个收公司筛选的后台接口(已全仓 grep 确认)。它的语义就是本方案要复制的模板,两条都对:
- 超管不传 = 不筛(`AdminUserService.java:89-90` 只在超管分支加 `eq(company_id)`);
- 非超管传别家 = **返回空集,故意不报错也不越权**(`AdminUserService.java:75-81`)。
### 3.2 A 类不必新造范围机制
`modules/permission/support/UserDataScopeSupport.java` 已经提供 `resolveVisibleUserIds(operatorId)`(operator → 自己带的分组 → 成员 user ids,历史无分组主管回退按 `created_by_id` 兜底,上限 2000),并且已被密钥管理、任务看板(`TaskCenterScopeService.java:36`)、去重库(`DedupeTotalDataService.java:1188`)使用。
本方案只加**一条**新方法,然后与它组合,不另起平行实现:
```
CompanyScopeSupport.memberUserIds(companyId) // SELECT id FROM users WHERE company_id = ?
```
组合规则(**这是本方案唯一的范围公式,写在一处**):
- 超管:`scope = memberUserIds(tabCompanyId)`(替换掉分组派生的" unrestricted",不是交集)。
- 非超管:`scope = resolveVisibleUserIds(operatorId) ∩ memberUserIds(operatorCompanyId)`。
今天这个交集是恒等的(第 2 家公司只有 1 个账号、0 条业务数据),但**它必须存在**:`resolveCompanyMove` 允许把账号在两家公司之间移(`AdminUserService.java:221-230`),移动后交集就起作用了。这条之所以安全,是因为移人已经有不变式兜着——「账号的 `created_by_id` 必须与它同一家公司,除非创建人是超管」(`AdminUserService.java:236-243` 注释明写这条是"二期不回改 77 处 `eq(getUserId, userId)` 过滤点的前提")。
`memberUserIds` 不加 `LIMIT`:今天全库 140 行 `users`。但要在代码里放一个**计数哨兵**:成员数 > 500 时把 `IN (...)` 改成子查询 `user_id IN (SELECT id FROM users WHERE company_id = #{companyId})`。**不预先做**(YAGNI),哨兵要有,理由见 §10 护栏 G6。
## 4. tab 是什么、不是什么(这条最重要)
**tab 不是安全边界。** 它是超管的一个读筛选。真正的边界是:
- 非超管**永远**被会话裁剪到自己公司,前端传什么都不算(后端一律按 `operator.company_id` 覆盖);
- 超管不传 `company_id` 时**保持今天的不筛行为**。
选这个弱度换来两件实在的好处:
1. **发布顺序安全**:jar 先上(参数可选、向后兼容,旧前端不传照常),前端后上(tab 出现且真的开始筛)。反过来会有"tab 存在但不筛"的**撒谎窗口**——超管点了"第 2 家"却看到第 1 家的数据,这比报错更坏。
2. 混合版本窗口里(一期实测约 15 分钟)旧 jar 遇到未知参数直接忽略,不会 500。
代价必须承认:**超管失去"一眼看全部公司"的能力**,这是"不允许「全部」"这个选择的直接后果。今天 2 家,来回切代价小;三家以上,"哪家在掉量"这类横向判断只能靠切 tab。二期 §12 已明确"不做跨公司汇总/对比报表",所以本方案**不**补汇总页,只在这里记账。
另两个必须钉死的口径(不写清就会各自理解):
- **"第一家"的定义 = `company.id` 最小的启用中公司**,不是超管自己所属公司,也不是后端返回顺序的第一条。刷新后回到第一家(见下面 store 口径)。
- **tab 状态不进 URL,只进 Pinia store**。理由:16 个页面的取数函数都去读 `route.query` 是真实成本,批次 1 铺不完;代价是**复制链接/截图不带公司上下文**,超管从 tab=2 发给同事的链接,对方打开是第一家。这个代价是否可接受,见 §12 待确认第 4 条。
- tab 条渲染在 `AdminLayout.vue` 的顶栏/面包屑那一行(截图红框位置,`AdminLayout.vue:97-121`),**不在各页里各画一遍**。所以护栏不能测"页面渲染了 tab",只能测"页面的请求带了 companyId"(§10 G1)。
## 5. C 类两页:显式声明"不按公司分",而不是静默不筛
商品类目(平台字典,带 `isBuiltin`)和店铺密钥(紫鸟 token 池)**今天就没有任何归属列**。给它们加 tab 只有两种坏结果:要么假装有隔离(切 tab 数据纹丝不动,用户会以为隔离坏了),要么为它们临时造归属(回到二期 §12"不给其余 55 张表加 `company_id`"的破例讨论)。
做法:注册表里 `companyScoped: false`(**显式写,不留空**——留空与 `false` 运行时等价,但只有写出来才是"读过普查、决定不参与"的证据,实施计划 Task 1 Step 1 那支用例钉的就是这个)+ 一句"本页全平台共享,不按公司区分"。让用户看到的是"这页不参与",而不是"这页坏了"。这条也回答了二期 §9.4 对品牌库"未分组是预期的"的同类处理。
承载方式与原方案**有一处偏离**(10-04 定案时写的是"页头常驻一条说明"):那句话改放进 `operation-guides.ts` 这两页的既有引导文案里,随批次 1 一起上。两个理由:①"页头常驻一条说明"本身就是 §12 第 5 条不许的新提示条;②引导条那一支已经有分母取注册表的用例(谁被声明成 `false` 就自动被要求带这句),新控件没有这个搭车。⚠️ 这件事**不排在批次 3**:tab 条挂在 `AdminLayout` 上是全局件,批次 1 一上线"切了纹丝不动"这坏观感就同时上线。
## 6. 铁律:闸门读写同页;归属不从界面注入(2026-10-04 收窄过一次,最终版)
这一节原来写的是"一个页要进 tab 范围,它的读筛选和**写归属**必须同一批落地"。后半句已作废——它会把公司这个维度重新端回界面(弹窗里长出一个"所属公司"),而**新维度默认只做后端,界面暴露要单独批准**。拆成三条:
### 6.1 闸门必须读写同页(这条仍是铁律)
一页进了 tab 范围,它的**角色/归属闸门**要读写一起动。只收窄列表、不收窄按 id 的读出口 = "列表看不见但按 id 能读能下载",那是真越权。已定位必须补行级闸门的出口:
| 出口 | 要求 |
|---|---|
| 列表读 | 带 `company_id`,经 §7 的唯一入口 |
| **导出** | 同一个 `company_id`。**否则 tab 筛了表格、导出全量 = 越权泄露**。已定位:`/api/admin/dedupe-total-data/export`(`dedupe-total-export.ts:5,39` 的 `toExportUrl(state)`)、`/api/admin/product-categories/export`、`/api/admin/shop-data-crawl/duplicate-check-export`(`AdminShopDataDuplicateCheckController.java:179`) |
| **按 id 的详情 / 下载** | 凡该端点存在**非超管或内部令牌通道**的,必须先取行再判归属。已定位:`ImageVideoAdminTaskController.java:93`(`detail`)与 `:100`(`download-zip`)——它们走 `requireAdminOrInternal`,漏掉它 = 列表筛了但内容能越权读 |
| 按 id 的单行 改 / 删 | 同上,用 `CompanyScopeSupport.assertSameCompany(...)`(`CompanyScopeSupport.java:44`,目前 **0 个生产调用方**,本方案是第一个使用者) |
反过来,**这页只有超管能进(无任何非超管/内部通道)时,按 id 的端点刻意不加公司闸门**:日志管理那页 9 个端点全是 `requireSuperAdmin`(`AdminDeviceLogController.java:152-159`),加了只会误伤 `uid IS NULL` 的麦象日志——那是排障现场不是越权面。这条边界要有测试钉着,不许下一个人"顺手补齐"(实施计划 Task 12 Step 4)。
### 6.2 归属由后端从操作者推导,写请求体一律不带 `company_id`
与二期的建号口径同源:`AdminUserService.resolveTargetCompanyId`(`:201-212`)在超管未传 `company_id` 时返回 `operator.getCompanyId()`,前端 `85e1e92a` 起**故意不发这个字段**,并被 `tests/company-user-create.test.ts` 反向钉住。店铺/分组(Task 11)沿用同一条,不搞两套。
另一个更硬的理由:`ShopManageEntity`/`ShopManageGroupEntity` 根本没有 `company_id` 列。⚠️ 而**店铺的归属人今天来自请求体的 `createdById`**(`ShopManageService.java:86` 读 `request.getCreatedById()`),不是操作者 ⇒ "落到第 2 家"早就做得到(把负责人选成第 2 家的账号)。再加一个 `company_id` 参数不是"补能力",是**造两个互相矛盾的归属控件**(选了第 2 家 + 负责人是公司 1 的人,听谁的?)。反过来,若为它加"负责人必须是那家成员"的校验,超管自己不在别家成员集里 ⇒ **超管把负责人留成自己就 403**,比今天更糟。
### 6.3 明写不吞的副作用
> **建号**:超管切到「第 2 家」tab 后建的号,仍归**超管自己所属的公司 1**(`resolveTargetCompanyId` 落操作者),要归属第 2 家必须用那家自己的 admin 登录去建(`users.id=1193` 就是这么来的)。memory 里那句"超管建的号一律归公司 1"就是这条。
> **店铺/分组**(17:5x 实查后订正——上一版把这句一并写成了"仍归公司 1",**不对**):归属由请求体的**负责人 `created_by_id`** 决定,**与顶部 tab 无关**。把负责人选成第 2 家的账号,店铺就归第 2 家;这一条本轮一行代码都没动。
今天影响为零(第 2 家 0 行业务数据,实查见实施计划 Task 5 Step 0),但它是运维手册里必须存在的一行字。落点:`operation-guides.ts` 店铺管理那条引导加一句文案(**只加文案,不加控件**),由实施计划 **Task 7 Step 7** 与其余 7 页那句一起落,别在接线任务里再落一遍。
## 7. 后端:一个统一入口,不许各页自己 if
新增 `DataReadScope.readScope(...)`,**唯一**负责"操作者 + 请求里的 company_id → 该查哪批 user ids / 哪家公司":
```
DataReadScope readScope(AdminUserEntity operator, Long requestedCompanyId)
超管 + null → 不筛(今天的行为)
超管 + id → memberUserIds(id)
超管 + 不存在的 id → 空集(不 403;tab 值可能来自过期 store)
非超管 + null → resolveVisibleUserIds(operator) ∩ memberUserIds(operator.companyId)
非超管 + 自己 id → 同上
非超管 + 别家 id → 空集(照 AdminUserService:75-81「故意不报错也不越权」)
```
两条硬约束:
- **每个收 `company_id` 参数的 controller 方法必须调这个入口**,不许出现第二个 if。护栏 G2 扫的就是这条。
- `CompanyScopeSupport` 现有的 `requireCompanyId` 取不到就抛、绝不返回 null(`CompanyScopeSupport.java:25-42` 的注释给了理由:null 进实体 → MyBatis-Plus 跳过该列 → 被 V145 的 `DEFAULT 1` 静默兜住 = "归属失真且不报错")。**新入口沿用同一条纪律**:范围解析失败返回"空集"或抛,永不返回 null 让调用方自己猜。
## 8. 前端:两个闸门 + 一个 store
### 8.1 A 类(公司配置只超管)
- `routes.ts` 的 `AdminPageDef` 加 `superAdminOnly?: boolean`,`account/companies` 置 true。
- `router/helpers.ts:26-33` 的 `isRouteAllowed` 现在是 `if (isSuperAdmin) return true` —— **超管恒 true,所以只剪菜单树对超管无效,只加角色闸门对非超管的侧边栏又不够**。两处都要做,缺一处就留旁路:
1. `isRouteAllowed` 先判 `superAdminOnly && !isSuperAdmin → false`(与菜单树无关的硬闸门);
2. `stores/admin-session.ts:30` 的 `canonicalizeMenuTree(...)` 之后**剪掉** `superAdminOnly` 节点(覆盖 sidebar、面包屑、`firstVisiblePath`、路由守卫四个消费者——它们都从这一棵树来,这是唯一单点)。
- `CreateUserDialog.vue:123`:`v-if="companyOptions.length"` → `v-if="operatorSuper && companyOptions.length"`。今天非超管也会看到一个只有单项的"所属公司"(`selectableCompanies` 给非超管返回自己那一行),按需求 1 要整个隐藏。隐藏后**不需要**补默认值——后端 `resolveTargetCompanyId` 对非超管恒返回 `operator.getCompanyId()`。
- `UsersPage.vue:146` 的 `void loadCompanies()`:改成超管才调。**这条必须在 jar 上 403 之前发**,见 §11。
### 8.2 B 类(tab)
- 新 store `company-tab`:`companies`(超管才拉)、`activeId`(默认 `id` 最小的启用公司)、`memberUserIds` 不缓存(每次请求交后端解析,避免"改了成员没刷新"的不一致)。
- 请求侧:`company_id` 由各页的 api 模块**显式**从 store 取并塞进参数,**不做 http 层中央注入**。中央注入看着省事,实际会让"C 类页也带上参数",后端要么忽略(撒谎)要么honour(把平台字典误筛成公司私有)。护栏 G1 用双向对账来防漏:注册表声明了 `companyScoped: true` 的页,它的 api 模块必须出现 `company_id`;出现了 `company_id` 的页必须被注册表声明。
## 9. 三个会静默丢数据的坑(都不报错,都会让人以为改造坏了)
### 9.1 `group_id IS NULL` 的历史行会从**所有** tab 消失
品牌库 14,224 行 AUTO 的 `group_id` 是 NULL(V145 头部实查 + 二期 §7.3 明确"这是刻意的切法")。B 类页若走 `group_id → 分组 → 公司` 推导,这些行在**每一个** tab 下都不出现 = 对超管等于数据被删。符合 memory 里那条「读过滤与写按范围替换必须同时改,否则隐藏=静默删除」。
处置三选一,**不许默认选 (c)**:
(a) 该页不声明 `companyScoped`;(b) 把 NULL 行回填成公司 1(它们事实上就属于公司 1);(c) 接受消失并写文案。
**已锁 (a)**(§12 第 2 条):批次 2 开工前先跑 §11.2 的 SQL 数出 NULL 行数,(b) 需要用户单独授权才做。
### 9.2 日志管理的 `uid` 对麦象采集机恒空
`DeviceLogFileEntity.java:27` 注释逐字:「桌面客户端当前登录用户 id(users.id),**maixiang 上报为空**」。⇒ 按 `uid IN (成员)` 筛之后,**所有麦象采集机日志在任何 tab 下都看不见**。而麦象机器正在跑跟价(见 `maixiang-linux-migration`)。
处置(**已锁**,§12 第 2 条):日志管理按 `source` 分支——`client` 按 uid 筛、`maixiang` 恒可见。若 §11.2 第 2 条取证显示麦象行占多数,则整页改判不声明 `companyScoped`。**默认不筛**比默认丢日志安全。
### 9.3 tab 会改变"这页今天有几行"的观感
一期 10-04 刚把三张任务记录列表页的日期初值改成留空(`00e5df02` / `48018068`)。tab 再一上,超管第一次切过去的行数变化会被报成"数据丢了"。承载方式按 §12 第 5 条:**不新做页头控件/提示条**,改在 `operation-guides.ts` 的既有引导条目里加一句"超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了",店铺管理那条再补一句 §6.3 的归属口径。分母取 `COMPANY_SCOPED_PAGES` 那 8 页(不是只有那三张任务记录页),其中「数据权限分组」今天共用通用 fallback,要给它一条独立文案——这是**故意**偏离"沿用旧版 guides 表原文"的约定,因为那句 tab 说明不能塞进 fallback(会被没进 tab 的页共用)。`admin_users` 不在其列:它一期就已按公司筛。
⚠️ **这句必须以"超级管理员"开头**:引导文案按 `menuKey` 取、**不分支角色**,而非超管看不到 tab 条(G1 那侧的 `isSuperAdmin` 判断)。写成"当前公司由上方 tab 决定"会让非超管读到一句指不到任何控件的话——比不写更容易被报成 bug。同理,文案不许给非超管承诺他们没拿到的收窄(附B 记了分组那半边本轮刻意没动)。缓解是**部分强度**:引导条默认展开,但折叠态按浏览器持久化,早就收起提示的人看不见这句。
## 10. 护栏(做进代码出口,不写进注释)+ 变异自证
| 号 | 断言 | 注入点(变异) |
|---|---|---|
| G1 | 注册表 `companyScoped:true` 的页 ↔ 其 api 模块出现 `company_id`,**双向**对账 | 把某页从注册表摘掉声明 / 从 api 模块删参数 |
| G2 | 每个带 `@RequestParam(name="company_id")` 的 controller 方法必须调 `readScope(` | 把某一处的 `readScope` 换成裸 `eq` |
| G3 | 非超管传别家 id ⇒ 空集;传自家 ⇒ 有数据;**两种都不许看到对方数据**(断言具体行为,不接受"没报错"当通过) | 删掉 `AdminUserService:75-81` 形状的那道判断 |
| G4 | `admin_companies` 在 `/current-user/menus`、`permission-menus?grantableOnly=true`、`updateUserColumnPermissions` 提交三处都不出现/写不进;`grantableOnly=false` 时**仍**能列出(菜单行要可管理) | 任一出口漏剪 |
| G5 | `CompanyService` 全文不出现 `hasAnyAdminMenu(`(防止有人把读路径重新挂回菜单授权,重演 12:3x),且 `ensureSuperAdmin(operator);` 恰好 3 处(create / update / **listVisible**) | 让 `listVisible` 退回非超管可 |
| G6 | `memberUserIds` 的成员数哨兵:> 500 时用例红,提示改子查询 | 无(它本身就是倒计时) |
| **G7** | **反向钉"已摘掉的维度不得回流"**(五支):`tests/company-user-create.test.ts`(建号不带 `companyId`)、`company-user-list.test.ts:66`(账号页不调 `fetchCompanies`)、Task 11 Step 1 第四支(店铺写入口不收 `company_id`)、Task 12 Step 4 那条(按 `fileId` 的端点不接 `company_id`)、Task 7 Step 7 第 4 支("当前公司"只由文案与 `is-active` 承载:`CompanyTabs.vue` 里不许长出提示条,且 `COMPANY_SCOPED_PAGES` 那 8 页的引导文案必须都带那句) | 给任一写入口加一个 `company_id` 参数 ⇒ 对应那条红;给 tab 组件加回提示条 ⇒ 那支的反向半红;从任一页文案里删掉那句 ⇒ 分母半红。**每支必须自带"该做的确实做了"的取样自检**,否则符号根本不存在时它恒绿 = 没钉 |
现有用例要**翻转**的三条(不是新增,是改正确的行为):`CompanyServiceDirectoryTest.java:121` 「公司内管理员的目录只查自己公司」、`:161` 「公司内管理员读到本公司那一行:读端点不查 admin_companies 菜单」、`:172` 的"读得到目录也不能建第二家公司"文案——按需求 2 全部改成 403。这三条改完,`CompanyReadPathMenuGateTest` 的 `ensureSuperAdmin` 计数从 2 变 3(G5)。
变异自证遵守既有八条硬规矩:每轮开跑前所有被注入文件写回 pristine;还原只认注入前读进内存的字节,**不许 `git checkout`**(会连未提交的 V145 实现一起抹掉);CRLF 锚串先对齐行尾;分母只认本轮扫描结果。
## 11. 分批与发布顺序
### 11.1 四批
| 批 | 内容 | 页 | 发布顺序 |
|---|---|---|---|
| **0** | 公司配置只超管(§2 A + §8.1),无 DDL | 公司管理 1 页(建号选公司与账号页公司列**已由 `85e1e92a` 对所有人摘掉**,本批只核对 + 反向钉,见实施计划 Task 2) | **FE 先,jar 后**(现网那版 admin-vue 早于 `85e1e92a`,仍在调 `GET /api/admin/companies`;反过来 15 个 admin 一开「用户管理」就撞 403) |
| **1** | tab 机制 + A 类:客户端任务管理、视频任务记录、密钥用量统计、生成记录、日志管理、数据权限分组、密钥管理、店铺管理(8 页;**只筛读**,写侧归属按 §6.2 不动)。**日志管理只在 §9.2 的「`(source='maixiang' OR uid IN 成员集)` 一整组」这条路线下留在本批**;若 §11.2 第 2 条取证显示麦象行占多数,则改判不声明 `companyScoped`,本批变 7 页。**本批还捎带两件纯前端件**:§9.3 那 8 页的引导文案、§5 两页 C 类的 `companyScoped: false` 与"不参与"文案(都只是注册表标记 + 文案,无 DDL、无后端) | 8 | **jar 先,FE 后** |
| **2** | B 类 group 推导:查询ASIN、最低价ASIN;D 类裁剪链:撞款监控、店铺数据记录(4 页)。**开工前必须先解 §9.1/§9.2** | 4 | jar 先,FE 后 |
| **3** | 依赖二期 V145 物化列:数据去重总数据、不符合ASIN数据(**直接用 `company_id` 列,不许再走 §3.2 的推导路径,否则同页两个真相源**)。~~C 类两页的"显式声明不筛 + 文案"~~ 已提到**批次 1**(见 §5:tab 条一上线,"切了纹丝不动"就同时上线,等不到 V145) | 2 | 与二期批次 1 同批,见 §12 |
撞款监控/店铺数据记录(D 类)要新增"多成员版" `selectManagedShopNames`(现在只吃单个 `operatorId`,`ShopDuplicateCheckSourceMapper.java:87-97`),这是动裁剪链而不是加 SQL 条件,成本比 A 类高一档,所以不放批次 1。
### 11.2 上线前必须实跑的取证(只交付命令,由用户执行)
```sql
-- 1) 三个 group-only 表的 NULL 归属行数(决定 §9.1 走 a/b/c)
SELECT COUNT(*) total, SUM(group_id IS NULL) null_group FROM biz_query_asin;
SELECT COUNT(*) total, SUM(group_id IS NULL) null_group FROM biz_skip_price_asin;
-- 2) 日志管理里麦象行占比(决定 §9.2)
SELECT source, COUNT(*) FROM device_log_file GROUP BY source;
-- 3) 复核"admin_companies 授权 0 笔"这个前提(§2 的论证依赖它;一期 memory 记的是 0,需重取)
SELECT COUNT(*) FROM user_column_permission
WHERE column_id IN (SELECT id FROM columns WHERE column_key='admin_companies');
-- 4) 每家公司成员数(§3.2 的 500 哨兵分母)
SELECT company_id, COUNT(*) FROM users GROUP BY company_id;
```
### 11.3 复验口径(沿用既有两条已付学费的规矩)
逐节点复验**不能打 `0.0.0.0:18080`**(nginx 轮询池),主机 B 的 java 在 `127.0.0.1:19080`;两台 jar 必须同版,混合版本窗口里新参数会被旧 jar 随机忽略。admin-vue **只在主机 B 的 `/var/www`**,验"线上==本地构建"用整树聚合摘要。
## 12. 口径锁定(2026-10-04,用户「继续」= 按本文推荐执行;每条都可单独推翻,推翻只影响所列批次)
1. **不等二期 V145**:批次 0-2 先走,V145 那条线独立收尾(它的 `DEFAULT 1` 摘除有截止时间,不该被 tab 排期拖住)。⇒ 影响:批次 3 的排期挂到 V145 之后,批次 1 不因此改形。
附(17:0x 更正):V145 **已提交**(`b7873209`),但**仍未上线**——线上 jar 还是 `e42b37c1…`,Flyway 停在 144。"提交"与"上线"的差别要在批次 1 出包时显式判断(本计划的 jar 一旦重建重启就会把 V145 一起带上去),见实施计划 Task 13 Step 2。
2. **NULL 归属行的处置**:默认 (a) **不声明 `companyScoped`**(宁可不筛,不静默删可见性);要走 (b) 回填(动 14k+ 行的迁移)需用户单独授权,不在本方案里自决。批次 2 开工的**前置闸门**是 §11.2 四条 SQL 的实查结果——拿不到结果就不进批次 2。
日志管理单独定:按 `source` 分支,`client` 按 `uid` 筛、`maixiang` 恒可见(§9.2 路线 a;实现形状见实施计划 Task 12 Step 3——它是 `(source='maixiang' OR uid IN 成员集)` 一整组,不是 `source` 值分支)。
3. **`用户管理` 不在"必选一家"之列**:`85e1e92a` 之后这页连公司筛选器都没有了,超管看到的本来就是全公司账号——跨公司查号是它的职责。全局"默认选中第一家、不允许全部"只作用于 §11.1 批次 1 那 8 页。
4. **tab 只进 Pinia store,不进 URL**:批次 1 的 8 页铺完优先于"链接带公司上下文"。已知代价(§4):发给同事的链接对方打开回到第一家。
5. **界面暴露只批两处**(2026-10-04 定:新维度默认只做后端):已批 = ①`AdminLayout` 顶部那条公司 tab、②公司配置入口收窄到超管。**未批 = 任何页加"所属公司"列、任何弹窗加公司/成员下拉、按公司收窄的负责人选择器**。页头的"当前公司"行数说明也按未批处理——批次 1 先用 `operation-guides.ts` 的既有引导文案承载,不新做控件(§9.3)。
6. **写侧归属不从界面注入**:见 §6.2/§6.3。tab 是**纯读视图**,写侧的归属规则本轮一行都不动(建号恒落操作者自己那家;店铺看请求体里的负责人,与 tab 无关——两条的差别见 §6.3);这些副作用明写不吞,并用反向钉测试钉住"写入口不许收 `company_id`"(实施计划 Task 11 Step 1 第四支、Task 12 Step 4 那条)。
## 13. 明确不做
- 不给其余 55 张业务表加 `company_id` 列(tab 全程用 `user_id → users.company_id` **派生**,零 DDL;只有二期那两张表的物化列是破例)。
- 不做跨公司汇总/对比报表(二期 §12 同口径)。
- 不改 `group_id` 语义,不拿它当租户键。
- 不动 89 处数据出口、不重写 `UserDataScopeSupport` 的分组口径。
- 不在本方案里做阶段B 设备令牌(它是二期的完成条件,不是本方案的)。
- 不给 C 类两页临时造归属列。