Files
crawler-plugin/docs/plans/19-company-tab.md
T

2735 lines
204 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(超管按公司看数据)+ 公司配置读写只超管 实施计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 让 `admin_companies` 与公司下拉变成"角色内在只超管",并给后台业务数据页加一条超管用的公司 tab,使超管按公司看数据、非超管被会话锁死在本公司。
**Architecture:** 后端只加两个出口——`CompanyScopeSupport.memberUserIds(companyId)`(按公司枚举成员账号)和 `DataReadScope.readScope(operator, requestedCompanyId)`(把"操作者 + 请求里的 company_id"折成一个可求交的读范围),各页服务把它们叠进**既有**的 `scopedUserIds` / `UserDataScopeSupport` 口径,不另起第二套过滤。前端在 `routes.ts` 注册表上打两个标记(`superAdminOnly` / `companyScoped`),路由守卫加一条与菜单树无关的角色硬闸门,`admin-session.ts` 单点剪枝覆盖侧边栏/面包屑/首屏跳转,公司 tab 渲染在 `AdminLayout.vue` 一处、状态进 Pinia store,由各页 api 模块**显式**带 `company_id`(不做 http 层中央注入)。
**Tech Stack:** Java 21 / Spring Boot 3.3.9 / MyBatis-Plus 3.5.7(`LambdaQueryWrapper` + 注解 SQL)/ JUnit 5 + Mockito + AssertJ(源码扫描式护栏);Vue 3 + TS + Pinia + vue-router(`admin-frontend-vue`)+ `node --test tests/*.test.ts` + `vue-tsc --noEmit`。
**Spec:** `crawler-plugin/docs/ops/company-tab-design-2026-10-04.md`(已批准,§12 的四条口径已锁定)。本计划按 § 编号引用它,实施时两份一起读。
**基线(2026-10-04 17:0x 复查;这份计划写到一半时 HEAD 动过,以下已是动完之后的现状):**
- `crawler-plugin` 是**独立 git 仓库**,分支 `master`,HEAD = **`67b62cc3`**(`00e5df02` → `b7873209` V145 → `85e1e92a` 前端摘掉公司维度 → `67b62cc3` 18 号计划执行记录,三笔是本任务之外另一条线合进来的)。⚠️ 工作区根 `D:\todesk\副业\数富AI` 是另一个仓库(shufu-ops 运维仓库,`.gitignore:8` 的 `/*` 把 `crawler-plugin/` 整个忽略),在那里跑 `git status` 只会看到 2 个 untracked 探针、**看不到本计划依赖的任何文件**——所有 git 命令必须 `cd crawler-plugin`。
- 工作区现在只剩 4 项 untracked,其中两项是本计划自己的产出:`docs/ops/company-tab-design-2026-10-04.md`(设计文档,Task 1 之前先提交它)、`docs/plans/19-company-tab.md`(本计划)、`backend-java/tmp-probe.txt`(我 11:47 留下的探针,收尾要删)、`tmp/`(⚠️ `tmp/c8-build` 是**真 worktree**,不是垃圾,别删)。
- **`85e1e92a` 已经把后台的公司维度从界面上摘掉了**:`UsersPage.vue` 不再 import `fetchCompanies`、没有"全部公司"筛选、没有"所属公司"列;`CreateUserDialog.vue` 里没有 `companyId`;`user-create-model.ts` 里 `selectableCompanies`/`initialCompanyId` 已删;顶栏公司旁白删掉(`AdminLayout.vue` 因此少 3 行)。⇒ 本计划**不重做**这些,Task 2 改成"核对 + 反向钉";建号归属口径随之确定:前端请求体故意不带 `company_id`,后端 `resolveTargetCompanyId` 落操作者自己的公司 ⇒ **超管建的号一律归公司 1**(副作用见 Global Constraint 5 与 Task 11 Step 4)。
- `b7873209` 提交了 V145(两张规则库表补 `company_id` + 唯一键每公司一套),**但它只在 git 里,没上线**:线上 jar 仍是 `e42b37c1…`(13:44 那版),Flyway 仍停在 **144**。本计划批次 1 的 jar 与 V145 谁先上、会不会把 V145 一起带上去,是 Task 13 Step 2 的显式判断点,不许默认。
- 生产:两家启用中公司(`id=1` 厦门米椿花、`id=2` 于 10-04 14:55 开通,`users.id=1193`)、admin-vue 现网 `20261004-135428`(**早于 `85e1e92a`** ⇒ 现网那版仍在调 `GET /api/admin/companies`,这就是批次 0 顺序约束的来源,取证见 Task 2 Step 4)。
- 后端**零 DDL**:本计划不新增任何迁移文件,不碰 `src/main/resources/db/`。
---
## Global Constraints(每个任务都受这些约束,逐字照抄自 spec 与既有坑)
1. **发布顺序是硬约束,两条方向相反**:批次 0(Task 1-4)**前端先、jar 后**——`listVisible` 上 403 的那一版 jar 如果先发,15 个公司内管理员一开「用户管理」就撞 403,前端拦截器把 403 当未登录整页踢回登录页,症状又是"登录闪退"(2026-10-04 12:3x 生产事故的形状)。批次 1(Task 5-13)**jar 先、前端后**——jar 的 `company_id` 是可选参数、向后兼容,反过来会有"tab 存在但不筛"的撒谎窗口(spec §4、§11.1)。
2. **tab 不是安全边界**(spec §4):超管不传 `company_id` 时必须保持今天的不筛行为;非超管传任何值都必须被会话覆盖,传别家得到**空结果**,照 `AdminUserService.java:75-81` 的"故意不报错也不越权",不许 403、不许静默改写成自己公司。
3. **范围解析失败永不返回 null**(沿用 `CompanyScopeSupport.java:25-42` 的纪律):null 进实体 → MyBatis-Plus 跳过该列 → 被 V145 的 `DEFAULT 1` 静默兜住 = 归属失真且不报错。
4. **只加两个后端出口,不许出现第二个 if**:任何收 `company_id` 的 controller 方法必须调 `DataReadScope.readScope(...)`,**并且必须写成显式 `@RequestParam(name = "company_id")`**(本仓库多数 controller 靠方法参数名绑定,驼峰 `Long companyId` 收到的是 `companyId=`,前端发 `company_id=` ⇒ 参数静默为 null、tab 不筛且不报错)。护栏 G2(Task 6 Step 5)逐文件同时扫这两条。
5. **闸门读写同页,归属不从界面注入**(spec §6,2026-10-04 收窄过一次):一页进了 tab 范围,它的**角色闸门**必须读写一起动——只收窄读、不收窄行级写闸门 = 列表看不见但按 id 能改能下载(Task 8 的 `detail`/`download-zip` 就是这一类,必须补)。反过来,**任何写请求体都不许收 `company_id`**,界面上也不长出公司选择器(Task 11 Step 4 用它那条反向钉住)。⚠️ 但"归属由后端从操作者推导"这半句**只对建号成立**:店铺的归属人今天来自请求体的 `createdById`(`ShopManageService.java:86`),不是操作者 ⇒ 店铺归谁家由"负责人"决定、与 tab 无关(Task 11 Step 4 已按实查重写,spec §6.3 那句要同步限定)。已知副作用**明写不吞**:超管建号恒落自己公司 1;店铺要落别家就得把负责人选成别家的账号。
6. **`group_id IS NULL` / `uid IS NULL` 的行不许静默从所有 tab 消失**(spec §9.1、§9.2;memory「读过滤与写按范围替换必须同时改,否则隐藏=静默删除」):默认处置是**该页不声明 `companyScoped`**(§12 第 2 条),回填需用户单独授权。
7. **C 类两页不做 tab**:商品类目(`biz_product_category`,平台字典带 `isBuiltin`)与店铺密钥(`biz_shop_key`,紫鸟 token 池)**没有任何归属列**,本计划不给它们加列、不加参数,页头文案另开一笔(spec §5、§13)。
8. **两张 jar 必须同版**;逐节点复验**不能打 `0.0.0.0:18080`**(nginx 轮询池),主机 B 的 java 在 `127.0.0.1:19080`;混合版本窗口里新参数会被旧 jar 忽略。admin-vue **只在主机 B 的 `/var/www`**。
9. **不许 `skipTests` 上线**;`mvn test` 全量门禁**禁止与 Nuitka 打包并行**(`TxDurationBenchmarkTest` 抢 CPU 假红);主树禁 `git clean`;不许 `git stash`(红线归因用 detached worktree)。
10. **生产只做只读取证**,任何 `INSERT/UPDATE/DELETE/ALTER` 只交付命令、由用户执行(既定工作方式)。只读通道 = `scripts/_prod_watch.py:171 db_sections()`。
11. **护栏做进代码出口,不写进注释**(spec §10):G1-G6 六支实跑用例 + 每支配变异自证。变异八条硬规矩:每轮开跑前所有被注入文件写回 pristine、还原只认注入前读进内存的字节(**不许 `git checkout`**)、CRLF 锚串先对齐行尾、分母只认本轮扫描结果、扫描用例必须自带"取样集非空"自检(否则 0 命中恒绿)。
12. **前端是 `admin-frontend-vue`,不是 `frontend-vue`**(`CLAUDE.md` 只写了后者,别混)。
13. **不改既有测试的断言方向来迁就实现**。本计划只允许翻转 spec §10 点名的三条 `CompanyServiceDirectoryTest` 用例;其余既有用例(含 `tests/task-33.test.ts` 对 `isRouteAllowed` 三条签名的断言)必须保持绿。**执行期追加的两处点名例外(Task 1,控制方裁定,不许据此推广到别的用例)**:①`tests/task-29.test.ts:11` 那条正则的宿主真变了——brief Step 7 mandated「剪枝必须在唯一写点内」与旧字面量 `this.menuTree = canonicalizeMenuTree(...)` 互斥,新式 `pruneSuperAdminOnly(\s*canonicalizeMenuTree(` 保留旧式全部要求、外加两者必须相邻,因此**严格更强**(它把旧式放行的"双赋值留未剪中间态"判红);②`src/types/vue-router.d.ts` 补 `superAdminOnly?: boolean`(Files 清单外,但它把 `routes.ts` 生产者与守卫消费者之间那根字符串约定变成编译期契约)。
14. **界面暴露要单独批准,本计划只批了两处**(memory「新维度默认只做后端,界面暴露要单独批准」,2026-10-04):已批准 = ①`AdminLayout` 顶部那条公司 tab、②公司配置入口收窄到超管(Task 1)。**其余任何"加一列/加一个下拉/加一个筛选器"都算未批**——包括店铺列表加"所属公司"列、`GroupEditorDialog` 负责人下拉按公司收窄、C 类页页头文案之外的任何控件。执行到这类步骤时**默认不做**,把它记进附B「已知不做」,需要就回来要一次授权。归属信息的唯一正确来源是**后端从操作者会话推导**,不是界面上的一个选择器。**唯一例外是"改文案"**:spec §9.3 把"行数随 tab 变"的说明**指定**由 `operation-guides.ts` 的既有引导条目承载(正是为了不必新做控件),Task 7 Step 7 照它执行,不算未批暴露。
15. **撤维度时测试要反向钉"不得回流"**(同一条 memory):凡是"这轮决定不做/已从界面摘掉"的维度,必须留一条实跑用例钉住它不许长回来——本计划有五处:`tests/company-user-create.test.ts` 与 `company-user-list.test.ts`(二期那条线已写好,钉建号与公司列不回流)、Task 11 Step 1 **第四支**(钉写入口不收 `company_id`)、Task 12 Step 4 **那条**(钉按 `fileId` 的端点不接 `company_id`)、Task 7 Step 7 第 4 条(钉"当前公司"只由文案与 `is-active` 承载,`CompanyTabs.vue` 里不许长出提示条)。**反向钉用例必须自带取样非空自检**(同文件里断言一个"该做的确实做了"),否则它会因为符号根本不存在而恒绿,等于没钉。
---
## 文件结构总览
| 动作 | 文件 | 责任 |
|---|---|---|
| Create | `admin-frontend-vue/src/config/company-scope.ts` | 两张口径清单的唯一来源:`SUPER_ADMIN_ONLY_MENU_KEYS`、`COMPANY_SCOPED_PAGES`(menuKey → api 文件 + 端点前缀)。无 import,避免与 `routes.ts` 成环 |
| Modify | `admin-frontend-vue/src/router/routes.ts` | `AdminPageDef` 加 `superAdminOnly?` / `companyScoped?`;`routeOf()` 把 `superAdminOnly` 抄进 `meta` |
| Modify | `admin-frontend-vue/src/router/index.ts:52` | 角色硬闸门(与菜单树无关) |
| Modify | `admin-frontend-vue/src/stores/admin-session.ts:30` | 单点剪掉 `superAdminOnly` 节点(侧边栏/面包屑/`firstVisible`/守卫四个消费者一起生效) |
| Create | `admin-frontend-vue/src/stores/company-tab.ts` | 公司列表 + `activeId`(默认 `id` 最小的启用公司),Pinia |
| Create | `admin-frontend-vue/src/layout/CompanyTabs.vue` | tab 条,渲染在 `AdminLayout.vue:115` 之后一处 |
| Create | `admin-frontend-vue/src/layout/company-tab-model.ts` | `companyIdForRequest` / `firstSelectableCompanyId` 两支纯函数(store 与用例共用的口径) |
| Modify | `admin-frontend-vue/src/layout/AdminLayout.vue:115-116` | 挂 `<CompanyTabs />` |
| Modify | `admin-frontend-vue/src/layout/operation-guides.ts` | §9.3 承载:7 条既有 text 追加"行数随 tab 变"那句 + `admin_group_manage` 由 fallback 改独立条目(Task 7 Step 7) |
| Modify | 批次 1 的 8 页各自 `*Page.vue` | 传 `companyTab.requestCompanyId` + Task 7 Step 5 那条 `watch`(逐个见 Task 8-12 的 Files 块) |
| Modify | `backend-java/.../modules/company/service/CompanyService.java:58-76` | `listVisible` 非超管一律 403 |
| Modify | `backend-java/.../modules/permission/service/PermissionMenuService.java` | 三处出口把 `admin_companies` 从可见/可授予集合里摘掉 |
| Modify | `backend-java/.../common/service/CompanyScopeSupport.java` | 加 `memberUserIds(companyId)` + 成员数哨兵 |
| Create | `backend-java/.../common/service/DataReadScope.java` | 唯一的"操作者 + 请求 company_id → 读范围"出口 |
| Modify | 批次 1 的 8 个页面对应 controller/service(逐个见 Task 8-12 的 Files 块) | 叠 `readScope` |
**本计划不覆盖**:spec §11.1 的批次 2(查询ASIN、最低价ASIN、撞款监控、店铺数据记录)与批次 3 的表侧改造(去重库、品牌库,依赖二期 V145)。批次 2 的**前置闸门**是 §11.2 四条生产只读 SQL 的实查结果(拿不到结果就不开工);批次 3 依赖 V145 落地,两者各需自己的计划。**§5 那两页 C 类的"不参与"声明不排在批次 3**:tab 条一上线,"切了纹丝不动"这坏观感就同时上线,所以注册表的显式 `companyScoped: false` 与它的引导文案都由批次 1 落(Task 1 Step 4、Task 7 Step 7 第 5 条)。
---
## Task 0: 开工基线自证(不做完这一步,后面每条"绿"都没有分母)
**Files:**
- 只读,不改任何文件
- [ ] **Step 1: 确认 git 仓库与工作区状态**
```bash
cd D:/todesk/副业/数富AI/crawler-plugin
git rev-parse --abbrev-ref HEAD # 期望 master
git merge-base --is-ancestor 67b62cc3 HEAD && echo OK # 本计划依赖的三笔(V145 / 前端摘维度 / 18号计划记录)必须在历史里
git rev-parse --short HEAD # 抄进本任务提交信息;写这份计划时它在我眼皮底下从 00e5df02 跳到了 67b62cc3
git status --short # 期望恰好 4 行 untracked(tmp-probe.txt / tmp/ / 本计划两份文档)
```
⚠️ **18:0x 复核:分母已经不是 4 行了。** 本计划写完时工作区长出这批**不是这计划造的**条目(HEAD 仍是 `67b62cc3`,没人新提交,是另一会话的在飞改动):
```
M admin-frontend-vue/src/App.vue
M admin-frontend-vue/src/main.ts
M admin-frontend-vue/src/pages/task-center/TaskCenterBoardPage.vue
M admin-frontend-vue/src/pages/tasks/DuplicateCheckPage.vue
M admin-frontend-vue/tests/align-locale.test.ts
?? admin-frontend-vue/src/plugins/
?? admin-frontend-vue/tests/perf-admin-repeat-requests.test.ts
?? admin-frontend-vue/tests/perf-element-on-demand.test.ts
```
三条后果,都在下面第 2 条的处置里:①`TaskCenterBoardPage.vue` 就是 Task 10 要改的那一页,**别人的在飞改动没落定就不要动它**;`DuplicateCheckPage.vue` 属批次 2(本计划不覆盖),但同一批里还躺着 `main.ts` / `App.vue` / `src/plugins/` 这三个**全局件**——它们一动,Task 7 的 `npm test` 分母和 `vue-tsc` 结果都不再是本计划能预测的;②本计划所有提交都是按路径 `git add`,在脏树上加同名文件会把他们的半截改动一起带走;③Task 0 Step 2 的 `npm test` 分母会包含他们的用例(那两个 `perf-*.test.ts`),"红了几条"要按文件报,别把他们的红记到本计划头上。
⚠️ **这个仓库有另一个会话在并行提交**(16:0x→17:0x 之间 HEAD 动了一次)。所以:
1. 每个任务开工前重跑 `git rev-parse --short HEAD`;变了就读 `git log --oneline <上次的HEAD>..HEAD`,**尤其确认 `85e1e92a` 摘掉的公司维度没被谁加回来**(Task 2 Step 1 那三支反向钉会替你红,但红在半路比红在验收时难查)。
2. `git status --short` 出现**不是你这轮造的**条目 ⇒ 停下来出清单交用户决定(既定工作方式),别卷进提交、别回退、别替它提交。
3. `tmp/` 里的 `tmp/c8-build` 是**真 worktree**,不是垃圾;`backend-java/tmp-probe.txt` 是我 11:47 留下的探针,本计划收尾时删(Task 13 Step 4)。
- [ ] **Step 2: 实测前端干净树基线(不用记忆里的 1687)**
```bash
cd admin-frontend-vue && npm test 2>&1 | tail -5
```
Expected: `# fail 0`。记下 `# pass <N>`,写进本计划最后一笔的验收说明——后面任何一次对比都用这个 N,不用记忆值。
- [ ] **Step 3: 实测后端基线**
```bash
cd ../backend-java && mvn -q test 2>&1 | tail -20
```
Expected: `BUILD SUCCESS`,`Failures: 0, Errors: 0`。**不许与 Nuitka 打包并行**。
- [ ] **Step 4: 把两个基线数字记进提交信息**
后续每个任务的"全量绿"都是与这两个数字差分,不是绝对句。
- [ ] **Step 5: 先把设计文档与本计划入仓(第一笔,动任何代码之前)**
这两份文件现在还是 untracked。实施的第一笔就是它们,理由是后面 12 个任务都要引用 § 编号——不在仓里,引用就是悬空的。
```bash
git add docs/ops/company-tab-design-2026-10-04.md docs/plans/19-company-tab.md
git commit -m "docs(公司tab): 设计与实施计划入仓(批次 0-1,16 页普查与四条口径锁定)"
```
`crawler-plugin` 的远端钩子不拦 `docs/`(那条"Gitea 拒推含 docs 的提交"只适用于 `app_client` 仓库),所以这一笔能正常推。**推送与否由用户定**,本计划不代推。
---
## Task 1: 前端角色硬闸门(`superAdminOnly` 注册表 + 守卫 + 菜单树剪枝)
**Files:**
- Create: `admin-frontend-vue/src/config/company-scope.ts`
- Modify: `admin-frontend-vue/src/router/routes.ts:4-13`(`AdminPageMeta`/`AdminPageDef`)、`:22`(`account/companies` 那条)、`:40-49`(`routeOf`)
- Modify: `admin-frontend-vue/src/router/index.ts:52`
- Modify: `admin-frontend-vue/src/stores/admin-session.ts:30`
- Test: `admin-frontend-vue/tests/company-super-admin-only.test.ts`(新建)
**Interfaces:**
- Consumes: 无
- Produces:
- `SUPER_ADMIN_ONLY_MENU_KEYS: readonly string[]`(值恰好 `['admin_companies']`)
- `COMPANY_SCOPED_PAGES: readonly CompanyScopedPage[]`,`CompanyScopedPage = { menuKey: string; apiFiles: string[]; pageFiles: string[] }`
- `AdminPageDef.superAdminOnly?: boolean`、`AdminPageDef.companyScoped?: boolean`
- `pruneSuperAdminOnly<T extends { key: string }>(nodes: T[], isSuperAdmin: boolean): T[]`(放 `src/router/helpers.ts`)
- [ ] **Step 1: 写失败的测试**
Create `tests/company-super-admin-only.test.ts`:
```ts
import test from 'node:test'
import assert from 'node:assert/strict'
import { readFileSync } from 'node:fs'
import { adminPages } from '../src/router/routes.ts'
import { pruneSuperAdminOnly } from '../src/router/helpers.ts'
import { SUPER_ADMIN_ONLY_MENU_KEYS } from '../src/config/company-scope.ts'
/** 公司配置是角色内在闸门,不是菜单授权(spec §2:菜单授权可以被人改坏,role 不能)。
* 12:3x 事故的教训是"把页面可见性当数据可见性用",这里反过来防另一个方向:只挂一处会留旁路。 */
test('超管专属页必须同时被注册表与口径清单认领(两处不一致就是漏了一处)', () => {
const flagged = adminPages.filter((p) => p.superAdminOnly).map((p) => p.menuKey)
assert.deepEqual(flagged.sort(), [...SUPER_ADMIN_ONLY_MENU_KEYS].sort())
assert.ok(SUPER_ADMIN_ONLY_MENU_KEYS.includes('admin_companies'))
})
test('路由守卫里必须有一条与菜单树无关的角色判定', () => {
const guard = readFileSync('src/router/index.ts', 'utf8')
assert.match(guard, /superAdminOnly/, '守卫没查角色硬闸门')
assert.match(guard, /isSuperAdmin/, '守卫必须先判 session.isSuperAdmin')
})
test('剪枝:非超管拿不到超管专属节点,超管一个字节都不少', () => {
const tree = [
{ key: 'g1', children: [{ key: 'admin_companies', children: [] }, { key: 'admin_users', children: [] }] },
{ key: 'admin_history', children: [] },
]
const forAdmin = pruneSuperAdminOnly(tree, false)
assert.equal(JSON.stringify(forAdmin).includes('admin_companies'), false, '非超管菜单树里不许留公司管理')
assert.ok(JSON.stringify(forAdmin).includes('admin_users'), '普通节点不许被误剪')
assert.equal(pruneSuperAdminOnly(tree, true), tree, '超管原样返回,不做无谓拷贝')
})
test('剪枝是纯函数且幂等(store 里会反复调用)', () => {
const tree = [{ key: 'admin_companies', children: [] as unknown[] }]
const once = pruneSuperAdminOnly(tree, false)
assert.deepEqual(pruneSuperAdminOnly(once, false), once)
})
test('C 类两页必须显式声明 companyScoped: false(spec §5:声明,不是遗漏)', () => {
// 留空和 false 运行时等价,但只有 false 是"读过普查、决定不参与"的证据。
for (const key of ['admin_shop_keys', 'admin_product_categories']) {
const page = adminPages.find((p) => p.menuKey === key)
assert.ok(page, `注册表里找不到 ${key}`) // 取样非空自检
assert.equal(page.companyScoped, false, `${key} 必须显式写 companyScoped: false,不能留空`)
}
})
```
> 用 `assert.equal(page.companyScoped, false)` 而不是 `!page.companyScoped`:留空是 `undefined`,前者会红、后者会绿——这条要防的正是"留空"。
- [ ] **Step 2: 跑,确认失败**
Run: `cd admin-frontend-vue && node --test tests/company-super-admin-only.test.ts`
Expected: FAIL —— `Cannot find module '../src/config/company-scope.ts'`。
- [ ] **Step 3: 建口径清单**
Create `src/config/company-scope.ts`:
```ts
/** 公司口径的唯一清单(设计文档 §8)。
* 单独成文件而不是塞进 routes.ts:routes.ts 被 menu-route-map.ts import,
* 而护栏用例要从这里反过来读注册表,放在一起会成环。 */
/** 角色内在闸门:只有超管可见可读写,与 user_column_permission 无关。 */
export const SUPER_ADMIN_ONLY_MENU_KEYS: readonly string[] = ['admin_companies']
export interface CompanyScopedPage {
/** 与 routes.ts 的 menuKey 逐字一致。 */
menuKey: string
/** 相对 admin-frontend-vue 的 api/取数模块路径;护栏逐文件断言它真的带了 company_id。 */
apiFiles: string[]
/** 页面组件路径;护栏断言它 watch 了 tab.activeId(否则切 tab 不重取数,tab 是装饰品)。 */
pageFiles: string[]
}
/** 参与公司 tab 的页(spec §3 归属普查:批次 1 = 9 个 A 类页里除去依赖二期 V145 的去重库)。
* 后续批次往里加行时,同一笔提交必须带上对应 api 文件的 company_id,否则新用例红。 */
export const COMPANY_SCOPED_PAGES: readonly CompanyScopedPage[] = [
{ menuKey: 'admin_task_center', apiFiles: ['src/api/task-center.ts', 'src/pages/task-center/task-center-model.ts'], pageFiles: ['src/pages/task-center/TaskCenterBoardPage.vue'] },
{ menuKey: 'admin_image_video_tasks', apiFiles: ['src/pages/tasks/image-video-api.ts'], pageFiles: ['src/pages/tasks/ImageVideoTasksPage.vue'] },
{ menuKey: 'admin_user_secret_usage', apiFiles: ['src/api/user-secret-usage.ts'], pageFiles: ['src/pages/account/UserSecretUsagePage.vue'] },
{ menuKey: 'admin_user_secrets', apiFiles: ['src/api/user-secrets.ts'], pageFiles: ['src/pages/account/UserSecretsPage.vue'] },
{ menuKey: 'admin_history', apiFiles: ['src/pages/records/history-api.ts'], pageFiles: ['src/pages/records/RecordsHistoryPage.vue'] },
{ menuKey: 'admin_device_logs', apiFiles: ['src/api/device-logs.ts'], pageFiles: ['src/pages/records/DeviceLogsPage.vue'] },
{ menuKey: 'admin_group_manage', apiFiles: ['src/pages/account/shop-group-api.ts'], pageFiles: ['src/pages/account/GroupsPage.vue'] },
{ menuKey: 'admin_shop_manage', apiFiles: ['src/pages/shop/shop-manage-api.ts'], pageFiles: ['src/pages/shop/ShopManagePage.vue'] },
]
```
> `routes.ts:26-38` 的 `load()` 里写了各页真实路径(`@/pages/...`)——**Step 3 落盘前逐条与它核对**,路径写错会让护栏读不到文件而红,那正是它该有的失败方式(不许改成"文件不存在就跳过")。
- [ ] **Step 4: 注册表加字段并抄进 meta**
`src/router/routes.ts`:
```ts
export interface AdminPageMeta {
title: string
menuKey?: string
/** 角色内在闸门:非超管一律不可进(spec §2 的 A 类)。 */
superAdminOnly?: boolean
/** 参与公司 tab:取数必须带 company_id(spec §3)。 */
companyScoped?: boolean
}
```
`account/companies` 那条加 `superAdminOnly: true`;`COMPANY_SCOPED_PAGES` 里那 8 条各加 `companyScoped: true`(逐条写死,不从清单反推——清单会被 Step 1 的用例反过来对账)。
**C 类两页要显式写 `false`,不许留空**(spec §5:"显式声明'不按公司分',而不是静默不筛")——`routes.ts:24`(`admin_shop_keys` 店铺密钥管理)与 `:37`(`admin_product_categories` 商品类目)各加 `companyScoped: false`。留空和 `false` 在运行时**没有任何区别**(`routeOf()` 只把 `superAdminOnly` 抄进 meta,`companyScoped` 不进 meta),它的唯一作用是让"这页不参与"成为一个**写得出来的决定**,并由 Step 1 那支 `registry_declares_c_class_pages_as_explicitly_not_scoped` 钉住(它的文案在 Task 7 Step 7 第 5 条)。
`routeOf()` 里在 `if (page.menuKey) meta.menuKey = page.menuKey` 之后补:
```ts
if (page.superAdminOnly) meta.superAdminOnly = true
```
并把 `AdminPageMeta` 的 `meta` 局部类型从 `Record<string, string>` 改为 `Record<string, string | boolean>`(`superAdminOnly` 是布尔,原类型会在 `vue-tsc` 下报错)。
- [ ] **Step 5: 剪枝纯函数**
`src/router/helpers.ts` 末尾追加:
```ts
import { SUPER_ADMIN_ONLY_MENU_KEYS } from '@/config/company-scope'
/** 从菜单树上摘掉超管专属节点。非超管必须剪(它的公司管理页永远不该出现),
* 超管原样返回——超管的准入由 router/index.ts 那条角色闸门管,这里剪了反而会让侧边栏少一项。 */
export function pruneSuperAdminOnly<T extends { key: string }>(nodes: T[], isSuperAdmin: boolean): T[] {
if (isSuperAdmin) return nodes
return nodes
.filter((node) => !SUPER_ADMIN_ONLY_MENU_KEYS.includes(node.key))
.map((node) => ({ ...node, children: pruneSuperAdminOnly((node as { children?: T[] }).children || [], isSuperAdmin) }))
}
```
(`import` 要放到文件顶部,与既有的 `import type { AdminMenuNode }` 并列。)
- [ ] **Step 6: 守卫加角色硬闸门**
`src/router/index.ts:52` 之前插入:
```ts
// 角色内在闸门:与菜单树无关。超管恒 true 会让"只剪菜单树"这条对超管无效,
// 而非超管即使被历史授权过 admin_companies 也进不来(spec §8.1:两处缺一处就留旁路)。
if (to.meta.superAdminOnly && !session.isSuperAdmin) {
return session.firstVisible || '/'
}
```
- [ ] **Step 7: store 单点剪枝**
`src/stores/admin-session.ts:30` 改成:
```ts
this.menuTree = pruneSuperAdminOnly(
canonicalizeMenuTree(await fetchAdminMenuTree()),
isSuperAdminRole(this.user?.role),
)
```
并在 import 区加 `import { pruneSuperAdminOnly } from '@/router/helpers'` 与 `import { isSuperAdminRole } from '@/types/admin'`(后者该文件已 import,确认即可)。
⚠️ `this.user = await fetchCurrentUser()` 必须在剪枝**之前**完成——现有顺序本就如此(`:29` 再 `:30`),改的时候别调换,否则 `isSuperAdminRole(undefined)` 会把超管的菜单剪掉。
- [ ] **Step 8: 跑测试到绿**
Run: `node --test tests/company-super-admin-only.test.ts tests/task-33.test.ts tests/company-menu-route.test.ts tests/admin-scaffold.test.ts`
Expected: 全 PASS。`task-33.test.ts` 断言的是 `isRouteAllowed` 三条既有语义,本任务没动它——**它要是红了就说明你改了不该改的签名**。
- [ ] **Step 9: 类型与全量**
Run: `npx vue-tsc --noEmit && npm test 2>&1 | tail -5`
Expected: 无类型错误;`# fail 0`,`# pass` 与 Task 0 的 N 一致 +3。
- [ ] **Step 10: 提交**
```bash
git add src/config/company-scope.ts src/router/routes.ts src/router/helpers.ts src/router/index.ts src/stores/admin-session.ts tests/company-super-admin-only.test.ts
git commit -m "feat(前端): 公司管理加角色内在闸门(注册表+守卫+剪枝)"
```
---
## Task 2: 核对批次 0 的前端半边(公司维度已由 `85e1e92a` 摘掉)+ 补唯一那条真缺口
**这一步的前提是复查,不是写代码。** 本任务原先写的是"给建号弹窗和用户管理页的公司控件加超管判断",那是照 `00e5df02` 那棵树写的。用户请求 (a) 要的是"非超管看不到公司配置",而 `85e1e92a` 做的是**对所有人**摘掉建号选公司、用户管理的公司列与"全部公司"筛选、顶栏公司旁白——比 (a) 更严,已经把它盖住了。所以:
- **不许**在这个任务里把公司下拉按"超管可见"加回来:那是 Global Constraint 14 点名的未批界面暴露,而且会跟二期那条线的反向钉用例(`tests/company-user-create.test.ts`、`company-user-list.test.ts:66`)打起来。
- 真缺口只剩一处:**「公司管理」页本身**。摘掉之后 `fetchCompanies` 在 `src/` 里只剩两个消费者(`CompaniesPage.vue`、`CompanyEditorDialog.vue`),入口由 Task 1 的 `superAdminOnly` 覆盖;本任务负责**证明覆盖到位**并取现网的证。
**Files:**
- Test: `admin-frontend-vue/tests/company-config-entry-super-only.test.ts`(**新建**)
- Test: `admin-frontend-vue/tests/company-user-create.test.ts`、`tests/company-user-list.test.ts`(只各加一句注释,说明那三条"恒绿断言"是反向钉,不许删)
- 无生产代码改动:Task 1 的注册表就是这半边唯一的实现
**Interfaces:**
- Consumes: Task 1 的 `SUPER_ADMIN_ONLY_MENU_KEYS` / `pruneSuperAdminOnly`
- Produces: 批次 0 前端半边的闭合证据三支(反向钉仍绿 + 入口剪枝生效 + 现网那版还在调 `/api/admin/companies` 的结论),以及 Step 4 那条决定发布紧迫性的取证
- [ ] **Step 1: 先读那三支已经存在的反向钉,确认它们钉的就是"不得回流"**
```bash
node --test tests/company-user-create.test.ts tests/company-user-list.test.ts
```
逐条读到断言级别,给它们各补一句注释 `// 反向钉:公司维度不得回流到界面(2026-10-04 定口径)`——注释只加在**测试里**(这是"为什么这条今天恒绿的断言不许删"的唯一读者可见处):
| 用例 | 钉住的事实 |
|---|---|
| `company-user-create.test.ts`「建号模型源码里公司口径已摘干净」 | `user-create-model.ts` 与 `CreateUserDialog.vue` 里 `companyId`/`CompanyItem`/`所属公司`/`selectableCompanies` 一个都不许出现 |
| `company-user-create.test.ts`「请求体不带 companyId」 | `'companyId' in toCreateUserRequest(...) === false` ⇒ 归属由后端推导 |
| `company-user-list.test.ts:66` | `UsersPage.vue` 里不许出现 `fetchCompanies` |
> ⚠️ 这类"全文 doesNotContain"断言的共同失效方式:文件改名/路径写错时读文件会抛 ⇒ 用例红(好事)。但**如果有人把它改成 `if (exists) assert...`,它就恒绿了**。执行时确认这三条没有 existence 守卫,也没有被 `try/catch` 包住。
- [ ] **Step 2: 写公司配置入口的缺口用例(Task 1 的注册表在这里验收)**
Create `tests/company-config-entry-super-only.test.ts`:
```ts
import test from 'node:test'
import assert from 'node:assert/strict'
import { readdirSync, statSync } from 'node:fs'
import { join } from 'node:path'
import { readSource } from './helpers.ts'
import { adminPages } from '../src/router/routes.ts'
import { SUPER_ADMIN_ONLY_MENU_KEYS } from '../src/config/company-scope.ts'
/** 递归扫 src 下指定后缀的文件(相对路径统一正斜杠)。
* 不走 execSync('grep'):node 在 Windows 上把 execSync 交给 cmd.exe,那里没有 grep,
* 命令会「成功返回空串」而不是报错——正是恒绿的形状。扫描逻辑必须留在用例自己的进程里。 */
function filesWithSuffix(exts: string[]): string[] {
const out: string[] = []
const walk = (dir: string): void => {
for (const name of readdirSync(dir)) {
const abs = join(dir, name)
if (statSync(abs).isDirectory()) walk(abs)
else if (exts.some((e) => name.endsWith(e))) out.push(abs.split(/[\\/]+/).join('/'))
}
}
walk('src')
return out
}
test('名单里的每个 menuKey 都在页面注册表上打了 superAdminOnly', () => {
assert.ok(SUPER_ADMIN_ONLY_MENU_KEYS.length >= 1, '名单为空 = 这道闸门等于没写')
for (const key of SUPER_ADMIN_ONLY_MENU_KEYS) {
const page = adminPages.find((p) => p.menuKey === key)
assert.ok(page, `${key} 不在 adminPages 里,名单形同虚设`)
assert.equal(page.superAdminOnly, true, `${key} 没打 superAdminOnly 标记`)
}
})
test('公司 API 模块的消费者集合恰好是公司管理那两个文件(账号页已摘干净)', () => {
const found = filesWithSuffix(['.vue', '.ts'])
.filter((rel) => readSource(rel).includes("from '@/api/companies'"))
.sort()
assert.deepEqual(found, [
'src/pages/account/CompaniesPage.vue',
'src/pages/account/CompanyEditorDialog.vue',
].sort())
// 深比较的是"扫描真实得到的集合",不是常量和自己比;扫描漏抓会让 found 变空 ⇒ 这条红,不会恒绿。
})
/** 花括号配对取函数体(和 Task 12 的 Java methodBody 同一动机:整文件比字符串会被注释和无关行骗)。 */
function bodyOf(source: string, name: string): string {
const at = source.indexOf(`function ${name}(`)
assert.notEqual(at, -1, `${name} 不在了——读路径的钉子失去意义之前,先确认它不是被改名/删掉了`)
const open = source.indexOf('{', at)
let depth = 0
for (let i = open; i < source.length; i++) {
if (source[i] === '{') depth++
else if (source[i] === '}') { depth--; if (depth === 0) return source.slice(open, i + 1) }
}
assert.fail(`${name} 花括号不配对,解析失败`)
}
test('公司列表的读路径不靠 canManage 把关(把关只有两处:Task 1 剪枝 + Task 4 后端 403)', () => {
const page = readSource('src/pages/account/CompaniesPage.vue')
// 这一条在基线上就是绿的,是反向钉(Global Constraint 15):CompaniesPage.vue:21 的
// `const canManage = computed(() => session.isSuperAdmin)` 只门住 :63 新建、:100 编辑两个写按钮,
// 这是对的(和 GroupsPage/UserSecretsPage 同类,纯显示开关)。
// 要防的是有人把 canManage 挪进读路径,替掉后端闸门 ⇒ 非超管看到空列表而不是 403,静默失效。
const loader = bodyOf(page, 'loadCompanies')
assert.equal(loader.includes('canManage'), false,
'loadCompanies 里不许出现 canManage:列表可见性由入口剪枝和后端决定,前端再加一道就变成第三套口径')
})
```
> 三条断言都只读文件、不 shell out;`readSource` 拿不到文件会直接抛,`bodyOf` 找不到函数名会先 assert 红 ⇒ 用例红,这正是路径改名/函数改名时该有的失败方式(memory「护栏要做进代码出口」)。**不许**把它改成 `if (existsSync) assert...` 或包 `try/catch`。
>
> 第三条绿是设计如此,不是漏钉:Task 13 Step 1 变异时要在 `loadCompanies` 里真的写一次 `if (!canManage.value) return`,确认它红,才算钉住。
- [ ] **Step 3: 跑,确认它红在 Task 1 之前、绿在之后**
Run: `node --test tests/company-config-entry-super-only.test.ts`
Expected: Task 1 未完成时第一条红在 `没打 superAdminOnly 标记`(或 `SUPER_ADMIN_ONLY_MENU_KEYS` 导出不存在而编译红);Task 1 做完全 PASS。**不许**为了让它红而先动实现,也不许把 `>= 1` 改成 `>= 0` 让它早绿。
- [ ] **Step 4: 现网取证——批次 0 的顺序约束挂在这条读结果上**
现网 admin-vue 是 `20261004-135428`(13:54 构建),**早于 `85e1e92a`**,所以它大概率仍在调 `GET /api/admin/companies`——12:3x 事故就是"这个调用 + 一个 403"的形状。这条取证决定的是紧迫性,不改变顺序本身:
```bash
# 只读公开链:取现网入口 chunk,grep 能扛 minify 的字符串字面量
python scripts/_admin_vue_probe.py # 既有探针优先;没有就直接 curl 公开链
# 对照必须同时命中,否则"0 命中"只说明抓错了文件(memory「grep -v 过滤器连 stdout 一起吞、0 命中≠没有」)
```
判据(每条都要配一个非零对照,如 `/api/admin/users`):
- 命中 `/api/admin/companies` ⇒ 现网仍在拉公司目录 ⇒ **批次 0 的 admin-vue 必须先发**,Task 3 的 jar 才能上(Global Constraint 1);
- 未命中 ⇒ 现网已不依赖它,但 jar 仍要等到"包含 `85e1e92a` 之后构建的 admin-vue"上线后再上;把这条结论**写进 Task 3 的提交信息**,别留给下一个人重新猜一遍。
- [ ] **Step 5: 提交**
```bash
npx vue-tsc --noEmit && npm test 2>&1 | tail -5
git add src/config/company-scope.ts src/router/routes.ts src/router/index.ts src/stores/admin-session.ts \
tests/company-config-entry-super-only.test.ts tests/company-user-create.test.ts tests/company-user-list.test.ts
git commit -m "feat(前端): 公司配置入口按角色剪枝;核对 85e1e92a 已摘掉的公司维度并反向钉住"
```
> **部署关口**:Task 1-2 合起来就是批次 0 的前端半边,**必须先于 Task 3 的 jar 上线**。出一个 admin-vue 版本后走完 §11.3 的整树聚合摘要复验,才能进 Task 3。
---
## Task 3: 后端 `listVisible` 非超管一律 403(翻转三条既有断言)
**Files:**
- Modify: `backend-java/src/main/java/com/nanri/aiimage/modules/company/service/CompanyService.java:58-76`
- Modify: `backend-java/src/test/java/com/nanri/aiimage/modules/company/service/CompanyServiceDirectoryTest.java:120-131,160-169,172`
- Modify: `backend-java/src/test/java/com/nanri/aiimage/modules/company/service/CompanyReadPathMenuGateTest.java:41-51`
**Interfaces:**
- Consumes: 既有 `ensureSuperAdmin(AdminUserEntity)`(`CompanyService.java:198`,抛 403)
- Produces: `List<CompanyEntity> listVisible(AdminUserEntity operator)` —— 签名不变,语义变(非超管恒抛)
- [ ] **Step 1: 先翻转三条既有断言(红)**
`CompanyServiceDirectoryTest.java`:把 `:120-131` 整个替换为
```java
@Test
@DisplayName("公司内管理员读不到公司目录:读写都只超管(spec §12 需求 2)")
void companyScopedAdminCannotReadDirectory() {
assertThatThrownBy(() -> companyService.listVisible(operator("admin", 2L)))
.isInstanceOf(BusinessException.class)
.hasMessageContaining("公司");
verify(companyMapper, never()).selectList(any());
}
```
把 `:160-169` 的 `companyScopedAdminReadsOwnCompanyWithoutTheMenuGrant` 替换为
```java
/**
* 回归用例(2026-10-04 12:3x 生产事故)的**新形态**:当年挂 403 的是菜单授权(一笔都没发 ⇒ 全员闪退),
* 现在挂 403 的是角色。区别在于角色不会被"忘了授权"打穿,但**前端必须自己不发这个请求**
* (见 Task 2 与 tests/company-config-entry-super-only.test.ts),否则非超管照样吃 403。
*/
@Test
@DisplayName("非超管读公司目录只认角色,不认菜单授权(菜单那条已经不可能再伤到人)")
void directoryReadGateIsRoleIntrinsicNotMenuBased() {
assertThatThrownBy(() -> companyService.listVisible(operator("admin", 2L)))
.isInstanceOf(BusinessException.class)
.hasMessageContaining("超级管理员");
verify(companyMapper, never()).selectList(any());
}
```
`:172` 的 `@DisplayName` 文案「公司内管理员读得到目录也不能建第二家公司」改为「公司内管理员读不到目录也建不了公司」。
`CompanyReadPathMenuGateTest.java:41-51` 的期望从 `hasSize(2)` 改为 `hasSize(3)`,`.as(...)` 文案改成 `create / update / listVisible 三处的超管闸门 must 保留`。
- [ ] **Step 2: 跑,确认红在预期位置**
Run: `cd backend-java && mvn -q test -Dtest=CompanyServiceDirectoryTest,CompanyReadPathMenuGateTest`
Expected: FAIL —— 两条翻转正例失败(当前实现返回 1 行)、`hasSize(3)` 断言失败(当前 2 处)。**必须是这三条红**,别的全红说明环境不干净。
- [ ] **Step 3: 改实现**
`CompanyService.java:58` 起,`listVisible` 改为:
```java
public List<CompanyEntity> listVisible(AdminUserEntity operator) {
String role = adminAuthSupport.currentRole(operator);
if (role == null) {
throw new BusinessException(403, "需要管理员权限");
}
// 读写都只超管(spec §2 的 A 类):判角色、不判菜单授权——
// 12:3x 已经证明"把可见性挂在 user_column_permission 上"会因一笔授权没发而全员 403。
ensureSuperAdmin(operator);
return companyMapper.selectList(new LambdaQueryWrapper<CompanyEntity>()
.orderByAsc(CompanyEntity::getId));
}
```
同时把方法上方的 Javadoc(`:44-56`)改掉两段过时的话:「这里不查菜单权限……本方法同时是「用户管理」页公司下拉的数据源」——非超管已不再拉这份目录(Task 2),改成"仅超管读写;「用户管理」页的公司下拉也只超管可见"。**留着旧注释会误导下一个改这里的人**,这比补一段新说明更要紧。
⚠️ `ensureSuperAdmin` 的 403 消息必须**同时含**「超级管理员」和「公司」四个字(现为「只有超级管理员可以新增或修改公司」,含「公司」;若它给 `listVisible` 复用时会说"新增或修改",就在 `listVisible` 里单独抛:`throw new BusinessException(403, "只有超级管理员可以查看公司配置")`)。原因:`:134` 和 `:143` 两条既有拒绝用例分别断言 `hasMessageContaining("管理员")` 与 `hasMessageContaining("公司")`,消息选错会把它们中一条弄红——那是**红在用例而不是实现**,白排查一轮。
- [ ] **Step 4: 跑,确认绿**
Run: `mvn -q test -Dtest='Company*Test'`
Expected: `CompanyServiceDirectoryTest`、`CompanyReadPathMenuGateTest`、`CompanyServiceNameLookupTest`、`CompanyServiceRequireActiveTest` 全 PASS。
(`CompanyServiceRequireActiveTest` 若红,是 `create`/`update` 的 `requireActive` 链路被动到——本任务不该碰它,回去查 Step 3 有没有多删行。)
- [ ] **Step 5: 全量 + 提交**
```bash
mvn -q test 2>&1 | tail -10 # 与 Task 0 的基线差分,不许新增红
git add backend-java/src/main/java/com/nanri/aiimage/modules/company/service/CompanyService.java \
backend-java/src/test/java/com/nanri/aiimage/modules/company/service/CompanyServiceDirectoryTest.java \
backend-java/src/test/java/com/nanri/aiimage/modules/company/service/CompanyReadPathMenuGateTest.java
git commit -m "feat(公司配置): 公司目录读侧收成角色内在闸门,非超管一律403"
```
---
## Task 4: `admin_companies` 从可见/可授予集合里摘掉(三处出口 + 剥离不报错)
**Files:**
- Modify: `backend-java/src/main/java/com/nanri/aiimage/modules/permission/service/PermissionMenuService.java:77-92`(`list`)、`:317-337`(`getUserColumnPermissions`)、`:562-658`(`updateUserColumnPermissions`)
- Test: `backend-java/src/test/java/com/nanri/aiimage/modules/permission/PermissionCompanyMenuHiddenTest.java`(新建)
**Interfaces:**
- Consumes: `SUPER_ADMIN_ONLY_MENU_KEYS` 的后端对应物——本任务在 `PermissionMenuService` 里定义一个 `private static final Set<String> SUPER_ADMIN_ONLY_KEYS = Set.of("admin_companies")`
- Produces: 三个出口的一致行为(授权树 / 当前用户菜单 / 提交授权)
- [ ] **Step 0: 前置只读取证(这条决定本任务的行为变化幅度,只交付命令、由用户执行)**
```sql
SELECT COUNT(*) AS granted FROM user_column_permission
WHERE column_id IN (SELECT id FROM columns WHERE column_key='admin_companies');
```
Expected:`0`(一期 memory 与 spec §2 的论证都基于"这一笔授权从没发过")。
**若不为 0**:本任务的 Step 5 会从"没人受影响"变成"某些账号已有的公司管理入口会消失"——那是要先告知用户的真实变更,不许默默上线。把实查数字补进 spec §2 的"今天只是恰好看不见"那句。
- [ ] **Step 1: 写失败的测试**
Create `PermissionCompanyMenuHiddenTest.java`(源码扫描两支):
```java
package com.nanri.aiimage.modules.permission;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import org.junit.jupiter.api.Test;
/**
* admin_companies 只能由角色内在闸门管(设计文档 §8.1 的三处出口)。
*
* <p>菜单行本身要**留着**(历史 user_column_permission 数据无处安放,且「菜单管理」页还得能看见它),
* 所以断言的是"从可授予集合摘掉 + 提交时剥离",不是"库里删行"。</p>
*/
class PermissionCompanyMenuHiddenTest {
private static final String SERVICE = "PermissionMenuService.java";
private static final String KEY = "admin_companies";
private String source() throws IOException {
Path root = Path.of("src/main/java/com/nanri/aiimage/modules/permission/service");
assertThat(root).as("用例依赖以 backend-java 为工作目录运行,别让守卫静默通过").isDirectory();
String text = Files.readString(root.resolve(SERVICE), StandardCharsets.UTF_8);
assertThat(text).as("扫描取样集非空自检").contains("getUserColumnPermissions");
return text;
}
@Test
void threeExitsAllReferenceTheSuperAdminOnlySet() throws IOException {
String text = source();
assertThat(text).contains("SUPER_ADMIN_ONLY_KEYS");
// 三个出口各自都要引用它:漏一个就留一条旁路(授权树能看见 / 当前用户菜单能带出 / 提交能写回)。
assertThat(text.split("SUPER_ADMIN_ONLY_KEYS", -1).length - 1)
.as("SUPER_ADMIN_ONLY_KEYS 至少被引用 4 次(1 次定义 + 3 处出口)")
.isGreaterThanOrEqualTo(4);
}
@Test
void grantIsStrippedInsteadOfRejected() throws IOException {
String text = source();
// 整树提交里带一个历史 admin_companies 绝不能 403:那会让"改密码/建号"这条链整体回滚(09-16 的形状)。
assertThat(text).doesNotContainMatch("(?s)ensureGrantable[\\s\\S]{0,600}admin_companies[\\s\\S]{0,200}BusinessException");
assertThat(text).contains("log.warn");
}
}
```
- [ ] **Step 2: 跑,确认红**
Run: `cd backend-java && mvn -q test -Dtest=PermissionCompanyMenuHiddenTest`
Expected: FAIL —— 两条都红(现在源码里没有 `SUPER_ADMIN_ONLY_KEYS`)。
- [ ] **Step 3: 定义集合 + 出口 1(授权树 `list`,`:77-92`)**
`PermissionMenuService` 类顶部字段区加:
```java
/** 角色内在闸门菜单:非超管看不见、谁也授不出去(设计文档 §8.1)。
* 与前端 src/config/company-scope.ts 的 SUPER_ADMIN_ONLY_MENU_KEYS 必须同值,由 Task 7 的跨端用例钉住。 */
private static final Set<String> SUPER_ADMIN_ONLY_KEYS = Set.of("admin_companies");
```
`list(...)` 里,在把行集折成 VO **之前**加过滤(`grantableOnly` 为 true 时**对所有角色**都摘,包括超管——这条正是"超管也不能把它授予别人";为 false 时保留,让「菜单管理」页仍能管理这一行):
```java
boolean restrictGrantTarget = grantableOnly;
rows = rows.stream()
.filter(row -> !(restrictGrantTarget && SUPER_ADMIN_ONLY_KEYS.contains(row.getColumnKey())))
.collect(Collectors.toList());
```
(变量名以文件里既有的行集合变量为准;关键是**位置在 VO 折算前**,放在折算后会漏掉分组父节点判断。)
- [ ] **Step 4: 出口 2(`getUserColumnPermissions`,`:317-337`)**
在超管分支(`if (isSuperAdmin(user)) return toItemVos(menus, menus);`)之后、非超管返回之前,对 `menus` 剪掉该 key:
```java
// 非超管:即使历史上被授过 admin_companies 也不下发(前端拿不到 key,侧边栏与守卫都无从显示)。
List<PermissionMenuEntity> visible = menus.stream()
.filter(menu -> !SUPER_ADMIN_ONLY_KEYS.contains(menu.getColumnKey()))
.collect(Collectors.toList());
```
并把后续原本用 `menus` 的两处换成 `visible`。**别只改返回值忘了改喂给 `toItemVos` 的第二个参数**,否则父分组会因"组下无可显示子项"被整体剪掉——那是把「用户管理」一起弄红的经典改法。
- [ ] **Step 5: 出口 3(`updateUserColumnPermissions`,`:562-658` / `ensureGrantable` `:925-942`)**
在提交 id 集合进入 `ensureGrantable` **之前**剥离,并 warn 不抛:
```java
List<Long> stripped = ids.stream()
.filter(id -> SUPER_ADMIN_ONLY_KEYS.contains(keyOf(id)))
.toList();
if (!stripped.isEmpty()) {
// 剥离而不是 403:整树提交里带一条历史授权,绝不能让「保存权限」这次操作整体失败
// (09-16 的静默权限丢失是反例,但 403 会让用户以为保存坏了)。
log.warn("GRANT_SUPER_ADMIN_ONLY_STRIPPED 已剥离超管专属菜单授权 ids={} operatorId={}", stripped, operatorId);
ids = new ArrayList<>(ids);
ids.removeAll(stripped);
}
```
`keyOf(Long menuId)` 用本类已有的"按 id 取 columnKey"手段(若没有就 `permissionMenuMapper.selectBatchIds(stripped)` 一次批量取,**不许逐条查**——N 次点查在保存权限这个入口上会被日志放大)。
⚠️ 同时确认删除范围那段(`:624-641`)没被改窄:`stripped` 的 id **不许进"要删除"集合**,否则剥离动作会顺手把历史授权行删掉 = 静默改数据。断言方式:Step 6 里加一条 `verify(mapper, never()).delete(any())`(按本类实际的删除方法名写)。
- [ ] **Step 6: 跑 + 全量 + 提交**
Run: `mvn -q test -Dtest='Permission*Test'`
Expected: `PermissionCompanyMenuHiddenTest` 两支绿;既有 `PermissionMenuServiceTest` 系列不新增红。
```bash
mvn -q test 2>&1 | tail -10
git add backend-java/src/main/java/com/nanri/aiimage/modules/permission/service/PermissionMenuService.java \
backend-java/src/test/java/com/nanri/aiimage/modules/permission/PermissionCompanyMenuHiddenTest.java
git commit -m "feat(权限): admin_companies 从可见/可授予集合摘掉,提交时剥离不报错"
```
> **批次 0 到此齐**:Task 1-4 是完整一批(前端两笔先上、后端两笔后上)。上线后必须实跑:用一个**非超管 admin** 账号登录,确认①侧边栏没有「公司管理」②「用户管理」页正常打开且 Network 里**没有** `/api/admin/companies` 请求③给它保存一次权限、带一条历史 `admin_companies` 授权,保存成功且日志出 `GRANT_SUPER_ADMIN_ONLY_STRIPPED`。
---
## Task 5: `CompanyScopeSupport.memberUserIds`(按公司枚举成员)+ 成员数哨兵
**Files:**
- Modify: `backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java`
- Test: `backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java`(**二期那条线已建了这个文件;若已存在就在里面追加,别覆盖**)
**Interfaces:**
- Consumes: `common/mapper/AdminUserMapper`(`BaseMapper<AdminUserEntity>`)、`AdminUserEntity.getCompanyId()`
- Produces: `List<Long> memberUserIds(Long companyId)`(顺序不保证;空公司返回空集;`companyId` 非法抛 `BusinessException`)
- [ ] **Step 0: 先取分母(只读,不写)**
`memberUserIds` 返回的集合长度就是每个 tab 的 `user_id IN (...)` 长度,也是 G6 阈值的对照物。跑这条只读 SQL(通道见 memory「生产环境接入要点」的只读通道,不要自己另开一条):
```sql
SELECT company_id, COUNT(*) AS members
FROM users
GROUP BY company_id
ORDER BY company_id;
```
把结果抄进本任务的提交信息里。三个数各自决定一件事:
1. `MAX(members)` 与 `MEMBER_WARN_THRESHOLD = 500` 的余量——余量小于 5 倍说明阈值定太高,哨兵等于不存在;
2. `company_id IS NULL` 那一行的计数——**必须为 0**。非 0 说明 143/144 之后仍有游离账号,`memberUserIds` 按公司等值查会把他们从**每一个** tab 里丢掉(spec §9 的静默丢数形态),先补归属再往下走;
3. companies 数与 spec §1 的「生产已有 2 家」对账。
本文件正文写的「今天全库 140 行」是拆工时的那次读数,**不是分母**:以 Step 0 实跑结果为准,对不上就按实跑值改写 Step 3 的 javadoc 与本条,别把过期数字留在计划里(memory「结论要说比例不说绝对句」+「分母只认本轮」)。
- [ ] **Step 1: 追加失败的测试**
```java
@Test
@DisplayName("按公司枚举成员:只投影 id,别把整行拉进内存")
void memberUserIdsSelectsOnlyIdColumn() {
AdminUserEntity a = new AdminUserEntity(); a.setId(11L);
AdminUserEntity b = new AdminUserEntity(); b.setId(12L);
when(adminUserMapper.selectList(any())).thenReturn(List.of(a, b));
assertThat(companyScope.memberUserIds(2L)).containsExactlyInAnyOrder(11L, 12L);
ArgumentCaptor<LambdaQueryWrapper<AdminUserEntity>> captor = ArgumentCaptor.forClass(LambdaQueryWrapper.class);
verify(adminUserMapper).selectList(captor.capture());
LambdaQueryWrapper<AdminUserEntity> q = captor.getValue();
assertThat(q.getSqlSelect()).as("必须只 select id,今天全库 140 行不代表以后也是")
.containsIgnoringCase("id").doesNotContain("*");
assertThat(q.getParamNameValuePairs()).containsValue(2L);
}
@Test
@DisplayName("非法公司 id 直接抛,不返回空集——空集在调用方是「查不到行」,语义完全不同")
void memberUserIdsRejectsBadCompanyId() {
assertThatThrownBy(() -> companyScope.memberUserIds(null))
.isInstanceOf(BusinessException.class);
assertThatThrownBy(() -> companyScope.memberUserIds(0L))
.isInstanceOf(BusinessException.class);
verify(adminUserMapper, never()).selectList(any());
}
```
> `getSqlSelect()` 若在该 MP 版本上不渲染列,退成断言 `verify(adminUserMapper).selectList(...)` 的 wrapper 里 `sqlSelect` 非空——**先在 Step 2 跑出红来确认哪种读法咬得住,再定稿**,不许写成 `contains("company_id")` 那种恒真断言(memory「字符串断言必须排他」)。
- [ ] **Step 2: 跑,确认红**
Run: `mvn -q test -Dtest=CompanyScopeSupportTest`
Expected: FAIL —— `memberUserIds` 方法不存在(编译失败也算预期红)。
- [ ] **Step 3: 实现**
`CompanyScopeSupport.java` 加 `@Slf4j`(现无)与:
```java
/** 超过这个成员数就该把 `user_id IN (...)` 换成子查询(见下方 warn 与 spec §3.2)。 */
static final int MEMBER_WARN_THRESHOLD = 500;
/**
* 按公司枚举成员账号 id(spec §3.2:tab 的读范围唯一来源)。
*
* <p>不加 LIMIT:今天全库 140 行,截断会让某个公司的 tab 看起来"数据不全"且毫无提示。
* 用 {@link #MEMBER_WARN_THRESHOLD} 当倒计时哨兵——它红在日志里、可被巡检抓到,
* 比"以后再说"安全。</p>
*/
public List<Long> memberUserIds(Long companyId) {
if (companyId == null || companyId <= 0) {
throw new BusinessException("公司 id 不能为空");
}
List<AdminUserEntity> rows = adminUserMapper.selectList(
new LambdaQueryWrapper<AdminUserEntity>()
.select(AdminUserEntity::getId)
.eq(AdminUserEntity::getCompanyId, companyId));
List<Long> ids = new ArrayList<>(rows.size());
for (AdminUserEntity row : rows) {
if (row.getId() != null && row.getId() > 0) {
ids.add(row.getId());
}
}
if (ids.size() > MEMBER_WARN_THRESHOLD) {
log.warn("COMPANY_MEMBER_SET_LARGE companyId={} size={} threshold={}"
+ " —— user_id IN (...) 列表已过长,改成 SELECT id FROM users WHERE company_id = ? 子查询",
companyId, ids.size(), MEMBER_WARN_THRESHOLD);
}
return ids;
}
```
- [ ] **Step 4: 哨兵用例(G6)**
```java
@Test
@DisplayName("G6 倒计时哨兵:成员数过阈值必须打 COMPANY_MEMBER_SET_LARGE(护栏在代码出口,不在注释)")
void warnsWhenMemberSetExceedsThreshold() {
List<AdminUserEntity> many = new ArrayList<>();
for (long i = 1; i <= CompanyScopeSupport.MEMBER_WARN_THRESHOLD + 1; i++) {
AdminUserEntity u = new AdminUserEntity(); u.setId(i); many.add(u);
}
when(adminUserMapper.selectList(any())).thenReturn(many);
List<Long> ids = companyScope.memberUserIds(3L);
assertThat(ids).hasSize(CompanyScopeSupport.MEMBER_WARN_THRESHOLD + 1);
// 断言方式二选一,以本仓既有日志测试手段为准:要么 ListAppender 抓日志,
// 要么把阈值判定抽成 package-private 的 boolean shouldWarn(int) 直接断言。
assertThat(CompanyScopeSupport.shouldWarn(ids.size())).isTrue();
}
```
按 Step 4 的注释落定其一后,把 Step 3 里的 `if (ids.size() > MEMBER_WARN_THRESHOLD)` 换成 `if (shouldWarn(ids.size()))`,并加:
```java
static boolean shouldWarn(int size) {
return size > MEMBER_WARN_THRESHOLD;
}
```
- [ ] **Step 5: 跑 + 提交**
Run: `mvn -q test -Dtest=CompanyScopeSupportTest`
Expected: 全 PASS。
```bash
git add backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java \
backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java
git commit -m "feat(公司范围): memberUserIds 按公司枚举成员 + 500 成员倒计时哨兵"
```
---
## Task 6: `DataReadScope`——唯一的"操作者 + 请求 company_id → 读范围"出口(G2 落在这)
**Files:**
- Create: `backend-java/src/main/java/com/nanri/aiimage/common/service/DataReadScope.java`
- Test: `backend-java/src/test/java/com/nanri/aiimage/common/service/DataReadScopeTest.java`(新建)
- Test: `backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java`(新建,G2)
**Interfaces:**
- Consumes: `CompanyScopeSupport.memberUserIds(Long)`、`CompanyScopeSupport.requireCompanyId(AdminUserEntity)`、`common/security/AdminAuthSupport.currentRole(AdminUserEntity)`、`modules/permission/support/UserDataScopeSupport.resolveVisibleUserIds(Long)`
- Produces:
- `ReadScope DataReadScope.readScope(AdminUserEntity operator, Long requestedCompanyId)`
- `boolean ReadScope.isUnfiltered()`、`List<Long> ReadScope.userIds()`、`List<Long> ReadScope.userIdsOr(List<Long> base)`
- [ ] **Step 1: 写失败的测试(spec §7 的五种组合逐个断言)**
```java
package com.nanri.aiimage.common.service;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;
import com.nanri.aiimage.common.model.entity.AdminUserEntity;
import com.nanri.aiimage.common.security.AdminAuthSupport;
import com.nanri.aiimage.modules.permission.support.UserDataScopeSupport;
import java.util.List;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/** 公司 tab 的唯一范围出口(spec §7)。五种组合必须逐个钉死——它们决定线上会不会越权。 */
class DataReadScopeTest {
private CompanyScopeSupport companyScope;
private AdminAuthSupport adminAuthSupport;
private UserDataScopeSupport userDataScope;
private DataReadScope readScope;
private static AdminUserEntity user(long id, String role, Long companyId) {
AdminUserEntity u = new AdminUserEntity();
u.setId(id); u.setRole(role); u.setCompanyId(companyId);
return u;
}
@BeforeEach
void setUp() {
companyScope = mock(CompanyScopeSupport.class);
adminAuthSupport = mock(AdminAuthSupport.class);
userDataScope = mock(UserDataScopeSupport.class);
when(adminAuthSupport.currentRole(any())).thenAnswer(inv -> ((AdminUserEntity) inv.getArgument(0)).getRole());
readScope = new DataReadScope(companyScope, adminAuthSupport, userDataScope);
}
@Test
@DisplayName("超管不选公司 = 今天的行为:完全不筛")
void superAdminWithoutCompanyStaysUnfiltered() {
ReadScope scope = dataReadScope.readScope(user(1L, "super_admin", 1L), null);
assertThat(scope.isUnfiltered()).isTrue();
assertThat(scope.userIdsOr(List.of(9L))).containsExactly(9L);
assertThat(scope.userIdsOr(null)).isNull();
}
@Test
@DisplayName("超管选公司 = 该公司成员替换掉「不筛」")
void superAdminWithCompanyNarrowsToMembers() {
when(companyScope.memberUserIds(2L)).thenReturn(List.of(11L, 12L));
ReadScope scope = dataReadScope.readScope(user(1L, "super_admin", 1L), 2L);
assertThat(scope.userIdsOr(null)).containsExactlyInAnyOrder(11L, 12L);
}
@Test
@DisplayName("超管选不存在的公司 = 空集 → 空页,不是 403、也不是全量")
void superAdminWithUnknownCompanyYieldsEmpty() {
when(companyScope.memberUserIds(99L)).thenReturn(List.of());
ReadScope scope = dataReadScope.readScope(user(1L, "super_admin", 1L), 99L);
assertThat(scope.isUnfiltered()).isFalse();
assertThat(scope.userIdsOr(null)).isEmpty();
assertThat(scope.userIdsOr(List.of(9L))).isEmpty();
}
@Test
@DisplayName("非超管永远锁本公司,不传也一样")
void adminIsAlwaysPinnedToOwnCompany() {
when(companyScope.requireCompanyId(any(AdminUserEntity.class))).thenReturn(2L);
when(companyScope.memberUserIds(2L)).thenReturn(List.of(21L, 22L));
when(userDataScope.resolveVisibleUserIds(5L)).thenReturn(List.of(21L, 99L));
ReadScope scope = dataReadScope.readScope(user(5L, "admin", 2L), null);
// 与既有的分组可见集**求交**,不是替换:非超管的组长范围不能被公司 tab 放大。
assertThat(scope.userIdsOr(userDataScope.resolveVisibleUserIds(5L))).containsExactly(21L);
}
@Test
@DisplayName("非超管传别家 = 空结果,不报错也不越权(照 AdminUserService:75-81)")
void adminPassingForeignCompanyGetsEmptyNot403() {
when(companyScope.requireCompanyId(any(AdminUserEntity.class))).thenReturn(2L);
ReadScope scope = dataReadScope.readScope(user(5L, "admin", 2L), 7L);
assertThat(scope.isUnfiltered()).isFalse();
assertThat(scope.userIds()).isEmpty();
}
@Test
@DisplayName("非超管没有公司归属时炸,不退化成「不筛」")
void adminWithoutCompanyFailsFast() {
when(companyScope.requireCompanyId(any(AdminUserEntity.class)))
.thenThrow(new com.nanri.aiimage.common.exception.BusinessException(403, "当前账号没有所属公司"));
assertThat(org.assertj.core.api.Assertions.assertThatThrownBy(
() -> dataReadScope.readScope(user(5L, "admin", null), null)))
.isInstanceOf(com.nanri.aiimage.common.exception.BusinessException.class);
}
}
```
- [ ] **Step 2: 跑,确认红**
Run: `mvn -q test -Dtest=DataReadScopeTest`
Expected: 编译失败(`DataReadScope` / `ReadScope` 不存在)。
- [ ] **Step 3: 实现 `ReadScope`**
```java
package com.nanri.aiimage.common.service;
import java.util.ArrayList;
import java.util.List;
/**
* 一次读请求的租户范围(设计文档 §7)。两种状态:不筛(超管没选公司 = 今天的行为)
* 与"限定到这批账号"。
*
* <p>{@link #userIdsOr(List)} 是它与各页**既有** `scopedUserIds` 唯一的接合点:
* base 传 null 表示"这页原本不筛",此时返回公司范围;两边都有值时求交,
* 因为公司 tab 只能**收窄**、不能放大组长本来看不到的行。</p>
*/
public final class ReadScope {
private final boolean unfiltered;
private final List<Long> userIds;
private ReadScope(boolean unfiltered, List<Long> userIds) {
this.unfiltered = unfiltered;
this.userIds = userIds;
}
public static ReadScope unfiltered() {
return new ReadScope(true, List.of());
}
public static ReadScope users(List<Long> ids) {
return new ReadScope(false, ids == null ? List.of() : List.copyOf(ids));
}
public boolean isUnfiltered() {
return unfiltered;
}
public List<Long> userIds() {
return userIds;
}
/** 空集 = 调用方应当直接返回空页(各页服务本来就有这条分支,照它写)。 */
public List<Long> userIdsOr(List<Long> base) {
if (unfiltered) return base;
if (base == null) return userIds;
List<Long> out = new ArrayList<>(base);
out.retainAll(userIds);
return out;
}
}
```
- [ ] **Step 4: 实现 `DataReadScope`**
```java
package com.nanri.aiimage.common.service;
import com.nanri.aiimage.common.model.entity.AdminUserEntity;
import com.nanri.aiimage.common.security.AdminAuthSupport;
import com.nanri.aiimage.modules.permission.support.UserDataScopeSupport;
import java.util.List;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
/**
* "操作者 + 请求里的 company_id → 该查哪批账号"的**唯一**出口(设计文档 §7)。
*
* <p>各页 service 一律走这里,不许自己写 if:一条越权旁路的成本是"这一页的过滤是假的",
* 而它不会报错。护栏 {@code CompanyIdParamGoesThroughReadScopeTest} 逐文件扫这条纪律。</p>
*/
@Service
@RequiredArgsConstructor
public class DataReadScope {
private static final String SUPER_ADMIN = "super_admin";
private final CompanyScopeSupport companyScope;
private final AdminAuthSupport adminAuthSupport;
private final UserDataScopeSupport userDataScopeSupport;
public ReadScope readScope(AdminUserEntity operator, Long requestedCompanyId) {
Long companyId = requestedCompanyId != null && requestedCompanyId > 0 ? requestedCompanyId : null;
if (SUPER_ADMIN.equals(adminAuthSupport.currentRole(operator))) {
if (companyId == null) {
return ReadScope.unfiltered();
}
return ReadScope.users(companyScope.memberUserIds(companyId));
}
// 非超管:一律按会话裁剪,前端传什么都不算(spec §4——tab 不是安全边界,这条才是)。
Long own = companyScope.requireCompanyId(operator);
if (companyId != null && !companyId.equals(own)) {
return ReadScope.users(List.of());
}
List<Long> base = userDataScopeSupport.resolveVisibleUserIds(operator.getId());
return ReadScope.users(ReadScope.users(companyScope.memberUserIds(own)).userIdsOr(base));
}
}
```
- [ ] **Step 5: G2 源码扫描用例(防"第二个 if")**
```java
package com.nanri.aiimage.common.service;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.fail;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import org.junit.jupiter.api.Test;
/**
* G2(spec §10):每个收 company_id 的 controller 必须走 readScope。
* 漏一处 = 那一页的 tab 是假的,而且不报错。
*/
class CompanyIdParamGoesThroughReadScopeTest {
@Test
void everyCompanyIdEndpointGoesThroughReadScope() throws IOException {
Path root = Path.of("src/main/java");
if (!Files.isDirectory(root)) fail("找不到 " + root + " —— 用例依赖以 backend-java 为工作目录");
List<Path> controllers;
try (Stream<Path> walk = Files.walk(root)) {
controllers = walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith("Controller.java"))
.filter(p -> read(p).contains("company_id"))
.collect(Collectors.toList());
}
assertThat(controllers)
.as("取样集非空自检:一条都没扫到说明扫描失效,护栏等于没写")
.isNotEmpty();
for (Path controller : controllers) {
String text = read(controller);
assertThat(text)
.as(controller + " 收了 company_id 却没走唯一出口")
.contains("readScope(");
// 第二条:参数必须**显式**写 name = "company_id"。
// 本仓库多数 controller 靠"方法参数名即请求名"绑定(ShopManageController:66-71 的 pageSize/groupId/shopName 就是),
// 照那个习惯写成 `Long companyId` 时 Spring 收的是 companyId=,而前端发的是 company_id=
// ⇒ 参数永远 null、接口 200、tab 切了不筛。这是全批次唯一"错了也不红"的形状,所以钉在扫描里。
assertThat(text)
.as(controller + " 的 company_id 没写显式 name=,会和驼峰参数名混成两种拼写")
.contains("name = \"company_id\"");
}
}
private static String read(Path path) {
try {
return new String(Files.readAllBytes(path), StandardCharsets.UTF_8);
} catch (IOException e) {
throw new IllegalStateException("读不到 " + path, e);
}
}
}
```
- [ ] **Step 6: 跑 + 提交(jar 半边)**
Run: `mvn -q test -Dtest='DataReadScopeTest,CompanyIdParamGoesThroughReadScopeTest'`
Expected: 全 PASS。
```bash
mvn -q test 2>&1 | tail -10
git add backend-java/src/main/java/com/nanri/aiimage/common/service/DataReadScope.java \
backend-java/src/test/java/com/nanri/aiimage/common/service/
git commit -m "feat(公司范围): DataReadScope 唯一读范围出口 + G2 扫 company_id 端点"
```
---
## Task 7: tab 机制(store + 组件 + 请求侧显式带参 + G1 双向对账 + §9.3 引导文案承载)
**Files:**
- Create: `admin-frontend-vue/src/layout/company-tab-model.ts`(两支纯函数,store 与用例共用)
- Create: `admin-frontend-vue/src/stores/company-tab.ts`
- Create: `admin-frontend-vue/src/layout/CompanyTabs.vue`
- Modify: `admin-frontend-vue/src/layout/AdminLayout.vue:16`(import)、`:115-116`(挂载)
- Modify: `admin-frontend-vue/src/layout/operation-guides.ts`(Step 7:7 条既有 text 追加一句 + `admin_group_manage` 由 fallback 改独立条目)
- Modify: `admin-frontend-vue/tests/align-operation-guide.test.ts`(`:28-31` 那一支要跟着改 + Step 7 第 4 支新用例)
- Modify: `admin-frontend-vue/src/config/company-scope.ts`(加 `companyTabModel.ts` 需要的类型即可,不改清单)
- Test: `admin-frontend-vue/tests/company-tab-model.test.ts`、`tests/company-tab-wiring.test.ts`(新建)
**Interfaces:**
- Consumes: Task 1 的 `COMPANY_SCOPED_PAGES`、`api/companies.ts` 的 `fetchCompanies()`、`session.isSuperAdmin`
- Produces:
- `useCompanyTabStore()`:state `{ companies: CompanyItem[], activeId: number | null, loading: boolean, loaded: boolean }`,getters `{ visibleForOperator: boolean, requestCompanyId: number | null }`,actions `{ initialize(): Promise<void>, setActiveId(id: number): void }`
⚠️ 后续任务(Task 8/9/10/11/12)取公司值**一律写 `companyTab.requestCompanyId`**(getter,非超管与未初始化时恒 `null`)。`companyIdForRequest` 是它底下那支**纯函数**的名字,签名要两个入参——在页面里裸调它是编译错误,不是"少传一个参数"。
- `companyIdForRequest(isSuperAdmin: boolean, activeId: number | null): number | null`(纯函数,放 `src/layout/company-tab-model.ts`)
- `firstSelectableCompanyId(companies: readonly CompanyItem[]): number | null`(纯函数,同放 `src/layout/company-tab-model.ts`)
- [ ] **Step 1: 写失败的纯函数测试**
Create `tests/company-tab-model.test.ts`:
```ts
import test from 'node:test'
import assert from 'node:assert/strict'
import type { CompanyItem } from '../src/api/companies-dto.ts'
import { companyIdForRequest, firstSelectableCompanyId } from '../src/layout/company-tab-model.ts'
/** 定义在三条 test **之前**:node:test 的用例回调按声明序执行,挪到文件尾会踩 TDZ。 */
const company = (id: number, companyName: string, status: number): CompanyItem =>
({ id, companyName, status, remark: null, createdAt: null, updatedAt: null })
test('非超管永远不下传 company_id(后端按会话裁剪,前端传了也只会被忽略——不许出现"前端以为自己筛了")', () => {
assert.equal(companyIdForRequest(false, 2), null)
})
test('超管默认选中 id 最小的启用公司,不是超管自己那家、也不是接口返回顺序的第一条', () => {
// 字段名用 CompanyItem 的真名(id / companyName / status):它的 label 列叫 companyName 不叫 name,
// 写成 name 的用例照样绿(firstSelectableCompanyId 不读 label),但组件里 item.name 会是 undefined。
assert.equal(firstSelectableCompanyId([
company(3, '丙', 1),
company(1, '厦门米椿花', 1),
company(2, '乙', 0),
]), 1)
})
test('全是停用公司时返回 null,tab 条整体不渲染(而不是给一个选不中的空 tab)', () => {
assert.equal(firstSelectableCompanyId([company(2, '乙', 0)]), null)
})
test('超管没拿到 activeId 之前不下传(宁可不筛,也别拿 null 去拼 "company_id=null")', () => {
assert.equal(companyIdForRequest(true, null), null)
assert.equal(companyIdForRequest(true, 2), 2)
})
```
- [ ] **Step 2: 跑,确认红**
Run: `node --test tests/company-tab-model.test.ts`
Expected: FAIL —— 模块不存在。
- [ ] **Step 3: 实现纯函数 + store**
Create `src/layout/company-tab-model.ts`:
```ts
import { COMPANY_STATUS_ACTIVE, type CompanyItem } from '@/api/companies-dto'
/** 超管的读范围公司。非超管恒 null——它的公司是固定的,下传一个常数只会让人以为这页在按公司筛。 */
export function companyIdForRequest(isSuperAdmin: boolean, activeId: number | null): number | null {
return isSuperAdmin ? activeId : null
}
/** 「默认选中第一家」= id 最小的启用公司(spec §4 口径:不是超管自己所属公司,也不是返回顺序首条)。 */
export function firstSelectableCompanyId(companies: readonly CompanyItem[]): number | null {
const active = companies.filter((c) => c.status === COMPANY_STATUS_ACTIVE && c.id > 0)
if (!active.length) return null
return active.reduce((min, c) => (c.id < min ? c.id : min), active[0].id)
}
```
Create `src/stores/company-tab.ts`:
```ts
import { defineStore } from 'pinia'
import { fetchCompanies } from '@/api/companies'
import type { CompanyItem } from '@/api/companies-dto'
import { useAdminSessionStore } from '@/stores/admin-session'
import { firstSelectableCompanyId, companyIdForRequest } from '@/layout/company-tab-model'
/** 公司 tab 的状态。成员 user ids **不在这里缓存**——每次请求交后端解析,
* 否则"改了成员没刷新页面"会出现一个看起来筛了、实际按旧名单筛的范围。 */
export const useCompanyTabStore = defineStore('company-tab', {
state: () => ({
companies: [] as CompanyItem[],
activeId: null as number | null,
loading: false,
loaded: false,
}),
getters: {
/** 只有超管需要这份目录(Task 2 之后非超管连 GET 都不该发)。
* 「该不该画 tab 条」这条判断**只住在这里**:组件里再写一遍 `length > 1` 就是第二把尺子,
* 将来改口径会两边不一致。loaded 也计入——没拉完之前不画,免得先闪出一条空 tab。 */
visibleForOperator(): boolean {
return this.loaded && useAdminSessionStore().isSuperAdmin && this.companies.length > 1
},
requestCompanyId(): number | null {
return companyIdForRequest(useAdminSessionStore().isSuperAdmin, this.activeId)
},
},
actions: {
async initialize() {
const session = useAdminSessionStore()
if (this.loaded || this.loading || !session.isSuperAdmin) return
this.loading = true
try {
this.companies = await fetchCompanies()
this.activeId = firstSelectableCompanyId(this.companies)
this.loaded = true
} finally {
this.loading = false
}
},
setActiveId(id: number) {
this.activeId = id
},
$resetOnSignOut() {
this.$reset()
},
},
})
```
⚠️ `companies.length > 1` 才显示 tab 条:今天两家,符合"有得选才给选";只有一家时画一条孤零零的 tab 会让人以为筛选坏了。这条判断**只**放进 `visibleForOperator`,组件里 `show` 直接抄它——组件再算一遍 `tabs.value.length > 1` 就是第二把尺子(而且它数的是"启用中的",store 数的是"拉到的",停用一家时两者会差 1)。
- [ ] **Step 4: 组件与挂载**
Create `src/layout/CompanyTabs.vue`(`el-tabs` 型,逐字与截图红框位置一致):
```vue
<script setup lang="ts">
import { computed, watch } from 'vue'
import { COMPANY_STATUS_ACTIVE } from '@/api/companies-dto'
import { useCompanyTabStore } from '@/stores/company-tab'
import { useAdminSessionStore } from '@/stores/admin-session'
const tab = useCompanyTabStore()
const session = useAdminSessionStore()
const tabs = computed(() => tab.companies.filter((c) => c.status === COMPANY_STATUS_ACTIVE))
const show = computed(() => tab.visibleForOperator)
watch(() => session.isSuperAdmin, (v) => { if (v) void tab.initialize() }, { immediate: true })
</script>
<template>
<div v-if="show" class="company-tabs" role="tablist" aria-label="按公司查看数据">
<button
v-for="item in tabs"
:key="item.id"
type="button"
role="tab"
class="company-tab"
:class="{ 'is-active': item.id === tab.activeId }"
:aria-selected="item.id === tab.activeId"
@click="tab.setActiveId(item.id)"
>{{ item.companyName }}</button>
</div>
</template>
```
⚠️ **这个组件到此为止,不要在 tab 条旁边再挂一句"当前公司:X"**(草稿里我写了这么一支 `<span class="company-tab-hint">`,已删)。§12 第 5 条把页头"当前公司"提示条明确算**未批**的界面暴露,附B 也钉了它;当前公司由"哪一枚 tab 是 `is-active`"承载,这一个事实不许有两处表达(否则停用一家时 tab 条与提示条会各说一个公司)。行数观感的说明走 Step 7 的引导文案,不走控件。
⚠️ 标签文本读的是 **`item.companyName`**,不是 `item.name`:`CompanyItem`(`src/api/companies-dto.ts:11-18`)的列就叫 `companyName`,全仓没有 `name` 字段。写错**不会**编译报错(模板里的属性访问不受 `vue-tsc` 的严格约束),只会渲染出一条条空白 tab——而空白 tab 会被报成"tab 坏了",不是"我字段名写错了"。这条和 Step 1 测试注释里那句是同一个道理:口径唯一的来源是 DTO,别在模板里凭印象造字段。
`src/layout/AdminLayout.vue`:`import CompanyTabs from '@/layout/CompanyTabs.vue'`(`:16` 那组 import 之后),模板在 `</el-breadcrumb>`(`:115`)与 `<OperationGuide />`(`:116`)之间插一行 `<CompanyTabs />`。
- [ ] **Step 5: 切 tab 必须让当前页重新取数(否则 tab 是个装饰品)**
**已定机制(不做事后二选一)**:`CompanyTabs.vue` 只写 store,不碰 URL(§12 第 4 条:公司上下文不进 URL);各页组件加一行监听重取:
```ts
// 每页 setup 末尾,紧跟该页已有的 loadXxx 定义:
import { useCompanyTabStore } from '@/stores/company-tab'
const companyTab = useCompanyTabStore()
// 切公司 = 重新取数。不重取的页 = tab 在那页上是假的(G1 的 pageFiles 断言盯着这条)。
watch(() => companyTab.activeId, () => void load())
```
`watch` 从 `vue` import(多数页已有 `computed/watch` 的 import 行,补 `watch` 即可)。`load` 换成该页实际的取数函数名。
G1 的正向断言会把"漏了这一行的页"直接抓出来,所以这里**不许**用 `router.replace({query:{_c:id}})` 之类的"借路由重挂载"变通——那等于把公司上下文写进 URL,违反 §12 第 4 条,且刷新后仍会丢。
- [ ] **Step 6: G1 双向对账用例**
Create `tests/company-tab-wiring.test.ts`:
```ts
import test from 'node:test'
import assert from 'node:assert/strict'
import { existsSync, readFileSync, readdirSync } from 'node:fs'
import { adminPages } from '../src/router/routes.ts'
import { COMPANY_SCOPED_PAGES, SUPER_ADMIN_ONLY_MENU_KEYS } from '../src/config/company-scope.ts'
const read = (p: string) => {
assert.ok(existsSync(p), `护栏读不到 ${p}:api 文件改名了,清单必须同步(别把用例改成"不存在就跳过")`)
return readFileSync(p, 'utf8')
}
test('正向:声明 companyScoped 的页,其 api 文件必须真的带 company_id,页面组件必须 watch activeId', () => {
for (const page of COMPANY_SCOPED_PAGES) {
assert.ok(adminPages.some((p) => p.menuKey === page.menuKey && p.companyScoped),
`${page.menuKey} 在清单里但注册表没声明 companyScoped`)
for (const file of page.apiFiles) {
assert.match(read(file), /company_id|companyId/, `${file} 声明参与公司 tab 却没下传 company_id`)
}
for (const file of page.pageFiles) {
assert.match(read(file), /watch\(\(\)\s*=>\s*companyTab\.activeId/,
`${file} 没监听公司 tab:切 tab 不重取数 = 这页的 tab 是装饰品`)
}
}
})
test('反向:把 company_id 当查询参数用的取数模块必须被清单认领(防止"筛了但没人知道这页参与")', () => {
const claimed = new Set(COMPANY_SCOPED_PAGES.flatMap((p) => p.apiFiles))
const scanned = requestModules()
// 取样自检:扫描本身失效(目录改名/递归参数写错)时下面这支会"零文件 ⇒ 恒绿"。
assert.ok(scanned.length >= 35, `只扫到 ${scanned.length} 个取数模块,requestModules 八成是坏了`)
for (const file of scanned) {
if (claimed.has(file)) continue
const text = stripComments(readFileSync(file, 'utf8'))
assert.equal(/['"]company_id['"]|\bcompany_id\s*[:=]/.test(text), false,
`${file} 自己塞了 company_id 参数但没进 COMPANY_SCOPED_PAGES——它绕过了唯一清单`)
}
})
test('两张清单不许重叠:超管专属页不可能同时是按公司看数据的页', () => {
const scoped = new Set(COMPANY_SCOPED_PAGES.map((p) => p.menuKey))
for (const key of SUPER_ADMIN_ONLY_MENU_KEYS) assert.equal(scoped.has(key), false)
})
/** 分母 = **会把 company_id 发出去的模块**:`src/api` 下的 .ts 与 `src/pages` 下名字以 `-api.ts` 结尾的模块,实测 40 个。
* 不是"所有 .ts"(135 个):查询对象的**类型**声明住在 `history-dto.ts`、`image-video-filter.ts`、`shop-dto.ts`
* 这些兄弟模块里(Task 8/10/11 要给它们加 `company_id?: number`),类型行本身长得像"用了 company_id",
* 拿全量 .ts 当分母会让反向用例红在一行类型声明上,而那一行本来就该存在。 */
function requestModules(): string[] {
return ['src/api', 'src/pages'].flatMap(listTs)
.filter((f) => f.startsWith('src/api/') || f.endsWith('-api.ts'))
}
function listTs(dir: string): string[] {
// Node 24 的 readdirSync 支持 recursive + withFileTypes;parentPath 是新字段,path 是旧字段,两个都要兜。
// Windows 上递归结果的 parentPath 带反斜杠(`src\pages\shop\shop-manage-api.ts`),不转正斜杠就永远匹配不上 claimed。
return readdirSync(dir, { withFileTypes: true, recursive: true })
.filter((e) => e.isFile() && e.name.endsWith('.ts'))
.map((e) => `${(e as { parentPath?: string }).parentPath ?? e.path}/${e.name}`.split(/[\\/]+/).join('/'))
}
/** 去掉注释再匹配:**这是这支用例能不能用的关键**。
* 全仓目前只有一处 `company_id` 字面量——`src/pages/account/user-create-model.ts:68` 的注释
* 「故意不带 company_id:归属由后端 resolveTargetCompanyId 落操作者自己的公司」。
* 不剥注释,反向用例会在一条**说明为什么不传参**的注释上红,然后下一个人把它改成 `if (!/^\s*\*/.test(line))`
* 之类的临时豁免,整支用例就废了。剥注释的写法要连 `//` 行注释一起剥,但**不许**顺手放宽成"整文件不匹配"。 */
function stripComments(source: string): string {
return source
.replace(/\/\*[\s\S]*?\*\//g, '')
.split(/\r?\n/)
.filter((line) => !line.trimStart().startsWith('//'))
.join('\n')
}
```
> 反向用例的**排除名单不写死文件**(草稿里我列过 `src/api/companies.ts`、`src/api/users.ts` 要豁免——实测两处都**不含** `company_id` 字面量,豁免纯属我给编的,已删)。要防的只有注释误匹配,靠 `stripComments`。
>
> 匹配式 `\bcompany_id\s*[:=]` 与引号键名两形,是为了**只认"当成了参数"**:Task 8-12 落的写法是 `q.company_id = params.companyId`(等号形)和 `params: { company_id: ... }`(冒号形),两支都盖到;而"随便提一句 company_id"不该算接线。
- [ ] **Step 7: §9.3 的承载——把"行数会随 tab 变"写进既有引导文案(只加文案,不加控件)**
spec §9.3 定死了这件事的承载方式:**不新做页头控件/提示条**(§12 第 5 条那只未批的暴露),改在 `src/layout/operation-guides.ts` 的既有引导条目里说明。不做这一步的代价不是报错,而是超管第一次切 tab 时把行数变化**报成"数据丢了"**(Task 13 Step 3 的人工清单会当场撞上它)。
`OperationGuide.vue:13` 的折叠态是 `localStorage.getItem(KEY) === '1'`——**第一次进后台是展开的**,所以这段文案真会被看到;但也因为它是 per-浏览器持久化,一个早就把提示条收起的管理员看不见这句话。这条缓解是**部分强度**,别在运维手册里写成"界面已明确告知"。
⚠️ 这个文件有 `tests/align-operation-guide.test.ts` 钉着,三支钉法各不相同,**只有两支需要动**:
- `align_guide_users_matches_reference_text` 用 `assert.equal` 逐字比 `admin_users` 的 text ⇒ **不许改 `admin_users` 那条**。用户管理本来也不在这 7 页里(一期已经按公司筛过,tab 不改变它的观感),改它是自找红。
- `align_guide_history_and_version_reference_text` 用的是 `assert.match(..., /生成记录可按用户和时间范围回溯/)` ⇒ `admin_history` 在原句**之后**追加不会红(前缀还在)。
- `align_guide_group_manage_falls_back` 用 `deepEqual` 比整个对象 ⇒ 见下面第 2 条,这一支要改。
1. 下面 7 条 text 各追加同一句(**追加在原文之后,不改原句**;`admin_shop_manage` 那句 §6.3 归属口径另加):
`admin_image_video_tasks`、`admin_history`、`admin_task_center`、`admin_user_secrets`、`admin_user_secret_usage`、`admin_device_logs`、`admin_shop_manage`。
```ts
// 追加到各条 text 末尾(原句一个字都不动):
' 超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了。'
// admin_shop_manage 再追加第二句(§6.3:这条与直觉相反,不写在界面上就会被报成 bug):
' 店铺归哪家公司由「负责人」决定,不由公司 tab 决定:负责人选自己,店铺就落在你自己那家。'
```
⚠️ **这句必须以"超级管理员"开头,不能写成"当前公司由 tab 决定"**:引导文案按 `menuKey` 取,**不分支角色**,而非超管根本看不到 tab 条(`visibleForOperator` 里有 `isSuperAdmin`)。写成祈使式的"当前公司由页面上方的 tab 决定",15 个管理员里非超管那批会读到一句指不到任何控件的话——那比不写更容易被报成 bug。
2. `admin_group_manage`(数据权限分组,第 8 页)**今天没有独立条目**,它 `deepEqual` 到 `OPERATION_GUIDE_FALLBACK`(`operation-guides.ts:27`)。给 fallback 加这句会把"公司 tab"端给**所有没有独立文案的页**(含 C 类那三页没进 tab 的),所以只能给它自己一条——这就是**故意偏离**旧版 `admin-interactions.js` 的 guides 表(文件头注释和 `:12` 的测试注释都写着"沿用旧版原文"),要在测试注释里明写这次偏离,别让它读起来像手滑:
```ts
admin_group_manage: {
text: '数据权限分组决定"哪些账号能看到哪些店铺",分组按负责人和归属账号聚拢。超级管理员切换上方公司 tab 后,列表只保留当前公司账号相关的分组。'
+ ' 超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了。',
steps: ['选择分组', '维护负责人与归属账号', '核对店铺可见范围'],
},
```
⚠️ 这句里**不许**写"跨公司的分组彼此看不见"——那是 Task 11 Step 3 明确没做的半边:非超管的分组可见范围仍由 `listAccessibleGroupIds` 那套负责人/归属账号口径决定,本轮**一行都没动**(附B 记了这条"部分强度")。文案只描述超管 tab 的效果,不给非超管承诺他们没拿到的收窄。
```ts
// tests/align-operation-guide.test.ts:28-31 整支替换:
test('align_guide_group_manage_own_text', () => {
// 2026-10-04 公司 tab(spec §9.3):这页从"沿用旧版通用 fallback"改成自带文案——
// 上一行"对齐旧版 guides 表原文"的约定在这一页是**故意破的**,因为那句 tab 说明
// 不能塞进 fallback(fallback 会被没进 tab 的页共用,等于把 tab 端给它们)。
const g = operationGuideFor('admin_group_manage')
assert.ok(g)
assert.notEqual(g, OPERATION_GUIDE_FALLBACK)
assert.match(g.text, /超级管理员可用页面上方的公司 tab 切换公司/)
assert.deepEqual(g.steps, ['选择分组', '维护负责人与归属账号', '核对店铺可见范围'])
})
```
3. 本步覆盖的正好是注册表里那 8 页(上面 7 条 + `admin_group_manage`),一页不多一页不少。**`admin_users` 不在这 8 页里**——它一期就已按公司筛,§9.3 说的"第一次切过去会被报成数据丢了"指的是这次新窄下来的页,不要顺手也给它加(它的 text 还被 `assert.equal` 逐字钉着,改了必红)。
4. **把这件事做进代码出口,不留在注释里**(Constraint 15 的口径):往 `tests/align-operation-guide.test.ts` 追加一支,分母直接取注册表,别自己抄一份名单——将来往 `COMPANY_SCOPED_PAGES` 加第 9 页,这支会立刻红到那页的文案补上为止。
```ts
test('guide_copy_carries_company_tab_note_for_every_scoped_page', () => {
// spec §9.3:tab 会改行数观感,承载方式是既有引导文案(不新做控件)。
// 分母=COMPANY_SCOPED_PAGES,杜绝"加了一页忘了补文案"。
const need = COMPANY_SCOPED_PAGES.map((p) => p.menuKey)
assert.ok(need.length >= 8, '取样集非空自检:注册表应当至少有 8 页进了 tab 范围')
for (const key of need) {
const g = operationGuideFor(key)
assert.ok(g, `注册表页缺 guide: ${key}`)
assert.match(g.text, /超级管理员可用页面上方的公司 tab 切换公司/, `${key} 缺 §9.3 那句`)
}
// C 类两页(spec §5):它们要的是**另一句**——"这页不参与",不是"会随 tab 变"。
// 分母**取注册表里显式写 companyScoped:false 的页**,不抄名单:漏写一条 ⇒ 这支在自检那句红。
const scoped = new Set(COMPANY_SCOPED_PAGES.map((p) => p.menuKey))
const cClass = adminPages.filter((p) => p.companyScoped === false).map((p) => p.menuKey)
assert.ok(cClass.length >= 2, '取样集非空自检:注册表里显式 companyScoped:false 的至少 C 类那两页')
for (const key of cClass) {
assert.equal(scoped.has(key), false, `${key} 既声明 false 又在清单里,两处口径打架`)
const g = operationGuideFor(key)
assert.ok(g, `不参与 tab 的页缺 guide: ${key}`)
assert.match(g.text, /全平台共享,不按公司区分/, `${key} 缺 §5 那句`)
assert.equal(g.text.includes('公司 tab 切换公司'), false, `${key} 不该带 tab 那句(它不参与)`)
}
// 反向钉:这句话只能由文案承载。tab 组件里再长出"当前公司:X"就是第二处表达(§12 第 5 条未批)。
const tabs = readSource('src/layout/CompanyTabs.vue')
assert.ok(tabs.length > 0, '取样集非空自检:CompanyTabs.vue 读到了')
assert.equal(tabs.includes('company-tab-hint'), false, '不许有页头"当前公司"提示条')
assert.equal(tabs.includes('当前公司'), false, '同上:当前公司只由 is-active 的 tab 表达')
})
```
补 import:`import { COMPANY_SCOPED_PAGES } from '../src/config/company-scope.ts'`(`readSource`、`operationGuideFor`、`adminPages` 该文件已 import)。
5. **C 类两页的那句也要在这一支里落**(`admin_shop_keys` 店铺密钥管理、`admin_product_categories` 商品类目):
```ts
// 追加到这两条 text 末尾:
' 本页全平台共享,不按公司区分:超级管理员切换上方公司 tab 时它不会变,这不是筛选坏了。'
```
⚠️ 这里**偏离了 spec §5 选的承载**(它写的是"页头常驻一条说明")。改走引导文案有两个理由:①"常驻一条说明"本身就是 §12 第 5 条禁止的新提示条;②引导条这一支已经有分母取自注册表的用例(上面第 4 条),换承载就多一个没人管的控件。这条偏离已写回 spec §5,执行时不必再来问一次。
不做这两句的代价:tab 条是挂在 `AdminLayout` 上的全局件,批次 1 一上线,超管在这两页切 tab 会看到"数据纹丝不动"——而 §5 说得很清楚,那种观感要么是"假装有隔离",要么是"隔离坏了"。
- [ ] **Step 8: 全量 + 提交(前端半边,批次 1 的最后一步)**
```bash
node --test tests/company-tab-model.test.ts tests/company-tab-wiring.test.ts \
tests/align-operation-guide.test.ts
npx vue-tsc --noEmit && npm test 2>&1 | tail -5
git add src/stores/company-tab.ts src/layout/CompanyTabs.vue src/layout/company-tab-model.ts \
src/layout/AdminLayout.vue src/layout/operation-guides.ts \
tests/company-tab-model.test.ts tests/company-tab-wiring.test.ts \
tests/align-operation-guide.test.ts src/config/company-scope.ts
git commit -m "feat(前端): 公司 tab(store+组件+G1 双向对账) + §9.3 引导文案承载"
```
> G1 的正向断言在 Task 8-12 之前会**红**(那 8 个 api 文件还没带 `company_id`)。这是刻意的:**把 Task 8-12 做完之前不许单独提交 Task 7 的这支配测**,否则 `npm test` 有一次红。落地做法:Task 7 先提交代码、把 `company-tab-wiring.test.ts` 留到 Task 12 一起提交,或在 Task 7 提交信息里写明"下一条提交补齐接线"。
>
> ⚠️ 这一步的红**有且只有** `company-tab-wiring.test.ts` 正向那半(`align-operation-guide.test.ts` 的两支、`company-tab-model.test.ts` 都必须已经绿)。出现别的红就是回归,别用"反正接线还没做"解释过去——Task 0 记的分母(前端 1687 例 0 红)在这里的作用是让你能说出"红了几条、分别是哪一支",而不是"有一片红"。
---
## Task 8: 接线 —— 视频任务记录 + 生成记录(形态相同:service 里一个 `userId` 参数)
**Files:**
- Modify: `backend-java/.../modules/imagevideo/controller/AdminImageVideoTaskController.java:67-91`(`page`)、`:93-98`(`detail`)、`:100-…`(`download-zip`)
- Modify: `backend-java/.../modules/imagevideo/service/ImageVideoAdminTaskService.java:74-91`(`page`)
- Modify: `backend-java/.../modules/imagevideo/mapper/ImageVideoAdminTaskMapper.java:37`(page 的 `<if userId>`)、`:64`(count 的同一条)、`:47-58`(`selectAdminTaskPage` 参数表)、`:72-…`(`countAdminTaskPage` 参数表)、`:80-92`(`selectAdminZipRows` 补 `t.user_id`,Step 4 的 download-zip 闸门靠它)
- Modify: `backend-java/.../modules/imagevideo/service/ImageVideoAdminTaskService.java:97-103`(`detail`)、`:108-…`(`buildZip`,`VideoSelection` 在同文件 `:447`)
- Modify: `backend-java/.../modules/imagehistory/controller/ImageHistoryController.java:32-48`(`listHistory`)
- Modify: `admin-frontend-vue/src/pages/tasks/image-video-api.ts`、`src/pages/records/history-api.ts`、`src/pages/tasks/ImageVideoTasksPage.vue`、`src/pages/records/RecordsHistoryPage.vue`
- Test: 上述两个 service 的既有测试类里追加
**Interfaces:**
- Consumes: `DataReadScope.readScope(operator, companyId)` → `ReadScope.userIdsOr(base)`
- Produces: 两个新查询参数 `company_id`(GET query)
> **两个已确认的现状(2026-10-04 16:2x 逐行读过,不是推测)**:
> 1. `AdminImageVideoTaskController.java:78` 现在是 `adminAuthSupport.requireAdminOrInternal(request);` **返回值被丢掉**——本任务必须改成 `AdminUserEntity operator = adminAuthSupport.requireAdminOrInternal(request);`,否则拿不到角色与 `companyId`。
> 2. `ImageVideoAdminTaskService.page(...)`(`:74-76`)**没有 operator 参数**,签名是 `page(Long userId, String username, String status, String executeId, LocalDateTime submittedFrom, LocalDateTime submittedTo, int page, int pageSize)`。⇒ 范围在 **controller** 里算、把 `List<Long> userIds` 传进 service,不改 service 的鉴权依赖(比给 service 塞 operator 少一层耦合,也让 `requireAdminOrInternal` 的 internal 分支不会走进 `readScope` 的非超管分支)。
> 3. `requireAdminOrInternal` 在 JWT 失败时用 `X-Internal-Token + operatorId` 回退(`AdminAuthSupport.java:122-133`)。internal 调用**不传 `company_id`** ⇒ `readScope` 走"超管不筛"或"按那个 operatorId 的公司裁剪",两条都不会把客户端的取数弄窄;但如果该回退账号没有 `company_id`,非超管分支会抛 403(Task 6 的 `adminWithoutCompanyFailsFast` 钉的就是这条)——**Step 5 的验收必须真跑一次 internal 通道**,不能只跑浏览器。
- [ ] **Step 1: 写失败的测试(后端,两条组合即可,别铺开)**
`ImageVideoAdminTaskServiceTest`(无则新建):
```java
@Test
@DisplayName("超管选了公司:userId 的单值过滤之外必须多出成员集合")
void companyMembersGoToBothPageAndCountQueries() {
when(mapper.selectAdminTaskPage(any(), any(), any(), any(), any(), any(), any(), anyInt(), anyInt()))
.thenReturn(List.of());
when(mapper.countAdminTaskPage(any(), any(), any(), any(), any(), any())).thenReturn(0L);
service.page(null, null, null, null, null, null, 1, 20, List.of(11L, 12L));
// 关键:行集与总数必须拿到同一个范围。只换 page 不换 count ⇒ "总数对不上但没人报错"。
ArgumentCaptor<List<Long>> rowsCap = ArgumentCaptor.forClass(List.class);
ArgumentCaptor<List<Long>> cntCap = ArgumentCaptor.forClass(List.class);
verify(mapper).selectAdminTaskPage(any(), any(), any(), any(), any(), any(), any(), rowsCap.capture(), anyInt());
verify(mapper).countAdminTaskPage(any(), any(), any(), any(), any(), any(), cntCap.capture());
assertThat(rowsCap.getValue()).containsExactlyInAnyOrder(11L, 12L);
assertThat(cntCap.getValue()).containsExactlyInAnyOrder(11L, 12L);
}
@Test
@DisplayName("不筛时传 null,不是空集——空集在 mapper 那里会渲染出 IN () 语法错")
void unfilteredPassesNullNotEmptyList() {
when(mapper.selectAdminTaskPage(any(), any(), any(), any(), any(), any(), any(), any(), anyInt()))
.thenReturn(List.of());
service.page(null, null, null, null, null, null, 1, 20, null);
verify(mapper).selectAdminTaskPage(any(), any(), any(), any(), any(), any(), any(), isNull(), anyInt());
}
```
> 上面参数个数**已按 `ImageVideoAdminTaskMapper.java:47-58` 与 `:72-…` 实际签名写定**(page 侧 8 个业务参数 + 新加的 `userIds`,count 侧 6 个 + `userIds`)。实现时以文件为准逐位对齐:`selectAdminTaskPage(userId, username, status, executeId, submittedFrom, submittedTo, limit, offset)`。凭手感写的 `any()` 数量会让用例编译失败,浪费一轮。
- [ ] **Step 2: 跑,确认红**
Run: `mvn -q test -Dtest='ImageVideoAdminTaskServiceTest,ImageHistory*Test'`
Expected: FAIL(新方法/新参数不存在)。
- [ ] **Step 3: mapper 支持成员集合**
`ImageVideoAdminTaskMapper.java` 里 `:37` 与 `:64` 两处**逐字相同**的片段都改成(两支一起改,方法参数在 `:48` 的 `@Param("userId")` 之后加 `@Param("userIds") List<Long> userIds`,count 侧同理):
```java
"<if test=\"userId != null\"> AND t.user_id = #{userId}</if>"
+ "<if test=\"userIds != null\"> AND t.user_id IN"
+ " <foreach collection='userIds' item='uid' open='(' separator=',' close=')'>#{uid}</foreach></if>",
```
`userId` 那条**保留**(它是页面上"按单个账号筛"的既有能力),两条是 AND 关系 = 交集,语义正确。
⚠️ 空集**不许进 mapper**:`userIds=[]` 会渲染成 `IN ()`,MySQL 语法错 → 500。短路放在 Step 4。
- [ ] **Step 4: service 早退 + controller 算范围**
`ImageVideoAdminTaskService.page(...)` 签名末尾加 `List<Long> userIds`,第一行:
```java
if (userIds != null && userIds.isEmpty()) {
// 空集 = 这个公司今天没有任何成员账号 ⇒ 空页。绝不退化成"不筛"(那是越权)。
Map<String, Object> empty = new LinkedHashMap<>();
empty.put("items", List.of());
empty.put("total", 0L);
empty.put("page", (long) page);
empty.put("page_size", (long) pageSize);
return empty;
}
```
并把 `userIds` 透传给 `selectAdminTaskPage` 与 `countAdminTaskPage` 两支。
`AdminImageVideoTaskController.page(...)`:参数表末尾加
`@RequestParam(name = "company_id", required = false) Long companyId`,并按上面「已确认现状 1」接住 operator:
```java
AdminUserEntity operator = adminAuthSupport.requireAdminOrInternal(request);
// 既有语义保留:显式传 user_id 时按那一个人筛;公司 tab 叠在它上面(交集)。
List<Long> base = userId != null && userId > 0 ? List.of(userId) : null;
List<Long> scoped = dataReadScope.readScope(operator, companyId).userIdsOr(base);
```
`detail`(`:93-98`)与 `download-zip`(`:100-115`)按 §6.1 用**同一把 ReadScope** 门住,判据是行的 `user_id` 落不落得进列表那条同样的 `read.userIdsOr(base)`(不是"列表筛了、按 id 照读",那正是越权而不是收窄):
- `detail`:`selectAdminTaskDetail` 的 SELECT **已经带 `t.user_id`**(`mapper:95`),取行后直接判,不在集合里抛 `new BusinessException(403, "该任务不属于当前公司")`。**越权必须是 403,不许复用现有那句 404**(`service:100`「视频任务不存在或无权访问」把两件事混在一句里,404 只留给"真查不到行")。
- `download-zip`:`selectAdminZipRows`(`mapper:80-92`)现在只 `SELECT t.id, t.video_urls_json, t.archived_videos_json`——**没有 `user_id`**,所以这条闸门必须先给那条 SQL 补上 `t.user_id`,`buildZip` 才拿得到行主人(这是本任务唯一一处 SQL 列改动,不是可选优化)。判法与 detail 同:**一次请求里任一条 selection 越界就整单 403**,不许静默跳过——`X-Archive-Error-Count`(`controller:105-114`)那套"部分失败"语义是给上游拉不到文件用的,拿它掩盖越权等于把越权报成网络问题(memory「权限范围限制要连读接口一起收窄」)。
- [ ] **Step 5: 前端带参 + 重取**
两页的取数都不在 api 模块里就地拼 query,而是调 builder:`fetchImageVideoTasks`(`image-video-api.ts:11-21`)用 `toImageVideoQuery(filter, page, pageSize)`,`fetchHistoryList`(`history-api.ts:9-14`)用 `toHistoryListQuery(normalizeHistoryParams(params))`。**统一落在"builder 出来之后、发请求之前"这一处**,别再往 filter/params 里塞:
`src/pages/tasks/image-video-api.ts`:`fetchImageVideoTasks` 参数表末尾加 `companyId?: number | null`,函数体改成
```ts
const query = toImageVideoQuery(filter, page, pageSize)
if (companyId != null) query.company_id = companyId
const { data } = await http.get<unknown>(IMAGE_VIDEO_TASKS_ENDPOINT, { params: query })
```
`src/pages/records/history-api.ts`:
```ts
const normalized = normalizeHistoryParams(params)
const query = toHistoryListQuery(normalized)
if (params.companyId != null) query.company_id = params.companyId
const { data } = await http.get<unknown>(HISTORY_ENDPOINT, { params: query })
```
两支类型各加一个可选键:`ImageVideoQuery`(`image-video-filter.ts:21-30`)与 `HistoryListQuery`(`history-dto.ts:38-44`)各加 `company_id?: number`。
> **为什么不改 `HistoryListParams` 那条路**:`normalizeHistoryParams`(`history-dto.ts:61-76`)是**白名单**构造返回值(`page/pageSize/userId/timeStart/timeEnd` 逐条点名),把 `companyId` 加进 `HistoryListParams` 类型会被它原样丢掉——类型检查绿、请求里没有这个参数、页面永远看全量。这正是 §9 记的那类"静默失效",所以本批次一律落在 builder 之后(Task 10/11 同)。
>
> `companyId` 由页面组件传入(**不用 `useCompanyTabStore()` 裸调**:这两个 api 模块在 `node --test` 里被直接 import,Pinia 未激活会抛 "no active pinia";Task 9/10/12 一律沿用"页面传值"这一种,全批次不许一半 store 一半入参)。页面组件加 Task 7 Step 5 那条 `watch`,并在取数调用里传 `companyId: companyTab.requestCompanyId`。`fetchImageVideoTasks` 多了一个参数 ⇒ 调用点 `ImageVideoTasksPage.vue` 必须跟着改,漏改是 `vue-tsc` 报错而不是静默。
- [ ] **Step 6: 跑两支全量 + 提交**
```bash
mvn -q test 2>&1 | tail -10
node --test tests/company-tab-wiring.test.ts # 这两页的正向断言应转绿
npx vue-tsc --noEmit
git add backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo backend-java/src/main/java/com/nanri/aiimage/modules/imagehistory backend-java/src/test/java/com/nanri/aiimage/modules/imagevideo admin-frontend-vue/src/pages/records
git commit -m "feat(公司tab): 视频任务记录与生成记录按公司筛(成员集合替换单 userId)"
```
---
## Task 9: 接线 —— 密钥管理 + 密钥用量统计(已有 `group_id`「仅超管生效」,公司叠在它上面)
**Files:**
- Modify: `backend-java/.../modules/usersecret/controller/AdminUserApiSecretController.java:49-64`
- Modify: `backend-java/.../modules/usersecret/controller/AdminUserSecretUsageController.java:38-47`
- Modify: `backend-java/.../modules/usersecret/model/dto/AdminUserSecretQuery.java`(加 `companyId`)
- Modify: `backend-java/.../modules/usersecret/service/UserApiSecretService.java:317-345`(`adminPage`)
- Modify: `backend-java/.../modules/usersecret/service/UserSecretUsageService.java:99-123`(`superAdmin` 判定在 `:99`,`scopedUserIds` 三段分支在 `:101-107`,早退在 `:108` 与 `:122`——与 `UserApiSecretService.adminPage` 同形)
- Modify: `admin-frontend-vue/src/api/user-secrets.ts`、`src/api/user-secret-usage.ts`、`src/pages/account/UserSecretsPage.vue`、`UserSecretUsagePage.vue`
- Test: `UserApiSecretServiceTest`(追加)
**Interfaces:**
- Consumes: `DataReadScope`(Task 6)
- Produces: 两个 `company_id` query 参数;`scopedUserIds` 的三层语义(组长锁定 ∩ 超管 group_id ∩ 公司)
- [ ] **Step 1: 写失败的测试**
```java
@Test
@DisplayName("超管 group_id + company_id 同时给:取交集,不是后一个覆盖前一个")
void groupAndCompanyIntersect() {
when(adminAuthSupport.currentRole(operator)).thenReturn("super_admin");
when(dataReadScope.readScope(operator, 2L)).thenReturn(ReadScope.users(List.of(11L, 12L, 13L)));
when(adminGroupMapper.selectUserIdsByGroupId(7L)).thenReturn(List.of(12L, 13L, 99L));
List<Long> scoped = service.scopedUserIds(operator, 7L, 2L);
assertThat(scoped).containsExactlyInAnyOrder(12L, 13L);
}
@Test
@DisplayName("公司选了但交集为空:返回空页,不许退化成「不筛」(那是越权)")
void emptyIntersectionReturnsEmptyPage() {
when(adminAuthSupport.currentRole(operator)).thenReturn("super_admin");
when(dataReadScope.readScope(operator, 2L)).thenReturn(ReadScope.users(List.of(11L)));
when(adminGroupMapper.selectUserIdsByGroupId(7L)).thenReturn(List.of(99L));
assertThat(service.scopedUserIds(operator, 7L, 2L)).isEmpty();
}
```
> `scopedUserIds` 是把 `adminPage` 里那段范围计算抽成的 **package-private** 方法(`List<Long> scopedUserIds(AdminUserEntity, Long groupId, Long companyId)`);测试类与被测类同包,直接调它,不要再造一个 `...ForTest` 的别名(别名会随重构腐烂)。**必须抽**:不抽就只能靠 mock 整条 mapper 链测这段逻辑,那段最关键的交集代码反而没被测到。
- [ ] **Step 2: 跑,确认红** → `mvn -q test -Dtest=UserApiSecretServiceTest`,Expected: FAIL(方法不存在)。
- [ ] **Step 3: 抽范围方法并叠公司**
`UserApiSecretService.java:317-341` 的那段改成:
```java
/** 可见用户集:null = 不筛(超管没选公司也没选分组,今天的行为)。 */
List<Long> scopedUserIds(AdminUserEntity operator, Long requestedGroupId, Long companyId) {
boolean superAdmin = "super_admin".equals(adminAuthSupport.currentRole(operator));
List<Long> base = null;
if (superAdmin) {
if (requestedGroupId != null && requestedGroupId > 0) {
base = adminGroupMapper.selectUserIdsByGroupId(requestedGroupId);
}
} else {
base = userDataScopeSupport.resolveVisibleUserIds(operator.getId());
}
return dataReadScope.readScope(operator, companyId).userIdsOr(base);
}
```
`adminPage` 里把原 4 行分支替换成 `List<Long> scopedUserIds = scopedUserIds(operator, safeQuery.getGroupId(), safeQuery.getCompanyId());`,**保留它下面 `isEmpty() → emptyPageWithGroups(...)` 那条早退**(非超管历史上就靠它返回空页带分组下拉)。
- [ ] **Step 4: DTO / controller / usage service**
`AdminUserSecretQuery` 加 `private Long companyId;`;两个 controller 各加
`@RequestParam(name = "company_id", required = false) Long companyId` 并 `query.setCompanyId(companyId)`。
`UserSecretUsageService:99-123` 那段照 Step 3 同样抽成 package-private `scopedUserIds(operator, requestedGroupId, companyId)`。**注意它与 `adminPage` 的一处不同**:`UserApiSecretService` 空集走 `emptyPageWithGroups(...)`,这里空集走 `:108`/`:122` 的早退并 `log.info` 一条"无匹配用户"——抽方法时把这两条早退**留在原处**,别一起搬进新方法,否则用量页会从"空列表 + 一行日志"变成"空列表 + 无日志",排障时看不出是筛空还是查空。
- [ ] **Step 5: 前端带参**
照 **Task 8 Step 5 定下的那一种**(值由页面组件传入、api 模块里**不**碰 Pinia store)。两支文件形状一样,各改两处:
`src/api/user-secrets.ts` 的 `UserSecretQuery`(`:54`)与 `src/api/user-secret-usage.ts` 的 `UserSecretUsageQuery`(`:28`)各加一个可选字段:
```ts
/** 公司 tab 的当前口径;不传 = 后端按操作者自己的公司(批次 1 里非超管只有这一家)。 */
companyId?: number | null
```
`fetchUserSecretList`(`:65-69`)与 `fetchUserSecretUsage`(`:40-45`)的 `query` 构造块里,紧跟既有的 `if (params.groupId) query.group_id = params.groupId` 各加一行:
```ts
if (params.companyId != null) query.company_id = params.companyId
```
> 用 `!= null` 而不是旁边那几行的 truthy 写法:既有那几行筛的是字符串/`groupId`,`0` 对它们是"没筛";`company_id` 传 0 后端 `requireCompanyId` 会抛(`CompanyScopeSupport:37`),宁可让它在参数缺失时不出现,也别把 `0` 悄悄当没传。
两个调用页(`UserSecretsPage.vue`、`UserSecretUsagePage.vue`)在取数调用里传 `companyId: companyTab.requestCompanyId`,并加 Task 7 Step 5 那条 `watch`。
> 全批次 8 个页一律"页面传值",不许有第二形态:api 模块被 `node --test` 直接 import 时 Pinia 未激活会抛 `no active pinia`,一半 store 一半入参还会让 G1 的 `pageFiles` 断言只能盯住其中一半。
- [ ] **Step 6: 跑 + 提交**
```bash
mvn -q test 2>&1 | tail -10
node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit
git add backend-java/src/main/java/com/nanri/aiimage/modules/usersecret admin-frontend-vue/src/api/user-secret*.ts admin-frontend-vue/src/pages/account/UserSecret*.vue backend-java/src/test/java/com/nanri/aiimage/modules/usersecret
git commit -m "feat(公司tab): 密钥管理与用量统计按公司筛(分组∩公司,空集不退化)"
```
---
## Task 10: 接线 —— 客户端任务管理(**一处** `resolve` 收窄,五个端点自动同宽)
**Files:**
- Modify: `backend-java/.../modules/taskcenter/service/TaskCenterScopeService.java:27-40`(`resolve`)、`:42-47`(`addAll` 保持不动)、`:70-87`(`ScopeContext` 与 `sqlUserIds()`——**只读确认那个 `[-1]` 兜底,不许改**)
- Modify: `backend-java/.../modules/taskcenter/controller/AdminTaskCenterController.java`:`resolveScope`(`:100-104`)加一个入参,五个端点各加一个可选 `company_id`(`overview :46`、`shop-options :54`、`tasks :62`、`tasks/detail :72`、`variant-tasks :86`)
- **不动**: `TaskCenterQueryMapper.java:92-96` 的 `USER_SCOPE_T`/`USER_SCOPE_B`/`USER_SCOPE_S` 片段——理由见 Step 3 的更正,判空早已被 `sqlUserIds()` 兜住
- Modify: `admin-frontend-vue/src/api/task-center.ts:82,88,94,101,109`(**五支**,含按 `taskNo` 的 detail)、`src/pages/task-center/task-center-model.ts:200,218`(`buildTaskQuery`/`buildVariantQuery`)、`src/pages/task-center/TaskCenterBoardPage.vue:98,107,116,130` 及详情调用点
- Test: `TaskCenterScopeServiceTest`(追加)
**Interfaces:**
- Consumes: `DataReadScope.readScope(AdminUserEntity, Long)` → `ReadScope.isUnfiltered()` / `ReadScope.userIdsOr(List<Long>)`(Task 6 定义,两侧都有值时**求交**)
- Produces: `ScopeContext TaskCenterScopeService.resolve(Long operatorId, Long companyId)`;既有 `resolve(Long)` 保留成 `resolve(operatorId, null)` 的委托(改之前先 `grep -rn "\.resolve(" src/main --include=*.java` 数清还有几个调用点,别把别模块的调用打断)
> **这页的接合点和别的页不一样,而且是好消息**:五个端点全部只调 `resolveScope(request)` 一次(`controller:50,58,68,78,96`),集合的消费只有两种形状——`scope.sqlUserIds()` 进 SQL(`TaskCenterQueryService:59,72,154`、`TaskCenterVariantService:52`),以及 `scope.visible(userId)` 做行级判断(`TaskCenterQueryService:180`,`tasks/detail` 就是靠它)。所以 **`resolve` 一处收窄,五个出口天然同宽**,§6.1 那条"列表筛了但按 id 能读"在这一页本来就不存在,不需要像 Task 8 那样单独补 detail 闸门。反过来讲:**这一页的护栏就落在前端**——`fetchTaskCenterTaskDetail` 少带 `company_id`,超管在「第 2 家」tab 下按 `taskNo` 打开别家任务的详情就还是放行(`allUsers=true` ⇒ `scope.visible()` 恒真),而接口照样返回 200,谁都不会发现。Step 5 因此把 detail 也算进"五个都带"。
- [ ] **Step 1: 写失败的测试**
```java
@Test
@DisplayName("超管选了公司:allUsers 必须翻成 false,否则集合根本不进 SQL,tab 是装饰品")
void superAdminWithCompanyStopsBeingUnfiltered() {
AdminUserEntity operator = user(1L, "super_admin");
when(adminUserMapper.selectById(1L)).thenReturn(operator); // 夹具同现有 :46 的写法
when(dataReadScope.readScope(operator, 2L)).thenReturn(ReadScope.users(List.of(11L, 12L)));
TaskCenterScopeService.ScopeContext scope = service.resolve(1L, 2L);
assertFalse(scope.allUsers(), "选了公司还 allUsers=true ⇒ sqlUserIds() 交 null ⇒ SQL 整段条件不渲染");
assertThat(scope.sqlUserIds()).containsExactlyInAnyOrder(11L, 12L);
assertTrue(scope.visible(11L));
assertFalse(scope.visible(13L), "别家账号连 tasks/detail 也进不去(详情走 scope.visible,不走 SQL)");
}
@Test
@DisplayName("不传 company_id = 今天的行为一分不变")
void superAdminWithoutCompanyStaysUnfiltered() {
AdminUserEntity operator = user(1L, "super_admin");
when(adminUserMapper.selectById(1L)).thenReturn(operator);
when(dataReadScope.readScope(operator, null)).thenReturn(ReadScope.unfiltered());
assertThat(service.resolve(1L, null).sqlUserIds()).isNull();
}
@Test
@DisplayName("历史超管(role 为空 + isAdmin=1 + createdById 为空)选了公司,也得跟着窄")
void legacySuperAdminIsNotLeftUnfiltered() {
AdminUserEntity legacy = new AdminUserEntity();
legacy.setId(2L);
legacy.setIsAdmin(1);
legacy.setCreatedById(null);
when(adminUserMapper.selectById(2L)).thenReturn(legacy);
// 这条桩必须返回"筛过"的集合:DataReadScope 用 AdminAuthSupport.currentRole 判超管,
// 而 DeviceSessionPolicy.resolveRole:34-36 对这个形状返回 super_admin(与 :60-64 的 isSuperAdmin 同规则)。
// 两把尺子必须同一条,否则这页会出现"readScope 当它是超管不筛、service 当它是 admin 求交"的分裂。
when(dataReadScope.readScope(legacy, 3L)).thenReturn(ReadScope.users(List.of(31L)));
assertThat(service.resolve(2L, 3L).sqlUserIds()).containsExactly(31L);
}
@Test
@DisplayName("成员集为空时交给 SQL 的是 [-1] 不是空集:IN () 是语法错,兜底在 ScopeContext 里")
void emptyMemberSetFallsBackToSentinelNotEmptyList() {
AdminUserEntity operator = user(1L, "super_admin");
when(adminUserMapper.selectById(1L)).thenReturn(operator);
when(dataReadScope.readScope(operator, 99L)).thenReturn(ReadScope.users(List.of()));
TaskCenterScopeService.ScopeContext scope = service.resolve(1L, 99L);
assertTrue(scope.visibleUserIds().isEmpty());
assertThat(scope.sqlUserIds()).containsExactly(-1L); // :84 那条兜底,本任务不许改它
}
@Test
@DisplayName("非超管:公司集与既有分组集求交,只收窄不放大")
void adminIntersectsWithGroupScope() {
AdminUserEntity operator = user(5L, "admin");
when(adminUserMapper.selectById(5L)).thenReturn(operator);
when(shopManageGroupMapper.selectAccessibleGroupIds(5L)).thenReturn(List.of(3L));
when(shopManageGroupMapper.selectUserIdsByGroupIds(List.of(3L))).thenReturn(List.of(6L));
// 分组集 = 本人 5 + 组员 6(:33-38 的既有口径),公司成员 = 6、7 ⇒ 只剩 6
when(dataReadScope.readScope(operator, 2L)).thenReturn(ReadScope.users(List.of(6L, 7L)));
assertThat(service.resolve(5L, 2L).sqlUserIds()).containsExactly(6L);
}
```
布线照 `TaskCenterScopeServiceTest` 现有形状补(`:32-42`):字段名是 `service` 不是 `scopeService`;操作者是 `adminUserMapper.selectById(id)` 打桩返回的 `user(id, role)` 夹具(`:36-42`),所以 `dataReadScope.readScope(operator, ...)` 的入参必须用**同一个实例**(先 `AdminUserEntity operator = user(...)` 再把它塞进两处桩——别新造一个对象去匹配,Mockito 按 `equals` 比,`AdminUserEntity` 没重写 `equals`,那样永远匹配不上、桩返回 null,用例会红在错的地方)。新增 `@Mock private DataReadScope dataReadScope;` 一支,`@InjectMocks` 才填得进新加的构造参数;`assertFalse`/`assertTrue` 是这个文件已经在用的静态导入(`:50-52`),别混进 `assertThat(...).isTrue()` 之外的第三种风格。
- [ ] **Step 2: 跑,确认红** → `mvn -q test -Dtest=TaskCenterScopeServiceTest`(`resolve(Long, Long)` 不存在 = 编译失败也算预期红)
- [ ] **Step 3: `resolve` 加一个重载**
`TaskCenterScopeService`:把既有 `resolve(Long operatorId)` 的方法体搬进 `resolve(Long operatorId, Long companyId)`,旧签名改成一行委托 `return resolve(operatorId, null);`(这样其余调用点一分不变,Step 4 只动 controller)。新方法体的形状:
```java
public ScopeContext resolve(Long operatorId) {
return resolve(operatorId, null); // 旧签名一行委托,其余调用点一分不变
}
/** 公司 tab 的收窄点:只与既有可见集**求交**,一律不放大(spec §4)。五个端点共用这一处。 */
public ScopeContext resolve(Long operatorId, Long companyId) {
AdminUserEntity operator = requireOperator(operatorId);
ReadScope read = dataReadScope.readScope(operator, companyId);
if (read.isUnfiltered()) {
return new ScopeContext(true, Set.of()); // 今天的行为:超管没选公司 = 不筛
}
List<Long> base = null;
if (!isSuperAdmin(operator)) {
// ↓↓↓ 既有 :32-38 那段分组口径**原样搬过来**:不改写、不换 mapper 方法、不动 addAll 的过滤条件。
List<Long> accessibleGroupIds = shopManageGroupMapper.selectAccessibleGroupIds(operator.getId());
LinkedHashSet<Long> visibleUserIds = new LinkedHashSet<>();
visibleUserIds.add(operator.getId());
if (accessibleGroupIds != null && !accessibleGroupIds.isEmpty()) {
addAll(visibleUserIds, shopManageGroupMapper.selectUserIdsByGroupIds(accessibleGroupIds));
}
addAll(visibleUserIds, shopManageGroupMapper.selectManagedMemberUserIds(operator.getId()));
base = new ArrayList<>(visibleUserIds);
}
// 超管选了公司 ⇒ base=null ⇒ userIdsOr 交出公司集本身;非超管 ⇒ 分组集 ∩ 公司集(Task 6 的求交语义)。
List<Long> narrowed = read.userIdsOr(base);
return new ScopeContext(false, narrowed == null ? Set.of() : Set.copyOf(narrowed));
}
```
两处不能省,说明白免得执行时"顺手简化":
- 早退只看 `read.isUnfiltered()`,**不再叠 `&& isSuperAdmin(operator)`**(Constraint 4 的"不许第二个 if"就是这个意思)。非超管会不会拿到 unfiltered 由 Task 6 的 `DataReadScope` 独家保证,那条已经有 G3 的用例钉着(`adminWithoutCompanyFailsFast` 与别家=空集两支),这里再判一次只会造出两把尺子。
- 但 `!isSuperAdmin(operator)` 那个分支**必须留着**:它不是范围判断,是"这页原本要不要算分组集"的判断。选了公司的超管没有分组限制,`base` 必须是 `null`;一旦把它简化成"所有人都算分组集",超管在第 2 家 tab 下会看到"那家公司成员 ∪ 超管自己创建的组"——放大,不是收窄。
关键点只有一个:**选了公司的超管必须走 `allUsers=false`**。超管 `allUsers=true` 时 `ScopeContext.sqlUserIds()` 直接返回 `null`,`USER_SCOPE_T/B` 的 `<if test='userIds != null'>` 整段不渲染 ⇒ tab 切了、SQL 没变,症状是"页面一切正常但数字永远一样",接口照样 200,没有任何一处会报错——所以 Step 1 第一条用例断的是 `assertFalse(scope.allUsers())`,不是断集合内容。
还有一条**新旧两把尺子必须同一条**的账:`isSuperAdmin(:60-64)` 认"role 为空 + isAdmin=1 + createdById 为空"的历史超管,`DataReadScope` 走的是 `AdminAuthSupport.currentRole` → `DeviceSessionPolicy.resolveRole:34-36`,对这个形状同样返回 `super_admin`。两者一致是这条链成立的前提,Step 1 那条 `legacySuperAdminIsNotLeftUnfiltered` 就是钉它的(哪一天 `resolveRole` 或 `isSuperAdmin` 单边改了,这条会红,而不是让某个历史超管在 tab 下看到全量)。
⚠️ **更正(草稿写错过一次,执行时别再写回来)**:草稿在这里写的是"空集直传会渲染成 `AND t.user_id IN ()`,MySQL 语法错,所以要在 service 里判空短路"。**实读 `TaskCenterScopeService.java:79-86` 后不成立**:`ScopeContext.sqlUserIds()` 已经做了 `visibleUserIds.isEmpty() ? List.of(-1L) : ...`,非超管再小也交出去一个 `[-1]`,`IN ()` 这个形状根本到不了 SQL。所以**不许**在本 service 里再加一层判空短路——那会造出第二个空集口径(一半走 `[-1]`、一半直接空页),而 `tasks/detail` 走的是 `scope.visible(userId)`(`TaskCenterQueryService:180`)不是 SQL,两个口径分叉时列表和详情会给出不同答案。要防的只是:**新代码绕开 `ScopeContext` 自己拼 List 传给 mapper**,那才会真的把空集递进去。Step 1 的 `[-1]` 那条用例钉的就是这件事。
- [ ] **Step 4: 五个端点加参数**
`AdminTaskCenterController` 的 `overview`(`:46`)/ `shop-options`(`:54`)/ `tasks`(`:62`)/ `tasks/detail`(`:72`)/ `variant-tasks`(`:86`)各加一个 `@RequestParam(name = "company_id", required = false) Long companyId`,并把它交给 `resolveScope(request, companyId)`(私有方法 `:100-104` 加一个入参,五个调用点一起改)。
**`tasks` 那一支不许用"往 `TaskCenterTaskQuery` 加 `companyId` 字段"的省事写法**:那个对象是 Spring **按字段名绑定**的(`moduleType`/`shop`/`startTime`/`pageSize` 全是驼峰,实读 `TaskCenterTaskQuery.java:11-28`),加了字段就意味着前端必须发 `companyId=`,而另外 7 页和这个页的其余 4 个端点发的是 `company_id=`。两种拼写并存的结果是参数被**静默丢弃**(`required = false` + 没人报错),且只在"任务列表"这一支上丢——看板数字窄了、列表没窄,正是 §4 记的那种最难查的形态。统一显式 `@RequestParam(name = "company_id")`,五个端点一个形状。
- [ ] **Step 5: 前端五支都带参**
`src/api/task-center.ts` 的四支取数函数各自加参数(`fetchTaskCenterOverview` `:82`、`fetchTaskCenterShopOptions` `:88` 现在**一个参数都没有**,要新加 `companyId?: number | null` 并把 `http.get(url)` 改成 `http.get(url, { params: query })`;`fetchTaskCenterTasks` `:94`、`fetchTaskCenterVariantTasks` `:109` 收的是 `params: QueryParams`,在传进来的对象上补键即可):
```ts
const query: QueryParams = { company_id: companyId } // 两支无参函数
const { data } = await http.get('/api/admin/task-center/overview', { params: query })
```
`src/pages/task-center/task-center-model.ts` 的 `buildTaskQuery`(`:200-216`)与 `buildVariantQuery`(`:218-227`)各在 `const query: TaskCenterQueryParams = { page, pageSize }` 之后加一行 `if (companyId != null) query.company_id = companyId`(`TaskCenterQueryParams` 是 `Record<string, string | number>`(`:19`),加键不动类型,也不存在 Task 8 那种白名单丢弃问题)。`fetchTaskCenterTaskDetail`(`:101`)**同样要带** `company_id`——理由见本节开头那条:详情走 `scope.visible()`,api 少传这一支,超管在别家 tab 下按 `taskNo` 就能读到别家详情,而这页 UI 上看不出任何异常。
`TaskCenterBoardPage.vue` 的四处调用(`:98`、`:107`、`:116`、`:130`)与详情调用点各传 `companyTab.requestCompanyId`,页面组件加 Task 7 Step 5 那条 `watch`。
- [ ] **Step 6: 跑 + 提交**
```bash
mvn -q test 2>&1 | tail -10
node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit
git add backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter admin-frontend-vue/src/api/task-center.ts admin-frontend-vue/src/pages/task-center backend-java/src/test/java/com/nanri/aiimage/modules/taskcenter
git commit -m "feat(公司tab): 任务看板五个端点按公司筛(一处 resolve 收窄,detail 靠 scope.visible 同宽)"
```
---
## Task 11: 接线 —— 店铺管理 + 数据权限分组(只筛读;写侧归属刻意不动,并反向钉住)
**先读这五条已确认现状(2026-10-04 逐行实查,别再照草稿的假设推):**
1. `ShopManageController.requireOperator(request)` 走的是 **`adminAuthSupport.requireAdminOrInternal(request)`**(`controller/ShopManageController.java:50-52`)⇒ 这页**存在非超管与内部令牌两条通道**。按 §6.1,它的按 id 读出口必须补行级闸门,与 Task 12 那页"只有超管进得来"是两回事。
2. `ShopManageService.page(long page, long pageSize, Long groupId, String shopName, Long operatorId, boolean superAdmin)`(`service/ShopManageService.java:31`)——**service 拿到的是 `operatorId` + 一个布尔,不是 `AdminUserEntity`**。⇒ `readScope(AdminUserEntity, Long)` 只能由 controller 调(它手上就有 operator 实体),把算好的成员集当参数传进去。这跟 Task 12 的 `memberUids` 是同一个形状,两页别各发明一套。
3. 超管今天**完全不锁**:`:43` 的 `if (!superAdmin) { ... }` 里才有 `accessibleCreatorUserIds`/`accessibleGroupIds` 那套 OR(`:48-59`)。⇒ 超管 + 选了公司这一支是**新增**的收窄,不是"改既有过滤"。
4. ⚠️ **`create`/`update` 的归属来自请求体,不来自操作者**:`ShopManageService.java:86` 是 `normalizePositiveId(request.getCreatedById(), "创建人不能为空")`,`:96` `entity.setCreatedById(createdById)`。⇒ 草稿写的"`created_by_id = operator.getId()`"**是错的**,Step 4 的口径说明按这条重写。
5. `ShopManageGroupService.list(Long createdById)`(`service/ShopManageGroupService.java:51-57`)生成的是 `created_by_id = ? OR (user_id = ?)` 这种**平铺 OR**。MP 的 normal 段按声明顺序拼 `AND`/`OR`,事后在外面叠一条 `in(...)` 会得到 `A OR (B) AND C` ⇒ MySQL 里 AND 优先,**左半边 `created_by_id = ?` 整个逃出公司筛选**(不报错、不 403,就是多放行)。
**Files:**
- Modify: `backend-java/.../modules/shopkey/controller/ShopManageController.java` —— 读侧 `page`(`:66-80`)、`listGroups`(`:115-123`) 各加 `company_id`;**闸门侧 `adminCredential`(`:175-182`)**;写侧 `create`(`:84`)/`update`(`:94`)/`delete`(`:105`)/`createGroup`(`:127`)/`updateGroup`(`:137`)/`deleteGroup`(`:148`) **不动**
- Modify: `backend-java/.../modules/shopkey/service/ShopManageService.java:31-82`(`page` 末位加 `List<Long> companyMemberIds`)、`:155-164`(`getCredentialById` 加同宽闸门)
- Modify: `backend-java/.../modules/shopkey/service/ShopManageGroupService.java:51-57`(`list` 末位加 `List<Long> companyMemberIds`,**套括号**)
- Modify: `admin-frontend-vue/src/pages/shop/shop-manage-api.ts`、`src/pages/account/shop-group-api.ts`
- Test: `ShopManageServiceTest`(**已存在,追加**;`@Mock` 字段名是 **`shopManageMapper`** / `shopManageGroupService` / `shopCredentialCryptoService`,`@InjectMocks private ShopManageService service`。它现在只用 `org.junit.jupiter.api.Assertions`,本任务要加这些 import:`org.assertj.core.api.Assertions.assertThat` / `assertThatCode`、`org.mockito.ArgumentCaptor`、`org.mockito.Mockito.verify`、`org.junit.jupiter.api.BeforeEach`、`java.util.List`,以及上面 `TableInfoHelper` 那三行要的 `com.baomidou.mybatisplus.core.MybatisConfiguration` / `com.baomidou.mybatisplus.core.metadata.TableInfoHelper` / `org.apache.ibatis.builder.MapperBuilderAssistant`)
- Test: `ShopManageGroupServiceTest`(**新建** —— 实查 `backend-java/src/test` 下没有这个文件,别按"追加"去找。它的 `@Mock` 要覆盖 `ShopManageGroupService` 那 7 个构造参数里的 `groupMapper`(字段名就叫 `groupMapper`);余下 6 个 `@Mock` 不给也行,`@InjectMocks` 留 null,本任务三条用例都不走它们)
- Test: `ShopManageCredentialAuthTest`(**已存在**,它是 `getCredentialByShopName` 两条通道的既有守卫 ⇒ Step 3 改 `adminCredential` 时**必须**回来跑它,那条 JWT 通道一断就是 4.0.44 客户端整片取不到凭据)
- Test: 新建 `backend-java/src/test/java/com/nanri/aiimage/testutil/SourceScan.java`
**Interfaces:**
- Consumes: `DataReadScope.readScope(AdminUserEntity, Long)` → `ReadScope.userIdsOr(List<Long>)`(Task 6)
- Produces:
- `ShopManagePageVo page(long page, long pageSize, Long groupId, String shopName, Long operatorId, boolean superAdmin, List<Long> companyMemberIds)` —— `companyMemberIds == null` 表示不筛(超管没选公司 / 非超管由既有分支自己锁)
- `List<ShopManageGroupItemVo> list(Long createdById, List<Long> companyMemberIds)`(零参 `list()` 保留并委托到它`list(null, null)`;`list()` 有活调用方 `listAccessible`,删了编译断。原稿点名的单参 `list(Long)` 落地后无人调用,**已删**——见 Step 3(c) 那条执行期订正)
- `ShopManageCredentialVo getCredentialById(Long id, Long operatorId, boolean superAdmin)` —— 非超管时行的 `created_by_id ∈ 可访问创建人集` **或** `group_id ∈ 可访问分组集` 才放行,两腿都不认 ⇒ `BusinessException(403, ...)`;超管短路不查可见集。**为什么不是原稿那个成员集版**见 Step 3(d) 的执行期定案(用账号集合当闸门会把"建在我可访问分组里、创建人是别人"的行 403 掉 = 静默删掉正当访问)
- 写侧**不新增任何参数**——见 Step 4 的口径与它那条反向钉
- [ ] **Step 1: 写失败的测试(读侧一条 + 分组括号一条 + 凭据闸门一条 + 写侧"不得回流"一条)**
先建那个共用的测试工具类(Task 12 Step 4 用它,本任务的反向钉也用它;**放在 `testutil` 包而不是各写一份**):
`backend-java/src/test/java/com/nanri/aiimage/testutil/SourceScan.java`
```java
package com.nanri.aiimage.testutil;
import static org.junit.jupiter.api.Assertions.fail;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
/** 源码扫描式护栏的取文助手。<b>路径解析照抄 {@code common/security/InternalTokenSingleOutletTest} 的
* moduleRoot()/mainSources() 两支</b>——surefire 的 cwd 是模块目录,从仓库根或 IDE 跑时要退到 backend-java/,
* 定位不到必须 fail 而不是静默跳过(静默跳过 = 整支护栏恒绿)。 */
public final class SourceScan {
private SourceScan() {
}
/** 按文件名(不含目录)取 {@code src/main/java} 下那份源码的<b>全文字符串</b>。
* ⚠️ 返回 String,与 InternalTokenSingleOutletTest 里那个返回 Path 的私有 {@code sourceOf} 不是一回事,
* 别指望复用它的——那个是 private。 */
public static String sourceText(String fileName) {
return mainSources().stream()
.filter(p -> p.getFileName().toString().equals(fileName))
.findFirst()
.map(SourceScan::read)
.orElseThrow(() -> new IllegalStateException(
"src/main/java 下找不到 " + fileName + " —— 文件改名/挪目录了,护栏要红在这里"));
}
/** 大括号配平切出「某个方法」的源码:<b>从它的签名行往前一直含到注解</b>,到方法收尾的 `}` 为止。
*
* <p>两条它必须自己防住的坑,都写在用例里过:</p>
* <ul>
* <li><b>名字必须是完整词</b>:{@code delete} 是 {@code deleteGroup} 的前缀。用 {@code indexOf(name)}
* 会先撞上那个更长的方法 ⇒ "切出来的是隔壁",而断言仍然绿。所以下面用 {@code (?<![A-Za-z0-9_])} 卡左边界,
* 并且要求紧跟 {@code (}(构造器/局部变量名同前缀也不算方法)。</li>
* <li><b>找不到必须抛</b>,不许返回空串:返回 "" 的话 {@code doesNotContain("company_id")} 恒真,
* 反向钉会因为方法被改名而悄悄失效(memory「字符串断言必须排他、解析断言必须可匹配」)。
* 配套要求:每个用它的反向钉都要带一条"该做的确实做了"的取样自检。</li>
* </ul>
*/
public static String methodBody(String source, String methodName) {
var matcher = java.util.regex.Pattern
.compile("(?<![A-Za-z0-9_])" + java.util.regex.Pattern.quote(methodName) + "\\s*\\(")
.matcher(source);
while (matcher.find()) {
int open = matcher.end() - 1;
int signatureStart = findSignatureStart(source, matcher.start());
int bodyEnd = matchBraces(source, nextBrace(source, open));
if (bodyEnd < 0) {
continue;
}
return source.substring(signatureStart, bodyEnd + 1);
}
throw new AssertionError("源码里没有方法「" + methodName + "」——它被改名或删掉了。"
+ "反向钉宁可红在这里,也不许因为切不到方法而恒绿。");
}
/** 从签名的左括号往前退到上一条 `{`/`}`/`;` 之后,再退回到第一行注解的起始(注解属于这个方法,必须含进来)。 */
private static int findSignatureStart(String source, int nameStart) {
int boundary = 0;
for (int i = nameStart; i-- > 0; ) {
char c = source.charAt(i);
if (c == '{' || c == '}' || c == ';') {
boundary = i + 1;
break;
}
}
String head = source.substring(boundary, nameStart);
int firstMeaningful = head.length();
for (String raw : head.split("\n", -1)) {
if (!raw.isBlank()) {
firstMeaningful = head.indexOf(raw.stripLeading());
break;
}
}
return boundary + firstMeaningful;
}
private static int nextBrace(String source, int from) {
for (int i = from; i < source.length(); i++) {
if (source.charAt(i) == '{') {
return i;
}
if (source.charAt(i) == ';') {
return -1; // 抽象方法/接口声明,不是我们要切的东西
}
}
return -1;
}
/** 朴素配平:源码里的 `{` 与 `}` 若出现在字符串字面量里会算错。本仓库 controller 没有这种写法,
* 但这条限制必须写在脸上——将来有人往方法体里塞一段带花括号的字符串,这个助手会悄悄切短。 */
private static int matchBraces(String source, int open) {
if (open < 0) {
return -1;
}
int depth = 0;
for (int i = open; i < source.length(); i++) {
char c = source.charAt(i);
if (c == '{') {
depth++;
} else if (c == '}') {
if (--depth == 0) {
return i;
}
}
}
return -1;
}
private static List<Path> mainSources() {
Path root = moduleRoot().resolve("src/main/java");
try (Stream<Path> walk = Files.walk(root)) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith(".java"))
.collect(Collectors.toList());
} catch (IOException e) {
throw fail("遍历 " + root + " 失败: " + e.getMessage());
}
}
private static Path moduleRoot() {
Path here = Path.of("").toAbsolutePath();
if (Files.isDirectory(here.resolve("src/main/java"))) {
return here;
}
Path nested = here.resolve("backend-java");
if (Files.isDirectory(nested.resolve("src/main/java"))) {
return nested;
}
throw new IllegalStateException("无法定位 backend-java 模块目录(cwd=" + here + ")");
}
private static String read(Path file) {
try {
return Files.readString(file, StandardCharsets.UTF_8);
} catch (IOException e) {
throw new IllegalStateException("读取失败: " + file, e);
}
}
}
```
> 为什么值得为它写一整份而不是"照抄一个":草稿那句"Java 侧照抄一个即可"本身就是一条占位(writing-plans 的 No Placeholders)。而它最容易死在 `delete` / `deleteGroup` 这种前缀关系上——切错方法比切不到方法坏得多,因为**它会绿**。
再写四支用例(前三支是本任务真正要的收窄,第四支是反向钉):
⚠️ **前三支都要先补 `TableInfoHelper`,否则它们红在框架而不是红在逻辑**。`getSqlSegment()` 要把 `ShopManageEntity::getCreatedById` 这个 lambda 解析成列名,靠的是 MyBatis-Plus 的 `TableInfo` 缓存;单测里没有 Spring 容器去建它,**没初始化就抛 "can not find lambda cache for this entity"**,报得完全不像"我的筛选没生效"。`ShopManageServiceTest` 今天不查 `getSqlSegment()` ⇒ 它**没有**这一步,必须补。写法逐字照本仓库既有惯例(`modules/admin/service/AdminUserListCompanyTest.java:44-45`——它是 `@BeforeEach` 里一行,不是 `@BeforeAll`,也不要自己 new `MapperRegistry`):
```java
@BeforeEach
void initTableInfo() {
TableInfoHelper.initTableInfo(
new MapperBuilderAssistant(new MybatisConfiguration(), ""), ShopManageEntity.class);
TableInfoHelper.initTableInfo(
new MapperBuilderAssistant(new MybatisConfiguration(), ""), ShopManageGroupEntity.class);
}
```
(新建的 `ShopManageGroupServiceTest` 同样要一份,它只需 `ShopManageGroupEntity` 那一行;第四支 `writeEntryPointsCarryNoCompanyId` 只读源码文本,不需要它。)
顺便:`AdminUserListCompanyTest` 的类注释给了本任务该学的断言口径——"断言必须打在**有没有碰表**上,只断言返回空集合的话,把条件写反了也是空"。上面前三支都按这条写(捕 wrapper 看 segment / pairs),没有一支是"断返回空"。
```java
@Test
@DisplayName("读:超管选了公司 ⇒ created_by_id 落进成员集;非超管不叠这一条")
void superAdminPageNarrowsToCompanyMembers() {
// 字段名逐字用 ShopManageServiceTest 已有的:mock 是 shopManageMapper,被测是 service。
when(shopManageMapper.selectCount(any())).thenReturn(1L);
when(shopManageMapper.selectList(any())).thenReturn(List.of());
service.page(1L, 15L, null, null, 1L, true, List.of(11L, 12L));
ArgumentCaptor<LambdaQueryWrapper<ShopManageEntity>> captor =
ArgumentCaptor.forClass(LambdaQueryWrapper.class);
verify(shopManageMapper).selectCount(captor.capture());
// 值在 paramNameValuePairs 里,segment 里只有 MPGENVAL 占位 ⇒ 结构从 segment 读、值从 pairs 读。
assertThat(captor.getValue().getSqlSegment()).contains("created_by_id").contains("IN (");
assertThat(captor.getValue().getParamNameValuePairs().values()).contains(11L, 12L);
}
@Test
@DisplayName("分组:list 叠公司必须把既有那条平铺 OR 整个套进括号(否则 created_by_id=? 那半边逃出筛选)")
void groupListWrapsTheOrBeforeNarrowing() {
when(groupMapper.selectList(any())).thenReturn(List.of());
groupService.list(5L, List.of(11L));
ArgumentCaptor<LambdaQueryWrapper<ShopManageGroupEntity>> captor =
ArgumentCaptor.forClass(LambdaQueryWrapper.class);
verify(groupMapper).selectList(captor.capture());
String segment = captor.getValue().getSqlSegment();
// 断"OR 被包在 and( ... ) 里"的形状:OR 之前必须出现一个 '(',且整段以 AND (…IN…) 收尾。
assertThat(segment).contains("(created_by_id").contains(" OR ");
assertThat(segment.lastIndexOf("AND ("))
.as("公司条件必须自成一组,不能与 OR 平铺")
.isGreaterThan(segment.indexOf("created_by_id"));
}
@Test
@DisplayName("凭据:选了公司的超管按 id 读别家店铺的明文凭据 ⇒ 403(列表筛了、按 id 照读 = 越权,§6.1)")
void credentialByIdIsGatedByTheSameMemberSet() {
ShopManageEntity foreign = new ShopManageEntity();
foreign.setId(77L);
foreign.setCreatedById(999L); // 不在 {11,12} 里
when(shopManageMapper.selectById(77L)).thenReturn(foreign);
assertThatThrownBy(() -> service.getCredentialById(77L, List.of(11L, 12L)))
.isInstanceOf(BusinessException.class)
.hasFieldOrPropertyWithValue("code", 403);
// null ⇒ 不筛,保持超管没选公司时的今天行为(Constraint 2:tab 不是安全边界,别把默认改成拒绝)。
assertThatCode(() -> service.getCredentialById(77L, null)).doesNotThrowAnyException();
}
@Test
@DisplayName("写:店铺与分组的写入口一律不收 company_id——归属不从界面注入(§6.2,未批的界面暴露)")
void writeEntryPointsCarryNoCompanyId() {
String text = SourceScan.sourceText("ShopManageController.java");
// 必须逐方法体判:page 这个读入口这轮就要加 company_id,全文 doesNotContain 会被自己弄红。
for (String writer : List.of("create", "update", "delete", "createGroup", "updateGroup", "deleteGroup")) {
assertThat(SourceScan.methodBody(text, writer))
.as("写入口「" + writer + "」一旦出现 company_id,等于把公司维度端回界面(未批)")
.doesNotContain("company_id")
.doesNotContain("companyId");
}
assertThat(SourceScan.methodBody(text, "page")).contains("company_id"); // 取样非空自检:读侧确实接上了
}
```
> `methodBody(text, "delete")` 与 `deleteGroup` 是本任务最容易写错的一对:`methodBody` 靠 `(?<![A-Za-z0-9_])` 卡完整词才切得对,**这条不是保险而是这支用例能不能用的前提**——`indexOf("delete")` 会先撞见 `deleteGroup` 的参数表,于是 `delete` 那条断言实际上什么都没判,还报绿。
第二条是**反向钉**(memory「撤维度时测试要反向钉不得回流」):它现在对写入口恒绿(那几个方法本就不收这个参数),作用是把"写侧不接公司维度"这条口径钉死——将来谁想让 `create` 收 `company_id`,这条会先红,逼他来问一次,而不是让界面悄悄长回一个下拉。
- [ ] **Step 2: 跑,确认红** → `mvn -q test -Dtest='ShopManage*Test'`
`ShopManageService.page(...)` 里既有的是 `created_by_id IN`(超管不锁、主管锁自己带的组),改成经 `scopedUserIds` 折一次:
- [ ] **Step 3: 读侧叠范围 + 凭据闸门(四处,形状各不相同)**
**(a) `ShopManageService.page`** —— 末位加 `List<Long> companyMemberIds`。实查 `:31-61`:**超管今天完全不锁**(`:43` 的 `if (!superAdmin)` 里才有那套 OR),所以这一支是**新增**,不是"改既有过滤";插在 `if (!superAdmin) { ... }` 之后、`selectCount`(`:63`)之前:
```java
// companyMemberIds 由 controller 算好传进来(service 手上只有 operatorId + 一个布尔,
// 而 readScope 要 AdminUserEntity)。null = 不筛,与"超管没选公司"的今天逐字一致。
if (companyMemberIds != null) {
if (companyMemberIds.isEmpty()) {
query.eq(ShopManageEntity::getId, -1L); // 照 :46 既有的"必空"写法,别再发明一种
} else {
query.in(ShopManageEntity::getCreatedById, companyMemberIds);
}
}
```
> 走 `created_by_id` 而**不是** `group_id`:一个店铺同时有 `created_by_id` 和一个 `group_id`,而分组自己也有 `user_id`/`created_by_id` ⇒ 两个候选真相源。§11.1 批次 3 那条"同页两个真相源"的告诫在这里同样成立,**这页只认 `created_by_id`**,并把"店铺建在别家名下但创建人是超管"这类行留给 Tab 的第一家(超管自己那家)。今天实查第 2 家 0 行 ⇒ 无可观察差异。
**(b) `ShopManageController`** —— `page`(`:66-80`) 与 `listGroups`(`:115-123`) 各加 `@RequestParam(name = "company_id", required = false) Long companyId`(**必须显式 `name=`**,见 Step 5 那条 ⚠️),并在调 service 前折一次范围:
```java
AdminUserEntity operator = requireOperator(request);
ReadScope read = dataReadScope.readScope(operator, companyId);
List<Long> memberIds = read.isUnfiltered() ? null : read.userIds();
```
⚠️ **`memberIds` 只在超管分支下传,非超管一律传 `null`**。理由不是"已经锁过了"那么轻:非超管那套 OR(`:48-59`,它**本身已经包在 `and(wrapper -> …)` 里**,所以不存在 Step 3(c) 那个括号问题)含一条 `group_id IN accessibleGroupIds` —— 分组行上**没有账号列可推公司**,一个由别人创建、但把该非超管设为负责人的分组今天对他可见。给它外面再叠一条 `AND created_by_id IN (自家成员)`,那批"靠分组可见"的行会**从他的每一个 tab 里消失**,且不报错。这正是 spec §9.1 点名的静默删除形状,代价比"非超管理论上可能跨公司"更确定(今天 2 家、第 2 家 0 行业务数据)。`listGroups` 更是分岔的:`:119-122` 超管走 `list(createdById)`、非超管走 `listAccessible(...)` ⇒ **只给超管那条传 `memberIds`,`listAccessible` 一行都不许动**。非超管的跨公司收窄要做得先回答"分组算哪家公司",而重写 `listAccessibleGroupIds` 是 spec §13「不重写 `UserDataScopeSupport` 的分组口径」明确排除的(⇒ 记进附B,并且**对外别说"非超管已按公司锁死"**)。
**(c) `ShopManageGroupService.list`** —— 见下面那段括号警告,形状是:
```java
public List<ShopManageGroupItemVo> list(Long createdById, List<Long> companyMemberIds) {
LambdaQueryWrapper<ShopManageGroupEntity> qw = new LambdaQueryWrapper<ShopManageGroupEntity>()
.orderByAsc(ShopManageGroupEntity::getId);
if (createdById != null && createdById > 0) {
// 原来这两条是平铺的 .eq(...).or(... -> ...);一旦外面再叠 AND,
// MySQL 的 AND 优先于 OR,created_by_id = ? 那半边会整块逃出公司筛选(多放行、不报错)。
// ⇒ 有 companyMemberIds 时必须把 OR 组收进一个 and()。
qw.and(w -> w.eq(ShopManageGroupEntity::getCreatedById, createdById)
.or(x -> x.eq(ShopManageGroupEntity::getUserId, createdById)));
}
if (companyMemberIds != null) {
if (companyMemberIds.isEmpty()) {
qw.eq(ShopManageGroupEntity::getId, -1L);
} else {
qw.in(ShopManageGroupEntity::getCreatedById, companyMemberIds);
}
}
return toVoList(groupMapper.selectList(qw));
}
```
只保留 `list()` 一支委托到它(`list()` 被同文件 `listAccessible` 调用)。**执行期订正**:原稿说的 `list(Long)` 单参重载并没有活调用方——controller 那一支从一开始就要传公司成员集,落地时调的是二参 `list(createdById, memberIds)`(`ShopManageController.java:129`),单参那支成了死代码,已随修复轮删除(`grep` 全仓 `src/main` + `src/test` 零命中)。零参 `list()` 仍在用,删它才会编译断。
**(d) `getCredentialById` 的闸门**(`ShopManageService.java:155-164`)—— 这是本任务里唯一一处"不做就是真越权"的东西:`:175-182` 的 `adminCredential(id)` 走 `requireOperator` = **`requireAdminOrInternal`**(`:50-52`),今天**任何**已认证后台账号(含内部令牌通道)拿一个 id 就能读到**别家店铺的明文账号密码**,连分组都不判。§6.1 那条"列表筛了、按 id 照读 = 越权"在这里是字面成立的,而且读出来的是凭据。
(下面这段代码块是**执行期定案后的实际形状**,原稿设想的 `companyMemberIds` 版已被替换,理由见代码块之后。)
**执行期定案(与原稿不同,差异是实质性的,照原稿写会静默删掉正当访问)**:闸门不收 `companyMemberIds`,
收 `(Long id, Long operatorId, boolean superAdmin)`,判据用 `page()` 那把尺子的**两腿**——
`created_by_id ∈ 可访问创建人集` **或** `group_id ∈ 可访问分组集`:
```java
public ShopManageCredentialVo getCredentialById(Long id, Long operatorId, boolean superAdmin) {
if (id == null || id <= 0) {
throw new BusinessException("店铺 ID 不合法");
}
ShopManageEntity entity = shopManageMapper.selectById(id);
if (entity == null) {
throw new BusinessException("店铺不存在");
}
// 尺子必须与 page() 那一条同形:created_by_id IN creators OR group_id IN groups。
// 账号集合表达不了分组那一腿(店铺建在我可访问的分组里、创建人却不在我的账号集),
// 拿它当闸门会把列表看得见的行读凭据时 403 掉——那是把正当访问静默删掉。
if (!superAdmin) {
Set<Long> creators = shopManageGroupService.listAccessibleCreatorUserIds(operatorId, false);
Set<Long> groups = shopManageGroupService.listAccessibleGroupIds(operatorId, false);
boolean visible = (entity.getCreatedById() != null && creators.contains(entity.getCreatedById()))
|| (entity.getGroupId() != null && groups.contains(entity.getGroupId()));
if (!visible) {
throw new BusinessException(403, "无权查看该店铺的凭据");
}
}
return toCredentialVo(entity);
}
```
为什么不能用原稿那个 `companyMemberIds.contains(created_by_id)`:这一页的列表口径本来就是"创建人集 ∪ 分组集"两条腿
(`page()` 里那条 `... OR group_id IN (...)`),而成员集只表达前一条腿。用它当闸门 ⇒ 超管选了公司时、以及管理员读
"建在自己分组里、创建人是别人"的店铺时会被 403,**症状是列表看得见、点开除凭据报无权**,而这类"把正当访问筛没了"
的错误不会有任何接口红。钉这个差异的用例是 `ShopManageServiceTest.credentialByIdKeepsGroupVisibleRowsReadable`
(分组可见、创建人不在账号集 ⇒ 必须 200),它是防误伤的正样本;反向越权由
`credentialByIdRejectsRowOutsideBothVisibleSets` 钉(两腿都不认 ⇒ 403)。超管仍走 `superAdmin` 短路不查可见集
(tab 不是安全边界,这一页的既定口径)。
⚠️ **`getCredentialByShopName`(`:156-171`)这轮刻意不动**,理由与影响记进附B:它的调用方是 Python 自动化与 4.0.44 起的登录态客户端(`ShopManageCredentialAuthTest` 钉着那两条通道),`requireUser` 拿到的可能是**根本不是后台账号**的客户端用户 —— 那里没有"操作者公司"可推导,硬加闸门会把跟价机整片打停。它今天同样是跨公司的(按名字就能读凭据),**那是一期就存在的洞,不是本计划引入的**,要修得单独一张工单、单独授权。
- [ ] **Step 4: 写侧**——本任务**不动**它,并说明为什么(这是 2026-10-04 定下的口径,不是偷懒)
`ShopManageController` 的 `create`(`:84`)/`update`(`:94`)/`delete`(`:105`) 与三个分组写入口**保持原样**:请求体不收 `company_id`,界面上也不给"所属公司"下拉。
⚠️ **先把草稿里一句说错的话改对**:原来写的是"归属继续由后端从操作者推导(`created_by_id = operator.getId()`)"——**不对**。实查 `ShopManageService.java:86` 是 `normalizePositiveId(request.getCreatedById(), "创建人不能为空")`,`:96` `entity.setCreatedById(createdById)` ⇒ **店铺的归属人今天就是请求体里那个 `createdById`,由调用方挑**(后台弹窗里那个"负责人"下拉就是它)。⇒ 三条后果,都得写在脸上:
1. **"超管在别家 tab 下导入会落到自己公司"这句对店铺不成立**。超管把负责人选成 `users.id=1193`(第 2 家自己的 admin),店铺就归第 2 家 —— 这是**现成的、今天就能用的**路径,spec §6.3 那条副作用在店铺这页是"取决于你选谁当负责人",不是"恒落公司 1"。**Step 6 的提交信息与人工验收第 4 条按这个改**(那条原本写"确认没有跟着 tab 走",在店铺这页会把一次正常行为报成 bug)。
2. **反向钉的口径要收窄**:钉的是"不收 `company_id`",不是"归属不可指定"。`createdById` 这个既有字段照旧收 —— 动它才是回归。Step 1 第四支用例的断言式因此只看 `company_id`/`companyId` 两个词,不看 `createdById`。
3. **今天 `createdById` 没有任何公司校验**:任何已认证后台账号(含内部令牌通道)能把店铺挂到任意 `users.id` 名下。这跟 (d) 那个凭据读出口是同一类"一期就在的洞",本计划不顺手补(补它 = 给写侧加一条会 403 新老数据的校验,是要单独批的行为变更),**记进附B**。
为什么仍不给 `create` 加 `company_id`,三条理由:
1. **新维度默认只做后端,界面暴露要单独批准**(memory,2026-10-04 与用户对二期那条线的同一轮定调)。让 `create` 收 `company_id` = 在弹窗里长出一个公司选择器,那是要单独批的界面暴露,不在本计划已批范围(已批的是:超管用的 tab 一条 + 公司配置入口收窄)。何况**归属已经能从"负责人"表达**——再加一个公司选择器就是两个控件说同一件事,且它们会互相矛盾(选了第 2 家 + 选了公司 1 的负责人,听谁的?)。
2. **与建号同口径**:`AdminUserService.resolveTargetCompanyId`(`AdminUserService.java:201-207`)今天就是"前端不传 ⇒ 落操作者自己的公司",二期那条线还专门用 `tests/company-user-create.test.ts` 把它反向钉死了。店铺这边若单独改成"按 tab 选的公司落",同一后台就出现两套归属口径——那正是 memory「别自己定"全局统一默认值"口径」点名的坑。
3. **实体没有可落的列**:`ShopManageEntity`/`ShopManageGroupEntity` 只有 `createdById`/`groupId`/`userId`,**没有 `company_id`**(实查 `modules/shopkey/model/entity/ShopManageEntity.java:16-28`、`common/model/entity/ShopManageGroupEntity.java:16-22`)。要让"这店铺属于第 2 家"成为一个可写的显式事实,只能给这两张表加列(那是 DDL,spec §13 排除)或加一条"负责人必须是那家成员"的校验(超管自己不在任何别家的成员集里 ⇒ **那条校验一旦上线,超管把负责人留成自己就 403**,比今天更糟)。
⇒ **本任务的诚实边界**:tab 是**纯读视图**,写侧的归属规则一行都没动。运维手册里要写清的是这一句(它比 spec §6.3 原文更准确):
> 店铺/分组的归属由**负责人(`created_by_id`)**决定,不由顶部 tab 决定。要让数据归第 2 家,就把负责人选成第 2 家的账号(或用第 2 家自己的 admin 登录来建)。切 tab **不会**改变新建数据的归属。建号同理(`users.id=1193` 就是第 2 家自己的 admin 建的)。
这条对第 2 家公司当前**影响为零**(Task 5 Step 0 的 SQL 会给出它有几行数据;实查是 0 行业务数据),但对第 3 家开始就是运维手册里的一行字。**两处落点都已经写好,本步只需核对,不要再追加**:①spec §6.3 已按实查重写成"建号/店铺/分组"两段(17:5x 那轮订正,再追加一遍就是一份文档两个口径);②`operation-guides.ts` 店铺管理那句文案由 **Task 7 Step 7** 统一落地(它那一支用例的分母就是注册表,本任务补等于绕过护栏)。执行到这一步只做一个动作:`Grep` 一遍 spec §6.3 与 `admin_shop_manage` 的 text,确认这段口径各只有**一处**,多出来的那份删掉。
- [ ] **Step 5: 前端只带读参数**
两页的取数入口形状不同,逐一写清楚(这页最容易出的错不是筛错,是**参数名对不上被静默丢掉**):
- `src/pages/shop/shop-manage-api.ts:25-31`:`fetchShopManageList(params)` 的 query 由 `toShopManagePageQuery(normalizeShopListParams(params))` 产出(`shop-dto.ts:140-160`)。照 Task 8 Step 5 的形状,在 **builder 之后**补键,别去改 `ShopManageListParams`——`normalizeShopListParams`(`shop-dto.ts:140-146`)是白名单构造返回值,加进去的字段会被原样丢掉:
```ts
const query = toShopManagePageQuery(normalized)
if (params.companyId != null) query.company_id = params.companyId
```
`ShopManagePageQuery`(同文件)加 `company_id?: number`。
- `src/pages/account/shop-group-api.ts:14-17`:`fetchShopGroups()` **今天一个参数都没有**,`http.get(SHOP_GROUPS_ENDPOINT)` 也没带 `params`。⇒ 要新加 `companyId?: number | null` 入参并改成 `http.get(SHOP_GROUPS_ENDPOINT, { params: companyId != null ? { company_id: companyId } : {} })`,调用点 `GroupsPage.vue` 跟着传。**这一步漏掉的后果比筛错更坏**:分组列表继续返回全部公司可访问的分组,而店铺列表已经窄了,两页下拉对不上。
⚠️ **参数名一律写 `company_id`,后端对应 `@RequestParam(name = "company_id")` 必须显式带 `name=`**。这两页的邻居参数全是驼峰(`page`/`pageSize`/`groupId`/`shopName`/`createdById`,实读 `ShopManageController.java:66-71` 与 `:113-117`,它们靠方法参数名绑定),照抄邻居写法写成 `Long companyId` 的话,Spring 收的是 `companyId=`,而前端发的是 `company_id=` ⇒ 参数**永远为 null**、接口 200、列表永远不窄。这是本批次最难发现的一种红(它根本不红),Task 10 Step 4 同一条。
**不做**的事列清楚,免得执行时手滑:
- 不改 `GroupEditorDialog.vue` 的"负责人"下拉(那是界面暴露,未批;且 `AdminUserQuery` 侧已有公司收窄,选错人会被 Step 4 说的既有校验接住——执行时先 `Grep` 确认这个校验在,不在就**记进本任务的"已知不做"附B**,不要顺手加下拉)。
- 不给店铺列表加"所属公司"列(也是界面暴露、Global Constraint 14 未批;且这页进 tab 后,列的语义本来就由 tab 承担)。
- [ ] **Step 6: 跑 + 提交**
```bash
mvn -q test 2>&1 | tail -10
node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit
git add backend-java/src/main/java/com/nanri/aiimage/modules/shopkey \
backend-java/src/test/java/com/nanri/aiimage/modules/shopkey \
backend-java/src/test/java/com/nanri/aiimage/testutil/SourceScan.java \
admin-frontend-vue/src/pages/shop admin-frontend-vue/src/pages/account
git commit -m "feat(公司tab): 店铺管理与数据权限分组按公司筛(纯读;凭据按 id 出口补闸门;写侧归属不动并反向钉)"
```
⚠️ `SourceScan.java` 是新建文件、`git add` 漏了它 ⇒ 本地全绿、别人拉下来编译红(Task 12 Step 4 依赖它)。`git status --short` 收笔前确认它不在 `??` 里。
---
## Task 12: 接线 —— 日志管理(按 `uid` 成员集筛,麦象日志恒可见)
**先读这三条已确认现状(2026-10-04 实查,别再照记忆推):**
1. `AdminDeviceLogController` 的**全部 9 个端点**第一行都是私有的 `requireSuperAdmin(request)`(`controller/AdminDeviceLogController.java:152-159`,非超管 403「仅超级管理员可访问日志管理」)。⇒ 这一页**根本不存在非超管调用方**,12:3x 那类"读端点挂闸门误伤管理员"的形状在这里不成立;tab 对这页只是超管的视图过滤器。
(9 是逐行点 `@*Mapping` 数出来的:`/files:52`、`/content:70`、`/download:80`、`DELETE /{id}:93`、`/config:102`、`/devices:114`、`PUT /config/global:121`、`PUT /config/device:130`、`DELETE /config/device/{id}:142`。**spec §6.1 那句写的"10 个"是错的**,已同步改 spec;这条不是抠字眼——"9 个里有几个动了 operator"是 Step 4 那条反向钉的分母,分母错则断言漏。)
2. `DeviceLogService.page(source, uid, startDate, endDate, pageParam, pageSizeParam)`(`service/DeviceLogService.java:162`)把条件包在一个 `Function<Boolean, LambdaQueryWrapper<DeviceLogFileEntity>> wrapperBuilder` 里,**`selectCount` 与 `selectList` 共用它**(`:186`/`:190`)。⇒ 公司过滤必须加在 builder **内部**;加在外面任何一侧都会得到"total 与行集不同宽 = 分页错位"。
3. 现有 `uid` 条件就是单条 `qw.eq(DeviceLogFileEntity::getUid, uid)`(`:176`),而端点文档自己写着「未登录/采集机的行 uid 为空,不匹配任何 uid」——`DeviceLogFileEntity.uid` 是 `Long`(`:27`),麦象上报的行恒为 NULL。⇒ **这就是 §9.2 那条静默丢数的现场**:直接叠 `uid IN 成员集` 会把跟价机的日志从所有 tab 里抹掉。
**Files:**
- Modify: `backend-java/.../modules/devicelog/controller/AdminDeviceLogController.java:52-68`(`files` 接 operator + 算成员集 + 透传;`devices`/`content`/`download`/`delete` **不动**,理由见 Step 4)
- Modify: `backend-java/.../modules/devicelog/service/DeviceLogService.java:162-205`(`page` 加末位参数 `List<Long> memberUids`)
- Modify: `admin-frontend-vue/src/api/device-logs.ts`(query 带 `company_id`)
- Test: `backend-java/src/test/java/com/nanri/aiimage/modules/devicelog/service/DeviceLogServiceTest.java`(**已存在,追加**;它已有 `@BeforeAll TableInfoHelper.initTableInfo(... DeviceLogFileEntity.class)` 与 `service()` 工厂,四参构造 `new DeviceLogService(mapper, adminUserMapper, storage, properties)` **不用改**——成员集是从 controller 传进来的值,service 不需要新依赖)
**Interfaces:**
- Consumes: `DataReadScope.readScope(AdminUserEntity, Long)`(Task 6)、`com.nanri.aiimage.testutil.SourceScan`(**Task 11 Step 1 建的那支共用工具类,直接 import,别再切一份方法体**)
- Produces: `DeviceLogPageVo page(String source, Long uid, LocalDate startDate, LocalDate endDate, Long pageParam, Long pageSizeParam, List<Long> memberUids)` —— `memberUids == null` 表示不筛(超管没选公司),非 null 空集表示"只放行麦象行"
- [ ] **Step 0: 先定这页留不留在批次 1(只读取证)**
spec §11.1 给批次 1 的数量留了一个判据:日志管理这页值不值得进 tab,取决于麦象行占比。跑这条只读 SQL(同 Task 5 Step 0 的通道):
```sql
SELECT source, COUNT(*) FROM device_log_file GROUP BY source;
```
- 麦象占多数 ⇒ 公司 tab 只能筛掉小半边,"按公司看日志"这个诉求在这页基本落空 ⇒ **不声明 `companyScoped`,本批变 7 页**,同时把 `COMPANY_SCOPED_PAGES` 里那条删掉(G1 会跟着少一条正向断言——这是合法删除,不是"让红消失",两者区别见附A 最后一行)。
- 客户端占多数 ⇒ 留在批次 1,Step 1 起往下做。
- 结果抄进本任务的提交信息。**"0 命中"或只出一个 source 时先怀疑抓错表**:配一个 `SELECT COUNT(*) FROM device_log_file` 做非零对照(memory「grep -v 过滤器连 stdout 一起吞、0 命中≠没有」)。
✅ **已实跑(2026-10-05 15:1x,主机 A 业务库只读,非零对照齐全)**:`COUNT(*)` = **1028**;`GROUP BY source` = `client` **831** / `maixiang` **197**(831+197=1028,与对照逐数相符)⇒ **客户端占多数 ⇒ 这页留在批次 1,`companyScoped` 照声明,Step 1 起往下做**。另有一条本任务要用:`WHERE uid IS NULL GROUP BY source` = `client` **22** / `maixiang` **197** ⇒ 那 22 行是"有 source=client 但没有账号可归属"的一族,`(maixiang OR uid IN (成员集))` 那个形状照样会把它们抹掉 ⇒ Step 1 的用例要替它们说句话(放行还是接受消失,二选一写进附B,不许沉默)。
- [ ] **Step 1: 写失败的测试(这条测试的价值全在"麦象行不许消失")**
```java
@Test
@DisplayName("选了公司:客户端行按成员集筛,麦象行照常出现(uid 恒 NULL,叠等值就整类消失)")
void maixiangRowsSurviveCompanyFilter() {
when(mapper.selectCount(any())).thenReturn(1L);
when(mapper.selectList(any())).thenReturn(List.of(row(1024L, 2)));
service().page(null, null, null, null, 1L, 20L, List.of(11L, 12L));
AbstractWrapper<?, ?, ?> q = capturedCount();
assertThat(q.getSqlSegment())
.as("必须是 (source = ? OR uid IN (...)) 一整组,括号丢了就等于把麦象筛掉")
.contains(" OR ").contains("IN (");
// 值落在 paramNameValuePairs 里,不在 getSqlSegment() 里——别写成 segment.contains("maixiang"),
// MP 渲染的是 #{ew.paramNameValuePairs.MPGENVAL1},那条断言恒假。
assertThat(q.getParamNameValuePairs().values()).contains("maixiang", 11L, 12L);
}
@Test
@DisplayName("成员集为空:退化成只看麦象,不许渲染 IN () 打炸 SQL")
void emptyMemberSetFallsBackToMaixiangOnly() {
when(mapper.selectCount(any())).thenReturn(0L);
service().page(null, null, null, null, 1L, 20L, List.of());
AbstractWrapper<?, ?, ?> q = capturedCount();
// 只用 contains/doesNotContain:page 里还有 log_date >= ? 那条必带参数,
// 写 containsExactly(...) 会因为多一个 LocalDate 而恒红。
assertThat(q.getParamNameValuePairs().values())
.as("空集走 in() 会渲染出 IN (),MySQL 直接语法错;这里必须只看 maixiang")
.contains("maixiang")
.doesNotContain(11L);
assertThat(q.getSqlSegment()).doesNotContain("IN (");
}
@Test
@DisplayName("null = 不筛,保持今天的行为(超管没选公司时与上线前逐字一致)")
void nullMemberSetKeepsOldBehaviour() {
when(mapper.selectCount(any())).thenReturn(0L);
service().page("client", 7L, null, null, 1L, 20L, null);
AbstractWrapper<?, ?, ?> q = capturedCount();
assertThat(q.getSqlSegment()).doesNotContain(" OR ");
assertThat(q.getParamNameValuePairs().values()).doesNotContain("maixiang");
assertThat(q.getParamNameValuePairs().values()).contains("client", 7L);
}
@Test
@DisplayName("计数支与列表支必须同宽:total 与行集不一致就是分页错位")
void countAndListShareTheSameCondition() {
when(mapper.selectCount(any())).thenReturn(1L);
when(mapper.selectList(any())).thenReturn(List.of(row(1024L, 2)));
service().page(null, null, null, null, 1L, 20L, List.of(11L));
// 比 paramNameValuePairs 而不是 getSqlSegment():列表那支在 builder 外面又叠了
// orderByDesc(lastUploadAt)+orderByDesc(id)+last("limit o,s")(DeviceLogService.java:190-193),
// 两支的 segment 天生就不相等 ⇒ 断 isEqualTo(getSqlSegment()) 会红在排序上,而不是红在条件上。
// 条件同宽的正确锚点是"参数绑定序列逐字相同"——排序与 limit 不往 pairs 里塞值。
assertThat(capturedList().getParamNameValuePairs())
.as("total 与行集按不同条件算出来的 = 页码跳空/重复行")
.isEqualTo(capturedCount().getParamNameValuePairs());
}
```
**读法三条,都是这组用例能不能咬住实现的关键:**
1. `selectCount` **一定**被打到,`selectList` 只在 `total != 0` 时才打(`DeviceLogService.java:189-193` 的三元)。所以凡是"看生成的条件"的用例,要么把 `selectCount` 桩成 `1L` 再捕两支,要么直接捕 `selectCount` 那支——别写一个"selectCount 桩 0 然后断言 selectList 的 wrapper"的用例,它捕到的是 null,红在断言之前。
2. MP 把值放进 `paramNameValuePairs`,`getSqlSegment()` 里只有 `#{ew.paramNameValuePairs.MPGENVAL1}` 这种占位。⇒ **结构**(括号、`OR`、`IN`)从 segment 读,**值**(`"maixiang"`、`11L`)从 `getParamNameValuePairs().values()` 读。写成 `segment.contains("maixiang")` 是恒假断言(memory「字符串断言必须排他、解析断言必须可匹配」)。**同一条还有后半截:`paramNameValuePairs` 是惰性填的**——MP 3.5.7 把值装进 `() -> formatParam(null, val)` 这样的 lambda,只有 `getSqlSegment()` 被求值过一次,pairs 里才落值。所以凡断 pairs 的用例必须**先取一次 segment** 再读 pairs;反过来写(Task 12 实跑撞过)会拿到 `[]`,于是 `doesNotContain(...)` 恒真、`两支的 pairs 相等` 变成「两个空 map 相等」也恒真——尺子绿着,什么都没钉住。
3. `capturedCount()` / `capturedList()` 各用一个 `ArgumentCaptor<Wrapper<DeviceLogFileEntity>>` 捕(本文件已 import `ArgumentCaptor` 与 `AbstractWrapper`),捕获后 `(AbstractWrapper<?, ?, ?>)` 转型取 `getSqlSegment()`。`row(1024L, 2)` 用文件里已有的助手即可——这几条测的是**生成的 SQL 形状**,不是返回内容,所以不需要给行设 `source`/`uid`。
- [ ] **Step 2: 跑,确认红**
Run: `mvn -q test -Dtest=DeviceLogServiceTest`
Expected: 编译失败 —— 七参 `page` 不存在。这是预期红;若红在别的文件,先把它读干净再往下(不许为了绿而改断言方向,Global Constraint 13)。
- [ ] **Step 3: 实现(改 `wrapperBuilder` 内部,别改外面)**
`DeviceLogService.page(...)` 末位加参数 `List<Long> memberUids`(实查只有一个调用方——`AdminDeviceLogController.java:67`——所以**不需要**留六参重载;加了就没人用,是死参数)。在闭包里 `uid` 那条 `eq`(`:176`)之后插入:
```java
// memberUids:超管选了公司才非 null。麦象上报的行 uid 恒为 NULL,
// 叠等值会把跟价机的日志从每个 tab 里抹掉(spec §9.2),所以它必须走 OR 那半边。
if (memberUids != null) {
if (memberUids.isEmpty()) {
qw.eq(DeviceLogFileEntity::getSource, "maixiang");
} else {
qw.and(w -> w.eq(DeviceLogFileEntity::getSource, "maixiang")
.or(o -> o.in(DeviceLogFileEntity::getUid, memberUids)));
}
}
```
三点都要照做:
1. 放在闭包**内部**——`selectCount` 与 `selectList` 共用这个 `Function`,放外面只作用于其中一支,得到"total 与行集不同宽"的分页错位,而且不报错。
2. **不要**平铺成 `qw.or(...)`:MP 的 `or()` 不带 `wrapper ->` 时只接左半边,会把已有的 `source`/`log_date` 条件拆坏(与 Task 11 Step 3(c) 那条 `ShopManageGroupService.java:55-56` 同一个坑)。
3. 空集单独走 `eq(source,'maixiang')` 分支——别赌 `.in(column, 空集合)` 的 MP 行为,它渲染出的 `IN ()` 在 MySQL 是语法错。空集的处置是"只看基础设施日志"而不是"整页空",这是 §12 第 2 条"默认不筛比默认丢日志安全"的落点。
`AdminDeviceLogController`:把 `requireSuperAdmin(request)` 的返回类型从 `void` 改成 `AdminUserEntity`(它本来就取了 `adminAuthSupport.requireAdmin(request)`,现在只是把已经拿到的东西传出来),`files(...)` 加参数 `@RequestParam(name = "company_id", required = false) Long companyId`:
```java
AdminUserEntity operator = requireSuperAdmin(request);
ReadScope read = dataReadScope.readScope(operator, companyId);
List<Long> memberUids = read.isUnfiltered() ? null : read.userIds();
return ApiResponse.success(
deviceLogService.page(source, uid, startDate, endDate, page, pageSize, memberUids));
```
`requireSuperAdmin` 一共 9 个调用点(实查行号 66/76/84/97/106/117/125/137/145),**只有 `files` 那一处(`:66`)需要接住返回值**,其余 8 处本来就丢弃它、一行都不动;它内部那句 `log.warn("[device-log] 非超管访问日志管理被拒 ...")` 保持不动。
- [ ] **Step 4: `content`/`download`/`delete`/`devices` 刻意不加公司闸门(写明理由,免得下一个人"顺手补上")**
- `content`(`:72`) / `download`(`:82`) / `delete`(`:95`) 按 `fileId` 动单行。这页只有超管进得来,列表已不含别家成员的行;按 id 的端点再判一次公司**只会误伤 `uid IS NULL` 的麦象行**——那是排障现场,不是越权面。**这里刻意不做行级闸门**,和 Task 8 的 `detail`/`download-zip` **必须**做闸门是两回事:那两页有 `requireAdminOrInternal` 的非超管/内部通道,这页没有。
- `devices`(`:114` → `DeviceLogService.recentDevices():213`) 是 `GROUP BY source, device_id` 的去重列表、喂给「终端采集覆盖」选择器,行上没有账号归属,筛不动也不该筛。
- 这两条决定不写进注释,写进一条实跑用例的 `@DisplayName`:
```java
@Test
@DisplayName("按 fileId 的端点与 devices 刻意不收 company_id:这页无超管外调用方,收了只会误伤麦象日志")
void singleFileEndpointsStayUnscoped() {
String text = SourceScan.sourceText("AdminDeviceLogController.java");
assertThat(SourceScan.methodBody(text, "content")).doesNotContain("dataReadScope");
assertThat(SourceScan.methodBody(text, "download")).doesNotContain("dataReadScope");
assertThat(SourceScan.methodBody(text, "delete")).doesNotContain("dataReadScope");
assertThat(SourceScan.methodBody(text, "devices")).doesNotContain("dataReadScope");
assertThat(SourceScan.methodBody(text, "files")).contains("dataReadScope"); // 取样非空自检
}
```
`SourceScan.methodBody` 是 Task 11 Step 1 建的那个共用工具类(`com.nanri.aiimage.testutil.SourceScan`),**本任务直接 import 它,不许再切一份**。`methodBody` 找不到方法会抛 `AssertionError` ⇒ 反向钉不会因为方法被改名而悄悄恒绿;**不许用全文 `contains`**——那会因为 `files` 里出现一次而四条全部恒绿。
- [ ] **Step 5: 前端带参**
`src/api/device-logs.ts` 的列表 query 构造处加 `if (params.companyId != null) q.company_id = params.companyId`(形状同 Task 8 Step 5,值由页面组件传入,不在 api 模块里裸调 Pinia store)。日志页组件加 Task 7 Step 5 那条 `watch`。
- [ ] **Step 6: 跑两支全量 + 提交**
```bash
mvn -q test 2>&1 | tail -10
node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit
git add backend-java/src/main/java/com/nanri/aiimage/modules/devicelog backend-java/src/test/java/com/nanri/aiimage/modules/devicelog admin-frontend-vue/src/api/device-logs.ts admin-frontend-vue/src/pages
git commit -m "feat(公司tab): 日志管理按 uid 成员集筛,麦象行走 OR 不被筛掉"
```
- [ ] **Step 7: 确认 G1 全套转绿**
Run: `node --test tests/company-tab-wiring.test.ts`
Expected: 全 PASS(8 个页的正反两向都对上了)。若还有红,**说明某页只改了注册表或只改了 api 文件**——那就是 §6.1 的"半套",不许靠把该页从清单里删掉来让它绿。
---
## Task 13: 变异自证 + 发布与人工验收
**Files:**
- Create: `backend-java/docs/mutation-company-tab.md`(变异台账,照 `docs/` 既有惯例放正式目录,不塞 gitignore 的 tmp)
- [ ] **Step 1: 七支护栏各配一个注入点,逐条验它真的会红**
| 护栏 | 注入 | 期望 |
|---|---|---|
| G1(`company-tab-wiring.test.ts`) | 从 `COMPANY_SCOPED_PAGES` 删一行 / 从一个 api 文件删掉 `company_id` | 两支各红一条 |
| G2(`CompanyIdParamGoesThroughReadScopeTest`) | ① 把某 controller 的 `readScope(` 换成裸 `eq`;② 把某处的 `@RequestParam(name = "company_id")` 改成 `@RequestParam Long companyId`(驼峰静默失效的形状) | **两支各红一次**;② 特别要做——它注入后接口仍然 200、页面看不出异常,只有这条扫描会红 |
| G3(`DataReadScopeTest`) | 把"非超管传别家 → 空集"改成"忽略参数" | `adminPassingForeignCompanyGetsEmptyNot403` 红 |
| G4(`PermissionCompanyMenuHiddenTest`) | 三个出口里注释掉任意一处 `SUPER_ADMIN_ONLY_KEYS` | 红 |
| G5(`CompanyReadPathMenuGateTest`) | 让 `listVisible` 退回非超管可 | `hasSize(3)` 红 |
| G6(`CompanyScopeSupportTest`) | 把 `MEMBER_WARN_THRESHOLD` 改成 `Integer.MAX_VALUE` | 哨兵用例红 |
| **G7**(反向钉五支:`company-user-create` / `company-user-list:66` / Task 11 Step 1 第四支 / Task 12 Step 4 那条 / Task 7 Step 7 第 4 条) | ①给 `ShopManageController.create` 加一个 `company_id` 参数;②给 `AdminDeviceLogController.content` 加 `dataReadScope`;③把 `CompanyTabs.vue` 里加回一支 `<span class="company-tab-hint">当前公司:…</span>`;④从 8 条引导文案里任意删掉那句"超级管理员可用页面上方的公司 tab 切换公司" | **各红一条**。③④ 各打在那支的两半上(③红反向那半、④红分母那半——所以一支用例里必须**两半都做变异**,只做③会让"文案其实没落地"看不出来)。G7 天生恒绿,所以它的变异**必须先做**:不做变异就不能声称钉住了(memory「护栏要做进代码出口」+「字符串断言必须排他」) |
### Step 1b:执行期补的注入点(Task 8-12 评审累积,跑 Step 1 之前先落 ① 那条新守卫)
| # | 注入 | 期望 —— 以及"如果没人红"意味着什么 |
|---|---|---|
| ① | 把 controller 传给 `readScope(operator, companyId)` / `resolveScope(request, companyId)` 的**实参**从 `companyId` 改成 `null`(绑定与 `readScope(` 都还在) | **今天七支尺子全杀不掉**:G1 只看前端文件;G2 的 A/B/C 只问"`readScope(` 在不在、`@RequestParam(name = "company_id")` 字面量在不在、那个变量的值有没有被喂进某支调用"——传 `null` 三条都还满足。症状是切 tab 一动不动、接口 200、`sqlUserIds()` 交 `null`。⇒ **先给 G2 加一条 D**:`readScope(` 的单层括号实参表里必须出现从 `@RequestParam(name = "company_id")` 绑来的那个变量名(`null` 字面量不算)。加完 D 再注入 ⇒ 期望红;不注入的对照轮 ⇒ 期望绿。**这条是 8 页共用的一处形状,不是本页的事**,所以它排在变异轮前面 |
| ② | `ShopManageGroupService.list` 里两处平铺:把 `qw.and(w -> w.in(getCreatedById, companyMemberIds))` 改成 `qw.in(...)`;或把 `and(w -> eq(createdById).or(x -> eq(userId)))` 改成平铺 `.eq().or(...)` | 各红 `ShopManageGroupServiceTest.groupListWrapsTheOrBeforeNarrowing`(结构断 `getSqlSegment()`、值断 `getParamNameValuePairs()`)。这是 Task 11 评审 I-1 那支新用例的自证——**没做过这轮变异就不许声称括号被钉住了** |
| ③ | 删掉 `ShopManageController.page` 签名里的 `@RequestParam(name = "company_id")` 整条参数,但**留着** `@Operation` 描述里那句"company_id 只收窄可见集" | 期望红 `writeEntryPointsCarryNoCompanyId` 的取样自检(本轮锚点已从 `contains("company_id")` 换成 `contains("@RequestParam(name = \"company_id\"")`)。若锚点退回旧写法 ⇒ 这条注入恒绿,正是评审 I-2 说的"文案满足断言" |
| ④ | 删掉 `fetchTaskCenterOverview` / `fetchTaskCenterShopOptions` 新补的第二个实参 `{ params: query }`(把 `http.get(url, { params })` 改回 `http.get(url)`) | G1 **看不见**:它按文件文本查 `company_id = companyId`,那串还在。⇒ 本轮给 `task-center` 补一支用例断"`http.get(` 之后必须跟着带 `params` 的第二实参",否则症状是"前端发了、URL 里根本没有",而接口照样 200 |
| ⑤ | 删掉任一**新增**用例的 `@Test`(保留 `@DisplayName` 与方法体) | **没有任何尺子会红**:方法体还在、G1 的文本断言还在,只是 surefire 不再跑它 ⇒「1726 例全绿」与"那支根本没跑"同形。新增人工步骤:**本轮新建/改动的每个测试文件,`grep -c "@Test"` 必须等于 surefire 该类 `Tests run:` 的数**(Task 11 已对齐:`ShopManageServiceTest` 8=8、`ShopManageGroupServiceTest` 3=3) |
| ⑥ | 页面侧 reach:删掉某页组件里的 `watch(() => companyTab.activeId, …)`,或把 `companyTab.requestCompanyId` 换成 `companyTab.activeId` | 各红 G1 正向那支的两半(原表 G1 行只写了"从 api 文件删 `company_id`",没覆盖页面侧;这是 Task 9 评审 I-3/I-4 的账)。`activeId` 那一刀只有当 store 里 `requestCompanyId` 与 `activeId` 语义不同才会红——先确认这两者在「默认第一家、不允许全部」下是否恒等,若恒等则这条要改成注入"删掉 getter 调用" |
十二条硬规矩(以 memory「变异自证脚本的十二条硬规矩」为准,本段原文写的「八条」是旧的;第十二条对本轮尤其致命——摘要解析要锚 `failed` 这个词,`^(\d+) (failed|passed)` 那种取第一个数字的写法会把 `2 passed` 读成"抓到了")逐字执行:每轮开跑前把被注入文件**写回 pristine**(还原只认注入前读进内存的字节,**不许 `git checkout`**——这个仓库有另一个会话在并行提交,`checkout` 会把你不认识的在飞改动一起抹掉,17:0x 那三笔就是这么进来的);CRLF 锚串先对齐行尾;分母只认本轮扫描结果;变异点若落在 mock 边界外必然存活,遇到"注入后仍绿"先判是不是注入根本没被执行到。
- [ ] **Step 2: 出包与发布(顺序不可颠倒)**
```bash
# 批次 0(Task 1-4):admin-vue 先上,复验后 jar 才上
# 批次 1(Task 5-12):jar 先上两台同版,复验后 admin-vue 再上
```
逐节点复验走主机 B 的 `127.0.0.1:19080`(**不是** `0.0.0.0:18080` 轮询池);admin-vue 用整树聚合摘要核"线上==本地构建"。
⚠️ **批次 1 的 jar 会把 V145 一起带上去,这是必须显式决定的一件事**(不是默认):V145 已在 `b7873209` 提交,但线上 jar 仍是 `e42b37c1…`、Flyway 停在 144。按 memory「要不要重启是可判定的」那条算一次差分:
```bash
git diff --name-only e42b37c1..<本批次构建的commit> -- backend-java/src/main 'backend-java/src/main/resources/db' | wc -l
```
只要结果里含 `V145__brand_dedupe_company_scope.sql`,这一版 jar 一启动就会**在生产应用 V145**(两张规则库表补 `company_id` + 唯一键改每公司一套)。而二期 §13 记着"消费侧 Task 3–8 已叫停 ⇒ 跨公司串扰仍在发生"——也就是说迁移上了、消费端还没上。两个选择,**由用户定**,本计划不自决:
| 选择 | 做法 | 代价 |
|---|---|---|
| A(默认,最小半径) | 批次 1 的构建树用 `git worktree` 从"Task 12 最后一笔但不含 V145"的提交拉出来——**实际做不到**,因为 V145 在历史里更早(`b7873209` 是 `00e5df02` 的后代)。真要做只能 `git revert b7873209` 出一个临时提交 | 反悔成本高、易出错;不建议 |
| B(推荐) | 让 V145 随批次 1 一起上,但**上线前**把二期的回滚脚本 `backend-java/docs/rollback-V145-company-scope.sql` 读一遍确认它仍是可执行路径,并把 §11.2 四条 SQL 在 V145 之前先跑一次留底 | 消费侧未上线 ⇒ 串扰窗口延长到批次 2/3;V145 本身是加列+改唯一键,属前向兼容 |
> 若用户选"这次不带 V145",那批次 1 的 jar 就不能从 `master` 直接构建——**这件事必须在出包前说清并留下书面决定**,别到启动日志里看到 `Migrating schema … to version 145` 才发现。
- [ ] **Step 3: 人工实跑清单(`mvn test` 验不到生产长什么样,这批必须实跑)**
1. **非超管回归**(批次 0 的账):一个 admin 账号登录 → 侧边栏无「公司管理」→ 直接手输 URL `/admin-vue/account/companies` 被弹回首屏 → 「用户管理」正常打开且 Network 无 `/api/admin/companies`。
2. **越权实验**(G3 的真身):非超管带 `?company_id=<别家>` 请求 `/api/admin/user-secrets` → **200 + 空列表**,不是 403、不是别家数据。
3. **tab 有效性**:超管切公司,八页各切一次,行数必须变;`overview` 计数与列表行集同宽(Task 10 Step 4 那五个端点如果漏了一个,这一步会露出来)。
4. **写归属按 Task 11 Step 4 的口径实测(这条的预期与直觉相反,而且**建号与店铺两件事要分开验,别用一条验收覆盖两页**)**:
- **建号**:超管切到第 2 家 tab 建一个账号 → 查库确认新账号 `company_id` 是**1**(超管自己那家),没跟着 tab 走 —— 这是设计(`AdminUserService.resolveTargetCompanyId`,spec §6.3)。
- **店铺**:⚠️ **这页的预期完全不同**。店铺的 `created_by_id` 来自请求体(Task 11 Step 4 那条更正),所以"新建店铺的归属跟着 tab 走吗"这个问题问错了。要验的是两件事:① 负责人选超管自己 ⇒ `created_by_id=超管`、这家账号所属公司为 1;② 负责人选 `users.id=1193` ⇒ 店铺**就归第 2 家**(今天已经能做,本轮没改它)。**别把 ② 报成"tab 生效了"**,那是负责人字段生效,与 tab 无关。
- 两条都要再验一次"切 tab 不改变上述任何一条"。测完删掉测试行(只交付命令,用户执行)。
5. **凭据读出口按会话收窄**(Task 11 Step 3(d) 的账,这条 `mvn test` 验不到)。⚠️ **2026-10-05 执行时订正原预期**:原写「超管切到第 2 家 tab → 按 id 请求 ⇒ 403」,实现做出来是**另一件事**,而那一件才是 §6.1 要的。理由:`adminCredential` 若靠调用方自己带 `company_id` 才收窄,**不带参数的请求就绕过闸门**——而按 id 读明文密码的越权面,越权的人本来就不会替你把 tab 的公司 id 带上;那等于"只拦老实人"的装饰,落进 memory「护栏要做进代码出口」的反面。本仓已有的范形是 Task 8 的 `AdminImageVideoTaskController.detail/download-zip`:私有 `scopeOf(operator)` = `readScope(operator, null)` ⇒ **超管不筛(tab 不是安全边界,Constraint 2),非超管与内部令牌按其可见成员集收窄**。⇒ 这条验收改成两读:① 用一个**主管**账号(不是超管)从 Network 里取一个不属于它可见集的店铺 id 请求 `GET /api/admin/shop-manages/<id>/credential` → **403**,不是 200 + 明文密码;② 超管在**任意 tab** 下同一请求必须 **200**——若这里红了,说明闸门被写死成"非当前 tab 全禁",那是回归不是收紧。③ 顺手确认这条**没有**波及 `GET /credential?shopName=`(4.0.44 客户端与 Python 自动化走的那条,本轮刻意不动)。
6. **麦象日志不消失**(Task 12 的账):切任意公司 tab,日志管理里 `source=maixiang` 的行必须还在。⚠️ 生产只读实测(10-05,`device_log_file` 共 1028 行):`client` 831 / `maixiang` 197,**但 `client` 里有 22 行 `uid IS NULL`**(22/831=2.6%)——这 22 行按「`source='maixiang' OR uid IN (成员集)`」的形状仍会被筛掉,Task 12 要么给它一条同族的"无法归属"放行腿,要么在附B 里明写这 22 行在各 tab 下消失是设计。
7. **保存权限不炸**(Task 4 的账):给一个历史带 `admin_companies` 授权的账号保存一次权限 → 成功 + 日志 `GRANT_SUPER_ADMIN_ONLY_STRIPPED`。
8. **文案这三眼看**(§9.3 / §5 的账,`node --test` 只能验"字符串在不在",验不到"读的人怎么理解"):①超管在任意一页看到引导条那句"超级管理员可用页面上方的公司 tab 切换公司"时,tab 条**确实在它上方**(Task 7 Step 4 挂的是 `</el-breadcrumb>` 与 `<OperationGuide />` 之间,顺序反了这句话就指错了方向);②引导条被收起过的人看不见这句——找一个 `localStorage.shufuAdminGuideCollapsed='1'` 的浏览器确认这不是硬伤,并在运维手册里说明这句的位置;③非超管账号读同一句时不会去找那个他根本不会有的控件(这句以"超级管理员"开头就是为这一步,若真读着别扭,改法是加 `isSuperAdmin` 分支而不是改回祈使句)。
- [ ] **Step 4: 更新两份文档 + 清掉我自己留下的临时件**
- `docs/ops/company-tab-design-2026-10-04.md` 顶部状态改「已实施(批次 0-1)」,并把 §12 第 1 条的实际取舍(V145 带没带上、谁定的)补一句。
- `docs/plans/` 里新开批次 2/3 的计划占位(只写前置闸门:§11.2 四条只读 SQL + 二期 V145 落地),**不写任务**——没有取证结果就写任务必然编造(writing-plans 的 No Placeholders)。
- 删 `backend-java/tmp-probe.txt`(我 11:47 为取 V145 生产现状留的探针,无引用;删前 `git grep tmp-probe` 确认 0 消费者)。**不要**碰 `tmp/c8-build`——那是真 worktree。
```bash
git commit -m "docs(公司tab): 批次 0-1 出厂记录 + 批次 2/3 前置闸门占位"
```
---
## 附 A:只能同批改的配对(滞后一条就是线上事故)
| 配对 | 为什么不能拆 |
|---|---|
| 批次 0 的 admin-vue 上线(现网那版早于 `85e1e92a`,仍在调公司目录)↔ Task 3(后端读端点 403) | 顺序反了 = 15 个管理员开「用户管理」即 403 → 整页踢回登录页(12:3x 原样重演);现网到底还调不调,由 Task 2 Step 4 的取证定,但**顺序本身不变** |
| Task 4 Step 5(剥离而非 403)↔ 保存权限这条链 | 整树提交里带一条历史授权就 403,会让"改密码/建号"整体回滚(09-16 的形状) |
| Task 10 Step 3 的 `allUsers=false` ↔ `USER_SCOPE_T/B` 的 `<if test='userIds != null'>` | 选了公司还给超管留 `allUsers=true` ⇒ `sqlUserIds()` 交 `null`、整段条件不渲染,**切 tab 什么也不发生且全程 200**。(草稿原先把这条写成"空集直传 = `IN ()` 语法错",实读 `ScopeContext.sqlUserIds():79-86` 后发现空集早被折成 `[-1]`,已更正——见 Task 10 Step 3 的 ⚠️) |
| Task 10 Step 5 的 `fetchTaskCenterTaskDetail` 带 `company_id` ↔ `tasks/detail` 的 `scope.visible()` | 详情不走 SQL 而走 Java 行判,api 少这一支 ⇒ 超管在别家 tab 下按 `taskNo` 读到别家详情,列表侧却是窄的,两边不同宽 |
| `company_id` 这一个拼写 ↔ `TaskCenterTaskQuery` 的驼峰字段绑定 | 对象绑定按字段名收参数,加 `companyId` 字段就得让前端发 `companyId=`;两种拼写并存时那支的参数被静默丢弃,症状是"看板窄了、列表没窄"(Task 10 Step 4 因此规定五支一律显式 `@RequestParam(name = "company_id")`) |
| Task 11 Step 3(c) 的 `and(w -> eq().or(x -> eq()))` ↔ 分组列表叠公司 | MP 的 normal 段按声明顺序拼:平铺的 `created_by_id = ? OR (user_id = ?)` 后面再 `AND created_by_id IN (…)`,MySQL 里 AND 优先 ⇒ **左半边整块逃出筛选**。症状是多放行、不报错、单测不看括号就发现不了 |
| Task 8-12 的列表读筛选 ↔ 同页按 id 的出口(`detail`/`download-zip`/导出/`/{id}/credential`) | 只筛列表 = "看不见但按 id 能读能下载",那是越权而不是收窄(spec §6.1;刻意**不**配的是写侧归属,见 spec §6.2) |
| Task 11 Step 3(a) 的 `page` 末位新参数 ↔ 它唯一的生产调用方 `ShopManageController.java:73` ↔ `ShopManageServiceTest` 里**已有**的 `service.page(...)` 调用 | 六参改七参是**编译期**断,但断在三处:controller、本任务新用例、该文件里跟本轮无关的老用例。只改前两处 ⇒ `mvn -q test` 红在老用例上,看起来像别人引入的回归 |
| Task 11 Step 3(d) 的 `getCredentialById` 加参 ↔ `ShopManageController.java:181` ↔ `ShopManageCredentialAuthTest` | 同一类编译断。那支测试测的是**另一条**端点(`getCredentialByShopName`),容易被当成"与本轮无关的红"跳过——它是相邻端点,改 `adminCredential` 时必须回来跑 |
| Task 11 的凭据闸门(只补 `/{id}/credential`)↔ **不**补 `/credential?shopName=` | 两条凭据端点今天都没有归属校验,但只有按 id 那条的调用方是后台账号(有 operator 可推);按名字那条的调用方含内部令牌与**客户端登录用户**(`requireUser`),那里推不出"操作者公司",硬加会把跟价机整片打停。**同页两个端点、两种处置**必须写在这张表里,否则下一个人会"顺手补齐" |
| Task 12 Step 3 的 `(maixiang OR uid IN …)` ↔ 该页的 `source`/`log_date` 既有条件 | OR 平铺不加括号会把已有条件拆成只作用于左半边(同 `ShopManageGroupService.java:55-56` 那一族) |
| Task 7 Step 7 给 `admin_group_manage` 立独立文案 ↔ `align-operation-guide.test.ts:28-31` 那支 `deepEqual(FALLBACK)` | 只改一处必红:改了文案不动测试 ⇒ 该支红;只动测试不改文案 ⇒ 新支(分母取注册表)红。这两支是同一件事的两半,不许分两条提交 |
| C 类两页的 `companyScoped: false` ↔ 那两句"不参与"文案 | 分两处改就各有一半没人管:只写 `false` ⇒ 超管切 tab 时这两页纹丝不动、看起来像坏了;只补文案 ⇒ 声明仍是隐式的,下一个人加页时抄不到"要不要写 false"。两支用例(Task 1 Step 1 的注册表那支 + Task 7 Step 7 第 4 条的 C 类循环)各钉一半,所以**必须同批** |
| `company-tab-wiring.test.ts` ↔ `COMPANY_SCOPED_PAGES` 的删除动作 | 让某页不红的最省事做法是把它从清单删掉——**那是把护栏改成谎**。红就补接线 |
## 附 B:已知不做(别顺手加)
- 不给 `biz_shop_manage`、`biz_shop_manage_group`、`biz_query_asin` 等表加 `company_id` 列(全程派生;只有二期两张表是破例)。
- 不做跨公司汇总/对比报表、不加「全部公司」tab(§12 需求 2 的直接代价,spec §4 已记账)。
- 不做 http 层中央注入 `company_id`(会让 C 类页也带上参数)。
- 不动 `UserDataScopeSupport` 的分组口径、不重写它的 `FALLBACK_LIMIT=2000` 兜底逻辑。
- 不给商品类目/店铺密钥做任何公司化(含"临时用 group 推一下")。本批只给这两页落 §5 的两件轻件:`companyScoped: false`(Task 1 Step 4)与"全平台共享,不按公司区分"那句文案(Task 7 Step 7 第 5 条)——**声明不参与 ≠ 公司化**。
- **不新增任何界面暴露**(Global Constraint 14 / spec §12 第 5 条):不给列表加"所属公司"列、不给弹窗加公司或"按公司收窄的负责人"下拉、不做页头"当前公司"提示控件(这一条已由 Task 7 Step 7 第 4 条钉进代码,不再只是注释)。这类要做先要一次单独授权,做完得配 G7 那样的反向钉。
- **写请求体一律不收 `company_id`**(spec §6.2):三个页的写入口本轮一个参数都不加。⚠️ 但"归属由后端从操作者推导"这半句**只对建号成立**:店铺的 `created_by_id` 今天来自**请求体**(`ShopManageService.java:86` 读 `request.getCreatedById()`)⇒ 店铺归属由"负责人"决定、与 tab 无关(Task 11 Step 4 与 spec §6.3 都已按这条订正)。
- **不改 `created_by_id` 的可写性**:不给它加"必须是操作者同公司成员"的校验。那是会 403 现有调用方的行为变更,且超管不在别家的成员集里 ⇒ 加了反而让超管没法把店铺挂到别家名下(今天能做)。
- **不补 `/credential?shopName=`(`getCredentialByShopName`)的归属校验**:一期就有的跨公司读点,调用方含内部令牌与客户端登录用户,那里推不出"操作者公司"。本轮只补 `/{id}/credential`(理由见 Task 11 Step 3(d) 那条 ⚠️ 与附A)。要修它是单独一张工单。
- **不补密钥管理页那两支按 id 的写出口的归属闸门**:`POST /api/admin/user-secrets/{userId}/check` 与 `DELETE /{userId}`(`AdminUserApiSecretController:72-89`)把 `requireAdmin(request)` 的返回值直接丢掉,service 侧 `adminCheckByUser(userId)` / `adminClearByUser(userId)` 不收操作者 —— 一期就没有闸门。本轮把那页的**读**接进公司 tab 之后,它成了同一页里唯一还开着的越权写点(别家管理员可一键清空任意 userId 的密钥,`check` 还会真打 LLM 与代理配额)。补它 = 给写侧加一条会 403 的校验,属未批的行为变更 ⇒ 单独一张工单。(Task 9 评审 I-1,2026-10-05 记)
- **不重写 `listAccessibleGroupIds` / `listAccessible`**:非超管的分组可见口径不动(spec §13)。⇒ 本计划对非超管的跨公司保证,只在**真正经过 `DataReadScope` 的那几支列表**上成立,是**部分强度**(与二期 §9.4 同词)。验收时别把它说成"非超管已按公司锁死"。
- 不做"tab 值进 URL / 可分享链接带公司上下文"(spec §12 第 4 条)。
- **生产里已有 4 行归属不到任何公司,上 tab 后它们在**每一个** tab 下都不出现(代码本轮不改,只能走数据)**:
2026-10-05 16:5x 主机 A 业务库只读实查(通道 `scripts/_prod_watch.py:171 db_sections`,非零对照齐全)——
`biz_shop_manage` 共 **86** 行,其中 **2** 行的 `created_by_id` 指向已不存在的账号(id **85** 店铺「鲍丽明」→ 账号 66、
id **86**「傅旭东」→ 账号 45,两行都挂在 `group_id=2`);`biz_shop_manage_group` 共 **12** 行,其中 **2** 行
`created_by_id IS NULL`(id **2**「周丽娥」、id **3**「郭亚芳」)。可归属分解:店铺 company 1 → 84(84+2=86 逐数相符),
分组 company 1 → 9、company 2 → 1(9+1+2=12 相符);`company` 表 3 行(1 厦门米椿花 / 2 德阳-团队 / 3 先锋-团队)。
⇒ 症状是**收窄顺手做出的静默删除**,不是权限修复:这 4 行在"还没有 tab 的今天"对超管可见,上了 tab 就哪家都不出现。
**为什么不放宽闸门**:给"归属不到"的行放行等于让它在家家 tab 都可见,与 tab 的语义正相反;把闸门退回全量等于撤销本批目的。
处置只有两条,都由用户决定:① 把这 4 行的 `created_by_id` 归到在职账号名下(`UPDATE`,我只交付命令不执行);
② 接受这 4 行只存在于库里、界面上不再出现。**注意这两行的凭据仍可按 id 读到**(超管走 `superAdmin` 短路、
`/{id}/credential` 不收 tab),所以"看不见"不等于"读不到",验收时别把这两件事混报(Task 11 评审遗留项,已取证)。
- **日志管理那 22 行 `source='client'` 且 `uid IS NULL` 的匿名客户端日志:选了公司就不出现(定案 (a),代码刻意不加 `IS NULL` 那条腿)**:
2026-10-05 15:1x 主机 A 业务库只读实查 `device_log_file` 共 **1028** 行(`client` **831** / `maixiang` **197**),其中 `uid IS NULL` 的
`client` **22** 行(22/831 = 2.6%,22/1028 = 2.1%)⇒ `(source='maixiang' OR uid IN (成员集))` 这个形状会把它们抹掉。
**为什么不放行**:麦象那 197 行能进每一家 tab,前提是它是**平台自己的采集机**(基础设施,不属于任何一家);这 22 行的性质是"桌面端没登录",
它们是某家的资产、只是没有账号替它们认领。给它们加一条 `uid IS NULL` 腿 = 让同一条**无归属**行在家家 tab 各出现一次,那是错的归属,
并且把"这家有多少条日志"这个数变成不可用;而且 `uid IS NULL` 对将来任何新来源同样成立(今天钉 22 行,明天就是"凡没账号的都全局可见")。
**代价要说比例,别只说"仍拿得到全量"**:① 这 22 行**在界面上点不回来**——tab 条按 §12 第 2 条没有「全部公司」那一枚,默认落在 `id` 最小的启用公司;
② 兜底只在后端成立:`GET /api/admin/device-logs/files` 的 `company_id` 是 `required = false`,不传 ⇒ unfiltered ⇒ 一条条件都不叠
(`nullMemberSetKeepsOldBehaviour` 钉着),要看全量只能走接口、不能走这页的界面;③ 这页 9 支端点全在 `requireSuperAdmin` 之后,
**不存在超管之外的读者**,所以"消失"是过滤器效果,既不是越权面收窄、也不影响任何账号的日常使用。
若将来要让它们在界面上可见,正路不是加 SQL 腿,而是给 tab 条补一枚「全部公司」⇒ 那是 §12 第 5 条**未批**的界面暴露,要单独授权。
(Task 12 定案,2026-10-05 记;钉住这个形状的实跑用例是 `DeviceLogServiceTest.anonymousClientRowsFallOutOfEveryCompanyTabByDecision`。)
- 不碰二期的 V145 迁移文件(已在 `b7873209` 提交,本计划不改它、不替它决定上线时机——上线时机是 Task 13 Step 2 那条要用户拍板的显式决定)。