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 渲染形态 ⇒ 升级会假红不是假绿,这条代价写进正文。
209 KiB
公司 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→b7873209V145 →85e1e92a前端摘掉公司维度 →67b62cc318 号计划执行记录,三笔是本任务之外另一条线合进来的)。⚠️ 工作区根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不再 importfetchCompanies、没有"全部公司"筛选、没有"所属公司"列;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 与既有坑)
- 发布顺序是硬约束,两条方向相反:批次 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)。 - tab 不是安全边界(spec §4):超管不传
company_id时必须保持今天的不筛行为;非超管传任何值都必须被会话覆盖,传别家得到空结果,照AdminUserService.java:75-81的"故意不报错也不越权",不许 403、不许静默改写成自己公司。 - 范围解析失败永不返回 null(沿用
CompanyScopeSupport.java:25-42的纪律):null 进实体 → MyBatis-Plus 跳过该列 → 被 V145 的DEFAULT 1静默兜住 = 归属失真且不报错。 - 只加两个后端出口,不许出现第二个 if:任何收
company_id的 controller 方法必须调DataReadScope.readScope(...),并且必须写成显式@RequestParam(name = "company_id")(本仓库多数 controller 靠方法参数名绑定,驼峰Long companyId收到的是companyId=,前端发company_id=⇒ 参数静默为 null、tab 不筛且不报错)。护栏 G2(Task 6 Step 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;店铺要落别家就得把负责人选成别家的账号。 group_id IS NULL/uid IS NULL的行不许静默从所有 tab 消失(spec §9.1、§9.2;memory「读过滤与写按范围替换必须同时改,否则隐藏=静默删除」):默认处置是该页不声明companyScoped(§12 第 2 条),回填需用户单独授权。- C 类两页不做 tab:商品类目(
biz_product_category,平台字典带isBuiltin)与店铺密钥(biz_shop_key,紫鸟 token 池)没有任何归属列,本计划不给它们加列、不加参数,页头文案另开一笔(spec §5、§13)。 - 两张 jar 必须同版;逐节点复验不能打
0.0.0.0:18080(nginx 轮询池),主机 B 的 java 在127.0.0.1:19080;混合版本窗口里新参数会被旧 jar 忽略。admin-vue 只在主机 B 的/var/www。 - 不许
skipTests上线;mvn test全量门禁禁止与 Nuitka 打包并行(TxDurationBenchmarkTest抢 CPU 假红);主树禁git clean;不许git stash(红线归因用 detached worktree)。 - 生产只做只读取证,任何
INSERT/UPDATE/DELETE/ALTER只交付命令、由用户执行(既定工作方式)。只读通道 =scripts/_prod_watch.py:171 db_sections()。 - 护栏做进代码出口,不写进注释(spec §10):G1-G6 六支实跑用例 + 每支配变异自证。变异八条硬规矩:每轮开跑前所有被注入文件写回 pristine、还原只认注入前读进内存的字节(不许
git checkout)、CRLF 锚串先对齐行尾、分母只认本轮扫描结果、扫描用例必须自带"取样集非空"自检(否则 0 命中恒绿)。 - 前端是
admin-frontend-vue,不是frontend-vue(CLAUDE.md只写了后者,别混)。 - 不改既有测试的断言方向来迁就实现。本计划只允许翻转 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生产者与守卫消费者之间那根字符串约定变成编译期契约)。 - 界面暴露要单独批准,本计划只批了两处(memory「新维度默认只做后端,界面暴露要单独批准」,2026-10-04):已批准 = ①
AdminLayout顶部那条公司 tab、②公司配置入口收窄到超管(Task 1)。其余任何"加一列/加一个下拉/加一个筛选器"都算未批——包括店铺列表加"所属公司"列、GroupEditorDialog负责人下拉按公司收窄、C 类页页头文案之外的任何控件。执行到这类步骤时默认不做,把它记进附B「已知不做」,需要就回来要一次授权。归属信息的唯一正确来源是后端从操作者会话推导,不是界面上的一个选择器。唯一例外是"改文案":spec §9.3 把"行数随 tab 变"的说明指定由operation-guides.ts的既有引导条目承载(正是为了不必新做控件),Task 7 Step 7 照它执行,不算未批暴露。 - 撤维度时测试要反向钉"不得回流"(同一条 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 动了一次)。所以:
- 每个任务开工前重跑
git rev-parse --short HEAD;变了就读git log --oneline <上次的HEAD>..HEAD,尤其确认85e1e92a摘掉的公司维度没被谁加回来(Task 2 Step 1 那三支反向钉会替你红,但红在半路比红在验收时难查)。 git status --short出现不是你这轮造的条目 ⇒ 停下来出清单交用户决定(既定工作方式),别卷进提交、别回退、别替它提交。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?: booleanpruneSuperAdminOnly<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;
把结果抄进本任务的提交信息里。三个数各自决定一件事:
MAX(members)与MEMBER_WARN_THRESHOLD = 500的余量——余量小于 5 倍说明阈值定太高,哨兵等于不存在;company_id IS NULL那一行的计数——必须为 0。非 0 说明 143/144 之后仍有游离账号,memberUserIds按公司等值查会把他们从每一个 tab 里丢掉(spec §9 的静默丢数形态),先补归属再往下走;- 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 条,这一支要改。
- 下面 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。
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, ['选择分组', '维护负责人与归属账号', '核对店铺可见范围'])
})
-
本步覆盖的正好是注册表里那 8 页(上面 7 条 +
admin_group_manage),一页不多一页不少。admin_users不在这 8 页里——它一期就已按公司筛,§9.3 说的"第一次切过去会被报成数据丢了"指的是这次新窄下来的页,不要顺手也给它加(它的 text 还被assert.equal逐字钉着,改了必红)。 -
把这件事做进代码出口,不留在注释里(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)。
- 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 逐行读过,不是推测):
AdminImageVideoTaskController.java:78现在是adminAuthSupport.requireAdminOrInternal(request);返回值被丢掉——本任务必须改成AdminUserEntity operator = adminAuthSupport.requireAdminOrInternal(request);,否则拿不到角色与companyId。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的非超管分支)。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_idquery 参数;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 逐行实查,别再照草稿的假设推):
ShopManageController.requireOperator(request)走的是adminAuthSupport.requireAdminOrInternal(request)(controller/ShopManageController.java:50-52)⇒ 这页存在非超管与内部令牌两条通道。按 §6.1,它的按 id 读出口必须补行级闸门,与 Task 12 那页"只有超管进得来"是两回事。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是同一个形状,两页别各发明一套。- 超管今天完全不锁:
:43的if (!superAdmin) { ... }里才有accessibleCreatorUserIds/accessibleGroupIds那套 OR(:48-59)。⇒ 超管 + 选了公司这一支是新增的收窄,不是"改既有过滤"。 - ⚠️
create/update的归属来自请求体,不来自操作者:ShopManageService.java:86是normalizePositiveId(request.getCreatedById(), "创建人不能为空"),:96entity.setCreatedById(createdById)。⇒ 草稿写的"created_by_id = operator.getId()"是错的,Step 4 的口径说明按这条重写。 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,由调用方挑(后台弹窗里那个"负责人"下拉就是它)。⇒ 三条后果,都得写在脸上:
- "超管在别家 tab 下导入会落到自己公司"这句对店铺不成立。超管把负责人选成
users.id=1193(第 2 家自己的 admin),店铺就归第 2 家 —— 这是现成的、今天就能用的路径,spec §6.3 那条副作用在店铺这页是"取决于你选谁当负责人",不是"恒落公司 1"。Step 6 的提交信息与人工验收第 4 条按这个改(那条原本写"确认没有跟着 tab 走",在店铺这页会把一次正常行为报成 bug)。 - 反向钉的口径要收窄:钉的是"不收
company_id",不是"归属不可指定"。createdById这个既有字段照旧收 —— 动它才是回归。Step 1 第四支用例的断言式因此只看company_id/companyId两个词,不看createdById。 - 今天
createdById没有任何公司校验:任何已认证后台账号(含内部令牌通道)能把店铺挂到任意users.id名下。这跟 (d) 那个凭据读出口是同一类"一期就在的洞",本计划不顺手补(补它 = 给写侧加一条会 403 新老数据的校验,是要单独批的行为变更),记进附B。
为什么仍不给 create 加 company_id,三条理由:
- 新维度默认只做后端,界面暴露要单独批准(memory,2026-10-04 与用户对二期那条线的同一轮定调)。让
create收company_id= 在弹窗里长出一个公司选择器,那是要单独批的界面暴露,不在本计划已批范围(已批的是:超管用的 tab 一条 + 公司配置入口收窄)。何况归属已经能从"负责人"表达——再加一个公司选择器就是两个控件说同一件事,且它们会互相矛盾(选了第 2 家 + 选了公司 1 的负责人,听谁的?)。 - 与建号同口径:
AdminUserService.resolveTargetCompanyId(AdminUserService.java:201-207)今天就是"前端不传 ⇒ 落操作者自己的公司",二期那条线还专门用tests/company-user-create.test.ts把它反向钉死了。店铺这边若单独改成"按 tab 选的公司落",同一后台就出现两套归属口径——那正是 memory「别自己定"全局统一默认值"口径」点名的坑。 - 实体没有可落的列:
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.companyIdShopManagePageQuery(同文件)加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 实查,别再照记忆推):
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 那条反向钉的分母,分母错则断言漏。)DeviceLogService.page(source, uid, startDate, endDate, pageParam, pageSizeParam)(service/DeviceLogService.java:162)把条件包在一个Function<Boolean, LambdaQueryWrapper<DeviceLogFileEntity>> wrapperBuilder里,selectCount与selectList共用它(:186/:190)。⇒ 公司过滤必须加在 builder 内部;加在外面任何一侧都会得到"total 与行集不同宽 = 分页错位"。- 现有
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());
}
读法四条,都是这组用例能不能咬住实现的关键:
selectCount一定被打到,selectList只在total != 0时才打(DeviceLogService.java:189-193的三元)。所以凡是"看生成的条件"的用例,要么把selectCount桩成1L再捕两支,要么直接捕selectCount那支——别写一个"selectCount 桩 0 然后断言 selectList 的 wrapper"的用例,它捕到的是 null,红在断言之前。- 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 相等」也恒真——尺子绿着,什么都没钉住。 capturedCount()/capturedList()各用一个ArgumentCaptor<Wrapper<DeviceLogFileEntity>>捕(本文件已 importArgumentCaptor与AbstractWrapper),捕获后(AbstractWrapper<?, ?, ?>)转型取getSqlSegment()。row(1024L, 2)用文件里已有的助手即可——这几条测的是生成的 SQL 形状,不是返回内容,所以不需要给行设source/uid。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)));
}
}
三点都要照做:
- 放在闭包内部——
selectCount与selectList共用这个Function,放外面只作用于其中一支,得到"total 与行集不同宽"的分页错位,而且不报错。 - 不要平铺成
qw.or(...):MP 的or()不带wrapper ->时只接左半边,会把已有的source/log_date条件拆坏(与 Task 11 Step 3(c) 那条ShopManageGroupService.java:55-56同一个坑)。 - 空集单独走
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验不到生产长什么样,这批必须实跑)
- 非超管回归(批次 0 的账):一个 admin 账号登录 → 侧边栏无「公司管理」→ 直接手输 URL
/admin-vue/account/companies被弹回首屏 → 「用户管理」正常打开且 Network 无/api/admin/companies。 - 越权实验(G3 的真身):非超管带
?company_id=<别家>请求/api/admin/user-secrets→ 200 + 空列表,不是 403、不是别家数据。 - tab 有效性:超管切公司,八页各切一次,行数必须变;
overview计数与列表行集同宽(Task 10 Step 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 不改变上述任何一条"。测完删掉测试行(只交付命令,用户执行)。
- 建号:超管切到第 2 家 tab 建一个账号 → 查库确认新账号
- 凭据读出口按会话收窄(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 自动化走的那条,本轮刻意不动)。 - 麦象日志不消失(Task 12 的账):切任意公司 tab,日志管理里
source=maixiang的行必须还在。⚠️ 生产只读实测(10-05,device_log_file共 1028 行):client831 /maixiang197,但client里有 22 行uid IS NULL(22/831=2.6%)——这 22 行按「source='maixiang' OR uid IN (成员集)」的形状仍会被筛掉,Task 12 要么给它一条同族的"无法归属"放行腿,要么在附B 里明写这 22 行在各 tab 下消失是设计。 - 保存权限不炸(Task 4 的账):给一个历史带
admin_companies授权的账号保存一次权限 → 成功 + 日志GRANT_SUPER_ADMIN_ONLY_STRIPPED。 - 文案这三眼看(§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 行(client831 /maixiang197),其中uid IS NULL的client22 行(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 那条要用户拍板的显式决定)。