Files
crawler-plugin/docs/plans/19-company-tab.md
T
huangzd1997 aef7906951 docs(公司tab): 把两轮实测出来的「MP 白送最外层括号 ⇒ contains("(列名") 恒真」写成第 4 条读法
Task 11 修复轮 2 与 Task 12 修复轮 1 各撞一次同一族的恒真判据,教训是同一条:
`NormalSegmentList.childrenSqlSegment()` 无条件给整段 WHERE 套一对括号 ⇒ 平铺实现照样含开头的 `(`,
所以 contains("(created_by_id")/contains("(source =")/lastIndexOf("AND (")>indexOf(列名) 都在
"它声称要防的形状"上恒真。判据要么数到第二对括号 + doesNotContain(") OR "),要么脱敏后整串逐字比对
(字面量只认实跑打印,脱敏函数自带"占位符一个不剩"自检)。
顺带回写三处执行期订正:分组侧整串 ((created_by_id = ? OR (user_id = ?)) AND (created_by_id IN (?))) ORDER BY id ASC、
店铺侧非超管那块可见集从没被任何用例渲染过(平铺实测 8 例全绿)⇒ 新用例与其整串、
日志管理 maixiangRows/companyFilterStacks 两支的第二对括号锚串(REAL-1/REAL-2 原文)。
整串比对绑死 MP 渲染形态 ⇒ 升级会假红不是假绿,这条代价写进正文。
2026-10-05 19:18:04 +08:00

209 KiB
Raw Blame History

公司 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 仓库与工作区状态

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)
cd admin-frontend-vue && npm test 2>&1 | tail -5

Expected: # fail 0。记下 # pass <N>,写进本计划最后一笔的验收说明——后面任何一次对比都用这个 N,不用记忆值。

  • Step 3: 实测后端基线
cd ../backend-java && mvn -q test 2>&1 | tail -20

Expected: BUILD SUCCESS,Failures: 0, Errors: 0。不许与 Nuitka 打包并行。

  • Step 4: 把两个基线数字记进提交信息

后续每个任务的"全量绿"都是与这两个数字差分,不是绝对句。

  • Step 5: 先把设计文档与本计划入仓(第一笔,动任何代码之前)

这两份文件现在还是 untracked。实施的第一笔就是它们,理由是后面 12 个任务都要引用 § 编号——不在仓里,引用就是悬空的。

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:

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:

/** 公司口径的唯一清单(设计文档 §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:

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 之后补:

  if (page.superAdminOnly) meta.superAdminOnly = true

并把 AdminPageMeta 的 meta 局部类型从 Record<string, string> 改为 Record<string, string | boolean>(superAdminOnly 是布尔,原类型会在 vue-tsc 下报错)。

  • Step 5: 剪枝纯函数

src/router/helpers.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 之前插入:

  // 角色内在闸门:与菜单树无关。超管恒 true 会让"只剪菜单树"这条对超管无效,
  // 而非超管即使被历史授权过 admin_companies 也进不来(spec §8.1:两处缺一处就留旁路)。
  if (to.meta.superAdminOnly && !session.isSuperAdmin) {
    return session.firstVisible || '/'
  }
  • Step 7: store 单点剪枝

src/stores/admin-session.ts:30 改成:

        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: 提交
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: 先读那三支已经存在的反向钉,确认它们钉的就是"不得回流"

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:

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"的形状。这条取证决定的是紧迫性,不改变顺序本身:

# 只读公开链:取现网入口 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: 提交

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 整个替换为

    @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 替换为

    /**
     * 回归用例(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 改为:

    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: 全量 + 提交
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: 前置只读取证(这条决定本任务的行为变化幅度,只交付命令、由用户执行)

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(源码扫描两支):

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 类顶部字段区加:

    /** 角色内在闸门菜单:非超管看不见、谁也授不出去(设计文档 §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 时保留,让「菜单管理」页仍能管理这一行):

        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:

        // 非超管:即使历史上被授过 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 不抛:

        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 系列不新增红。

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「生产环境接入要点」的只读通道,不要自己另开一条):

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: 追加失败的测试
    @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(现无)与:

    /** 超过这个成员数就该把 `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)
    @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())),并加:

    static boolean shouldWarn(int size) {
        return size > MEMBER_WARN_THRESHOLD;
    }
  • Step 5: 跑 + 提交

Run: mvn -q test -Dtest=CompanyScopeSupportTest Expected: 全 PASS。

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 的五种组合逐个断言)

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
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
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")
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。

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:

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:

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:

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 型,逐字与截图红框位置一致):

<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);各页组件加一行监听重取:

// 每页 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:

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。
// 追加到各条 text 末尾(原句一个字都不动):
' 超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了。'

// admin_shop_manage 再追加第二句(§6.3:这条与直觉相反,不写在界面上就会被报成 bug):
' 店铺归哪家公司由「负责人」决定,不由公司 tab 决定:负责人选自己,店铺就落在你自己那家。'

⚠️ 这句必须以"超级管理员"开头,不能写成"当前公司由 tab 决定":引导文案按 menuKey 取,不分支角色,而非超管根本看不到 tab 条(visibleForOperator 里有 isSuperAdmin)。写成祈使式的"当前公司由页面上方的 tab 决定",15 个管理员里非超管那批会读到一句指不到任何控件的话——那比不写更容易被报成 bug。

  1. admin_group_manage(数据权限分组,第 8 页)今天没有独立条目,它 deepEqual 到 OPERATION_GUIDE_FALLBACK(operation-guides.ts:27)。给 fallback 加这句会把"公司 tab"端给所有没有独立文案的页(含 C 类那三页没进 tab 的),所以只能给它自己一条——这就是故意偏离旧版 admin-interactions.js 的 guides 表(文件头注释和 :12 的测试注释都写着"沿用旧版原文"),要在测试注释里明写这次偏离,别让它读起来像手滑:
  admin_group_manage: {
    text: '数据权限分组决定"哪些账号能看到哪些店铺",分组按负责人和归属账号聚拢。超级管理员切换上方公司 tab 后,列表只保留当前公司账号相关的分组。'
      + ' 超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了。',
    steps: ['选择分组', '维护负责人与归属账号', '核对店铺可见范围'],
  },

⚠️ 这句里不许写"跨公司的分组彼此看不见"——那是 Task 11 Step 3 明确没做的半边:非超管的分组可见范围仍由 listAccessibleGroupIds 那套负责人/归属账号口径决定,本轮一行都没动(附B 记了这条"部分强度")。文案只描述超管 tab 的效果,不给非超管承诺他们没拿到的收窄。

// 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, ['选择分组', '维护负责人与归属账号', '核对店铺可见范围'])
})
  1. 本步覆盖的正好是注册表里那 8 页(上面 7 条 + admin_group_manage),一页不多一页不少。admin_users 不在这 8 页里——它一期就已按公司筛,§9.3 说的"第一次切过去会被报成数据丢了"指的是这次新窄下来的页,不要顺手也给它加(它的 text 还被 assert.equal 逐字钉着,改了必红)。

  2. 把这件事做进代码出口,不留在注释里(Constraint 15 的口径):往 tests/align-operation-guide.test.ts 追加一支,分母直接取注册表,别自己抄一份名单——将来往 COMPANY_SCOPED_PAGES 加第 9 页,这支会立刻红到那页的文案补上为止。

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)。

  1. C 类两页的那句也要在这一支里落(admin_shop_keys 店铺密钥管理、admin_product_categories 商品类目):
// 追加到这两条 text 末尾:
' 本页全平台共享,不按公司区分:超级管理员切换上方公司 tab 时它不会变,这不是筛选坏了。'

⚠️ 这里偏离了 spec §5 选的承载(它写的是"页头常驻一条说明")。改走引导文案有两个理由:①"常驻一条说明"本身就是 §12 第 5 条禁止的新提示条;②引导条这一支已经有分母取自注册表的用例(上面第 4 条),换承载就多一个没人管的控件。这条偏离已写回 spec §5,执行时不必再来问一次。

不做这两句的代价:tab 条是挂在 AdminLayout 上的全局件,批次 1 一上线,超管在这两页切 tab 会看到"数据纹丝不动"——而 §5 说得很清楚,那种观感要么是"假装有隔离",要么是"隔离坏了"。

  • Step 8: 全量 + 提交(前端半边,批次 1 的最后一步)
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(无则新建):

    @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 侧同理):

            "<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,第一行:

        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:

        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,函数体改成

  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:

  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: 跑两支全量 + 提交
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: 写失败的测试

    @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 的那段改成:

    /** 可见用户集: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)各加一个可选字段:

  /** 公司 tab 的当前口径;不传 = 后端按操作者自己的公司(批次 1 里非超管只有这一家)。 */
  companyId?: number | null

fetchUserSecretList(:65-69)与 fetchUserSecretUsage(:40-45)的 query 构造块里,紧跟既有的 if (params.groupId) query.group_id = params.groupId 各加一行:

  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: 跑 + 提交
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: 写失败的测试
    @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)。新方法体的形状:

    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,在传进来的对象上补键即可):

  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: 跑 + 提交
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

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):

    @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),没有一支是"断返回空"。

    @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);
        // ⚠️ 执行期补(Task 11 修复轮 2,评审 F5):**超管**分支这两句不是恒真(那串里两个 contains 只可能来自公司腿),
        // 但**非超管**那块 `query.and(wrapper -> created_by_id IN (…) OR group_id IN (…))` 本 Step 没给用例 ⇒
        // 平铺它实测 `8 例全绿、rc=0`(同样是"错了不报错、只多放行")。已另写一支
        // nonSuperAdminVisibleSetOrIsBracketedBeforeCompanyLeg 用同一把尺子(脱敏整串逐字比对)钉住,实测串:
        //   ((created_by_id IN (?) OR group_id IN (?)) AND created_by_id IN (?,?)) ORDER BY id DESC LIMIT 0, 15
        // (注意公司腿这一形是**平铺**的 `AND created_by_id IN (?,?)`、外面只有一层白送括号——与上面分组侧那形不同,
        // 别照抄串;一切以实跑打印为准。)
    }

    @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( ... ) 里"的形状。⚠️ 执行期订正(Task 11 修复轮 2,评审 I-1/F1–F3):
        // 原写法 contains("(created_by_id") + lastIndexOf("AND (") > indexOf("created_by_id") **两句都恒真**——
        // "(created_by_id" 有两个白送来源:①公司腿自己的 `AND (created_by_id IN (`;②MP 的
        // NormalSegmentList.childrenSqlSegment() 无条件给整段 normal 套一对最外层括号
        // (LEFT_BRACKET + str + RIGHT_BRACKET),实测连平铺实现也含开头的 "(";而 lastIndexOf("AND (")
        // 只量到"公司条件自成一组",杀平铺纯属顺带命中。⇒ 把 :57 那条 OR 改回平铺,全仓 16 例照绿。
        // 主锚改成**脱敏后整串逐字比对**,字面量来自实跑打印的 getSqlSegment()(不是推理):
        String masked = segment.replaceAll("#\\{ew\\.paramNameValuePairs\\.MPGENVAL\\d+}", "?");
        assertThat(masked).isEqualTo(
                "((created_by_id = ? OR (user_id = ?)) AND (created_by_id IN (?))) ORDER BY id ASC");
        // 分组括号与"白送括号"的差就是那**第二对**——正确实现两对、平铺一对,整串恰好量这一维。
        // 代价(明写):绑死 MP 3.5.7 的渲染形态与占位符个数 ⇒ 升级 MP 或改分页会**假红**(不是假绿),
        // 处置是重跑探针重取串,不许手改字面量。值仍旧单独从 getParamNameValuePairs() 断。
    }

    @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)之前:

        // 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 前折一次范围:

        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 —— 见下面那段括号警告,形状是:

    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 ∈ 可访问分组集:

    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)是白名单构造返回值,加进去的字段会被原样丢掉:

      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: 跑 + 提交

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 的通道):

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: 写失败的测试(这条测试的价值全在"麦象行不许消失")
    @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();
        String seg = q.getSqlSegment();
        assertThat(seg)
                .as("必须是 (source = ? OR uid IN (...)) 一整组,括号丢了就等于把麦象筛掉")
                .contains(" OR ").contains("IN (")
                // ⚠️ 执行期订正(Task 12 修复轮 1,评审 I-1):上面那两句**平铺实现照样全满足** ⇒ 那句 .as 声称的
                // 检查并没有被执行。但"补 contains(\"(source =\")"也不行——MP 3.5.7 给整段 WHERE 白送一对最外层括号,
                // 平铺实测原文是 `(source = ? OR uid IN (?,?) AND log_date >= ?)`,那句恒真。
                // 判据必须**数到第二对括号**,并排掉"半开"那形(`.and(w->eq).or(o->in)` 照样含 `AND (source =`,
                // 但 OR 已在组外):
                .contains("((source =")          // 分组实测原文以两对括号开头(REAL-1)
                .doesNotContain(") OR ");        // 一出现 ") OR " 就说明 OR 的左半边被括在组外
        // 实跑原文(脱敏后):((source = ? OR (uid IN (?,?))) AND log_date >= ?)
        // 「外层条件 + OR 组并存」那一支(companyFilterStacks…)换一组锚:contains("AND (source =")
        // + doesNotContain(") OR ") + indexOf("AND (") < indexOf(" OR ")(原文 REAL-2:
        // (source = ? AND (source = ? OR (uid IN (?,?))) AND log_date >= ?))。
        // 值落在 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。
  4. contains("(列名") 这一族判据一律不能用(Task 11 修复轮 2 + Task 12 修复轮 1 各撞一次,两轮实测):MP 3.5.7 的 NormalSegmentList.childrenSqlSegment() 是 join(" ") 外面无条件套 ( + )——整段 WHERE 白送一对最外层括号,平铺实现照样含开头的 (。于是 contains("(created_by_id")、contains("(source =") 在它声称要防的形状上恒真;lastIndexOf("AND (") > indexOf(列名) 只量到"公司条件自成一组",杀平铺属顺带命中。⇒ 两条出路:①数到第二对括号(contains("((source =") / contains("AND (source ="))并叠 doesNotContain(") OR ") 排掉"半开"那形(.and(w->eq).or(o->in) 照样含 AND (source =,但 OR 已在组外);②脱敏后整串逐字比对——segment.replaceAll("#\\{ew\\.paramNameValuePairs\\.MPGENVAL\\d+}", "?") 再 isEqualTo(实测串),字面量只能来自实跑打印(不许推理),且脱敏函数自带"占位符一个不剩"的自检(doesNotContain("MPGENVAL").doesNotContain("#{")),否则脱敏漏一种形状会退化成"整串恒不匹配"的糊涂红。②的代价要明写:绑死 MP 渲染形态与占位符个数 ⇒ 升级 MP/改分页算术时假红(不是假绿),届时重跑探针重新取串,不许手改字面量。这一族的失败模式是"错了不报错、只多放行",所以宁可选会假红的尺子。
  • 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)之后插入:

            // 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:

        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:

    @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: 跑两支全量 + 提交
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: 出包与发布(顺序不可颠倒)
# 批次 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「要不要重启是可判定的」那条算一次差分:

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。

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 那条要用户拍板的显式决定)。