diff --git a/docs/ops/company-tab-design-2026-10-04.md b/docs/ops/company-tab-design-2026-10-04.md new file mode 100644 index 000000000..9bd39278d --- /dev/null +++ b/docs/ops/company-tab-design-2026-10-04.md @@ -0,0 +1,242 @@ +# 公司 tab(超管按公司看数据)+ 公司配置读写只超管 —— 设计 + +日期:2026-10-04 +需求来源:用户三句话,逐字记录 +1. 「公司管理和创建用户选公司只能超管才能看到」 +2. 「除了超管都不能操作公司配置 读写都不行」 +3. 「前端改一下 超管通过tab看不同公司的数据,其他菜单也是这样(去重数据库之外的菜单)」(附「去重数据汇总」页截图,面包屑那一行画了四个空红框 = tab 位置) + +已定的两个口径(用户选的,不是我推荐的): +- 范围:**一次铺完 16 页**,分 3 批发布(我推荐的 5 页首批被否)。 +- 默认:**默认选中第一家,不允许「全部」**(我推荐的"默认全部"被否)。 + +配套文档:一期 `company-multi-tenant-design-2026-10-04.md`;二期(品牌库/去重库)`brand-dedupe-company-isolation-design-2026-10-04.md`。本方案**不依赖**二期落地,但批次 3 的两页要用二期的物化列。 + +--- + +## 1. 先更正一条我上一轮说错的事实 + +我说过"生产 `company` 表只有 1 行 ⇒ tab 上线只有一个标签"。**这句是错的**,来源是我的 13:5x 记忆快照,而 V145 头部记的是 15:0x 实查: + +> `company` 表今天有两行(1=厦门米椿花、2 于 10-04 14:55 开通),第 2 家只有 1 个管理员账号(`users.id=1193`)、0 个任务、0 行去重数据。 + +两个后果,都比"tab 好不好看"更要紧: +- tab 今天就有真实内容,不是空壳演示。 +- **二期的 `company_id DEFAULT 1` 摘除倒计时已经触发**(V145 头部自己写的:「第二家公司已于 10-04 14:55 开通 ⇒ 本次发布之后 DEFAULT 的每一分钟都是风险」)。而且 14:55 到批次 1 上线之间,第 2 家公司的**品牌库自动导入行无法追回**(`biz_invalid_asin_data` 今天连账号列都没有)。这条不在本方案范围内,但它决定了本方案什么时候能开工——见 §12 待确认第 1 条。 + +## 2. 需求拆成两件事,它们必须分开做 + +| | 是什么 | 判据 | 落点 | +|---|---|---|---| +| **A. 公司配置的读写只超管** | 页面/接口**可见性闸门** | 角色内在(`role == super_admin`),**不查菜单授权** | `CompanyService` + `PermissionMenuService` 三处出口 + 前端注册表 `superAdminOnly` | +| **B. 超管按公司看数据** | 读路径的**数据过滤** | 超管 = tab 选中的公司;非超管 = 恒锁自己公司 | 各页接口 + tab store + 统一的范围解析入口 | + +为什么 A 必须是"角色内在"而不是"菜单授权"——这正是 **10-04 12:3x 生产事故的形状**:`listVisible` 挂上 `admin_companies` 菜单闸门,而该菜单授权笔数为 0 ⇒ 15 个管理员账号一开「用户管理」就 403,被踢回登录页,报成"登录闪退"(见 `CompanyService.java:80` 那段注释记录的教训)。所以: + +- 用 `role` 判,不用菜单授权判。菜单授权可以被人改坏,角色不能。 +- A 做完后,`admin_companies` 这个菜单行**仍然留在 `columns` 表里**(否则历史授权数据无处安放),只是从"可授予集合"里摘出来,让超管也没法把它授给别人。 + +## 3. 16 页归属普查(逐页取证,不是估的) + +分母来源:`admin-frontend-vue/src/router/routes.ts:17-38` 共 22 页。扣掉 6 页非数据页——`account/users`(已有公司筛选,见 §3.1)、`account/companies`(A 类闸门,不做 tab)、`account/menus`(平台字典)、`records/software-version` / `records/tutorial` / `records/digital-human-version`(平台发布物,全公司共享)——**剩 16 页,与用户说的"16 页"对得上**。 + +| 类 | 判据 | 页 | 归属列证据 | +|---|---|---|---| +| **A(9)** | 表上有账号列,一条 `user_id IN (成员)` 就够 | 数据权限分组、密钥管理、密钥用量统计、店铺管理、生成记录、日志管理、视频任务记录、客户端任务管理、数据去重总数据 | `biz_shop_manage_group.user_id/created_by_id`、`biz_user_api_secret.user_id`、`biz_user_secret_usage_daily.user_id`、`biz_shop_manage.created_by_id`、`image_history.user_id`、`device_log_file.uid`、`biz_image_video_async_task.user_id`(`ImageVideoAdminTaskMapper.java:37` 已有 ` AND t.user_id = #{userId}`)、`biz_task.user_id`(`TaskCenterQueryMapper.java:93-95` 已有 `USER_SCOPE_T/USER_SCOPE_B` 的 `IN` 片段)、`biz_dedupe_total_data.uploader_user_id` | +| **B(3)** | 只有 `group_id`,没有账号列 | 不符合ASIN数据(品牌库)、查询ASIN、最低价ASIN | `InvalidAsinDataEntity.java:20`、`QueryAsinEntity.java:20`、`SkipPriceAsinEntity.java:21` 都只有 `groupId`(品牌库二期 V145 后会多出 `company_id`) | +| **C(2)** | **零归属列**,本质是全平台共享 | 商品类目、店铺密钥管理 | `ProductCategoryEntity.java:15-23`(`parentId/name/categoryKey/sortOrder/isBuiltin`,无归属);`ShopKeyEntity.java:17-32`(紫鸟 token 池 `ziniaoToken/proxyUrl/ipWhitelist*`,无归属) | +| **D(2)** | 快照无归属列,可见性靠"店铺名集合"裁剪 | 店铺撞款监控、店铺数据记录 | `ShopDataDuplicateCheckQueryService.java:78-89 resolveVisibleShopKeys` + `cropShops/cropItems`;底层 `shop_data_duplicate_scan` 只有 `status/summary_json/payload_json`(`ShopDataDuplicateScanEntity.java:16-22`),**全局一份快照**;裁剪链靠 `ShopDuplicateCheckSourceMapper.java:87-97 selectManagedShopNames(operatorId)`(`biz_shop_manage.group_id IN (自己带的分组)`) | + +### 3.1 参照实现已经有了:`用户管理` + +`AdminUserController.java:43` 的 `@RequestParam(name="company_id", required=false)` 是**全仓唯一**一个收公司筛选的后台接口(已全仓 grep 确认)。它的语义就是本方案要复制的模板,两条都对: +- 超管不传 = 不筛(`AdminUserService.java:89-90` 只在超管分支加 `eq(company_id)`); +- 非超管传别家 = **返回空集,故意不报错也不越权**(`AdminUserService.java:75-81`)。 + +### 3.2 A 类不必新造范围机制 + +`modules/permission/support/UserDataScopeSupport.java` 已经提供 `resolveVisibleUserIds(operatorId)`(operator → 自己带的分组 → 成员 user ids,历史无分组主管回退按 `created_by_id` 兜底,上限 2000),并且已被密钥管理、任务看板(`TaskCenterScopeService.java:36`)、去重库(`DedupeTotalDataService.java:1188`)使用。 + +本方案只加**一条**新方法,然后与它组合,不另起平行实现: +``` +CompanyScopeSupport.memberUserIds(companyId) // SELECT id FROM users WHERE company_id = ? +``` +组合规则(**这是本方案唯一的范围公式,写在一处**): +- 超管:`scope = memberUserIds(tabCompanyId)`(替换掉分组派生的" unrestricted",不是交集)。 +- 非超管:`scope = resolveVisibleUserIds(operatorId) ∩ memberUserIds(operatorCompanyId)`。 + 今天这个交集是恒等的(第 2 家公司只有 1 个账号、0 条业务数据),但**它必须存在**:`resolveCompanyMove` 允许把账号在两家公司之间移(`AdminUserService.java:221-230`),移动后交集就起作用了。这条之所以安全,是因为移人已经有不变式兜着——「账号的 `created_by_id` 必须与它同一家公司,除非创建人是超管」(`AdminUserService.java:236-243` 注释明写这条是"二期不回改 77 处 `eq(getUserId, userId)` 过滤点的前提")。 + +`memberUserIds` 不加 `LIMIT`:今天全库 140 行 `users`。但要在代码里放一个**计数哨兵**:成员数 > 500 时把 `IN (...)` 改成子查询 `user_id IN (SELECT id FROM users WHERE company_id = #{companyId})`。**不预先做**(YAGNI),哨兵要有,理由见 §10 护栏 G6。 + +## 4. tab 是什么、不是什么(这条最重要) + +**tab 不是安全边界。** 它是超管的一个读筛选。真正的边界是: +- 非超管**永远**被会话裁剪到自己公司,前端传什么都不算(后端一律按 `operator.company_id` 覆盖); +- 超管不传 `company_id` 时**保持今天的不筛行为**。 + +选这个弱度换来两件实在的好处: +1. **发布顺序安全**:jar 先上(参数可选、向后兼容,旧前端不传照常),前端后上(tab 出现且真的开始筛)。反过来会有"tab 存在但不筛"的**撒谎窗口**——超管点了"第 2 家"却看到第 1 家的数据,这比报错更坏。 +2. 混合版本窗口里(一期实测约 15 分钟)旧 jar 遇到未知参数直接忽略,不会 500。 + +代价必须承认:**超管失去"一眼看全部公司"的能力**,这是"不允许「全部」"这个选择的直接后果。今天 2 家,来回切代价小;三家以上,"哪家在掉量"这类横向判断只能靠切 tab。二期 §12 已明确"不做跨公司汇总/对比报表",所以本方案**不**补汇总页,只在这里记账。 + +另两个必须钉死的口径(不写清就会各自理解): +- **"第一家"的定义 = `company.id` 最小的启用中公司**,不是超管自己所属公司,也不是后端返回顺序的第一条。刷新后回到第一家(见下面 store 口径)。 +- **tab 状态不进 URL,只进 Pinia store**。理由:16 个页面的取数函数都去读 `route.query` 是真实成本,批次 1 铺不完;代价是**复制链接/截图不带公司上下文**,超管从 tab=2 发给同事的链接,对方打开是第一家。这个代价是否可接受,见 §12 待确认第 4 条。 +- tab 条渲染在 `AdminLayout.vue` 的顶栏/面包屑那一行(截图红框位置,`AdminLayout.vue:97-121`),**不在各页里各画一遍**。所以护栏不能测"页面渲染了 tab",只能测"页面的请求带了 companyId"(§10 G1)。 + +## 5. C 类两页:显式声明"不按公司分",而不是静默不筛 + +商品类目(平台字典,带 `isBuiltin`)和店铺密钥(紫鸟 token 池)**今天就没有任何归属列**。给它们加 tab 只有两种坏结果:要么假装有隔离(切 tab 数据纹丝不动,用户会以为隔离坏了),要么为它们临时造归属(回到二期 §12"不给其余 55 张表加 `company_id`"的破例讨论)。 + +做法:注册表里 `companyScoped: false`(**显式写,不留空**——留空与 `false` 运行时等价,但只有写出来才是"读过普查、决定不参与"的证据,实施计划 Task 1 Step 1 那支用例钉的就是这个)+ 一句"本页全平台共享,不按公司区分"。让用户看到的是"这页不参与",而不是"这页坏了"。这条也回答了二期 §9.4 对品牌库"未分组是预期的"的同类处理。 + +承载方式与原方案**有一处偏离**(10-04 定案时写的是"页头常驻一条说明"):那句话改放进 `operation-guides.ts` 这两页的既有引导文案里,随批次 1 一起上。两个理由:①"页头常驻一条说明"本身就是 §12 第 5 条不许的新提示条;②引导条那一支已经有分母取注册表的用例(谁被声明成 `false` 就自动被要求带这句),新控件没有这个搭车。⚠️ 这件事**不排在批次 3**:tab 条挂在 `AdminLayout` 上是全局件,批次 1 一上线"切了纹丝不动"这坏观感就同时上线。 + +## 6. 铁律:闸门读写同页;归属不从界面注入(2026-10-04 收窄过一次,最终版) + +这一节原来写的是"一个页要进 tab 范围,它的读筛选和**写归属**必须同一批落地"。后半句已作废——它会把公司这个维度重新端回界面(弹窗里长出一个"所属公司"),而**新维度默认只做后端,界面暴露要单独批准**。拆成三条: + +### 6.1 闸门必须读写同页(这条仍是铁律) + +一页进了 tab 范围,它的**角色/归属闸门**要读写一起动。只收窄列表、不收窄按 id 的读出口 = "列表看不见但按 id 能读能下载",那是真越权。已定位必须补行级闸门的出口: + +| 出口 | 要求 | +|---|---| +| 列表读 | 带 `company_id`,经 §7 的唯一入口 | +| **导出** | 同一个 `company_id`。**否则 tab 筛了表格、导出全量 = 越权泄露**。已定位:`/api/admin/dedupe-total-data/export`(`dedupe-total-export.ts:5,39` 的 `toExportUrl(state)`)、`/api/admin/product-categories/export`、`/api/admin/shop-data-crawl/duplicate-check-export`(`AdminShopDataDuplicateCheckController.java:179`) | +| **按 id 的详情 / 下载** | 凡该端点存在**非超管或内部令牌通道**的,必须先取行再判归属。已定位:`ImageVideoAdminTaskController.java:93`(`detail`)与 `:100`(`download-zip`)——它们走 `requireAdminOrInternal`,漏掉它 = 列表筛了但内容能越权读 | +| 按 id 的单行 改 / 删 | 同上,用 `CompanyScopeSupport.assertSameCompany(...)`(`CompanyScopeSupport.java:44`,目前 **0 个生产调用方**,本方案是第一个使用者) | + +反过来,**这页只有超管能进(无任何非超管/内部通道)时,按 id 的端点刻意不加公司闸门**:日志管理那页 9 个端点全是 `requireSuperAdmin`(`AdminDeviceLogController.java:152-159`),加了只会误伤 `uid IS NULL` 的麦象日志——那是排障现场不是越权面。这条边界要有测试钉着,不许下一个人"顺手补齐"(实施计划 Task 12 Step 4)。 + +### 6.2 归属由后端从操作者推导,写请求体一律不带 `company_id` + +与二期的建号口径同源:`AdminUserService.resolveTargetCompanyId`(`:201-212`)在超管未传 `company_id` 时返回 `operator.getCompanyId()`,前端 `85e1e92a` 起**故意不发这个字段**,并被 `tests/company-user-create.test.ts` 反向钉住。店铺/分组(Task 11)沿用同一条,不搞两套。 + +另一个更硬的理由:`ShopManageEntity`/`ShopManageGroupEntity` 根本没有 `company_id` 列。⚠️ 而**店铺的归属人今天来自请求体的 `createdById`**(`ShopManageService.java:86` 读 `request.getCreatedById()`),不是操作者 ⇒ "落到第 2 家"早就做得到(把负责人选成第 2 家的账号)。再加一个 `company_id` 参数不是"补能力",是**造两个互相矛盾的归属控件**(选了第 2 家 + 负责人是公司 1 的人,听谁的?)。反过来,若为它加"负责人必须是那家成员"的校验,超管自己不在别家成员集里 ⇒ **超管把负责人留成自己就 403**,比今天更糟。 + +### 6.3 明写不吞的副作用 + +> **建号**:超管切到「第 2 家」tab 后建的号,仍归**超管自己所属的公司 1**(`resolveTargetCompanyId` 落操作者),要归属第 2 家必须用那家自己的 admin 登录去建(`users.id=1193` 就是这么来的)。memory 里那句"超管建的号一律归公司 1"就是这条。 +> **店铺/分组**(17:5x 实查后订正——上一版把这句一并写成了"仍归公司 1",**不对**):归属由请求体的**负责人 `created_by_id`** 决定,**与顶部 tab 无关**。把负责人选成第 2 家的账号,店铺就归第 2 家;这一条本轮一行代码都没动。 + +今天影响为零(第 2 家 0 行业务数据,实查见实施计划 Task 5 Step 0),但它是运维手册里必须存在的一行字。落点:`operation-guides.ts` 店铺管理那条引导加一句文案(**只加文案,不加控件**),由实施计划 **Task 7 Step 7** 与其余 7 页那句一起落,别在接线任务里再落一遍。 + +## 7. 后端:一个统一入口,不许各页自己 if + +新增 `DataReadScope.readScope(...)`,**唯一**负责"操作者 + 请求里的 company_id → 该查哪批 user ids / 哪家公司": + +``` +DataReadScope readScope(AdminUserEntity operator, Long requestedCompanyId) + 超管 + null → 不筛(今天的行为) + 超管 + id → memberUserIds(id) + 超管 + 不存在的 id → 空集(不 403;tab 值可能来自过期 store) + 非超管 + null → resolveVisibleUserIds(operator) ∩ memberUserIds(operator.companyId) + 非超管 + 自己 id → 同上 + 非超管 + 别家 id → 空集(照 AdminUserService:75-81「故意不报错也不越权」) +``` + +两条硬约束: +- **每个收 `company_id` 参数的 controller 方法必须调这个入口**,不许出现第二个 if。护栏 G2 扫的就是这条。 +- `CompanyScopeSupport` 现有的 `requireCompanyId` 取不到就抛、绝不返回 null(`CompanyScopeSupport.java:25-42` 的注释给了理由:null 进实体 → MyBatis-Plus 跳过该列 → 被 V145 的 `DEFAULT 1` 静默兜住 = "归属失真且不报错")。**新入口沿用同一条纪律**:范围解析失败返回"空集"或抛,永不返回 null 让调用方自己猜。 + +## 8. 前端:两个闸门 + 一个 store + +### 8.1 A 类(公司配置只超管) + +- `routes.ts` 的 `AdminPageDef` 加 `superAdminOnly?: boolean`,`account/companies` 置 true。 +- `router/helpers.ts:26-33` 的 `isRouteAllowed` 现在是 `if (isSuperAdmin) return true` —— **超管恒 true,所以只剪菜单树对超管无效,只加角色闸门对非超管的侧边栏又不够**。两处都要做,缺一处就留旁路: + 1. `isRouteAllowed` 先判 `superAdminOnly && !isSuperAdmin → false`(与菜单树无关的硬闸门); + 2. `stores/admin-session.ts:30` 的 `canonicalizeMenuTree(...)` 之后**剪掉** `superAdminOnly` 节点(覆盖 sidebar、面包屑、`firstVisiblePath`、路由守卫四个消费者——它们都从这一棵树来,这是唯一单点)。 +- `CreateUserDialog.vue:123`:`v-if="companyOptions.length"` → `v-if="operatorSuper && companyOptions.length"`。今天非超管也会看到一个只有单项的"所属公司"(`selectableCompanies` 给非超管返回自己那一行),按需求 1 要整个隐藏。隐藏后**不需要**补默认值——后端 `resolveTargetCompanyId` 对非超管恒返回 `operator.getCompanyId()`。 +- `UsersPage.vue:146` 的 `void loadCompanies()`:改成超管才调。**这条必须在 jar 上 403 之前发**,见 §11。 + +### 8.2 B 类(tab) + +- 新 store `company-tab`:`companies`(超管才拉)、`activeId`(默认 `id` 最小的启用公司)、`memberUserIds` 不缓存(每次请求交后端解析,避免"改了成员没刷新"的不一致)。 +- 请求侧:`company_id` 由各页的 api 模块**显式**从 store 取并塞进参数,**不做 http 层中央注入**。中央注入看着省事,实际会让"C 类页也带上参数",后端要么忽略(撒谎)要么honour(把平台字典误筛成公司私有)。护栏 G1 用双向对账来防漏:注册表声明了 `companyScoped: true` 的页,它的 api 模块必须出现 `company_id`;出现了 `company_id` 的页必须被注册表声明。 + +## 9. 三个会静默丢数据的坑(都不报错,都会让人以为改造坏了) + +### 9.1 `group_id IS NULL` 的历史行会从**所有** tab 消失 +品牌库 14,224 行 AUTO 的 `group_id` 是 NULL(V145 头部实查 + 二期 §7.3 明确"这是刻意的切法")。B 类页若走 `group_id → 分组 → 公司` 推导,这些行在**每一个** tab 下都不出现 = 对超管等于数据被删。符合 memory 里那条「读过滤与写按范围替换必须同时改,否则隐藏=静默删除」。 +处置三选一,**不许默认选 (c)**: +(a) 该页不声明 `companyScoped`;(b) 把 NULL 行回填成公司 1(它们事实上就属于公司 1);(c) 接受消失并写文案。 +**已锁 (a)**(§12 第 2 条):批次 2 开工前先跑 §11.2 的 SQL 数出 NULL 行数,(b) 需要用户单独授权才做。 + +### 9.2 日志管理的 `uid` 对麦象采集机恒空 +`DeviceLogFileEntity.java:27` 注释逐字:「桌面客户端当前登录用户 id(users.id),**maixiang 上报为空**」。⇒ 按 `uid IN (成员)` 筛之后,**所有麦象采集机日志在任何 tab 下都看不见**。而麦象机器正在跑跟价(见 `maixiang-linux-migration`)。 +处置(**已锁**,§12 第 2 条):日志管理按 `source` 分支——`client` 按 uid 筛、`maixiang` 恒可见。若 §11.2 第 2 条取证显示麦象行占多数,则整页改判不声明 `companyScoped`。**默认不筛**比默认丢日志安全。 + +### 9.3 tab 会改变"这页今天有几行"的观感 +一期 10-04 刚把三张任务记录列表页的日期初值改成留空(`00e5df02` / `48018068`)。tab 再一上,超管第一次切过去的行数变化会被报成"数据丢了"。承载方式按 §12 第 5 条:**不新做页头控件/提示条**,改在 `operation-guides.ts` 的既有引导条目里加一句"超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了",店铺管理那条再补一句 §6.3 的归属口径。分母取 `COMPANY_SCOPED_PAGES` 那 8 页(不是只有那三张任务记录页),其中「数据权限分组」今天共用通用 fallback,要给它一条独立文案——这是**故意**偏离"沿用旧版 guides 表原文"的约定,因为那句 tab 说明不能塞进 fallback(会被没进 tab 的页共用)。`admin_users` 不在其列:它一期就已按公司筛。 + +⚠️ **这句必须以"超级管理员"开头**:引导文案按 `menuKey` 取、**不分支角色**,而非超管看不到 tab 条(G1 那侧的 `isSuperAdmin` 判断)。写成"当前公司由上方 tab 决定"会让非超管读到一句指不到任何控件的话——比不写更容易被报成 bug。同理,文案不许给非超管承诺他们没拿到的收窄(附B 记了分组那半边本轮刻意没动)。缓解是**部分强度**:引导条默认展开,但折叠态按浏览器持久化,早就收起提示的人看不见这句。 + +## 10. 护栏(做进代码出口,不写进注释)+ 变异自证 + +| 号 | 断言 | 注入点(变异) | +|---|---|---| +| G1 | 注册表 `companyScoped:true` 的页 ↔ 其 api 模块出现 `company_id`,**双向**对账 | 把某页从注册表摘掉声明 / 从 api 模块删参数 | +| G2 | 每个带 `@RequestParam(name="company_id")` 的 controller 方法必须调 `readScope(` | 把某一处的 `readScope` 换成裸 `eq` | +| G3 | 非超管传别家 id ⇒ 空集;传自家 ⇒ 有数据;**两种都不许看到对方数据**(断言具体行为,不接受"没报错"当通过) | 删掉 `AdminUserService:75-81` 形状的那道判断 | +| G4 | `admin_companies` 在 `/current-user/menus`、`permission-menus?grantableOnly=true`、`updateUserColumnPermissions` 提交三处都不出现/写不进;`grantableOnly=false` 时**仍**能列出(菜单行要可管理) | 任一出口漏剪 | +| G5 | `CompanyService` 全文不出现 `hasAnyAdminMenu(`(防止有人把读路径重新挂回菜单授权,重演 12:3x),且 `ensureSuperAdmin(operator);` 恰好 3 处(create / update / **listVisible**) | 让 `listVisible` 退回非超管可 | +| G6 | `memberUserIds` 的成员数哨兵:> 500 时用例红,提示改子查询 | 无(它本身就是倒计时) | +| **G7** | **反向钉"已摘掉的维度不得回流"**(五支):`tests/company-user-create.test.ts`(建号不带 `companyId`)、`company-user-list.test.ts:66`(账号页不调 `fetchCompanies`)、Task 11 Step 1 第四支(店铺写入口不收 `company_id`)、Task 12 Step 4 那条(按 `fileId` 的端点不接 `company_id`)、Task 7 Step 7 第 4 支("当前公司"只由文案与 `is-active` 承载:`CompanyTabs.vue` 里不许长出提示条,且 `COMPANY_SCOPED_PAGES` 那 8 页的引导文案必须都带那句) | 给任一写入口加一个 `company_id` 参数 ⇒ 对应那条红;给 tab 组件加回提示条 ⇒ 那支的反向半红;从任一页文案里删掉那句 ⇒ 分母半红。**每支必须自带"该做的确实做了"的取样自检**,否则符号根本不存在时它恒绿 = 没钉 | + +现有用例要**翻转**的三条(不是新增,是改正确的行为):`CompanyServiceDirectoryTest.java:121` 「公司内管理员的目录只查自己公司」、`:161` 「公司内管理员读到本公司那一行:读端点不查 admin_companies 菜单」、`:172` 的"读得到目录也不能建第二家公司"文案——按需求 2 全部改成 403。这三条改完,`CompanyReadPathMenuGateTest` 的 `ensureSuperAdmin` 计数从 2 变 3(G5)。 + +变异自证遵守既有八条硬规矩:每轮开跑前所有被注入文件写回 pristine;还原只认注入前读进内存的字节,**不许 `git checkout`**(会连未提交的 V145 实现一起抹掉);CRLF 锚串先对齐行尾;分母只认本轮扫描结果。 + +## 11. 分批与发布顺序 + +### 11.1 四批 + +| 批 | 内容 | 页 | 发布顺序 | +|---|---|---|---| +| **0** | 公司配置只超管(§2 A + §8.1),无 DDL | 公司管理 1 页(建号选公司与账号页公司列**已由 `85e1e92a` 对所有人摘掉**,本批只核对 + 反向钉,见实施计划 Task 2) | **FE 先,jar 后**(现网那版 admin-vue 早于 `85e1e92a`,仍在调 `GET /api/admin/companies`;反过来 15 个 admin 一开「用户管理」就撞 403) | +| **1** | tab 机制 + A 类:客户端任务管理、视频任务记录、密钥用量统计、生成记录、日志管理、数据权限分组、密钥管理、店铺管理(8 页;**只筛读**,写侧归属按 §6.2 不动)。**日志管理只在 §9.2 的「`(source='maixiang' OR uid IN 成员集)` 一整组」这条路线下留在本批**;若 §11.2 第 2 条取证显示麦象行占多数,则改判不声明 `companyScoped`,本批变 7 页。**本批还捎带两件纯前端件**:§9.3 那 8 页的引导文案、§5 两页 C 类的 `companyScoped: false` 与"不参与"文案(都只是注册表标记 + 文案,无 DDL、无后端) | 8 | **jar 先,FE 后** | +| **2** | B 类 group 推导:查询ASIN、最低价ASIN;D 类裁剪链:撞款监控、店铺数据记录(4 页)。**开工前必须先解 §9.1/§9.2** | 4 | jar 先,FE 后 | +| **3** | 依赖二期 V145 物化列:数据去重总数据、不符合ASIN数据(**直接用 `company_id` 列,不许再走 §3.2 的推导路径,否则同页两个真相源**)。~~C 类两页的"显式声明不筛 + 文案"~~ 已提到**批次 1**(见 §5:tab 条一上线,"切了纹丝不动"就同时上线,等不到 V145) | 2 | 与二期批次 1 同批,见 §12 | + +撞款监控/店铺数据记录(D 类)要新增"多成员版" `selectManagedShopNames`(现在只吃单个 `operatorId`,`ShopDuplicateCheckSourceMapper.java:87-97`),这是动裁剪链而不是加 SQL 条件,成本比 A 类高一档,所以不放批次 1。 + +### 11.2 上线前必须实跑的取证(只交付命令,由用户执行) + +```sql +-- 1) 三个 group-only 表的 NULL 归属行数(决定 §9.1 走 a/b/c) +SELECT COUNT(*) total, SUM(group_id IS NULL) null_group FROM biz_query_asin; +SELECT COUNT(*) total, SUM(group_id IS NULL) null_group FROM biz_skip_price_asin; +-- 2) 日志管理里麦象行占比(决定 §9.2) +SELECT source, COUNT(*) FROM device_log_file GROUP BY source; +-- 3) 复核"admin_companies 授权 0 笔"这个前提(§2 的论证依赖它;一期 memory 记的是 0,需重取) +SELECT COUNT(*) FROM user_column_permission + WHERE column_id IN (SELECT id FROM columns WHERE column_key='admin_companies'); +-- 4) 每家公司成员数(§3.2 的 500 哨兵分母) +SELECT company_id, COUNT(*) FROM users GROUP BY company_id; +``` + +### 11.3 复验口径(沿用既有两条已付学费的规矩) +逐节点复验**不能打 `0.0.0.0:18080`**(nginx 轮询池),主机 B 的 java 在 `127.0.0.1:19080`;两台 jar 必须同版,混合版本窗口里新参数会被旧 jar 随机忽略。admin-vue **只在主机 B 的 `/var/www`**,验"线上==本地构建"用整树聚合摘要。 + +## 12. 口径锁定(2026-10-04,用户「继续」= 按本文推荐执行;每条都可单独推翻,推翻只影响所列批次) + +1. **不等二期 V145**:批次 0-2 先走,V145 那条线独立收尾(它的 `DEFAULT 1` 摘除有截止时间,不该被 tab 排期拖住)。⇒ 影响:批次 3 的排期挂到 V145 之后,批次 1 不因此改形。 + 附(17:0x 更正):V145 **已提交**(`b7873209`),但**仍未上线**——线上 jar 还是 `e42b37c1…`,Flyway 停在 144。"提交"与"上线"的差别要在批次 1 出包时显式判断(本计划的 jar 一旦重建重启就会把 V145 一起带上去),见实施计划 Task 13 Step 2。 +2. **NULL 归属行的处置**:默认 (a) **不声明 `companyScoped`**(宁可不筛,不静默删可见性);要走 (b) 回填(动 14k+ 行的迁移)需用户单独授权,不在本方案里自决。批次 2 开工的**前置闸门**是 §11.2 四条 SQL 的实查结果——拿不到结果就不进批次 2。 + 日志管理单独定:按 `source` 分支,`client` 按 `uid` 筛、`maixiang` 恒可见(§9.2 路线 a;实现形状见实施计划 Task 12 Step 3——它是 `(source='maixiang' OR uid IN 成员集)` 一整组,不是 `source` 值分支)。 +3. **`用户管理` 不在"必选一家"之列**:`85e1e92a` 之后这页连公司筛选器都没有了,超管看到的本来就是全公司账号——跨公司查号是它的职责。全局"默认选中第一家、不允许全部"只作用于 §11.1 批次 1 那 8 页。 +4. **tab 只进 Pinia store,不进 URL**:批次 1 的 8 页铺完优先于"链接带公司上下文"。已知代价(§4):发给同事的链接对方打开回到第一家。 +5. **界面暴露只批两处**(2026-10-04 定:新维度默认只做后端):已批 = ①`AdminLayout` 顶部那条公司 tab、②公司配置入口收窄到超管。**未批 = 任何页加"所属公司"列、任何弹窗加公司/成员下拉、按公司收窄的负责人选择器**。页头的"当前公司"行数说明也按未批处理——批次 1 先用 `operation-guides.ts` 的既有引导文案承载,不新做控件(§9.3)。 +6. **写侧归属不从界面注入**:见 §6.2/§6.3。tab 是**纯读视图**,写侧的归属规则本轮一行都不动(建号恒落操作者自己那家;店铺看请求体里的负责人,与 tab 无关——两条的差别见 §6.3);这些副作用明写不吞,并用反向钉测试钉住"写入口不许收 `company_id`"(实施计划 Task 11 Step 1 第四支、Task 12 Step 4 那条)。 + +## 13. 明确不做 + +- 不给其余 55 张业务表加 `company_id` 列(tab 全程用 `user_id → users.company_id` **派生**,零 DDL;只有二期那两张表的物化列是破例)。 +- 不做跨公司汇总/对比报表(二期 §12 同口径)。 +- 不改 `group_id` 语义,不拿它当租户键。 +- 不动 89 处数据出口、不重写 `UserDataScopeSupport` 的分组口径。 +- 不在本方案里做阶段B 设备令牌(它是二期的完成条件,不是本方案的)。 +- 不给 C 类两页临时造归属列。 diff --git a/docs/plans/19-company-tab.md b/docs/plans/19-company-tab.md new file mode 100644 index 000000000..2309deb8b --- /dev/null +++ b/docs/plans/19-company-tab.md @@ -0,0 +1,2676 @@ +# 公司 tab(超管按公司看数据)+ 公司配置读写只超管 实施计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 让 `admin_companies` 与公司下拉变成"角色内在只超管",并给后台业务数据页加一条超管用的公司 tab,使超管按公司看数据、非超管被会话锁死在本公司。 + +**Architecture:** 后端只加两个出口——`CompanyScopeSupport.memberUserIds(companyId)`(按公司枚举成员账号)和 `DataReadScope.readScope(operator, requestedCompanyId)`(把"操作者 + 请求里的 company_id"折成一个可求交的读范围),各页服务把它们叠进**既有**的 `scopedUserIds` / `UserDataScopeSupport` 口径,不另起第二套过滤。前端在 `routes.ts` 注册表上打两个标记(`superAdminOnly` / `companyScoped`),路由守卫加一条与菜单树无关的角色硬闸门,`admin-session.ts` 单点剪枝覆盖侧边栏/面包屑/首屏跳转,公司 tab 渲染在 `AdminLayout.vue` 一处、状态进 Pinia store,由各页 api 模块**显式**带 `company_id`(不做 http 层中央注入)。 + +**Tech Stack:** Java 21 / Spring Boot 3.3.9 / MyBatis-Plus 3.5.7(`LambdaQueryWrapper` + 注解 SQL)/ JUnit 5 + Mockito + AssertJ(源码扫描式护栏);Vue 3 + TS + Pinia + vue-router(`admin-frontend-vue`)+ `node --test tests/*.test.ts` + `vue-tsc --noEmit`。 + +**Spec:** `crawler-plugin/docs/ops/company-tab-design-2026-10-04.md`(已批准,§12 的四条口径已锁定)。本计划按 § 编号引用它,实施时两份一起读。 + +**基线(2026-10-04 17:0x 复查;这份计划写到一半时 HEAD 动过,以下已是动完之后的现状):** +- `crawler-plugin` 是**独立 git 仓库**,分支 `master`,HEAD = **`67b62cc3`**(`00e5df02` → `b7873209` V145 → `85e1e92a` 前端摘掉公司维度 → `67b62cc3` 18 号计划执行记录,三笔是本任务之外另一条线合进来的)。⚠️ 工作区根 `D:\todesk\副业\数富AI` 是另一个仓库(shufu-ops 运维仓库,`.gitignore:8` 的 `/*` 把 `crawler-plugin/` 整个忽略),在那里跑 `git status` 只会看到 2 个 untracked 探针、**看不到本计划依赖的任何文件**——所有 git 命令必须 `cd crawler-plugin`。 +- 工作区现在只剩 4 项 untracked,其中两项是本计划自己的产出:`docs/ops/company-tab-design-2026-10-04.md`(设计文档,Task 1 之前先提交它)、`docs/plans/19-company-tab.md`(本计划)、`backend-java/tmp-probe.txt`(我 11:47 留下的探针,收尾要删)、`tmp/`(⚠️ `tmp/c8-build` 是**真 worktree**,不是垃圾,别删)。 +- **`85e1e92a` 已经把后台的公司维度从界面上摘掉了**:`UsersPage.vue` 不再 import `fetchCompanies`、没有"全部公司"筛选、没有"所属公司"列;`CreateUserDialog.vue` 里没有 `companyId`;`user-create-model.ts` 里 `selectableCompanies`/`initialCompanyId` 已删;顶栏公司旁白删掉(`AdminLayout.vue` 因此少 3 行)。⇒ 本计划**不重做**这些,Task 2 改成"核对 + 反向钉";建号归属口径随之确定:前端请求体故意不带 `company_id`,后端 `resolveTargetCompanyId` 落操作者自己的公司 ⇒ **超管建的号一律归公司 1**(副作用见 Global Constraint 5 与 Task 11 Step 4)。 +- `b7873209` 提交了 V145(两张规则库表补 `company_id` + 唯一键每公司一套),**但它只在 git 里,没上线**:线上 jar 仍是 `e42b37c1…`(13:44 那版),Flyway 仍停在 **144**。本计划批次 1 的 jar 与 V145 谁先上、会不会把 V145 一起带上去,是 Task 13 Step 2 的显式判断点,不许默认。 +- 生产:两家启用中公司(`id=1` 厦门米椿花、`id=2` 于 10-04 14:55 开通,`users.id=1193`)、admin-vue 现网 `20261004-135428`(**早于 `85e1e92a`** ⇒ 现网那版仍在调 `GET /api/admin/companies`,这就是批次 0 顺序约束的来源,取证见 Task 2 Step 4)。 +- 后端**零 DDL**:本计划不新增任何迁移文件,不碰 `src/main/resources/db/`。 + +--- + +## Global Constraints(每个任务都受这些约束,逐字照抄自 spec 与既有坑) + +1. **发布顺序是硬约束,两条方向相反**:批次 0(Task 1-4)**前端先、jar 后**——`listVisible` 上 403 的那一版 jar 如果先发,15 个公司内管理员一开「用户管理」就撞 403,前端拦截器把 403 当未登录整页踢回登录页,症状又是"登录闪退"(2026-10-04 12:3x 生产事故的形状)。批次 1(Task 5-13)**jar 先、前端后**——jar 的 `company_id` 是可选参数、向后兼容,反过来会有"tab 存在但不筛"的撒谎窗口(spec §4、§11.1)。 +2. **tab 不是安全边界**(spec §4):超管不传 `company_id` 时必须保持今天的不筛行为;非超管传任何值都必须被会话覆盖,传别家得到**空结果**,照 `AdminUserService.java:75-81` 的"故意不报错也不越权",不许 403、不许静默改写成自己公司。 +3. **范围解析失败永不返回 null**(沿用 `CompanyScopeSupport.java:25-42` 的纪律):null 进实体 → MyBatis-Plus 跳过该列 → 被 V145 的 `DEFAULT 1` 静默兜住 = 归属失真且不报错。 +4. **只加两个后端出口,不许出现第二个 if**:任何收 `company_id` 的 controller 方法必须调 `DataReadScope.readScope(...)`,**并且必须写成显式 `@RequestParam(name = "company_id")`**(本仓库多数 controller 靠方法参数名绑定,驼峰 `Long companyId` 收到的是 `companyId=`,前端发 `company_id=` ⇒ 参数静默为 null、tab 不筛且不报错)。护栏 G2(Task 6 Step 5)逐文件同时扫这两条。 +5. **闸门读写同页,归属不从界面注入**(spec §6,2026-10-04 收窄过一次):一页进了 tab 范围,它的**角色闸门**必须读写一起动——只收窄读、不收窄行级写闸门 = 列表看不见但按 id 能改能下载(Task 8 的 `detail`/`download-zip` 就是这一类,必须补)。反过来,**任何写请求体都不许收 `company_id`**,界面上也不长出公司选择器(Task 11 Step 4 用它那条反向钉住)。⚠️ 但"归属由后端从操作者推导"这半句**只对建号成立**:店铺的归属人今天来自请求体的 `createdById`(`ShopManageService.java:86`),不是操作者 ⇒ 店铺归谁家由"负责人"决定、与 tab 无关(Task 11 Step 4 已按实查重写,spec §6.3 那句要同步限定)。已知副作用**明写不吞**:超管建号恒落自己公司 1;店铺要落别家就得把负责人选成别家的账号。 +6. **`group_id IS NULL` / `uid IS NULL` 的行不许静默从所有 tab 消失**(spec §9.1、§9.2;memory「读过滤与写按范围替换必须同时改,否则隐藏=静默删除」):默认处置是**该页不声明 `companyScoped`**(§12 第 2 条),回填需用户单独授权。 +7. **C 类两页不做 tab**:商品类目(`biz_product_category`,平台字典带 `isBuiltin`)与店铺密钥(`biz_shop_key`,紫鸟 token 池)**没有任何归属列**,本计划不给它们加列、不加参数,页头文案另开一笔(spec §5、§13)。 +8. **两张 jar 必须同版**;逐节点复验**不能打 `0.0.0.0:18080`**(nginx 轮询池),主机 B 的 java 在 `127.0.0.1:19080`;混合版本窗口里新参数会被旧 jar 忽略。admin-vue **只在主机 B 的 `/var/www`**。 +9. **不许 `skipTests` 上线**;`mvn test` 全量门禁**禁止与 Nuitka 打包并行**(`TxDurationBenchmarkTest` 抢 CPU 假红);主树禁 `git clean`;不许 `git stash`(红线归因用 detached worktree)。 +10. **生产只做只读取证**,任何 `INSERT/UPDATE/DELETE/ALTER` 只交付命令、由用户执行(既定工作方式)。只读通道 = `scripts/_prod_watch.py:171 db_sections()`。 +11. **护栏做进代码出口,不写进注释**(spec §10):G1-G6 六支实跑用例 + 每支配变异自证。变异八条硬规矩:每轮开跑前所有被注入文件写回 pristine、还原只认注入前读进内存的字节(**不许 `git checkout`**)、CRLF 锚串先对齐行尾、分母只认本轮扫描结果、扫描用例必须自带"取样集非空"自检(否则 0 命中恒绿)。 +12. **前端是 `admin-frontend-vue`,不是 `frontend-vue`**(`CLAUDE.md` 只写了后者,别混)。 +13. **不改既有测试的断言方向来迁就实现**。本计划只允许翻转 spec §10 点名的三条 `CompanyServiceDirectoryTest` 用例;其余既有用例(含 `tests/task-33.test.ts` 对 `isRouteAllowed` 三条签名的断言)必须保持绿。 +14. **界面暴露要单独批准,本计划只批了两处**(memory「新维度默认只做后端,界面暴露要单独批准」,2026-10-04):已批准 = ①`AdminLayout` 顶部那条公司 tab、②公司配置入口收窄到超管(Task 1)。**其余任何"加一列/加一个下拉/加一个筛选器"都算未批**——包括店铺列表加"所属公司"列、`GroupEditorDialog` 负责人下拉按公司收窄、C 类页页头文案之外的任何控件。执行到这类步骤时**默认不做**,把它记进附B「已知不做」,需要就回来要一次授权。归属信息的唯一正确来源是**后端从操作者会话推导**,不是界面上的一个选择器。**唯一例外是"改文案"**:spec §9.3 把"行数随 tab 变"的说明**指定**由 `operation-guides.ts` 的既有引导条目承载(正是为了不必新做控件),Task 7 Step 7 照它执行,不算未批暴露。 +15. **撤维度时测试要反向钉"不得回流"**(同一条 memory):凡是"这轮决定不做/已从界面摘掉"的维度,必须留一条实跑用例钉住它不许长回来——本计划有五处:`tests/company-user-create.test.ts` 与 `company-user-list.test.ts`(二期那条线已写好,钉建号与公司列不回流)、Task 11 Step 1 **第四支**(钉写入口不收 `company_id`)、Task 12 Step 4 **那条**(钉按 `fileId` 的端点不接 `company_id`)、Task 7 Step 7 第 4 条(钉"当前公司"只由文案与 `is-active` 承载,`CompanyTabs.vue` 里不许长出提示条)。**反向钉用例必须自带取样非空自检**(同文件里断言一个"该做的确实做了"),否则它会因为符号根本不存在而恒绿,等于没钉。 + +--- + +## 文件结构总览 + +| 动作 | 文件 | 责任 | +|---|---|---| +| Create | `admin-frontend-vue/src/config/company-scope.ts` | 两张口径清单的唯一来源:`SUPER_ADMIN_ONLY_MENU_KEYS`、`COMPANY_SCOPED_PAGES`(menuKey → api 文件 + 端点前缀)。无 import,避免与 `routes.ts` 成环 | +| Modify | `admin-frontend-vue/src/router/routes.ts` | `AdminPageDef` 加 `superAdminOnly?` / `companyScoped?`;`routeOf()` 把 `superAdminOnly` 抄进 `meta` | +| Modify | `admin-frontend-vue/src/router/index.ts:52` | 角色硬闸门(与菜单树无关) | +| Modify | `admin-frontend-vue/src/stores/admin-session.ts:30` | 单点剪掉 `superAdminOnly` 节点(侧边栏/面包屑/`firstVisible`/守卫四个消费者一起生效) | +| Create | `admin-frontend-vue/src/stores/company-tab.ts` | 公司列表 + `activeId`(默认 `id` 最小的启用公司),Pinia | +| Create | `admin-frontend-vue/src/layout/CompanyTabs.vue` | tab 条,渲染在 `AdminLayout.vue:115` 之后一处 | +| Create | `admin-frontend-vue/src/layout/company-tab-model.ts` | `companyIdForRequest` / `firstSelectableCompanyId` 两支纯函数(store 与用例共用的口径) | +| Modify | `admin-frontend-vue/src/layout/AdminLayout.vue:115-116` | 挂 `` | +| Modify | `admin-frontend-vue/src/layout/operation-guides.ts` | §9.3 承载:7 条既有 text 追加"行数随 tab 变"那句 + `admin_group_manage` 由 fallback 改独立条目(Task 7 Step 7) | +| Modify | 批次 1 的 8 页各自 `*Page.vue` | 传 `companyTab.requestCompanyId` + Task 7 Step 5 那条 `watch`(逐个见 Task 8-12 的 Files 块) | +| Modify | `backend-java/.../modules/company/service/CompanyService.java:58-76` | `listVisible` 非超管一律 403 | +| Modify | `backend-java/.../modules/permission/service/PermissionMenuService.java` | 三处出口把 `admin_companies` 从可见/可授予集合里摘掉 | +| Modify | `backend-java/.../common/service/CompanyScopeSupport.java` | 加 `memberUserIds(companyId)` + 成员数哨兵 | +| Create | `backend-java/.../common/service/DataReadScope.java` | 唯一的"操作者 + 请求 company_id → 读范围"出口 | +| Modify | 批次 1 的 8 个页面对应 controller/service(逐个见 Task 8-12 的 Files 块) | 叠 `readScope` | + +**本计划不覆盖**:spec §11.1 的批次 2(查询ASIN、最低价ASIN、撞款监控、店铺数据记录)与批次 3 的表侧改造(去重库、品牌库,依赖二期 V145)。批次 2 的**前置闸门**是 §11.2 四条生产只读 SQL 的实查结果(拿不到结果就不开工);批次 3 依赖 V145 落地,两者各需自己的计划。**§5 那两页 C 类的"不参与"声明不排在批次 3**:tab 条一上线,"切了纹丝不动"这坏观感就同时上线,所以注册表的显式 `companyScoped: false` 与它的引导文案都由批次 1 落(Task 1 Step 4、Task 7 Step 7 第 5 条)。 + +--- + +## Task 0: 开工基线自证(不做完这一步,后面每条"绿"都没有分母) + +**Files:** +- 只读,不改任何文件 + +- [ ] **Step 1: 确认 git 仓库与工作区状态** + +```bash +cd D:/todesk/副业/数富AI/crawler-plugin +git rev-parse --abbrev-ref HEAD # 期望 master +git merge-base --is-ancestor 67b62cc3 HEAD && echo OK # 本计划依赖的三笔(V145 / 前端摘维度 / 18号计划记录)必须在历史里 +git rev-parse --short HEAD # 抄进本任务提交信息;写这份计划时它在我眼皮底下从 00e5df02 跳到了 67b62cc3 +git status --short # 期望恰好 4 行 untracked(tmp-probe.txt / tmp/ / 本计划两份文档) +``` + +⚠️ **18:0x 复核:分母已经不是 4 行了。** 本计划写完时工作区长出这批**不是这计划造的**条目(HEAD 仍是 `67b62cc3`,没人新提交,是另一会话的在飞改动): + +``` + M admin-frontend-vue/src/App.vue + M admin-frontend-vue/src/main.ts + M admin-frontend-vue/src/pages/task-center/TaskCenterBoardPage.vue + M admin-frontend-vue/src/pages/tasks/DuplicateCheckPage.vue + M admin-frontend-vue/tests/align-locale.test.ts +?? admin-frontend-vue/src/plugins/ +?? admin-frontend-vue/tests/perf-admin-repeat-requests.test.ts +?? admin-frontend-vue/tests/perf-element-on-demand.test.ts +``` + +三条后果,都在下面第 2 条的处置里:①`TaskCenterBoardPage.vue` 就是 Task 10 要改的那一页,**别人的在飞改动没落定就不要动它**;`DuplicateCheckPage.vue` 属批次 2(本计划不覆盖),但同一批里还躺着 `main.ts` / `App.vue` / `src/plugins/` 这三个**全局件**——它们一动,Task 7 的 `npm test` 分母和 `vue-tsc` 结果都不再是本计划能预测的;②本计划所有提交都是按路径 `git add`,在脏树上加同名文件会把他们的半截改动一起带走;③Task 0 Step 2 的 `npm test` 分母会包含他们的用例(那两个 `perf-*.test.ts`),"红了几条"要按文件报,别把他们的红记到本计划头上。 + +⚠️ **这个仓库有另一个会话在并行提交**(16:0x→17:0x 之间 HEAD 动了一次)。所以: + +1. 每个任务开工前重跑 `git rev-parse --short HEAD`;变了就读 `git log --oneline <上次的HEAD>..HEAD`,**尤其确认 `85e1e92a` 摘掉的公司维度没被谁加回来**(Task 2 Step 1 那三支反向钉会替你红,但红在半路比红在验收时难查)。 +2. `git status --short` 出现**不是你这轮造的**条目 ⇒ 停下来出清单交用户决定(既定工作方式),别卷进提交、别回退、别替它提交。 +3. `tmp/` 里的 `tmp/c8-build` 是**真 worktree**,不是垃圾;`backend-java/tmp-probe.txt` 是我 11:47 留下的探针,本计划收尾时删(Task 13 Step 4)。 + +- [ ] **Step 2: 实测前端干净树基线(不用记忆里的 1687)** + +```bash +cd admin-frontend-vue && npm test 2>&1 | tail -5 +``` +Expected: `# fail 0`。记下 `# pass `,写进本计划最后一笔的验收说明——后面任何一次对比都用这个 N,不用记忆值。 + +- [ ] **Step 3: 实测后端基线** + +```bash +cd ../backend-java && mvn -q test 2>&1 | tail -20 +``` +Expected: `BUILD SUCCESS`,`Failures: 0, Errors: 0`。**不许与 Nuitka 打包并行**。 + +- [ ] **Step 4: 把两个基线数字记进提交信息** + +后续每个任务的"全量绿"都是与这两个数字差分,不是绝对句。 + +- [ ] **Step 5: 先把设计文档与本计划入仓(第一笔,动任何代码之前)** + +这两份文件现在还是 untracked。实施的第一笔就是它们,理由是后面 12 个任务都要引用 § 编号——不在仓里,引用就是悬空的。 + +```bash +git add docs/ops/company-tab-design-2026-10-04.md docs/plans/19-company-tab.md +git commit -m "docs(公司tab): 设计与实施计划入仓(批次 0-1,16 页普查与四条口径锁定)" +``` + +`crawler-plugin` 的远端钩子不拦 `docs/`(那条"Gitea 拒推含 docs 的提交"只适用于 `app_client` 仓库),所以这一笔能正常推。**推送与否由用户定**,本计划不代推。 + +--- + +## Task 1: 前端角色硬闸门(`superAdminOnly` 注册表 + 守卫 + 菜单树剪枝) + +**Files:** +- Create: `admin-frontend-vue/src/config/company-scope.ts` +- Modify: `admin-frontend-vue/src/router/routes.ts:4-13`(`AdminPageMeta`/`AdminPageDef`)、`:22`(`account/companies` 那条)、`:40-49`(`routeOf`) +- Modify: `admin-frontend-vue/src/router/index.ts:52` +- Modify: `admin-frontend-vue/src/stores/admin-session.ts:30` +- Test: `admin-frontend-vue/tests/company-super-admin-only.test.ts`(新建) + +**Interfaces:** +- Consumes: 无 +- Produces: + - `SUPER_ADMIN_ONLY_MENU_KEYS: readonly string[]`(值恰好 `['admin_companies']`) + - `COMPANY_SCOPED_PAGES: readonly CompanyScopedPage[]`,`CompanyScopedPage = { menuKey: string; apiFiles: string[]; pageFiles: string[] }` + - `AdminPageDef.superAdminOnly?: boolean`、`AdminPageDef.companyScoped?: boolean` + - `pruneSuperAdminOnly(nodes: T[], isSuperAdmin: boolean): T[]`(放 `src/router/helpers.ts`) + +- [ ] **Step 1: 写失败的测试** + +Create `tests/company-super-admin-only.test.ts`: + +```ts +import test from 'node:test' +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { adminPages } from '../src/router/routes.ts' +import { pruneSuperAdminOnly } from '../src/router/helpers.ts' +import { SUPER_ADMIN_ONLY_MENU_KEYS } from '../src/config/company-scope.ts' + +/** 公司配置是角色内在闸门,不是菜单授权(spec §2:菜单授权可以被人改坏,role 不能)。 + * 12:3x 事故的教训是"把页面可见性当数据可见性用",这里反过来防另一个方向:只挂一处会留旁路。 */ + +test('超管专属页必须同时被注册表与口径清单认领(两处不一致就是漏了一处)', () => { + const flagged = adminPages.filter((p) => p.superAdminOnly).map((p) => p.menuKey) + assert.deepEqual(flagged.sort(), [...SUPER_ADMIN_ONLY_MENU_KEYS].sort()) + assert.ok(SUPER_ADMIN_ONLY_MENU_KEYS.includes('admin_companies')) +}) + +test('路由守卫里必须有一条与菜单树无关的角色判定', () => { + const guard = readFileSync('src/router/index.ts', 'utf8') + assert.match(guard, /superAdminOnly/, '守卫没查角色硬闸门') + assert.match(guard, /isSuperAdmin/, '守卫必须先判 session.isSuperAdmin') +}) + +test('剪枝:非超管拿不到超管专属节点,超管一个字节都不少', () => { + const tree = [ + { key: 'g1', children: [{ key: 'admin_companies', children: [] }, { key: 'admin_users', children: [] }] }, + { key: 'admin_history', children: [] }, + ] + const forAdmin = pruneSuperAdminOnly(tree, false) + assert.equal(JSON.stringify(forAdmin).includes('admin_companies'), false, '非超管菜单树里不许留公司管理') + assert.ok(JSON.stringify(forAdmin).includes('admin_users'), '普通节点不许被误剪') + assert.equal(pruneSuperAdminOnly(tree, true), tree, '超管原样返回,不做无谓拷贝') +}) + +test('剪枝是纯函数且幂等(store 里会反复调用)', () => { + const tree = [{ key: 'admin_companies', children: [] as unknown[] }] + const once = pruneSuperAdminOnly(tree, false) + assert.deepEqual(pruneSuperAdminOnly(once, false), once) +}) + +test('C 类两页必须显式声明 companyScoped: false(spec §5:声明,不是遗漏)', () => { + // 留空和 false 运行时等价,但只有 false 是"读过普查、决定不参与"的证据。 + for (const key of ['admin_shop_keys', 'admin_product_categories']) { + const page = adminPages.find((p) => p.menuKey === key) + assert.ok(page, `注册表里找不到 ${key}`) // 取样非空自检 + assert.equal(page.companyScoped, false, `${key} 必须显式写 companyScoped: false,不能留空`) + } +}) +``` + +> 用 `assert.equal(page.companyScoped, false)` 而不是 `!page.companyScoped`:留空是 `undefined`,前者会红、后者会绿——这条要防的正是"留空"。 + +- [ ] **Step 2: 跑,确认失败** + +Run: `cd admin-frontend-vue && node --test tests/company-super-admin-only.test.ts` +Expected: FAIL —— `Cannot find module '../src/config/company-scope.ts'`。 + +- [ ] **Step 3: 建口径清单** + +Create `src/config/company-scope.ts`: + +```ts +/** 公司口径的唯一清单(设计文档 §8)。 + * 单独成文件而不是塞进 routes.ts:routes.ts 被 menu-route-map.ts import, + * 而护栏用例要从这里反过来读注册表,放在一起会成环。 */ + +/** 角色内在闸门:只有超管可见可读写,与 user_column_permission 无关。 */ +export const SUPER_ADMIN_ONLY_MENU_KEYS: readonly string[] = ['admin_companies'] + +export interface CompanyScopedPage { + /** 与 routes.ts 的 menuKey 逐字一致。 */ + menuKey: string + /** 相对 admin-frontend-vue 的 api/取数模块路径;护栏逐文件断言它真的带了 company_id。 */ + apiFiles: string[] + /** 页面组件路径;护栏断言它 watch 了 tab.activeId(否则切 tab 不重取数,tab 是装饰品)。 */ + pageFiles: string[] +} + +/** 参与公司 tab 的页(spec §3 归属普查:批次 1 = 9 个 A 类页里除去依赖二期 V145 的去重库)。 + * 后续批次往里加行时,同一笔提交必须带上对应 api 文件的 company_id,否则新用例红。 */ +export const COMPANY_SCOPED_PAGES: readonly CompanyScopedPage[] = [ + { menuKey: 'admin_task_center', apiFiles: ['src/api/task-center.ts', 'src/pages/task-center/task-center-model.ts'], pageFiles: ['src/pages/task-center/TaskCenterBoardPage.vue'] }, + { menuKey: 'admin_image_video_tasks', apiFiles: ['src/pages/tasks/image-video-api.ts'], pageFiles: ['src/pages/tasks/ImageVideoTasksPage.vue'] }, + { menuKey: 'admin_user_secret_usage', apiFiles: ['src/api/user-secret-usage.ts'], pageFiles: ['src/pages/account/UserSecretUsagePage.vue'] }, + { menuKey: 'admin_user_secrets', apiFiles: ['src/api/user-secrets.ts'], pageFiles: ['src/pages/account/UserSecretsPage.vue'] }, + { menuKey: 'admin_history', apiFiles: ['src/pages/records/history-api.ts'], pageFiles: ['src/pages/records/RecordsHistoryPage.vue'] }, + { menuKey: 'admin_device_logs', apiFiles: ['src/api/device-logs.ts'], pageFiles: ['src/pages/records/DeviceLogsPage.vue'] }, + { menuKey: 'admin_group_manage', apiFiles: ['src/pages/account/shop-group-api.ts'], pageFiles: ['src/pages/account/GroupsPage.vue'] }, + { menuKey: 'admin_shop_manage', apiFiles: ['src/pages/shop/shop-manage-api.ts'], pageFiles: ['src/pages/shop/ShopManagePage.vue'] }, +] +``` + +> `routes.ts:26-38` 的 `load()` 里写了各页真实路径(`@/pages/...`)——**Step 3 落盘前逐条与它核对**,路径写错会让护栏读不到文件而红,那正是它该有的失败方式(不许改成"文件不存在就跳过")。 + +- [ ] **Step 4: 注册表加字段并抄进 meta** + +`src/router/routes.ts`: + +```ts +export interface AdminPageMeta { + title: string + menuKey?: string + /** 角色内在闸门:非超管一律不可进(spec §2 的 A 类)。 */ + superAdminOnly?: boolean + /** 参与公司 tab:取数必须带 company_id(spec §3)。 */ + companyScoped?: boolean +} +``` + +`account/companies` 那条加 `superAdminOnly: true`;`COMPANY_SCOPED_PAGES` 里那 8 条各加 `companyScoped: true`(逐条写死,不从清单反推——清单会被 Step 1 的用例反过来对账)。 + +**C 类两页要显式写 `false`,不许留空**(spec §5:"显式声明'不按公司分',而不是静默不筛")——`routes.ts:24`(`admin_shop_keys` 店铺密钥管理)与 `:37`(`admin_product_categories` 商品类目)各加 `companyScoped: false`。留空和 `false` 在运行时**没有任何区别**(`routeOf()` 只把 `superAdminOnly` 抄进 meta,`companyScoped` 不进 meta),它的唯一作用是让"这页不参与"成为一个**写得出来的决定**,并由 Step 1 那支 `registry_declares_c_class_pages_as_explicitly_not_scoped` 钉住(它的文案在 Task 7 Step 7 第 5 条)。 + +`routeOf()` 里在 `if (page.menuKey) meta.menuKey = page.menuKey` 之后补: + +```ts + if (page.superAdminOnly) meta.superAdminOnly = true +``` + +并把 `AdminPageMeta` 的 `meta` 局部类型从 `Record` 改为 `Record`(`superAdminOnly` 是布尔,原类型会在 `vue-tsc` 下报错)。 + +- [ ] **Step 5: 剪枝纯函数** + +`src/router/helpers.ts` 末尾追加: + +```ts +import { SUPER_ADMIN_ONLY_MENU_KEYS } from '@/config/company-scope' + +/** 从菜单树上摘掉超管专属节点。非超管必须剪(它的公司管理页永远不该出现), + * 超管原样返回——超管的准入由 router/index.ts 那条角色闸门管,这里剪了反而会让侧边栏少一项。 */ +export function pruneSuperAdminOnly(nodes: T[], isSuperAdmin: boolean): T[] { + if (isSuperAdmin) return nodes + return nodes + .filter((node) => !SUPER_ADMIN_ONLY_MENU_KEYS.includes(node.key)) + .map((node) => ({ ...node, children: pruneSuperAdminOnly((node as { children?: T[] }).children || [], isSuperAdmin) })) +} +``` + +(`import` 要放到文件顶部,与既有的 `import type { AdminMenuNode }` 并列。) + +- [ ] **Step 6: 守卫加角色硬闸门** + +`src/router/index.ts:52` 之前插入: + +```ts + // 角色内在闸门:与菜单树无关。超管恒 true 会让"只剪菜单树"这条对超管无效, + // 而非超管即使被历史授权过 admin_companies 也进不来(spec §8.1:两处缺一处就留旁路)。 + if (to.meta.superAdminOnly && !session.isSuperAdmin) { + return session.firstVisible || '/' + } +``` + +- [ ] **Step 7: store 单点剪枝** + +`src/stores/admin-session.ts:30` 改成: + +```ts + this.menuTree = pruneSuperAdminOnly( + canonicalizeMenuTree(await fetchAdminMenuTree()), + isSuperAdminRole(this.user?.role), + ) +``` + +并在 import 区加 `import { pruneSuperAdminOnly } from '@/router/helpers'` 与 `import { isSuperAdminRole } from '@/types/admin'`(后者该文件已 import,确认即可)。 +⚠️ `this.user = await fetchCurrentUser()` 必须在剪枝**之前**完成——现有顺序本就如此(`:29` 再 `:30`),改的时候别调换,否则 `isSuperAdminRole(undefined)` 会把超管的菜单剪掉。 + +- [ ] **Step 8: 跑测试到绿** + +Run: `node --test tests/company-super-admin-only.test.ts tests/task-33.test.ts tests/company-menu-route.test.ts tests/admin-scaffold.test.ts` +Expected: 全 PASS。`task-33.test.ts` 断言的是 `isRouteAllowed` 三条既有语义,本任务没动它——**它要是红了就说明你改了不该改的签名**。 + +- [ ] **Step 9: 类型与全量** + +Run: `npx vue-tsc --noEmit && npm test 2>&1 | tail -5` +Expected: 无类型错误;`# fail 0`,`# pass` 与 Task 0 的 N 一致 +3。 + +- [ ] **Step 10: 提交** + +```bash +git add src/config/company-scope.ts src/router/routes.ts src/router/helpers.ts src/router/index.ts src/stores/admin-session.ts tests/company-super-admin-only.test.ts +git commit -m "feat(前端): 公司管理加角色内在闸门(注册表+守卫+剪枝)" +``` + +--- + +## Task 2: 核对批次 0 的前端半边(公司维度已由 `85e1e92a` 摘掉)+ 补唯一那条真缺口 + +**这一步的前提是复查,不是写代码。** 本任务原先写的是"给建号弹窗和用户管理页的公司控件加超管判断",那是照 `00e5df02` 那棵树写的。用户请求 (a) 要的是"非超管看不到公司配置",而 `85e1e92a` 做的是**对所有人**摘掉建号选公司、用户管理的公司列与"全部公司"筛选、顶栏公司旁白——比 (a) 更严,已经把它盖住了。所以: + +- **不许**在这个任务里把公司下拉按"超管可见"加回来:那是 Global Constraint 14 点名的未批界面暴露,而且会跟二期那条线的反向钉用例(`tests/company-user-create.test.ts`、`company-user-list.test.ts:66`)打起来。 +- 真缺口只剩一处:**「公司管理」页本身**。摘掉之后 `fetchCompanies` 在 `src/` 里只剩两个消费者(`CompaniesPage.vue`、`CompanyEditorDialog.vue`),入口由 Task 1 的 `superAdminOnly` 覆盖;本任务负责**证明覆盖到位**并取现网的证。 + +**Files:** +- Test: `admin-frontend-vue/tests/company-config-entry-super-only.test.ts`(**新建**) +- Test: `admin-frontend-vue/tests/company-user-create.test.ts`、`tests/company-user-list.test.ts`(只各加一句注释,说明那三条"恒绿断言"是反向钉,不许删) +- 无生产代码改动:Task 1 的注册表就是这半边唯一的实现 + +**Interfaces:** +- Consumes: Task 1 的 `SUPER_ADMIN_ONLY_MENU_KEYS` / `pruneSuperAdminOnly` +- Produces: 批次 0 前端半边的闭合证据三支(反向钉仍绿 + 入口剪枝生效 + 现网那版还在调 `/api/admin/companies` 的结论),以及 Step 4 那条决定发布紧迫性的取证 + +- [ ] **Step 1: 先读那三支已经存在的反向钉,确认它们钉的就是"不得回流"** + +```bash +node --test tests/company-user-create.test.ts tests/company-user-list.test.ts +``` + +逐条读到断言级别,给它们各补一句注释 `// 反向钉:公司维度不得回流到界面(2026-10-04 定口径)`——注释只加在**测试里**(这是"为什么这条今天恒绿的断言不许删"的唯一读者可见处): + +| 用例 | 钉住的事实 | +|---|---| +| `company-user-create.test.ts`「建号模型源码里公司口径已摘干净」 | `user-create-model.ts` 与 `CreateUserDialog.vue` 里 `companyId`/`CompanyItem`/`所属公司`/`selectableCompanies` 一个都不许出现 | +| `company-user-create.test.ts`「请求体不带 companyId」 | `'companyId' in toCreateUserRequest(...) === false` ⇒ 归属由后端推导 | +| `company-user-list.test.ts:66` | `UsersPage.vue` 里不许出现 `fetchCompanies` | + +> ⚠️ 这类"全文 doesNotContain"断言的共同失效方式:文件改名/路径写错时读文件会抛 ⇒ 用例红(好事)。但**如果有人把它改成 `if (exists) assert...`,它就恒绿了**。执行时确认这三条没有 existence 守卫,也没有被 `try/catch` 包住。 + +- [ ] **Step 2: 写公司配置入口的缺口用例(Task 1 的注册表在这里验收)** + +Create `tests/company-config-entry-super-only.test.ts`: + +```ts +import test from 'node:test' +import assert from 'node:assert/strict' +import { readdirSync, statSync } from 'node:fs' +import { join } from 'node:path' +import { readSource } from './helpers.ts' +import { adminPages } from '../src/router/routes.ts' +import { SUPER_ADMIN_ONLY_MENU_KEYS } from '../src/config/company-scope.ts' + +/** 递归扫 src 下指定后缀的文件(相对路径统一正斜杠)。 + * 不走 execSync('grep'):node 在 Windows 上把 execSync 交给 cmd.exe,那里没有 grep, + * 命令会「成功返回空串」而不是报错——正是恒绿的形状。扫描逻辑必须留在用例自己的进程里。 */ +function filesWithSuffix(exts: string[]): string[] { + const out: string[] = [] + const walk = (dir: string): void => { + for (const name of readdirSync(dir)) { + const abs = join(dir, name) + if (statSync(abs).isDirectory()) walk(abs) + else if (exts.some((e) => name.endsWith(e))) out.push(abs.split(/[\\/]+/).join('/')) + } + } + walk('src') + return out +} + +test('名单里的每个 menuKey 都在页面注册表上打了 superAdminOnly', () => { + assert.ok(SUPER_ADMIN_ONLY_MENU_KEYS.length >= 1, '名单为空 = 这道闸门等于没写') + for (const key of SUPER_ADMIN_ONLY_MENU_KEYS) { + const page = adminPages.find((p) => p.menuKey === key) + assert.ok(page, `${key} 不在 adminPages 里,名单形同虚设`) + assert.equal(page.superAdminOnly, true, `${key} 没打 superAdminOnly 标记`) + } +}) + +test('公司 API 模块的消费者集合恰好是公司管理那两个文件(账号页已摘干净)', () => { + const found = filesWithSuffix(['.vue', '.ts']) + .filter((rel) => readSource(rel).includes("from '@/api/companies'")) + .sort() + assert.deepEqual(found, [ + 'src/pages/account/CompaniesPage.vue', + 'src/pages/account/CompanyEditorDialog.vue', + ].sort()) + // 深比较的是"扫描真实得到的集合",不是常量和自己比;扫描漏抓会让 found 变空 ⇒ 这条红,不会恒绿。 +}) + +/** 花括号配对取函数体(和 Task 12 的 Java methodBody 同一动机:整文件比字符串会被注释和无关行骗)。 */ +function bodyOf(source: string, name: string): string { + const at = source.indexOf(`function ${name}(`) + assert.notEqual(at, -1, `${name} 不在了——读路径的钉子失去意义之前,先确认它不是被改名/删掉了`) + const open = source.indexOf('{', at) + let depth = 0 + for (let i = open; i < source.length; i++) { + if (source[i] === '{') depth++ + else if (source[i] === '}') { depth--; if (depth === 0) return source.slice(open, i + 1) } + } + assert.fail(`${name} 花括号不配对,解析失败`) +} + +test('公司列表的读路径不靠 canManage 把关(把关只有两处:Task 1 剪枝 + Task 4 后端 403)', () => { + const page = readSource('src/pages/account/CompaniesPage.vue') + // 这一条在基线上就是绿的,是反向钉(Global Constraint 15):CompaniesPage.vue:21 的 + // `const canManage = computed(() => session.isSuperAdmin)` 只门住 :63 新建、:100 编辑两个写按钮, + // 这是对的(和 GroupsPage/UserSecretsPage 同类,纯显示开关)。 + // 要防的是有人把 canManage 挪进读路径,替掉后端闸门 ⇒ 非超管看到空列表而不是 403,静默失效。 + const loader = bodyOf(page, 'loadCompanies') + assert.equal(loader.includes('canManage'), false, + 'loadCompanies 里不许出现 canManage:列表可见性由入口剪枝和后端决定,前端再加一道就变成第三套口径') +}) +``` + +> 三条断言都只读文件、不 shell out;`readSource` 拿不到文件会直接抛,`bodyOf` 找不到函数名会先 assert 红 ⇒ 用例红,这正是路径改名/函数改名时该有的失败方式(memory「护栏要做进代码出口」)。**不许**把它改成 `if (existsSync) assert...` 或包 `try/catch`。 +> +> 第三条绿是设计如此,不是漏钉:Task 13 Step 1 变异时要在 `loadCompanies` 里真的写一次 `if (!canManage.value) return`,确认它红,才算钉住。 + + + +- [ ] **Step 3: 跑,确认它红在 Task 1 之前、绿在之后** + +Run: `node --test tests/company-config-entry-super-only.test.ts` +Expected: Task 1 未完成时第一条红在 `没打 superAdminOnly 标记`(或 `SUPER_ADMIN_ONLY_MENU_KEYS` 导出不存在而编译红);Task 1 做完全 PASS。**不许**为了让它红而先动实现,也不许把 `>= 1` 改成 `>= 0` 让它早绿。 + +- [ ] **Step 4: 现网取证——批次 0 的顺序约束挂在这条读结果上** + +现网 admin-vue 是 `20261004-135428`(13:54 构建),**早于 `85e1e92a`**,所以它大概率仍在调 `GET /api/admin/companies`——12:3x 事故就是"这个调用 + 一个 403"的形状。这条取证决定的是紧迫性,不改变顺序本身: + +```bash +# 只读公开链:取现网入口 chunk,grep 能扛 minify 的字符串字面量 +python scripts/_admin_vue_probe.py # 既有探针优先;没有就直接 curl 公开链 +# 对照必须同时命中,否则"0 命中"只说明抓错了文件(memory「grep -v 过滤器连 stdout 一起吞、0 命中≠没有」) +``` + +判据(每条都要配一个非零对照,如 `/api/admin/users`): +- 命中 `/api/admin/companies` ⇒ 现网仍在拉公司目录 ⇒ **批次 0 的 admin-vue 必须先发**,Task 3 的 jar 才能上(Global Constraint 1); +- 未命中 ⇒ 现网已不依赖它,但 jar 仍要等到"包含 `85e1e92a` 之后构建的 admin-vue"上线后再上;把这条结论**写进 Task 3 的提交信息**,别留给下一个人重新猜一遍。 + +- [ ] **Step 5: 提交** + +```bash +npx vue-tsc --noEmit && npm test 2>&1 | tail -5 +git add src/config/company-scope.ts src/router/routes.ts src/router/index.ts src/stores/admin-session.ts \ + tests/company-config-entry-super-only.test.ts tests/company-user-create.test.ts tests/company-user-list.test.ts +git commit -m "feat(前端): 公司配置入口按角色剪枝;核对 85e1e92a 已摘掉的公司维度并反向钉住" +``` + +> **部署关口**:Task 1-2 合起来就是批次 0 的前端半边,**必须先于 Task 3 的 jar 上线**。出一个 admin-vue 版本后走完 §11.3 的整树聚合摘要复验,才能进 Task 3。 + +--- + +## Task 3: 后端 `listVisible` 非超管一律 403(翻转三条既有断言) + +**Files:** +- Modify: `backend-java/src/main/java/com/nanri/aiimage/modules/company/service/CompanyService.java:58-76` +- Modify: `backend-java/src/test/java/com/nanri/aiimage/modules/company/service/CompanyServiceDirectoryTest.java:120-131,160-169,172` +- Modify: `backend-java/src/test/java/com/nanri/aiimage/modules/company/service/CompanyReadPathMenuGateTest.java:41-51` + +**Interfaces:** +- Consumes: 既有 `ensureSuperAdmin(AdminUserEntity)`(`CompanyService.java:198`,抛 403) +- Produces: `List listVisible(AdminUserEntity operator)` —— 签名不变,语义变(非超管恒抛) + +- [ ] **Step 1: 先翻转三条既有断言(红)** + +`CompanyServiceDirectoryTest.java`:把 `:120-131` 整个替换为 + +```java + @Test + @DisplayName("公司内管理员读不到公司目录:读写都只超管(spec §12 需求 2)") + void companyScopedAdminCannotReadDirectory() { + assertThatThrownBy(() -> companyService.listVisible(operator("admin", 2L))) + .isInstanceOf(BusinessException.class) + .hasMessageContaining("公司"); + verify(companyMapper, never()).selectList(any()); + } +``` + +把 `:160-169` 的 `companyScopedAdminReadsOwnCompanyWithoutTheMenuGrant` 替换为 + +```java + /** + * 回归用例(2026-10-04 12:3x 生产事故)的**新形态**:当年挂 403 的是菜单授权(一笔都没发 ⇒ 全员闪退), + * 现在挂 403 的是角色。区别在于角色不会被"忘了授权"打穿,但**前端必须自己不发这个请求** + * (见 Task 2 与 tests/company-config-entry-super-only.test.ts),否则非超管照样吃 403。 + */ + @Test + @DisplayName("非超管读公司目录只认角色,不认菜单授权(菜单那条已经不可能再伤到人)") + void directoryReadGateIsRoleIntrinsicNotMenuBased() { + assertThatThrownBy(() -> companyService.listVisible(operator("admin", 2L))) + .isInstanceOf(BusinessException.class) + .hasMessageContaining("超级管理员"); + verify(companyMapper, never()).selectList(any()); + } +``` + +`:172` 的 `@DisplayName` 文案「公司内管理员读得到目录也不能建第二家公司」改为「公司内管理员读不到目录也建不了公司」。 + +`CompanyReadPathMenuGateTest.java:41-51` 的期望从 `hasSize(2)` 改为 `hasSize(3)`,`.as(...)` 文案改成 `create / update / listVisible 三处的超管闸门 must 保留`。 + +- [ ] **Step 2: 跑,确认红在预期位置** + +Run: `cd backend-java && mvn -q test -Dtest=CompanyServiceDirectoryTest,CompanyReadPathMenuGateTest` +Expected: FAIL —— 两条翻转正例失败(当前实现返回 1 行)、`hasSize(3)` 断言失败(当前 2 处)。**必须是这三条红**,别的全红说明环境不干净。 + +- [ ] **Step 3: 改实现** + +`CompanyService.java:58` 起,`listVisible` 改为: + +```java + public List 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() + .orderByAsc(CompanyEntity::getId)); + } +``` + +同时把方法上方的 Javadoc(`:44-56`)改掉两段过时的话:「这里不查菜单权限……本方法同时是「用户管理」页公司下拉的数据源」——非超管已不再拉这份目录(Task 2),改成"仅超管读写;「用户管理」页的公司下拉也只超管可见"。**留着旧注释会误导下一个改这里的人**,这比补一段新说明更要紧。 + +⚠️ `ensureSuperAdmin` 的 403 消息必须**同时含**「超级管理员」和「公司」四个字(现为「只有超级管理员可以新增或修改公司」,含「公司」;若它给 `listVisible` 复用时会说"新增或修改",就在 `listVisible` 里单独抛:`throw new BusinessException(403, "只有超级管理员可以查看公司配置")`)。原因:`:134` 和 `:143` 两条既有拒绝用例分别断言 `hasMessageContaining("管理员")` 与 `hasMessageContaining("公司")`,消息选错会把它们中一条弄红——那是**红在用例而不是实现**,白排查一轮。 + +- [ ] **Step 4: 跑,确认绿** + +Run: `mvn -q test -Dtest='Company*Test'` +Expected: `CompanyServiceDirectoryTest`、`CompanyReadPathMenuGateTest`、`CompanyServiceNameLookupTest`、`CompanyServiceRequireActiveTest` 全 PASS。 +(`CompanyServiceRequireActiveTest` 若红,是 `create`/`update` 的 `requireActive` 链路被动到——本任务不该碰它,回去查 Step 3 有没有多删行。) + +- [ ] **Step 5: 全量 + 提交** + +```bash +mvn -q test 2>&1 | tail -10 # 与 Task 0 的基线差分,不许新增红 +git add backend-java/src/main/java/com/nanri/aiimage/modules/company/service/CompanyService.java \ + backend-java/src/test/java/com/nanri/aiimage/modules/company/service/CompanyServiceDirectoryTest.java \ + backend-java/src/test/java/com/nanri/aiimage/modules/company/service/CompanyReadPathMenuGateTest.java +git commit -m "feat(公司配置): 公司目录读侧收成角色内在闸门,非超管一律403" +``` + +--- + +## Task 4: `admin_companies` 从可见/可授予集合里摘掉(三处出口 + 剥离不报错) + +**Files:** +- Modify: `backend-java/src/main/java/com/nanri/aiimage/modules/permission/service/PermissionMenuService.java:77-92`(`list`)、`:317-337`(`getUserColumnPermissions`)、`:562-658`(`updateUserColumnPermissions`) +- Test: `backend-java/src/test/java/com/nanri/aiimage/modules/permission/PermissionCompanyMenuHiddenTest.java`(新建) + +**Interfaces:** +- Consumes: `SUPER_ADMIN_ONLY_MENU_KEYS` 的后端对应物——本任务在 `PermissionMenuService` 里定义一个 `private static final Set SUPER_ADMIN_ONLY_KEYS = Set.of("admin_companies")` +- Produces: 三个出口的一致行为(授权树 / 当前用户菜单 / 提交授权) + +- [ ] **Step 0: 前置只读取证(这条决定本任务的行为变化幅度,只交付命令、由用户执行)** + +```sql +SELECT COUNT(*) AS granted FROM user_column_permission + WHERE column_id IN (SELECT id FROM columns WHERE column_key='admin_companies'); +``` +Expected:`0`(一期 memory 与 spec §2 的论证都基于"这一笔授权从没发过")。 +**若不为 0**:本任务的 Step 5 会从"没人受影响"变成"某些账号已有的公司管理入口会消失"——那是要先告知用户的真实变更,不许默默上线。把实查数字补进 spec §2 的"今天只是恰好看不见"那句。 + +- [ ] **Step 1: 写失败的测试** + +Create `PermissionCompanyMenuHiddenTest.java`(源码扫描两支): + +```java +package com.nanri.aiimage.modules.permission; + +import static org.assertj.core.api.Assertions.assertThat; +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import org.junit.jupiter.api.Test; + +/** + * admin_companies 只能由角色内在闸门管(设计文档 §8.1 的三处出口)。 + * + *

菜单行本身要**留着**(历史 user_column_permission 数据无处安放,且「菜单管理」页还得能看见它), + * 所以断言的是"从可授予集合摘掉 + 提交时剥离",不是"库里删行"。

+ */ +class PermissionCompanyMenuHiddenTest { + + private static final String SERVICE = "PermissionMenuService.java"; + private static final String KEY = "admin_companies"; + + private String source() throws IOException { + Path root = Path.of("src/main/java/com/nanri/aiimage/modules/permission/service"); + assertThat(root).as("用例依赖以 backend-java 为工作目录运行,别让守卫静默通过").isDirectory(); + String text = Files.readString(root.resolve(SERVICE), StandardCharsets.UTF_8); + assertThat(text).as("扫描取样集非空自检").contains("getUserColumnPermissions"); + return text; + } + + @Test + void threeExitsAllReferenceTheSuperAdminOnlySet() throws IOException { + String text = source(); + assertThat(text).contains("SUPER_ADMIN_ONLY_KEYS"); + // 三个出口各自都要引用它:漏一个就留一条旁路(授权树能看见 / 当前用户菜单能带出 / 提交能写回)。 + assertThat(text.split("SUPER_ADMIN_ONLY_KEYS", -1).length - 1) + .as("SUPER_ADMIN_ONLY_KEYS 至少被引用 4 次(1 次定义 + 3 处出口)") + .isGreaterThanOrEqualTo(4); + } + + @Test + void grantIsStrippedInsteadOfRejected() throws IOException { + String text = source(); + // 整树提交里带一个历史 admin_companies 绝不能 403:那会让"改密码/建号"这条链整体回滚(09-16 的形状)。 + assertThat(text).doesNotContainMatch("(?s)ensureGrantable[\\s\\S]{0,600}admin_companies[\\s\\S]{0,200}BusinessException"); + assertThat(text).contains("log.warn"); + } +} +``` + +- [ ] **Step 2: 跑,确认红** + +Run: `cd backend-java && mvn -q test -Dtest=PermissionCompanyMenuHiddenTest` +Expected: FAIL —— 两条都红(现在源码里没有 `SUPER_ADMIN_ONLY_KEYS`)。 + +- [ ] **Step 3: 定义集合 + 出口 1(授权树 `list`,`:77-92`)** + +`PermissionMenuService` 类顶部字段区加: + +```java + /** 角色内在闸门菜单:非超管看不见、谁也授不出去(设计文档 §8.1)。 + * 与前端 src/config/company-scope.ts 的 SUPER_ADMIN_ONLY_MENU_KEYS 必须同值,由 Task 7 的跨端用例钉住。 */ + private static final Set SUPER_ADMIN_ONLY_KEYS = Set.of("admin_companies"); +``` + +`list(...)` 里,在把行集折成 VO **之前**加过滤(`grantableOnly` 为 true 时**对所有角色**都摘,包括超管——这条正是"超管也不能把它授予别人";为 false 时保留,让「菜单管理」页仍能管理这一行): + +```java + boolean restrictGrantTarget = grantableOnly; + rows = rows.stream() + .filter(row -> !(restrictGrantTarget && SUPER_ADMIN_ONLY_KEYS.contains(row.getColumnKey()))) + .collect(Collectors.toList()); +``` + +(变量名以文件里既有的行集合变量为准;关键是**位置在 VO 折算前**,放在折算后会漏掉分组父节点判断。) + +- [ ] **Step 4: 出口 2(`getUserColumnPermissions`,`:317-337`)** + +在超管分支(`if (isSuperAdmin(user)) return toItemVos(menus, menus);`)之后、非超管返回之前,对 `menus` 剪掉该 key: + +```java + // 非超管:即使历史上被授过 admin_companies 也不下发(前端拿不到 key,侧边栏与守卫都无从显示)。 + List visible = menus.stream() + .filter(menu -> !SUPER_ADMIN_ONLY_KEYS.contains(menu.getColumnKey())) + .collect(Collectors.toList()); +``` + +并把后续原本用 `menus` 的两处换成 `visible`。**别只改返回值忘了改喂给 `toItemVos` 的第二个参数**,否则父分组会因"组下无可显示子项"被整体剪掉——那是把「用户管理」一起弄红的经典改法。 + +- [ ] **Step 5: 出口 3(`updateUserColumnPermissions`,`:562-658` / `ensureGrantable` `:925-942`)** + +在提交 id 集合进入 `ensureGrantable` **之前**剥离,并 warn 不抛: + +```java + List stripped = ids.stream() + .filter(id -> SUPER_ADMIN_ONLY_KEYS.contains(keyOf(id))) + .toList(); + if (!stripped.isEmpty()) { + // 剥离而不是 403:整树提交里带一条历史授权,绝不能让「保存权限」这次操作整体失败 + // (09-16 的静默权限丢失是反例,但 403 会让用户以为保存坏了)。 + log.warn("GRANT_SUPER_ADMIN_ONLY_STRIPPED 已剥离超管专属菜单授权 ids={} operatorId={}", stripped, operatorId); + ids = new ArrayList<>(ids); + ids.removeAll(stripped); + } +``` + +`keyOf(Long menuId)` 用本类已有的"按 id 取 columnKey"手段(若没有就 `permissionMenuMapper.selectBatchIds(stripped)` 一次批量取,**不许逐条查**——N 次点查在保存权限这个入口上会被日志放大)。 + +⚠️ 同时确认删除范围那段(`:624-641`)没被改窄:`stripped` 的 id **不许进"要删除"集合**,否则剥离动作会顺手把历史授权行删掉 = 静默改数据。断言方式:Step 6 里加一条 `verify(mapper, never()).delete(any())`(按本类实际的删除方法名写)。 + +- [ ] **Step 6: 跑 + 全量 + 提交** + +Run: `mvn -q test -Dtest='Permission*Test'` +Expected: `PermissionCompanyMenuHiddenTest` 两支绿;既有 `PermissionMenuServiceTest` 系列不新增红。 + +```bash +mvn -q test 2>&1 | tail -10 +git add backend-java/src/main/java/com/nanri/aiimage/modules/permission/service/PermissionMenuService.java \ + backend-java/src/test/java/com/nanri/aiimage/modules/permission/PermissionCompanyMenuHiddenTest.java +git commit -m "feat(权限): admin_companies 从可见/可授予集合摘掉,提交时剥离不报错" +``` + +> **批次 0 到此齐**:Task 1-4 是完整一批(前端两笔先上、后端两笔后上)。上线后必须实跑:用一个**非超管 admin** 账号登录,确认①侧边栏没有「公司管理」②「用户管理」页正常打开且 Network 里**没有** `/api/admin/companies` 请求③给它保存一次权限、带一条历史 `admin_companies` 授权,保存成功且日志出 `GRANT_SUPER_ADMIN_ONLY_STRIPPED`。 + +--- + +## Task 5: `CompanyScopeSupport.memberUserIds`(按公司枚举成员)+ 成员数哨兵 + +**Files:** +- Modify: `backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java` +- Test: `backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java`(**二期那条线已建了这个文件;若已存在就在里面追加,别覆盖**) + +**Interfaces:** +- Consumes: `common/mapper/AdminUserMapper`(`BaseMapper`)、`AdminUserEntity.getCompanyId()` +- Produces: `List memberUserIds(Long companyId)`(顺序不保证;空公司返回空集;`companyId` 非法抛 `BusinessException`) + +- [ ] **Step 0: 先取分母(只读,不写)** + +`memberUserIds` 返回的集合长度就是每个 tab 的 `user_id IN (...)` 长度,也是 G6 阈值的对照物。跑这条只读 SQL(通道见 memory「生产环境接入要点」的只读通道,不要自己另开一条): + +```sql +SELECT company_id, COUNT(*) AS members + FROM users + GROUP BY company_id + ORDER BY company_id; +``` + +把结果抄进本任务的提交信息里。三个数各自决定一件事: + +1. `MAX(members)` 与 `MEMBER_WARN_THRESHOLD = 500` 的余量——余量小于 5 倍说明阈值定太高,哨兵等于不存在; +2. `company_id IS NULL` 那一行的计数——**必须为 0**。非 0 说明 143/144 之后仍有游离账号,`memberUserIds` 按公司等值查会把他们从**每一个** tab 里丢掉(spec §9 的静默丢数形态),先补归属再往下走; +3. companies 数与 spec §1 的「生产已有 2 家」对账。 + +本文件正文写的「今天全库 140 行」是拆工时的那次读数,**不是分母**:以 Step 0 实跑结果为准,对不上就按实跑值改写 Step 3 的 javadoc 与本条,别把过期数字留在计划里(memory「结论要说比例不说绝对句」+「分母只认本轮」)。 + +- [ ] **Step 1: 追加失败的测试** + +```java + @Test + @DisplayName("按公司枚举成员:只投影 id,别把整行拉进内存") + void memberUserIdsSelectsOnlyIdColumn() { + AdminUserEntity a = new AdminUserEntity(); a.setId(11L); + AdminUserEntity b = new AdminUserEntity(); b.setId(12L); + when(adminUserMapper.selectList(any())).thenReturn(List.of(a, b)); + + assertThat(companyScope.memberUserIds(2L)).containsExactlyInAnyOrder(11L, 12L); + + ArgumentCaptor> captor = ArgumentCaptor.forClass(LambdaQueryWrapper.class); + verify(adminUserMapper).selectList(captor.capture()); + LambdaQueryWrapper q = captor.getValue(); + assertThat(q.getSqlSelect()).as("必须只 select id,今天全库 140 行不代表以后也是") + .containsIgnoringCase("id").doesNotContain("*"); + assertThat(q.getParamNameValuePairs()).containsValue(2L); + } + + @Test + @DisplayName("非法公司 id 直接抛,不返回空集——空集在调用方是「查不到行」,语义完全不同") + void memberUserIdsRejectsBadCompanyId() { + assertThatThrownBy(() -> companyScope.memberUserIds(null)) + .isInstanceOf(BusinessException.class); + assertThatThrownBy(() -> companyScope.memberUserIds(0L)) + .isInstanceOf(BusinessException.class); + verify(adminUserMapper, never()).selectList(any()); + } +``` + +> `getSqlSelect()` 若在该 MP 版本上不渲染列,退成断言 `verify(adminUserMapper).selectList(...)` 的 wrapper 里 `sqlSelect` 非空——**先在 Step 2 跑出红来确认哪种读法咬得住,再定稿**,不许写成 `contains("company_id")` 那种恒真断言(memory「字符串断言必须排他」)。 + +- [ ] **Step 2: 跑,确认红** + +Run: `mvn -q test -Dtest=CompanyScopeSupportTest` +Expected: FAIL —— `memberUserIds` 方法不存在(编译失败也算预期红)。 + +- [ ] **Step 3: 实现** + +`CompanyScopeSupport.java` 加 `@Slf4j`(现无)与: + +```java + /** 超过这个成员数就该把 `user_id IN (...)` 换成子查询(见下方 warn 与 spec §3.2)。 */ + static final int MEMBER_WARN_THRESHOLD = 500; + + /** + * 按公司枚举成员账号 id(spec §3.2:tab 的读范围唯一来源)。 + * + *

不加 LIMIT:今天全库 140 行,截断会让某个公司的 tab 看起来"数据不全"且毫无提示。 + * 用 {@link #MEMBER_WARN_THRESHOLD} 当倒计时哨兵——它红在日志里、可被巡检抓到, + * 比"以后再说"安全。

+ */ + public List memberUserIds(Long companyId) { + if (companyId == null || companyId <= 0) { + throw new BusinessException("公司 id 不能为空"); + } + List rows = adminUserMapper.selectList( + new LambdaQueryWrapper() + .select(AdminUserEntity::getId) + .eq(AdminUserEntity::getCompanyId, companyId)); + List ids = new ArrayList<>(rows.size()); + for (AdminUserEntity row : rows) { + if (row.getId() != null && row.getId() > 0) { + ids.add(row.getId()); + } + } + if (ids.size() > MEMBER_WARN_THRESHOLD) { + log.warn("COMPANY_MEMBER_SET_LARGE companyId={} size={} threshold={}" + + " —— user_id IN (...) 列表已过长,改成 SELECT id FROM users WHERE company_id = ? 子查询", + companyId, ids.size(), MEMBER_WARN_THRESHOLD); + } + return ids; + } +``` + +- [ ] **Step 4: 哨兵用例(G6)** + +```java + @Test + @DisplayName("G6 倒计时哨兵:成员数过阈值必须打 COMPANY_MEMBER_SET_LARGE(护栏在代码出口,不在注释)") + void warnsWhenMemberSetExceedsThreshold() { + List 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 ids = companyScope.memberUserIds(3L); + + assertThat(ids).hasSize(CompanyScopeSupport.MEMBER_WARN_THRESHOLD + 1); + // 断言方式二选一,以本仓既有日志测试手段为准:要么 ListAppender 抓日志, + // 要么把阈值判定抽成 package-private 的 boolean shouldWarn(int) 直接断言。 + assertThat(CompanyScopeSupport.shouldWarn(ids.size())).isTrue(); + } +``` + +按 Step 4 的注释落定其一后,把 Step 3 里的 `if (ids.size() > MEMBER_WARN_THRESHOLD)` 换成 `if (shouldWarn(ids.size()))`,并加: + +```java + static boolean shouldWarn(int size) { + return size > MEMBER_WARN_THRESHOLD; + } +``` + +- [ ] **Step 5: 跑 + 提交** + +Run: `mvn -q test -Dtest=CompanyScopeSupportTest` +Expected: 全 PASS。 +```bash +git add backend-java/src/main/java/com/nanri/aiimage/common/service/CompanyScopeSupport.java \ + backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyScopeSupportTest.java +git commit -m "feat(公司范围): memberUserIds 按公司枚举成员 + 500 成员倒计时哨兵" +``` + +--- + +## Task 6: `DataReadScope`——唯一的"操作者 + 请求 company_id → 读范围"出口(G2 落在这) + +**Files:** +- Create: `backend-java/src/main/java/com/nanri/aiimage/common/service/DataReadScope.java` +- Test: `backend-java/src/test/java/com/nanri/aiimage/common/service/DataReadScopeTest.java`(新建) +- Test: `backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java`(新建,G2) + +**Interfaces:** +- Consumes: `CompanyScopeSupport.memberUserIds(Long)`、`CompanyScopeSupport.requireCompanyId(AdminUserEntity)`、`common/security/AdminAuthSupport.currentRole(AdminUserEntity)`、`modules/permission/support/UserDataScopeSupport.resolveVisibleUserIds(Long)` +- Produces: + - `ReadScope DataReadScope.readScope(AdminUserEntity operator, Long requestedCompanyId)` + - `boolean ReadScope.isUnfiltered()`、`List ReadScope.userIds()`、`List ReadScope.userIdsOr(List base)` + +- [ ] **Step 1: 写失败的测试(spec §7 的五种组合逐个断言)** + +```java +package com.nanri.aiimage.common.service; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; +import com.nanri.aiimage.common.model.entity.AdminUserEntity; +import com.nanri.aiimage.common.security.AdminAuthSupport; +import com.nanri.aiimage.modules.permission.support.UserDataScopeSupport; +import java.util.List; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +/** 公司 tab 的唯一范围出口(spec §7)。五种组合必须逐个钉死——它们决定线上会不会越权。 */ +class DataReadScopeTest { + + private CompanyScopeSupport companyScope; + private AdminAuthSupport adminAuthSupport; + private UserDataScopeSupport userDataScope; + private DataReadScope readScope; + + private static AdminUserEntity user(long id, String role, Long companyId) { + AdminUserEntity u = new AdminUserEntity(); + u.setId(id); u.setRole(role); u.setCompanyId(companyId); + return u; + } + + @BeforeEach + void setUp() { + companyScope = mock(CompanyScopeSupport.class); + adminAuthSupport = mock(AdminAuthSupport.class); + userDataScope = mock(UserDataScopeSupport.class); + when(adminAuthSupport.currentRole(any())).thenAnswer(inv -> ((AdminUserEntity) inv.getArgument(0)).getRole()); + readScope = new DataReadScope(companyScope, adminAuthSupport, userDataScope); + } + + @Test + @DisplayName("超管不选公司 = 今天的行为:完全不筛") + void superAdminWithoutCompanyStaysUnfiltered() { + ReadScope scope = dataReadScope.readScope(user(1L, "super_admin", 1L), null); + assertThat(scope.isUnfiltered()).isTrue(); + assertThat(scope.userIdsOr(List.of(9L))).containsExactly(9L); + assertThat(scope.userIdsOr(null)).isNull(); + } + + @Test + @DisplayName("超管选公司 = 该公司成员替换掉「不筛」") + void superAdminWithCompanyNarrowsToMembers() { + when(companyScope.memberUserIds(2L)).thenReturn(List.of(11L, 12L)); + ReadScope scope = dataReadScope.readScope(user(1L, "super_admin", 1L), 2L); + assertThat(scope.userIdsOr(null)).containsExactlyInAnyOrder(11L, 12L); + } + + @Test + @DisplayName("超管选不存在的公司 = 空集 → 空页,不是 403、也不是全量") + void superAdminWithUnknownCompanyYieldsEmpty() { + when(companyScope.memberUserIds(99L)).thenReturn(List.of()); + ReadScope scope = dataReadScope.readScope(user(1L, "super_admin", 1L), 99L); + assertThat(scope.isUnfiltered()).isFalse(); + assertThat(scope.userIdsOr(null)).isEmpty(); + assertThat(scope.userIdsOr(List.of(9L))).isEmpty(); + } + + @Test + @DisplayName("非超管永远锁本公司,不传也一样") + void adminIsAlwaysPinnedToOwnCompany() { + when(companyScope.requireCompanyId(any(AdminUserEntity.class))).thenReturn(2L); + when(companyScope.memberUserIds(2L)).thenReturn(List.of(21L, 22L)); + when(userDataScope.resolveVisibleUserIds(5L)).thenReturn(List.of(21L, 99L)); + + ReadScope scope = dataReadScope.readScope(user(5L, "admin", 2L), null); + // 与既有的分组可见集**求交**,不是替换:非超管的组长范围不能被公司 tab 放大。 + assertThat(scope.userIdsOr(userDataScope.resolveVisibleUserIds(5L))).containsExactly(21L); + } + + @Test + @DisplayName("非超管传别家 = 空结果,不报错也不越权(照 AdminUserService:75-81)") + void adminPassingForeignCompanyGetsEmptyNot403() { + when(companyScope.requireCompanyId(any(AdminUserEntity.class))).thenReturn(2L); + ReadScope scope = dataReadScope.readScope(user(5L, "admin", 2L), 7L); + assertThat(scope.isUnfiltered()).isFalse(); + assertThat(scope.userIds()).isEmpty(); + } + + @Test + @DisplayName("非超管没有公司归属时炸,不退化成「不筛」") + void adminWithoutCompanyFailsFast() { + when(companyScope.requireCompanyId(any(AdminUserEntity.class))) + .thenThrow(new com.nanri.aiimage.common.exception.BusinessException(403, "当前账号没有所属公司")); + assertThat(org.assertj.core.api.Assertions.assertThatThrownBy( + () -> dataReadScope.readScope(user(5L, "admin", null), null))) + .isInstanceOf(com.nanri.aiimage.common.exception.BusinessException.class); + } +} +``` + +- [ ] **Step 2: 跑,确认红** + +Run: `mvn -q test -Dtest=DataReadScopeTest` +Expected: 编译失败(`DataReadScope` / `ReadScope` 不存在)。 + +- [ ] **Step 3: 实现 `ReadScope`** + +```java +package com.nanri.aiimage.common.service; + +import java.util.ArrayList; +import java.util.List; + +/** + * 一次读请求的租户范围(设计文档 §7)。两种状态:不筛(超管没选公司 = 今天的行为) + * 与"限定到这批账号"。 + * + *

{@link #userIdsOr(List)} 是它与各页**既有** `scopedUserIds` 唯一的接合点: + * base 传 null 表示"这页原本不筛",此时返回公司范围;两边都有值时求交, + * 因为公司 tab 只能**收窄**、不能放大组长本来看不到的行。

+ */ +public final class ReadScope { + + private final boolean unfiltered; + private final List userIds; + + private ReadScope(boolean unfiltered, List userIds) { + this.unfiltered = unfiltered; + this.userIds = userIds; + } + + public static ReadScope unfiltered() { + return new ReadScope(true, List.of()); + } + + public static ReadScope users(List ids) { + return new ReadScope(false, ids == null ? List.of() : List.copyOf(ids)); + } + + public boolean isUnfiltered() { + return unfiltered; + } + + public List userIds() { + return userIds; + } + + /** 空集 = 调用方应当直接返回空页(各页服务本来就有这条分支,照它写)。 */ + public List userIdsOr(List base) { + if (unfiltered) return base; + if (base == null) return userIds; + List out = new ArrayList<>(base); + out.retainAll(userIds); + return out; + } +} +``` + +- [ ] **Step 4: 实现 `DataReadScope`** + +```java +package com.nanri.aiimage.common.service; + +import com.nanri.aiimage.common.model.entity.AdminUserEntity; +import com.nanri.aiimage.common.security.AdminAuthSupport; +import com.nanri.aiimage.modules.permission.support.UserDataScopeSupport; +import java.util.List; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Service; + +/** + * "操作者 + 请求里的 company_id → 该查哪批账号"的**唯一**出口(设计文档 §7)。 + * + *

各页 service 一律走这里,不许自己写 if:一条越权旁路的成本是"这一页的过滤是假的", + * 而它不会报错。护栏 {@code CompanyIdParamGoesThroughReadScopeTest} 逐文件扫这条纪律。

+ */ +@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 base = userDataScopeSupport.resolveVisibleUserIds(operator.getId()); + return ReadScope.users(ReadScope.users(companyScope.memberUserIds(own)).userIdsOr(base)); + } +} +``` + +- [ ] **Step 5: G2 源码扫描用例(防"第二个 if")** + +```java +package com.nanri.aiimage.common.service; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.fail; +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.stream.Collectors; +import java.util.stream.Stream; +import org.junit.jupiter.api.Test; + +/** + * G2(spec §10):每个收 company_id 的 controller 必须走 readScope。 + * 漏一处 = 那一页的 tab 是假的,而且不报错。 + */ +class CompanyIdParamGoesThroughReadScopeTest { + + @Test + void everyCompanyIdEndpointGoesThroughReadScope() throws IOException { + Path root = Path.of("src/main/java"); + if (!Files.isDirectory(root)) fail("找不到 " + root + " —— 用例依赖以 backend-java 为工作目录"); + List controllers; + try (Stream walk = Files.walk(root)) { + controllers = walk.filter(Files::isRegularFile) + .filter(p -> p.getFileName().toString().endsWith("Controller.java")) + .filter(p -> read(p).contains("company_id")) + .collect(Collectors.toList()); + } + assertThat(controllers) + .as("取样集非空自检:一条都没扫到说明扫描失效,护栏等于没写") + .isNotEmpty(); + for (Path controller : controllers) { + String text = read(controller); + assertThat(text) + .as(controller + " 收了 company_id 却没走唯一出口") + .contains("readScope("); + // 第二条:参数必须**显式**写 name = "company_id"。 + // 本仓库多数 controller 靠"方法参数名即请求名"绑定(ShopManageController:66-71 的 pageSize/groupId/shopName 就是), + // 照那个习惯写成 `Long companyId` 时 Spring 收的是 companyId=,而前端发的是 company_id= + // ⇒ 参数永远 null、接口 200、tab 切了不筛。这是全批次唯一"错了也不红"的形状,所以钉在扫描里。 + assertThat(text) + .as(controller + " 的 company_id 没写显式 name=,会和驼峰参数名混成两种拼写") + .contains("name = \"company_id\""); + } + } + + private static String read(Path path) { + try { + return new String(Files.readAllBytes(path), StandardCharsets.UTF_8); + } catch (IOException e) { + throw new IllegalStateException("读不到 " + path, e); + } + } +} +``` + +- [ ] **Step 6: 跑 + 提交(jar 半边)** + +Run: `mvn -q test -Dtest='DataReadScopeTest,CompanyIdParamGoesThroughReadScopeTest'` +Expected: 全 PASS。 +```bash +mvn -q test 2>&1 | tail -10 +git add backend-java/src/main/java/com/nanri/aiimage/common/service/DataReadScope.java \ + backend-java/src/test/java/com/nanri/aiimage/common/service/ +git commit -m "feat(公司范围): DataReadScope 唯一读范围出口 + G2 扫 company_id 端点" +``` + +--- + +## Task 7: tab 机制(store + 组件 + 请求侧显式带参 + G1 双向对账 + §9.3 引导文案承载) + +**Files:** +- Create: `admin-frontend-vue/src/layout/company-tab-model.ts`(两支纯函数,store 与用例共用) +- Create: `admin-frontend-vue/src/stores/company-tab.ts` +- Create: `admin-frontend-vue/src/layout/CompanyTabs.vue` +- Modify: `admin-frontend-vue/src/layout/AdminLayout.vue:16`(import)、`:115-116`(挂载) +- Modify: `admin-frontend-vue/src/layout/operation-guides.ts`(Step 7:7 条既有 text 追加一句 + `admin_group_manage` 由 fallback 改独立条目) +- Modify: `admin-frontend-vue/tests/align-operation-guide.test.ts`(`:28-31` 那一支要跟着改 + Step 7 第 4 支新用例) +- Modify: `admin-frontend-vue/src/config/company-scope.ts`(加 `companyTabModel.ts` 需要的类型即可,不改清单) +- Test: `admin-frontend-vue/tests/company-tab-model.test.ts`、`tests/company-tab-wiring.test.ts`(新建) + +**Interfaces:** +- Consumes: Task 1 的 `COMPANY_SCOPED_PAGES`、`api/companies.ts` 的 `fetchCompanies()`、`session.isSuperAdmin` +- Produces: + - `useCompanyTabStore()`:state `{ companies: CompanyItem[], activeId: number | null, loading: boolean, loaded: boolean }`,getters `{ visibleForOperator: boolean, requestCompanyId: number | null }`,actions `{ initialize(): Promise, setActiveId(id: number): void }` + ⚠️ 后续任务(Task 8/9/10/11/12)取公司值**一律写 `companyTab.requestCompanyId`**(getter,非超管与未初始化时恒 `null`)。`companyIdForRequest` 是它底下那支**纯函数**的名字,签名要两个入参——在页面里裸调它是编译错误,不是"少传一个参数"。 + - `companyIdForRequest(isSuperAdmin: boolean, activeId: number | null): number | null`(纯函数,放 `src/layout/company-tab-model.ts`) + - `firstSelectableCompanyId(companies: readonly CompanyItem[]): number | null`(纯函数,同放 `src/layout/company-tab-model.ts`) + +- [ ] **Step 1: 写失败的纯函数测试** + +Create `tests/company-tab-model.test.ts`: + +```ts +import test from 'node:test' +import assert from 'node:assert/strict' +import type { CompanyItem } from '../src/api/companies-dto.ts' +import { companyIdForRequest, firstSelectableCompanyId } from '../src/layout/company-tab-model.ts' + +/** 定义在三条 test **之前**:node:test 的用例回调按声明序执行,挪到文件尾会踩 TDZ。 */ +const company = (id: number, companyName: string, status: number): CompanyItem => + ({ id, companyName, status, remark: null, createdAt: null, updatedAt: null }) + +test('非超管永远不下传 company_id(后端按会话裁剪,前端传了也只会被忽略——不许出现"前端以为自己筛了")', () => { + assert.equal(companyIdForRequest(false, 2), null) +}) + +test('超管默认选中 id 最小的启用公司,不是超管自己那家、也不是接口返回顺序的第一条', () => { + // 字段名用 CompanyItem 的真名(id / companyName / status):它的 label 列叫 companyName 不叫 name, + // 写成 name 的用例照样绿(firstSelectableCompanyId 不读 label),但组件里 item.name 会是 undefined。 + assert.equal(firstSelectableCompanyId([ + company(3, '丙', 1), + company(1, '厦门米椿花', 1), + company(2, '乙', 0), + ]), 1) +}) + +test('全是停用公司时返回 null,tab 条整体不渲染(而不是给一个选不中的空 tab)', () => { + assert.equal(firstSelectableCompanyId([company(2, '乙', 0)]), null) +}) + +test('超管没拿到 activeId 之前不下传(宁可不筛,也别拿 null 去拼 "company_id=null")', () => { + assert.equal(companyIdForRequest(true, null), null) + assert.equal(companyIdForRequest(true, 2), 2) +}) +``` + +- [ ] **Step 2: 跑,确认红** + +Run: `node --test tests/company-tab-model.test.ts` +Expected: FAIL —— 模块不存在。 + +- [ ] **Step 3: 实现纯函数 + store** + +Create `src/layout/company-tab-model.ts`: + +```ts +import { COMPANY_STATUS_ACTIVE, type CompanyItem } from '@/api/companies-dto' + +/** 超管的读范围公司。非超管恒 null——它的公司是固定的,下传一个常数只会让人以为这页在按公司筛。 */ +export function companyIdForRequest(isSuperAdmin: boolean, activeId: number | null): number | null { + return isSuperAdmin ? activeId : null +} + +/** 「默认选中第一家」= id 最小的启用公司(spec §4 口径:不是超管自己所属公司,也不是返回顺序首条)。 */ +export function firstSelectableCompanyId(companies: readonly CompanyItem[]): number | null { + const active = companies.filter((c) => c.status === COMPANY_STATUS_ACTIVE && c.id > 0) + if (!active.length) return null + return active.reduce((min, c) => (c.id < min ? c.id : min), active[0].id) +} +``` + +Create `src/stores/company-tab.ts`: + +```ts +import { defineStore } from 'pinia' +import { fetchCompanies } from '@/api/companies' +import type { CompanyItem } from '@/api/companies-dto' +import { useAdminSessionStore } from '@/stores/admin-session' +import { firstSelectableCompanyId, companyIdForRequest } from '@/layout/company-tab-model' + +/** 公司 tab 的状态。成员 user ids **不在这里缓存**——每次请求交后端解析, + * 否则"改了成员没刷新页面"会出现一个看起来筛了、实际按旧名单筛的范围。 */ +export const useCompanyTabStore = defineStore('company-tab', { + state: () => ({ + companies: [] as CompanyItem[], + activeId: null as number | null, + loading: false, + loaded: false, + }), + getters: { + /** 只有超管需要这份目录(Task 2 之后非超管连 GET 都不该发)。 + * 「该不该画 tab 条」这条判断**只住在这里**:组件里再写一遍 `length > 1` 就是第二把尺子, + * 将来改口径会两边不一致。loaded 也计入——没拉完之前不画,免得先闪出一条空 tab。 */ + visibleForOperator(): boolean { + return this.loaded && useAdminSessionStore().isSuperAdmin && this.companies.length > 1 + }, + requestCompanyId(): number | null { + return companyIdForRequest(useAdminSessionStore().isSuperAdmin, this.activeId) + }, + }, + actions: { + async initialize() { + const session = useAdminSessionStore() + if (this.loaded || this.loading || !session.isSuperAdmin) return + this.loading = true + try { + this.companies = await fetchCompanies() + this.activeId = firstSelectableCompanyId(this.companies) + this.loaded = true + } finally { + this.loading = false + } + }, + setActiveId(id: number) { + this.activeId = id + }, + $resetOnSignOut() { + this.$reset() + }, + }, +}) +``` + +⚠️ `companies.length > 1` 才显示 tab 条:今天两家,符合"有得选才给选";只有一家时画一条孤零零的 tab 会让人以为筛选坏了。这条判断**只**放进 `visibleForOperator`,组件里 `show` 直接抄它——组件再算一遍 `tabs.value.length > 1` 就是第二把尺子(而且它数的是"启用中的",store 数的是"拉到的",停用一家时两者会差 1)。 + +- [ ] **Step 4: 组件与挂载** + +Create `src/layout/CompanyTabs.vue`(`el-tabs` 型,逐字与截图红框位置一致): + +```vue + + + +``` + +⚠️ **这个组件到此为止,不要在 tab 条旁边再挂一句"当前公司:X"**(草稿里我写了这么一支 ``,已删)。§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 之后),模板在 ``(`:115`)与 ``(`:116`)之间插一行 ``。 + +- [ ] **Step 5: 切 tab 必须让当前页重新取数(否则 tab 是个装饰品)** + +**已定机制(不做事后二选一)**:`CompanyTabs.vue` 只写 store,不碰 URL(§12 第 4 条:公司上下文不进 URL);各页组件加一行监听重取: + +```ts +// 每页 setup 末尾,紧跟该页已有的 loadXxx 定义: +import { useCompanyTabStore } from '@/stores/company-tab' +const companyTab = useCompanyTabStore() +// 切公司 = 重新取数。不重取的页 = tab 在那页上是假的(G1 的 pageFiles 断言盯着这条)。 +watch(() => companyTab.activeId, () => void load()) +``` + +`watch` 从 `vue` import(多数页已有 `computed/watch` 的 import 行,补 `watch` 即可)。`load` 换成该页实际的取数函数名。 + +G1 的正向断言会把"漏了这一行的页"直接抓出来,所以这里**不许**用 `router.replace({query:{_c:id}})` 之类的"借路由重挂载"变通——那等于把公司上下文写进 URL,违反 §12 第 4 条,且刷新后仍会丢。 + +- [ ] **Step 6: G1 双向对账用例** + +Create `tests/company-tab-wiring.test.ts`: + +```ts +import test from 'node:test' +import assert from 'node:assert/strict' +import { existsSync, readFileSync, readdirSync } from 'node:fs' +import { adminPages } from '../src/router/routes.ts' +import { COMPANY_SCOPED_PAGES, SUPER_ADMIN_ONLY_MENU_KEYS } from '../src/config/company-scope.ts' + +const read = (p: string) => { + assert.ok(existsSync(p), `护栏读不到 ${p}:api 文件改名了,清单必须同步(别把用例改成"不存在就跳过")`) + return readFileSync(p, 'utf8') +} + +test('正向:声明 companyScoped 的页,其 api 文件必须真的带 company_id,页面组件必须 watch activeId', () => { + for (const page of COMPANY_SCOPED_PAGES) { + assert.ok(adminPages.some((p) => p.menuKey === page.menuKey && p.companyScoped), + `${page.menuKey} 在清单里但注册表没声明 companyScoped`) + for (const file of page.apiFiles) { + assert.match(read(file), /company_id|companyId/, `${file} 声明参与公司 tab 却没下传 company_id`) + } + for (const file of page.pageFiles) { + assert.match(read(file), /watch\(\(\)\s*=>\s*companyTab\.activeId/, + `${file} 没监听公司 tab:切 tab 不重取数 = 这页的 tab 是装饰品`) + } + } +}) + +test('反向:把 company_id 当查询参数用的取数模块必须被清单认领(防止"筛了但没人知道这页参与")', () => { + const claimed = new Set(COMPANY_SCOPED_PAGES.flatMap((p) => p.apiFiles)) + const scanned = requestModules() + // 取样自检:扫描本身失效(目录改名/递归参数写错)时下面这支会"零文件 ⇒ 恒绿"。 + assert.ok(scanned.length >= 35, `只扫到 ${scanned.length} 个取数模块,requestModules 八成是坏了`) + for (const file of scanned) { + if (claimed.has(file)) continue + const text = stripComments(readFileSync(file, 'utf8')) + assert.equal(/['"]company_id['"]|\bcompany_id\s*[:=]/.test(text), false, + `${file} 自己塞了 company_id 参数但没进 COMPANY_SCOPED_PAGES——它绕过了唯一清单`) + } +}) + +test('两张清单不许重叠:超管专属页不可能同时是按公司看数据的页', () => { + const scoped = new Set(COMPANY_SCOPED_PAGES.map((p) => p.menuKey)) + for (const key of SUPER_ADMIN_ONLY_MENU_KEYS) assert.equal(scoped.has(key), false) +}) + +/** 分母 = **会把 company_id 发出去的模块**:`src/api` 下的 .ts 与 `src/pages` 下名字以 `-api.ts` 结尾的模块,实测 40 个。 + * 不是"所有 .ts"(135 个):查询对象的**类型**声明住在 `history-dto.ts`、`image-video-filter.ts`、`shop-dto.ts` + * 这些兄弟模块里(Task 8/10/11 要给它们加 `company_id?: number`),类型行本身长得像"用了 company_id", + * 拿全量 .ts 当分母会让反向用例红在一行类型声明上,而那一行本来就该存在。 */ +function requestModules(): string[] { + return ['src/api', 'src/pages'].flatMap(listTs) + .filter((f) => f.startsWith('src/api/') || f.endsWith('-api.ts')) +} + +function listTs(dir: string): string[] { + // Node 24 的 readdirSync 支持 recursive + withFileTypes;parentPath 是新字段,path 是旧字段,两个都要兜。 + // Windows 上递归结果的 parentPath 带反斜杠(`src\pages\shop\shop-manage-api.ts`),不转正斜杠就永远匹配不上 claimed。 + return readdirSync(dir, { withFileTypes: true, recursive: true }) + .filter((e) => e.isFile() && e.name.endsWith('.ts')) + .map((e) => `${(e as { parentPath?: string }).parentPath ?? e.path}/${e.name}`.split(/[\\/]+/).join('/')) +} + +/** 去掉注释再匹配:**这是这支用例能不能用的关键**。 + * 全仓目前只有一处 `company_id` 字面量——`src/pages/account/user-create-model.ts:68` 的注释 + * 「故意不带 company_id:归属由后端 resolveTargetCompanyId 落操作者自己的公司」。 + * 不剥注释,反向用例会在一条**说明为什么不传参**的注释上红,然后下一个人把它改成 `if (!/^\s*\*/.test(line))` + * 之类的临时豁免,整支用例就废了。剥注释的写法要连 `//` 行注释一起剥,但**不许**顺手放宽成"整文件不匹配"。 */ +function stripComments(source: string): string { + return source + .replace(/\/\*[\s\S]*?\*\//g, '') + .split(/\r?\n/) + .filter((line) => !line.trimStart().startsWith('//')) + .join('\n') +} +``` + +> 反向用例的**排除名单不写死文件**(草稿里我列过 `src/api/companies.ts`、`src/api/users.ts` 要豁免——实测两处都**不含** `company_id` 字面量,豁免纯属我给编的,已删)。要防的只有注释误匹配,靠 `stripComments`。 +> +> 匹配式 `\bcompany_id\s*[:=]` 与引号键名两形,是为了**只认"当成了参数"**:Task 8-12 落的写法是 `q.company_id = params.companyId`(等号形)和 `params: { company_id: ... }`(冒号形),两支都盖到;而"随便提一句 company_id"不该算接线。 + + +- [ ] **Step 7: §9.3 的承载——把"行数会随 tab 变"写进既有引导文案(只加文案,不加控件)** + +spec §9.3 定死了这件事的承载方式:**不新做页头控件/提示条**(§12 第 5 条那只未批的暴露),改在 `src/layout/operation-guides.ts` 的既有引导条目里说明。不做这一步的代价不是报错,而是超管第一次切 tab 时把行数变化**报成"数据丢了"**(Task 13 Step 3 的人工清单会当场撞上它)。 + +`OperationGuide.vue:13` 的折叠态是 `localStorage.getItem(KEY) === '1'`——**第一次进后台是展开的**,所以这段文案真会被看到;但也因为它是 per-浏览器持久化,一个早就把提示条收起的管理员看不见这句话。这条缓解是**部分强度**,别在运维手册里写成"界面已明确告知"。 + +⚠️ 这个文件有 `tests/align-operation-guide.test.ts` 钉着,三支钉法各不相同,**只有两支需要动**: +- `align_guide_users_matches_reference_text` 用 `assert.equal` 逐字比 `admin_users` 的 text ⇒ **不许改 `admin_users` 那条**。用户管理本来也不在这 7 页里(一期已经按公司筛过,tab 不改变它的观感),改它是自找红。 +- `align_guide_history_and_version_reference_text` 用的是 `assert.match(..., /生成记录可按用户和时间范围回溯/)` ⇒ `admin_history` 在原句**之后**追加不会红(前缀还在)。 +- `align_guide_group_manage_falls_back` 用 `deepEqual` 比整个对象 ⇒ 见下面第 2 条,这一支要改。 + +1. 下面 7 条 text 各追加同一句(**追加在原文之后,不改原句**;`admin_shop_manage` 那句 §6.3 归属口径另加): + `admin_image_video_tasks`、`admin_history`、`admin_task_center`、`admin_user_secrets`、`admin_user_secret_usage`、`admin_device_logs`、`admin_shop_manage`。 + +```ts +// 追加到各条 text 末尾(原句一个字都不动): +' 超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了。' + +// admin_shop_manage 再追加第二句(§6.3:这条与直觉相反,不写在界面上就会被报成 bug): +' 店铺归哪家公司由「负责人」决定,不由公司 tab 决定:负责人选自己,店铺就落在你自己那家。' +``` + +⚠️ **这句必须以"超级管理员"开头,不能写成"当前公司由 tab 决定"**:引导文案按 `menuKey` 取,**不分支角色**,而非超管根本看不到 tab 条(`visibleForOperator` 里有 `isSuperAdmin`)。写成祈使式的"当前公司由页面上方的 tab 决定",15 个管理员里非超管那批会读到一句指不到任何控件的话——那比不写更容易被报成 bug。 + +2. `admin_group_manage`(数据权限分组,第 8 页)**今天没有独立条目**,它 `deepEqual` 到 `OPERATION_GUIDE_FALLBACK`(`operation-guides.ts:27`)。给 fallback 加这句会把"公司 tab"端给**所有没有独立文案的页**(含 C 类那三页没进 tab 的),所以只能给它自己一条——这就是**故意偏离**旧版 `admin-interactions.js` 的 guides 表(文件头注释和 `:12` 的测试注释都写着"沿用旧版原文"),要在测试注释里明写这次偏离,别让它读起来像手滑: + +```ts + admin_group_manage: { + text: '数据权限分组决定"哪些账号能看到哪些店铺",分组按负责人和归属账号聚拢。超级管理员切换上方公司 tab 后,列表只保留当前公司账号相关的分组。' + + ' 超级管理员可用页面上方的公司 tab 切换公司,切换后行数会变化——行数变少不是数据丢了。', + steps: ['选择分组', '维护负责人与归属账号', '核对店铺可见范围'], + }, +``` + +⚠️ 这句里**不许**写"跨公司的分组彼此看不见"——那是 Task 11 Step 3 明确没做的半边:非超管的分组可见范围仍由 `listAccessibleGroupIds` 那套负责人/归属账号口径决定,本轮**一行都没动**(附B 记了这条"部分强度")。文案只描述超管 tab 的效果,不给非超管承诺他们没拿到的收窄。 + +```ts +// tests/align-operation-guide.test.ts:28-31 整支替换: +test('align_guide_group_manage_own_text', () => { + // 2026-10-04 公司 tab(spec §9.3):这页从"沿用旧版通用 fallback"改成自带文案—— + // 上一行"对齐旧版 guides 表原文"的约定在这一页是**故意破的**,因为那句 tab 说明 + // 不能塞进 fallback(fallback 会被没进 tab 的页共用,等于把 tab 端给它们)。 + const g = operationGuideFor('admin_group_manage') + assert.ok(g) + assert.notEqual(g, OPERATION_GUIDE_FALLBACK) + assert.match(g.text, /超级管理员可用页面上方的公司 tab 切换公司/) + assert.deepEqual(g.steps, ['选择分组', '维护负责人与归属账号', '核对店铺可见范围']) +}) +``` + +3. 本步覆盖的正好是注册表里那 8 页(上面 7 条 + `admin_group_manage`),一页不多一页不少。**`admin_users` 不在这 8 页里**——它一期就已按公司筛,§9.3 说的"第一次切过去会被报成数据丢了"指的是这次新窄下来的页,不要顺手也给它加(它的 text 还被 `assert.equal` 逐字钉着,改了必红)。 + +4. **把这件事做进代码出口,不留在注释里**(Constraint 15 的口径):往 `tests/align-operation-guide.test.ts` 追加一支,分母直接取注册表,别自己抄一份名单——将来往 `COMPANY_SCOPED_PAGES` 加第 9 页,这支会立刻红到那页的文案补上为止。 + +```ts +test('guide_copy_carries_company_tab_note_for_every_scoped_page', () => { + // spec §9.3:tab 会改行数观感,承载方式是既有引导文案(不新做控件)。 + // 分母=COMPANY_SCOPED_PAGES,杜绝"加了一页忘了补文案"。 + const need = COMPANY_SCOPED_PAGES.map((p) => p.menuKey) + assert.ok(need.length >= 8, '取样集非空自检:注册表应当至少有 8 页进了 tab 范围') + for (const key of need) { + const g = operationGuideFor(key) + assert.ok(g, `注册表页缺 guide: ${key}`) + assert.match(g.text, /超级管理员可用页面上方的公司 tab 切换公司/, `${key} 缺 §9.3 那句`) + } + // C 类两页(spec §5):它们要的是**另一句**——"这页不参与",不是"会随 tab 变"。 + // 分母**取注册表里显式写 companyScoped:false 的页**,不抄名单:漏写一条 ⇒ 这支在自检那句红。 + const scoped = new Set(COMPANY_SCOPED_PAGES.map((p) => p.menuKey)) + const cClass = adminPages.filter((p) => p.companyScoped === false).map((p) => p.menuKey) + assert.ok(cClass.length >= 2, '取样集非空自检:注册表里显式 companyScoped:false 的至少 C 类那两页') + for (const key of cClass) { + assert.equal(scoped.has(key), false, `${key} 既声明 false 又在清单里,两处口径打架`) + const g = operationGuideFor(key) + assert.ok(g, `不参与 tab 的页缺 guide: ${key}`) + assert.match(g.text, /全平台共享,不按公司区分/, `${key} 缺 §5 那句`) + assert.equal(g.text.includes('公司 tab 切换公司'), false, `${key} 不该带 tab 那句(它不参与)`) + } + // 反向钉:这句话只能由文案承载。tab 组件里再长出"当前公司:X"就是第二处表达(§12 第 5 条未批)。 + const tabs = readSource('src/layout/CompanyTabs.vue') + assert.ok(tabs.length > 0, '取样集非空自检:CompanyTabs.vue 读到了') + assert.equal(tabs.includes('company-tab-hint'), false, '不许有页头"当前公司"提示条') + assert.equal(tabs.includes('当前公司'), false, '同上:当前公司只由 is-active 的 tab 表达') +}) +``` + +补 import:`import { COMPANY_SCOPED_PAGES } from '../src/config/company-scope.ts'`(`readSource`、`operationGuideFor`、`adminPages` 该文件已 import)。 + +5. **C 类两页的那句也要在这一支里落**(`admin_shop_keys` 店铺密钥管理、`admin_product_categories` 商品类目): + +```ts +// 追加到这两条 text 末尾: +' 本页全平台共享,不按公司区分:超级管理员切换上方公司 tab 时它不会变,这不是筛选坏了。' +``` + +⚠️ 这里**偏离了 spec §5 选的承载**(它写的是"页头常驻一条说明")。改走引导文案有两个理由:①"常驻一条说明"本身就是 §12 第 5 条禁止的新提示条;②引导条这一支已经有分母取自注册表的用例(上面第 4 条),换承载就多一个没人管的控件。这条偏离已写回 spec §5,执行时不必再来问一次。 + +不做这两句的代价:tab 条是挂在 `AdminLayout` 上的全局件,批次 1 一上线,超管在这两页切 tab 会看到"数据纹丝不动"——而 §5 说得很清楚,那种观感要么是"假装有隔离",要么是"隔离坏了"。 + +- [ ] **Step 8: 全量 + 提交(前端半边,批次 1 的最后一步)** + +```bash +node --test tests/company-tab-model.test.ts tests/company-tab-wiring.test.ts \ + tests/align-operation-guide.test.ts +npx vue-tsc --noEmit && npm test 2>&1 | tail -5 +git add src/stores/company-tab.ts src/layout/CompanyTabs.vue src/layout/company-tab-model.ts \ + src/layout/AdminLayout.vue src/layout/operation-guides.ts \ + tests/company-tab-model.test.ts tests/company-tab-wiring.test.ts \ + tests/align-operation-guide.test.ts src/config/company-scope.ts +git commit -m "feat(前端): 公司 tab(store+组件+G1 双向对账) + §9.3 引导文案承载" +``` + +> G1 的正向断言在 Task 8-12 之前会**红**(那 8 个 api 文件还没带 `company_id`)。这是刻意的:**把 Task 8-12 做完之前不许单独提交 Task 7 的这支配测**,否则 `npm test` 有一次红。落地做法:Task 7 先提交代码、把 `company-tab-wiring.test.ts` 留到 Task 12 一起提交,或在 Task 7 提交信息里写明"下一条提交补齐接线"。 +> +> ⚠️ 这一步的红**有且只有** `company-tab-wiring.test.ts` 正向那半(`align-operation-guide.test.ts` 的两支、`company-tab-model.test.ts` 都必须已经绿)。出现别的红就是回归,别用"反正接线还没做"解释过去——Task 0 记的分母(前端 1687 例 0 红)在这里的作用是让你能说出"红了几条、分别是哪一支",而不是"有一片红"。 + +--- + +## Task 8: 接线 —— 视频任务记录 + 生成记录(形态相同:service 里一个 `userId` 参数) + +**Files:** +- Modify: `backend-java/.../modules/imagevideo/controller/AdminImageVideoTaskController.java:67-91`(`page`)、`:93-98`(`detail`)、`:100-…`(`download-zip`) +- Modify: `backend-java/.../modules/imagevideo/service/ImageVideoAdminTaskService.java:74-91`(`page`) +- Modify: `backend-java/.../modules/imagevideo/mapper/ImageVideoAdminTaskMapper.java:37`(page 的 ``)、`:64`(count 的同一条)、`:47-58`(`selectAdminTaskPage` 参数表)、`:72-…`(`countAdminTaskPage` 参数表)、`:80-92`(`selectAdminZipRows` 补 `t.user_id`,Step 4 的 download-zip 闸门靠它) +- Modify: `backend-java/.../modules/imagevideo/service/ImageVideoAdminTaskService.java:97-103`(`detail`)、`:108-…`(`buildZip`,`VideoSelection` 在同文件 `:447`) +- Modify: `backend-java/.../modules/imagehistory/controller/ImageHistoryController.java:32-48`(`listHistory`) +- Modify: `admin-frontend-vue/src/pages/tasks/image-video-api.ts`、`src/pages/records/history-api.ts`、`src/pages/tasks/ImageVideoTasksPage.vue`、`src/pages/records/RecordsHistoryPage.vue` +- Test: 上述两个 service 的既有测试类里追加 + +**Interfaces:** +- Consumes: `DataReadScope.readScope(operator, companyId)` → `ReadScope.userIdsOr(base)` +- Produces: 两个新查询参数 `company_id`(GET query) + +> **两个已确认的现状(2026-10-04 16:2x 逐行读过,不是推测)**: +> 1. `AdminImageVideoTaskController.java:78` 现在是 `adminAuthSupport.requireAdminOrInternal(request);` **返回值被丢掉**——本任务必须改成 `AdminUserEntity operator = adminAuthSupport.requireAdminOrInternal(request);`,否则拿不到角色与 `companyId`。 +> 2. `ImageVideoAdminTaskService.page(...)`(`:74-76`)**没有 operator 参数**,签名是 `page(Long userId, String username, String status, String executeId, LocalDateTime submittedFrom, LocalDateTime submittedTo, int page, int pageSize)`。⇒ 范围在 **controller** 里算、把 `List userIds` 传进 service,不改 service 的鉴权依赖(比给 service 塞 operator 少一层耦合,也让 `requireAdminOrInternal` 的 internal 分支不会走进 `readScope` 的非超管分支)。 +> 3. `requireAdminOrInternal` 在 JWT 失败时用 `X-Internal-Token + operatorId` 回退(`AdminAuthSupport.java:122-133`)。internal 调用**不传 `company_id`** ⇒ `readScope` 走"超管不筛"或"按那个 operatorId 的公司裁剪",两条都不会把客户端的取数弄窄;但如果该回退账号没有 `company_id`,非超管分支会抛 403(Task 6 的 `adminWithoutCompanyFailsFast` 钉的就是这条)——**Step 5 的验收必须真跑一次 internal 通道**,不能只跑浏览器。 + +- [ ] **Step 1: 写失败的测试(后端,两条组合即可,别铺开)** + +`ImageVideoAdminTaskServiceTest`(无则新建): + +```java + @Test + @DisplayName("超管选了公司:userId 的单值过滤之外必须多出成员集合") + void companyMembersGoToBothPageAndCountQueries() { + when(mapper.selectAdminTaskPage(any(), any(), any(), any(), any(), any(), any(), anyInt(), anyInt())) + .thenReturn(List.of()); + when(mapper.countAdminTaskPage(any(), any(), any(), any(), any(), any())).thenReturn(0L); + + service.page(null, null, null, null, null, null, 1, 20, List.of(11L, 12L)); + + // 关键:行集与总数必须拿到同一个范围。只换 page 不换 count ⇒ "总数对不上但没人报错"。 + ArgumentCaptor> rowsCap = ArgumentCaptor.forClass(List.class); + ArgumentCaptor> 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 userIds`,count 侧同理): + +```java + " AND t.user_id = #{userId}" + + " AND t.user_id IN" + + " #{uid}", +``` + +`userId` 那条**保留**(它是页面上"按单个账号筛"的既有能力),两条是 AND 关系 = 交集,语义正确。 +⚠️ 空集**不许进 mapper**:`userIds=[]` 会渲染成 `IN ()`,MySQL 语法错 → 500。短路放在 Step 4。 + +- [ ] **Step 4: service 早退 + controller 算范围** + +`ImageVideoAdminTaskService.page(...)` 签名末尾加 `List userIds`,第一行: + +```java + if (userIds != null && userIds.isEmpty()) { + // 空集 = 这个公司今天没有任何成员账号 ⇒ 空页。绝不退化成"不筛"(那是越权)。 + Map empty = new LinkedHashMap<>(); + empty.put("items", List.of()); + empty.put("total", 0L); + empty.put("page", (long) page); + empty.put("page_size", (long) pageSize); + return empty; + } +``` + +并把 `userIds` 透传给 `selectAdminTaskPage` 与 `countAdminTaskPage` 两支。 + +`AdminImageVideoTaskController.page(...)`:参数表末尾加 +`@RequestParam(name = "company_id", required = false) Long companyId`,并按上面「已确认现状 1」接住 operator: + +```java + AdminUserEntity operator = adminAuthSupport.requireAdminOrInternal(request); + // 既有语义保留:显式传 user_id 时按那一个人筛;公司 tab 叠在它上面(交集)。 + List base = userId != null && userId > 0 ? List.of(userId) : null; + List scoped = dataReadScope.readScope(operator, companyId).userIdsOr(base); +``` + +`detail`(`:93-98`)与 `download-zip`(`:100-115`)按 §6.1 用**同一把 ReadScope** 门住,判据是行的 `user_id` 落不落得进列表那条同样的 `read.userIdsOr(base)`(不是"列表筛了、按 id 照读",那正是越权而不是收窄): + +- `detail`:`selectAdminTaskDetail` 的 SELECT **已经带 `t.user_id`**(`mapper:95`),取行后直接判,不在集合里抛 `new BusinessException(403, "该任务不属于当前公司")`。**越权必须是 403,不许复用现有那句 404**(`service:100`「视频任务不存在或无权访问」把两件事混在一句里,404 只留给"真查不到行")。 +- `download-zip`:`selectAdminZipRows`(`mapper:80-92`)现在只 `SELECT t.id, t.video_urls_json, t.archived_videos_json`——**没有 `user_id`**,所以这条闸门必须先给那条 SQL 补上 `t.user_id`,`buildZip` 才拿得到行主人(这是本任务唯一一处 SQL 列改动,不是可选优化)。判法与 detail 同:**一次请求里任一条 selection 越界就整单 403**,不许静默跳过——`X-Archive-Error-Count`(`controller:105-114`)那套"部分失败"语义是给上游拉不到文件用的,拿它掩盖越权等于把越权报成网络问题(memory「权限范围限制要连读接口一起收窄」)。 + + +- [ ] **Step 5: 前端带参 + 重取** + +两页的取数都不在 api 模块里就地拼 query,而是调 builder:`fetchImageVideoTasks`(`image-video-api.ts:11-21`)用 `toImageVideoQuery(filter, page, pageSize)`,`fetchHistoryList`(`history-api.ts:9-14`)用 `toHistoryListQuery(normalizeHistoryParams(params))`。**统一落在"builder 出来之后、发请求之前"这一处**,别再往 filter/params 里塞: + +`src/pages/tasks/image-video-api.ts`:`fetchImageVideoTasks` 参数表末尾加 `companyId?: number | null`,函数体改成 + +```ts + const query = toImageVideoQuery(filter, page, pageSize) + if (companyId != null) query.company_id = companyId + const { data } = await http.get(IMAGE_VIDEO_TASKS_ENDPOINT, { params: query }) +``` + +`src/pages/records/history-api.ts`: + +```ts + const normalized = normalizeHistoryParams(params) + const query = toHistoryListQuery(normalized) + if (params.companyId != null) query.company_id = params.companyId + const { data } = await http.get(HISTORY_ENDPOINT, { params: query }) +``` + +两支类型各加一个可选键:`ImageVideoQuery`(`image-video-filter.ts:21-30`)与 `HistoryListQuery`(`history-dto.ts:38-44`)各加 `company_id?: number`。 + +> **为什么不改 `HistoryListParams` 那条路**:`normalizeHistoryParams`(`history-dto.ts:61-76`)是**白名单**构造返回值(`page/pageSize/userId/timeStart/timeEnd` 逐条点名),把 `companyId` 加进 `HistoryListParams` 类型会被它原样丢掉——类型检查绿、请求里没有这个参数、页面永远看全量。这正是 §9 记的那类"静默失效",所以本批次一律落在 builder 之后(Task 10/11 同)。 +> +> `companyId` 由页面组件传入(**不用 `useCompanyTabStore()` 裸调**:这两个 api 模块在 `node --test` 里被直接 import,Pinia 未激活会抛 "no active pinia";Task 9/10/12 一律沿用"页面传值"这一种,全批次不许一半 store 一半入参)。页面组件加 Task 7 Step 5 那条 `watch`,并在取数调用里传 `companyId: companyTab.requestCompanyId`。`fetchImageVideoTasks` 多了一个参数 ⇒ 调用点 `ImageVideoTasksPage.vue` 必须跟着改,漏改是 `vue-tsc` 报错而不是静默。 + + +- [ ] **Step 6: 跑两支全量 + 提交** + +```bash +mvn -q test 2>&1 | tail -10 +node --test tests/company-tab-wiring.test.ts # 这两页的正向断言应转绿 +npx vue-tsc --noEmit +git add backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo backend-java/src/main/java/com/nanri/aiimage/modules/imagehistory backend-java/src/test/java/com/nanri/aiimage/modules/imagevideo admin-frontend-vue/src/pages/records +git commit -m "feat(公司tab): 视频任务记录与生成记录按公司筛(成员集合替换单 userId)" +``` + +--- + +## Task 9: 接线 —— 密钥管理 + 密钥用量统计(已有 `group_id`「仅超管生效」,公司叠在它上面) + +**Files:** +- Modify: `backend-java/.../modules/usersecret/controller/AdminUserApiSecretController.java:49-64` +- Modify: `backend-java/.../modules/usersecret/controller/AdminUserSecretUsageController.java:38-47` +- Modify: `backend-java/.../modules/usersecret/model/dto/AdminUserSecretQuery.java`(加 `companyId`) +- Modify: `backend-java/.../modules/usersecret/service/UserApiSecretService.java:317-345`(`adminPage`) +- Modify: `backend-java/.../modules/usersecret/service/UserSecretUsageService.java:99-123`(`superAdmin` 判定在 `:99`,`scopedUserIds` 三段分支在 `:101-107`,早退在 `:108` 与 `:122`——与 `UserApiSecretService.adminPage` 同形) +- Modify: `admin-frontend-vue/src/api/user-secrets.ts`、`src/api/user-secret-usage.ts`、`src/pages/account/UserSecretsPage.vue`、`UserSecretUsagePage.vue` +- Test: `UserApiSecretServiceTest`(追加) + +**Interfaces:** +- Consumes: `DataReadScope`(Task 6) +- Produces: 两个 `company_id` query 参数;`scopedUserIds` 的三层语义(组长锁定 ∩ 超管 group_id ∩ 公司) + +- [ ] **Step 1: 写失败的测试** + +```java + @Test + @DisplayName("超管 group_id + company_id 同时给:取交集,不是后一个覆盖前一个") + void groupAndCompanyIntersect() { + when(adminAuthSupport.currentRole(operator)).thenReturn("super_admin"); + when(dataReadScope.readScope(operator, 2L)).thenReturn(ReadScope.users(List.of(11L, 12L, 13L))); + when(adminGroupMapper.selectUserIdsByGroupId(7L)).thenReturn(List.of(12L, 13L, 99L)); + + List 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 scopedUserIds(AdminUserEntity, Long groupId, Long companyId)`);测试类与被测类同包,直接调它,不要再造一个 `...ForTest` 的别名(别名会随重构腐烂)。**必须抽**:不抽就只能靠 mock 整条 mapper 链测这段逻辑,那段最关键的交集代码反而没被测到。 + +- [ ] **Step 2: 跑,确认红** → `mvn -q test -Dtest=UserApiSecretServiceTest`,Expected: FAIL(方法不存在)。 + +- [ ] **Step 3: 抽范围方法并叠公司** + +`UserApiSecretService.java:317-341` 的那段改成: + +```java + /** 可见用户集:null = 不筛(超管没选公司也没选分组,今天的行为)。 */ + List scopedUserIds(AdminUserEntity operator, Long requestedGroupId, Long companyId) { + boolean superAdmin = "super_admin".equals(adminAuthSupport.currentRole(operator)); + List 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 scopedUserIds = scopedUserIds(operator, safeQuery.getGroupId(), safeQuery.getCompanyId());`,**保留它下面 `isEmpty() → emptyPageWithGroups(...)` 那条早退**(非超管历史上就靠它返回空页带分组下拉)。 + +- [ ] **Step 4: DTO / controller / usage service** + +`AdminUserSecretQuery` 加 `private Long companyId;`;两个 controller 各加 +`@RequestParam(name = "company_id", required = false) Long companyId` 并 `query.setCompanyId(companyId)`。 +`UserSecretUsageService:99-123` 那段照 Step 3 同样抽成 package-private `scopedUserIds(operator, requestedGroupId, companyId)`。**注意它与 `adminPage` 的一处不同**:`UserApiSecretService` 空集走 `emptyPageWithGroups(...)`,这里空集走 `:108`/`:122` 的早退并 `log.info` 一条"无匹配用户"——抽方法时把这两条早退**留在原处**,别一起搬进新方法,否则用量页会从"空列表 + 一行日志"变成"空列表 + 无日志",排障时看不出是筛空还是查空。 + +- [ ] **Step 5: 前端带参** + +照 **Task 8 Step 5 定下的那一种**(值由页面组件传入、api 模块里**不**碰 Pinia store)。两支文件形状一样,各改两处: + +`src/api/user-secrets.ts` 的 `UserSecretQuery`(`:54`)与 `src/api/user-secret-usage.ts` 的 `UserSecretUsageQuery`(`:28`)各加一个可选字段: + +```ts + /** 公司 tab 的当前口径;不传 = 后端按操作者自己的公司(批次 1 里非超管只有这一家)。 */ + companyId?: number | null +``` + +`fetchUserSecretList`(`:65-69`)与 `fetchUserSecretUsage`(`:40-45`)的 `query` 构造块里,紧跟既有的 `if (params.groupId) query.group_id = params.groupId` 各加一行: + +```ts + if (params.companyId != null) query.company_id = params.companyId +``` + +> 用 `!= null` 而不是旁边那几行的 truthy 写法:既有那几行筛的是字符串/`groupId`,`0` 对它们是"没筛";`company_id` 传 0 后端 `requireCompanyId` 会抛(`CompanyScopeSupport:37`),宁可让它在参数缺失时不出现,也别把 `0` 悄悄当没传。 + +两个调用页(`UserSecretsPage.vue`、`UserSecretUsagePage.vue`)在取数调用里传 `companyId: companyTab.requestCompanyId`,并加 Task 7 Step 5 那条 `watch`。 + +> 全批次 8 个页一律"页面传值",不许有第二形态:api 模块被 `node --test` 直接 import 时 Pinia 未激活会抛 `no active pinia`,一半 store 一半入参还会让 G1 的 `pageFiles` 断言只能盯住其中一半。 + +- [ ] **Step 6: 跑 + 提交** + +```bash +mvn -q test 2>&1 | tail -10 +node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit +git add backend-java/src/main/java/com/nanri/aiimage/modules/usersecret admin-frontend-vue/src/api/user-secret*.ts admin-frontend-vue/src/pages/account/UserSecret*.vue backend-java/src/test/java/com/nanri/aiimage/modules/usersecret +git commit -m "feat(公司tab): 密钥管理与用量统计按公司筛(分组∩公司,空集不退化)" +``` + +--- + +## Task 10: 接线 —— 客户端任务管理(**一处** `resolve` 收窄,五个端点自动同宽) + +**Files:** +- Modify: `backend-java/.../modules/taskcenter/service/TaskCenterScopeService.java:27-40`(`resolve`)、`:42-47`(`addAll` 保持不动)、`:70-87`(`ScopeContext` 与 `sqlUserIds()`——**只读确认那个 `[-1]` 兜底,不许改**) +- Modify: `backend-java/.../modules/taskcenter/controller/AdminTaskCenterController.java`:`resolveScope`(`:100-104`)加一个入参,五个端点各加一个可选 `company_id`(`overview :46`、`shop-options :54`、`tasks :62`、`tasks/detail :72`、`variant-tasks :86`) +- **不动**: `TaskCenterQueryMapper.java:92-96` 的 `USER_SCOPE_T`/`USER_SCOPE_B`/`USER_SCOPE_S` 片段——理由见 Step 3 的更正,判空早已被 `sqlUserIds()` 兜住 +- Modify: `admin-frontend-vue/src/api/task-center.ts:82,88,94,101,109`(**五支**,含按 `taskNo` 的 detail)、`src/pages/task-center/task-center-model.ts:200,218`(`buildTaskQuery`/`buildVariantQuery`)、`src/pages/task-center/TaskCenterBoardPage.vue:98,107,116,130` 及详情调用点 +- Test: `TaskCenterScopeServiceTest`(追加) + +**Interfaces:** +- Consumes: `DataReadScope.readScope(AdminUserEntity, Long)` → `ReadScope.isUnfiltered()` / `ReadScope.userIdsOr(List)`(Task 6 定义,两侧都有值时**求交**) +- Produces: `ScopeContext TaskCenterScopeService.resolve(Long operatorId, Long companyId)`;既有 `resolve(Long)` 保留成 `resolve(operatorId, null)` 的委托(改之前先 `grep -rn "\.resolve(" src/main --include=*.java` 数清还有几个调用点,别把别模块的调用打断) + +> **这页的接合点和别的页不一样,而且是好消息**:五个端点全部只调 `resolveScope(request)` 一次(`controller:50,58,68,78,96`),集合的消费只有两种形状——`scope.sqlUserIds()` 进 SQL(`TaskCenterQueryService:59,72,154`、`TaskCenterVariantService:52`),以及 `scope.visible(userId)` 做行级判断(`TaskCenterQueryService:180`,`tasks/detail` 就是靠它)。所以 **`resolve` 一处收窄,五个出口天然同宽**,§6.1 那条"列表筛了但按 id 能读"在这一页本来就不存在,不需要像 Task 8 那样单独补 detail 闸门。反过来讲:**这一页的护栏就落在前端**——`fetchTaskCenterTaskDetail` 少带 `company_id`,超管在「第 2 家」tab 下按 `taskNo` 打开别家任务的详情就还是放行(`allUsers=true` ⇒ `scope.visible()` 恒真),而接口照样返回 200,谁都不会发现。Step 5 因此把 detail 也算进"五个都带"。 + +- [ ] **Step 1: 写失败的测试** + +```java + @Test + @DisplayName("超管选了公司:allUsers 必须翻成 false,否则集合根本不进 SQL,tab 是装饰品") + void superAdminWithCompanyStopsBeingUnfiltered() { + AdminUserEntity operator = user(1L, "super_admin"); + when(adminUserMapper.selectById(1L)).thenReturn(operator); // 夹具同现有 :46 的写法 + when(dataReadScope.readScope(operator, 2L)).thenReturn(ReadScope.users(List.of(11L, 12L))); + + TaskCenterScopeService.ScopeContext scope = service.resolve(1L, 2L); + + assertFalse(scope.allUsers(), "选了公司还 allUsers=true ⇒ sqlUserIds() 交 null ⇒ SQL 整段条件不渲染"); + assertThat(scope.sqlUserIds()).containsExactlyInAnyOrder(11L, 12L); + assertTrue(scope.visible(11L)); + assertFalse(scope.visible(13L), "别家账号连 tasks/detail 也进不去(详情走 scope.visible,不走 SQL)"); + } + + @Test + @DisplayName("不传 company_id = 今天的行为一分不变") + void superAdminWithoutCompanyStaysUnfiltered() { + AdminUserEntity operator = user(1L, "super_admin"); + when(adminUserMapper.selectById(1L)).thenReturn(operator); + when(dataReadScope.readScope(operator, null)).thenReturn(ReadScope.unfiltered()); + + assertThat(service.resolve(1L, null).sqlUserIds()).isNull(); + } + + @Test + @DisplayName("历史超管(role 为空 + isAdmin=1 + createdById 为空)选了公司,也得跟着窄") + void legacySuperAdminIsNotLeftUnfiltered() { + AdminUserEntity legacy = new AdminUserEntity(); + legacy.setId(2L); + legacy.setIsAdmin(1); + legacy.setCreatedById(null); + when(adminUserMapper.selectById(2L)).thenReturn(legacy); + // 这条桩必须返回"筛过"的集合:DataReadScope 用 AdminAuthSupport.currentRole 判超管, + // 而 DeviceSessionPolicy.resolveRole:34-36 对这个形状返回 super_admin(与 :60-64 的 isSuperAdmin 同规则)。 + // 两把尺子必须同一条,否则这页会出现"readScope 当它是超管不筛、service 当它是 admin 求交"的分裂。 + when(dataReadScope.readScope(legacy, 3L)).thenReturn(ReadScope.users(List.of(31L))); + + assertThat(service.resolve(2L, 3L).sqlUserIds()).containsExactly(31L); + } + + @Test + @DisplayName("成员集为空时交给 SQL 的是 [-1] 不是空集:IN () 是语法错,兜底在 ScopeContext 里") + void emptyMemberSetFallsBackToSentinelNotEmptyList() { + AdminUserEntity operator = user(1L, "super_admin"); + when(adminUserMapper.selectById(1L)).thenReturn(operator); + when(dataReadScope.readScope(operator, 99L)).thenReturn(ReadScope.users(List.of())); + + TaskCenterScopeService.ScopeContext scope = service.resolve(1L, 99L); + + assertTrue(scope.visibleUserIds().isEmpty()); + assertThat(scope.sqlUserIds()).containsExactly(-1L); // :84 那条兜底,本任务不许改它 + } + + @Test + @DisplayName("非超管:公司集与既有分组集求交,只收窄不放大") + void adminIntersectsWithGroupScope() { + AdminUserEntity operator = user(5L, "admin"); + when(adminUserMapper.selectById(5L)).thenReturn(operator); + when(shopManageGroupMapper.selectAccessibleGroupIds(5L)).thenReturn(List.of(3L)); + when(shopManageGroupMapper.selectUserIdsByGroupIds(List.of(3L))).thenReturn(List.of(6L)); + // 分组集 = 本人 5 + 组员 6(:33-38 的既有口径),公司成员 = 6、7 ⇒ 只剩 6 + when(dataReadScope.readScope(operator, 2L)).thenReturn(ReadScope.users(List.of(6L, 7L))); + + assertThat(service.resolve(5L, 2L).sqlUserIds()).containsExactly(6L); + } +``` + +布线照 `TaskCenterScopeServiceTest` 现有形状补(`:32-42`):字段名是 `service` 不是 `scopeService`;操作者是 `adminUserMapper.selectById(id)` 打桩返回的 `user(id, role)` 夹具(`:36-42`),所以 `dataReadScope.readScope(operator, ...)` 的入参必须用**同一个实例**(先 `AdminUserEntity operator = user(...)` 再把它塞进两处桩——别新造一个对象去匹配,Mockito 按 `equals` 比,`AdminUserEntity` 没重写 `equals`,那样永远匹配不上、桩返回 null,用例会红在错的地方)。新增 `@Mock private DataReadScope dataReadScope;` 一支,`@InjectMocks` 才填得进新加的构造参数;`assertFalse`/`assertTrue` 是这个文件已经在用的静态导入(`:50-52`),别混进 `assertThat(...).isTrue()` 之外的第三种风格。 + + +- [ ] **Step 2: 跑,确认红** → `mvn -q test -Dtest=TaskCenterScopeServiceTest`(`resolve(Long, Long)` 不存在 = 编译失败也算预期红) + + +- [ ] **Step 3: `resolve` 加一个重载** + +`TaskCenterScopeService`:把既有 `resolve(Long operatorId)` 的方法体搬进 `resolve(Long operatorId, Long companyId)`,旧签名改成一行委托 `return resolve(operatorId, null);`(这样其余调用点一分不变,Step 4 只动 controller)。新方法体的形状: + +```java + public ScopeContext resolve(Long operatorId) { + return resolve(operatorId, null); // 旧签名一行委托,其余调用点一分不变 + } + + /** 公司 tab 的收窄点:只与既有可见集**求交**,一律不放大(spec §4)。五个端点共用这一处。 */ + public ScopeContext resolve(Long operatorId, Long companyId) { + AdminUserEntity operator = requireOperator(operatorId); + ReadScope read = dataReadScope.readScope(operator, companyId); + if (read.isUnfiltered()) { + return new ScopeContext(true, Set.of()); // 今天的行为:超管没选公司 = 不筛 + } + List base = null; + if (!isSuperAdmin(operator)) { + // ↓↓↓ 既有 :32-38 那段分组口径**原样搬过来**:不改写、不换 mapper 方法、不动 addAll 的过滤条件。 + List accessibleGroupIds = shopManageGroupMapper.selectAccessibleGroupIds(operator.getId()); + LinkedHashSet 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 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` 的 `` 整段不渲染 ⇒ tab 切了、SQL 没变,症状是"页面一切正常但数字永远一样",接口照样 200,没有任何一处会报错——所以 Step 1 第一条用例断的是 `assertFalse(scope.allUsers())`,不是断集合内容。 + +还有一条**新旧两把尺子必须同一条**的账:`isSuperAdmin(:60-64)` 认"role 为空 + isAdmin=1 + createdById 为空"的历史超管,`DataReadScope` 走的是 `AdminAuthSupport.currentRole` → `DeviceSessionPolicy.resolveRole:34-36`,对这个形状同样返回 `super_admin`。两者一致是这条链成立的前提,Step 1 那条 `legacySuperAdminIsNotLeftUnfiltered` 就是钉它的(哪一天 `resolveRole` 或 `isSuperAdmin` 单边改了,这条会红,而不是让某个历史超管在 tab 下看到全量)。 + +⚠️ **更正(草稿写错过一次,执行时别再写回来)**:草稿在这里写的是"空集直传会渲染成 `AND t.user_id IN ()`,MySQL 语法错,所以要在 service 里判空短路"。**实读 `TaskCenterScopeService.java:79-86` 后不成立**:`ScopeContext.sqlUserIds()` 已经做了 `visibleUserIds.isEmpty() ? List.of(-1L) : ...`,非超管再小也交出去一个 `[-1]`,`IN ()` 这个形状根本到不了 SQL。所以**不许**在本 service 里再加一层判空短路——那会造出第二个空集口径(一半走 `[-1]`、一半直接空页),而 `tasks/detail` 走的是 `scope.visible(userId)`(`TaskCenterQueryService:180`)不是 SQL,两个口径分叉时列表和详情会给出不同答案。要防的只是:**新代码绕开 `ScopeContext` 自己拼 List 传给 mapper**,那才会真的把空集递进去。Step 1 的 `[-1]` 那条用例钉的就是这件事。 + + +- [ ] **Step 4: 五个端点加参数** + +`AdminTaskCenterController` 的 `overview`(`:46`)/ `shop-options`(`:54`)/ `tasks`(`:62`)/ `tasks/detail`(`:72`)/ `variant-tasks`(`:86`)各加一个 `@RequestParam(name = "company_id", required = false) Long companyId`,并把它交给 `resolveScope(request, companyId)`(私有方法 `:100-104` 加一个入参,五个调用点一起改)。 + +**`tasks` 那一支不许用"往 `TaskCenterTaskQuery` 加 `companyId` 字段"的省事写法**:那个对象是 Spring **按字段名绑定**的(`moduleType`/`shop`/`startTime`/`pageSize` 全是驼峰,实读 `TaskCenterTaskQuery.java:11-28`),加了字段就意味着前端必须发 `companyId=`,而另外 7 页和这个页的其余 4 个端点发的是 `company_id=`。两种拼写并存的结果是参数被**静默丢弃**(`required = false` + 没人报错),且只在"任务列表"这一支上丢——看板数字窄了、列表没窄,正是 §4 记的那种最难查的形态。统一显式 `@RequestParam(name = "company_id")`,五个端点一个形状。 + +- [ ] **Step 5: 前端五支都带参** + +`src/api/task-center.ts` 的四支取数函数各自加参数(`fetchTaskCenterOverview` `:82`、`fetchTaskCenterShopOptions` `:88` 现在**一个参数都没有**,要新加 `companyId?: number | null` 并把 `http.get(url)` 改成 `http.get(url, { params: query })`;`fetchTaskCenterTasks` `:94`、`fetchTaskCenterVariantTasks` `:109` 收的是 `params: QueryParams`,在传进来的对象上补键即可): + +```ts + const query: QueryParams = { company_id: companyId } // 两支无参函数 + const { data } = await http.get('/api/admin/task-center/overview', { params: query }) +``` + +`src/pages/task-center/task-center-model.ts` 的 `buildTaskQuery`(`:200-216`)与 `buildVariantQuery`(`:218-227`)各在 `const query: TaskCenterQueryParams = { page, pageSize }` 之后加一行 `if (companyId != null) query.company_id = companyId`(`TaskCenterQueryParams` 是 `Record`(`:19`),加键不动类型,也不存在 Task 8 那种白名单丢弃问题)。`fetchTaskCenterTaskDetail`(`:101`)**同样要带** `company_id`——理由见本节开头那条:详情走 `scope.visible()`,api 少传这一支,超管在别家 tab 下按 `taskNo` 就能读到别家详情,而这页 UI 上看不出任何异常。 + +`TaskCenterBoardPage.vue` 的四处调用(`:98`、`:107`、`:116`、`:130`)与详情调用点各传 `companyTab.requestCompanyId`,页面组件加 Task 7 Step 5 那条 `watch`。 + +- [ ] **Step 6: 跑 + 提交** + +```bash +mvn -q test 2>&1 | tail -10 +node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit +git add backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter admin-frontend-vue/src/api/task-center.ts admin-frontend-vue/src/pages/task-center backend-java/src/test/java/com/nanri/aiimage/modules/taskcenter +git commit -m "feat(公司tab): 任务看板五个端点按公司筛(一处 resolve 收窄,detail 靠 scope.visible 同宽)" +``` + +--- + +## Task 11: 接线 —— 店铺管理 + 数据权限分组(只筛读;写侧归属刻意不动,并反向钉住) + +**先读这五条已确认现状(2026-10-04 逐行实查,别再照草稿的假设推):** + +1. `ShopManageController.requireOperator(request)` 走的是 **`adminAuthSupport.requireAdminOrInternal(request)`**(`controller/ShopManageController.java:50-52`)⇒ 这页**存在非超管与内部令牌两条通道**。按 §6.1,它的按 id 读出口必须补行级闸门,与 Task 12 那页"只有超管进得来"是两回事。 +2. `ShopManageService.page(long page, long pageSize, Long groupId, String shopName, Long operatorId, boolean superAdmin)`(`service/ShopManageService.java:31`)——**service 拿到的是 `operatorId` + 一个布尔,不是 `AdminUserEntity`**。⇒ `readScope(AdminUserEntity, Long)` 只能由 controller 调(它手上就有 operator 实体),把算好的成员集当参数传进去。这跟 Task 12 的 `memberUids` 是同一个形状,两页别各发明一套。 +3. 超管今天**完全不锁**:`:43` 的 `if (!superAdmin) { ... }` 里才有 `accessibleCreatorUserIds`/`accessibleGroupIds` 那套 OR(`:48-59`)。⇒ 超管 + 选了公司这一支是**新增**的收窄,不是"改既有过滤"。 +4. ⚠️ **`create`/`update` 的归属来自请求体,不来自操作者**:`ShopManageService.java:86` 是 `normalizePositiveId(request.getCreatedById(), "创建人不能为空")`,`:96` `entity.setCreatedById(createdById)`。⇒ 草稿写的"`created_by_id = operator.getId()`"**是错的**,Step 4 的口径说明按这条重写。 +5. `ShopManageGroupService.list(Long createdById)`(`service/ShopManageGroupService.java:51-57`)生成的是 `created_by_id = ? OR (user_id = ?)` 这种**平铺 OR**。MP 的 normal 段按声明顺序拼 `AND`/`OR`,事后在外面叠一条 `in(...)` 会得到 `A OR (B) AND C` ⇒ MySQL 里 AND 优先,**左半边 `created_by_id = ?` 整个逃出公司筛选**(不报错、不 403,就是多放行)。 + +**Files:** +- Modify: `backend-java/.../modules/shopkey/controller/ShopManageController.java` —— 读侧 `page`(`:66-80`)、`listGroups`(`:115-123`) 各加 `company_id`;**闸门侧 `adminCredential`(`:175-182`)**;写侧 `create`(`:84`)/`update`(`:94`)/`delete`(`:105`)/`createGroup`(`:127`)/`updateGroup`(`:137`)/`deleteGroup`(`:148`) **不动** +- Modify: `backend-java/.../modules/shopkey/service/ShopManageService.java:31-82`(`page` 末位加 `List companyMemberIds`)、`:155-164`(`getCredentialById` 加同宽闸门) +- Modify: `backend-java/.../modules/shopkey/service/ShopManageGroupService.java:51-57`(`list` 末位加 `List 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)`(Task 6) +- Produces: + - `ShopManagePageVo page(long page, long pageSize, Long groupId, String shopName, Long operatorId, boolean superAdmin, List companyMemberIds)` —— `companyMemberIds == null` 表示不筛(超管没选公司 / 非超管由既有分支自己锁) + - `List list(Long createdById, List companyMemberIds)`(保留现有 `list()` / `list(Long)` 两个重载委托到它,`list()`→`list(null, null)`;**实查 `list()` 有其它调用方,删重载会编译断**) + - `ShopManageCredentialVo getCredentialById(Long id, List companyMemberIds)` —— 成员集非 null 且行的 `created_by_id` 不在其中 ⇒ `BusinessException(403, ...)` + - 写侧**不新增任何参数**——见 Step 4 的口径与它那条反向钉 + +- [ ] **Step 1: 写失败的测试(读侧一条 + 分组括号一条 + 凭据闸门一条 + 写侧"不得回流"一条)** + +先建那个共用的测试工具类(Task 12 Step 4 用它,本任务的反向钉也用它;**放在 `testutil` 包而不是各写一份**): + +`backend-java/src/test/java/com/nanri/aiimage/testutil/SourceScan.java` + +```java +package com.nanri.aiimage.testutil; + +import static org.junit.jupiter.api.Assertions.fail; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.stream.Collectors; +import java.util.stream.Stream; + +/** 源码扫描式护栏的取文助手。路径解析照抄 {@code common/security/InternalTokenSingleOutletTest} 的 + * moduleRoot()/mainSources() 两支——surefire 的 cwd 是模块目录,从仓库根或 IDE 跑时要退到 backend-java/, + * 定位不到必须 fail 而不是静默跳过(静默跳过 = 整支护栏恒绿)。 */ +public final class SourceScan { + + private SourceScan() { + } + + /** 按文件名(不含目录)取 {@code src/main/java} 下那份源码的全文字符串。 + * ⚠️ 返回 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 + " —— 文件改名/挪目录了,护栏要红在这里")); + } + + /** 大括号配平切出「某个方法」的源码:从它的签名行往前一直含到注解,到方法收尾的 `}` 为止。 + * + *

两条它必须自己防住的坑,都写在用例里过:

+ *
    + *
  • 名字必须是完整词:{@code delete} 是 {@code deleteGroup} 的前缀。用 {@code indexOf(name)} + * 会先撞上那个更长的方法 ⇒ "切出来的是隔壁",而断言仍然绿。所以下面用 {@code (? + *
  • 找不到必须抛,不许返回空串:返回 "" 的话 {@code doesNotContain("company_id")} 恒真, + * 反向钉会因为方法被改名而悄悄失效(memory「字符串断言必须排他、解析断言必须可匹配」)。 + * 配套要求:每个用它的反向钉都要带一条"该做的确实做了"的取样自检。
  • + *
+ */ + public static String methodBody(String source, String methodName) { + var matcher = java.util.regex.Pattern + .compile("(? 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 mainSources() { + Path root = moduleRoot().resolve("src/main/java"); + try (Stream walk = Files.walk(root)) { + return walk.filter(Files::isRegularFile) + .filter(p -> p.getFileName().toString().endsWith(".java")) + .collect(Collectors.toList()); + } catch (IOException e) { + throw fail("遍历 " + root + " 失败: " + e.getMessage()); + } + } + + private static Path moduleRoot() { + Path here = Path.of("").toAbsolutePath(); + if (Files.isDirectory(here.resolve("src/main/java"))) { + return here; + } + Path nested = here.resolve("backend-java"); + if (Files.isDirectory(nested.resolve("src/main/java"))) { + return nested; + } + throw new IllegalStateException("无法定位 backend-java 模块目录(cwd=" + here + ")"); + } + + private static String read(Path file) { + try { + return Files.readString(file, StandardCharsets.UTF_8); + } catch (IOException e) { + throw new IllegalStateException("读取失败: " + file, e); + } + } +} +``` + +> 为什么值得为它写一整份而不是"照抄一个":草稿那句"Java 侧照抄一个即可"本身就是一条占位(writing-plans 的 No Placeholders)。而它最容易死在 `delete` / `deleteGroup` 这种前缀关系上——切错方法比切不到方法坏得多,因为**它会绿**。 + +再写四支用例(前三支是本任务真正要的收窄,第四支是反向钉): + +⚠️ **前三支都要先补 `TableInfoHelper`,否则它们红在框架而不是红在逻辑**。`getSqlSegment()` 要把 `ShopManageEntity::getCreatedById` 这个 lambda 解析成列名,靠的是 MyBatis-Plus 的 `TableInfo` 缓存;单测里没有 Spring 容器去建它,**没初始化就抛 "can not find lambda cache for this entity"**,报得完全不像"我的筛选没生效"。`ShopManageServiceTest` 今天不查 `getSqlSegment()` ⇒ 它**没有**这一步,必须补。写法逐字照本仓库既有惯例(`modules/admin/service/AdminUserListCompanyTest.java:44-45`——它是 `@BeforeEach` 里一行,不是 `@BeforeAll`,也不要自己 new `MapperRegistry`): + +```java + @BeforeEach + void initTableInfo() { + TableInfoHelper.initTableInfo( + new MapperBuilderAssistant(new MybatisConfiguration(), ""), ShopManageEntity.class); + TableInfoHelper.initTableInfo( + new MapperBuilderAssistant(new MybatisConfiguration(), ""), ShopManageGroupEntity.class); + } +``` + +(新建的 `ShopManageGroupServiceTest` 同样要一份,它只需 `ShopManageGroupEntity` 那一行;第四支 `writeEntryPointsCarryNoCompanyId` 只读源码文本,不需要它。) + +顺便:`AdminUserListCompanyTest` 的类注释给了本任务该学的断言口径——"断言必须打在**有没有碰表**上,只断言返回空集合的话,把条件写反了也是空"。上面前三支都按这条写(捕 wrapper 看 segment / pairs),没有一支是"断返回空"。 + +```java + @Test + @DisplayName("读:超管选了公司 ⇒ created_by_id 落进成员集;非超管不叠这一条") + void superAdminPageNarrowsToCompanyMembers() { + // 字段名逐字用 ShopManageServiceTest 已有的:mock 是 shopManageMapper,被测是 service。 + when(shopManageMapper.selectCount(any())).thenReturn(1L); + when(shopManageMapper.selectList(any())).thenReturn(List.of()); + + service.page(1L, 15L, null, null, 1L, true, List.of(11L, 12L)); + + ArgumentCaptor> captor = + ArgumentCaptor.forClass(LambdaQueryWrapper.class); + verify(shopManageMapper).selectCount(captor.capture()); + // 值在 paramNameValuePairs 里,segment 里只有 MPGENVAL 占位 ⇒ 结构从 segment 读、值从 pairs 读。 + assertThat(captor.getValue().getSqlSegment()).contains("created_by_id").contains("IN ("); + assertThat(captor.getValue().getParamNameValuePairs().values()).contains(11L, 12L); + } + + @Test + @DisplayName("分组:list 叠公司必须把既有那条平铺 OR 整个套进括号(否则 created_by_id=? 那半边逃出筛选)") + void groupListWrapsTheOrBeforeNarrowing() { + when(groupMapper.selectList(any())).thenReturn(List.of()); + + groupService.list(5L, List.of(11L)); + + ArgumentCaptor> captor = + ArgumentCaptor.forClass(LambdaQueryWrapper.class); + verify(groupMapper).selectList(captor.capture()); + String segment = captor.getValue().getSqlSegment(); + // 断"OR 被包在 and( ... ) 里"的形状:OR 之前必须出现一个 '(',且整段以 AND (…IN…) 收尾。 + assertThat(segment).contains("(created_by_id").contains(" OR "); + assertThat(segment.lastIndexOf("AND (")) + .as("公司条件必须自成一组,不能与 OR 平铺") + .isGreaterThan(segment.indexOf("created_by_id")); + } + + @Test + @DisplayName("凭据:选了公司的超管按 id 读别家店铺的明文凭据 ⇒ 403(列表筛了、按 id 照读 = 越权,§6.1)") + void credentialByIdIsGatedByTheSameMemberSet() { + ShopManageEntity foreign = new ShopManageEntity(); + foreign.setId(77L); + foreign.setCreatedById(999L); // 不在 {11,12} 里 + when(shopManageMapper.selectById(77L)).thenReturn(foreign); + + assertThatThrownBy(() -> service.getCredentialById(77L, List.of(11L, 12L))) + .isInstanceOf(BusinessException.class) + .hasFieldOrPropertyWithValue("code", 403); + // null ⇒ 不筛,保持超管没选公司时的今天行为(Constraint 2:tab 不是安全边界,别把默认改成拒绝)。 + assertThatCode(() -> service.getCredentialById(77L, null)).doesNotThrowAnyException(); + } + + @Test + @DisplayName("写:店铺与分组的写入口一律不收 company_id——归属不从界面注入(§6.2,未批的界面暴露)") + void writeEntryPointsCarryNoCompanyId() { + String text = SourceScan.sourceText("ShopManageController.java"); + // 必须逐方法体判:page 这个读入口这轮就要加 company_id,全文 doesNotContain 会被自己弄红。 + for (String writer : List.of("create", "update", "delete", "createGroup", "updateGroup", "deleteGroup")) { + assertThat(SourceScan.methodBody(text, writer)) + .as("写入口「" + writer + "」一旦出现 company_id,等于把公司维度端回界面(未批)") + .doesNotContain("company_id") + .doesNotContain("companyId"); + } + assertThat(SourceScan.methodBody(text, "page")).contains("company_id"); // 取样非空自检:读侧确实接上了 + } +``` + +> `methodBody(text, "delete")` 与 `deleteGroup` 是本任务最容易写错的一对:`methodBody` 靠 `(? companyMemberIds`。实查 `:31-61`:**超管今天完全不锁**(`:43` 的 `if (!superAdmin)` 里才有那套 OR),所以这一支是**新增**,不是"改既有过滤";插在 `if (!superAdmin) { ... }` 之后、`selectCount`(`:63`)之前: + +```java + // companyMemberIds 由 controller 算好传进来(service 手上只有 operatorId + 一个布尔, + // 而 readScope 要 AdminUserEntity)。null = 不筛,与"超管没选公司"的今天逐字一致。 + if (companyMemberIds != null) { + if (companyMemberIds.isEmpty()) { + query.eq(ShopManageEntity::getId, -1L); // 照 :46 既有的"必空"写法,别再发明一种 + } else { + query.in(ShopManageEntity::getCreatedById, companyMemberIds); + } + } +``` + +> 走 `created_by_id` 而**不是** `group_id`:一个店铺同时有 `created_by_id` 和一个 `group_id`,而分组自己也有 `user_id`/`created_by_id` ⇒ 两个候选真相源。§11.1 批次 3 那条"同页两个真相源"的告诫在这里同样成立,**这页只认 `created_by_id`**,并把"店铺建在别家名下但创建人是超管"这类行留给 Tab 的第一家(超管自己那家)。今天实查第 2 家 0 行 ⇒ 无可观察差异。 + +**(b) `ShopManageController`** —— `page`(`:66-80`) 与 `listGroups`(`:115-123`) 各加 `@RequestParam(name = "company_id", required = false) Long companyId`(**必须显式 `name=`**,见 Step 5 那条 ⚠️),并在调 service 前折一次范围: + +```java + AdminUserEntity operator = requireOperator(request); + ReadScope read = dataReadScope.readScope(operator, companyId); + List memberIds = read.isUnfiltered() ? null : read.userIds(); +``` + +⚠️ **`memberIds` 只在超管分支下传,非超管一律传 `null`**。理由不是"已经锁过了"那么轻:非超管那套 OR(`:48-59`,它**本身已经包在 `and(wrapper -> …)` 里**,所以不存在 Step 3(c) 那个括号问题)含一条 `group_id IN accessibleGroupIds` —— 分组行上**没有账号列可推公司**,一个由别人创建、但把该非超管设为负责人的分组今天对他可见。给它外面再叠一条 `AND created_by_id IN (自家成员)`,那批"靠分组可见"的行会**从他的每一个 tab 里消失**,且不报错。这正是 spec §9.1 点名的静默删除形状,代价比"非超管理论上可能跨公司"更确定(今天 2 家、第 2 家 0 行业务数据)。`listGroups` 更是分岔的:`:119-122` 超管走 `list(createdById)`、非超管走 `listAccessible(...)` ⇒ **只给超管那条传 `memberIds`,`listAccessible` 一行都不许动**。非超管的跨公司收窄要做得先回答"分组算哪家公司",而重写 `listAccessibleGroupIds` 是 spec §13「不重写 `UserDataScopeSupport` 的分组口径」明确排除的(⇒ 记进附B,并且**对外别说"非超管已按公司锁死"**)。 + +**(c) `ShopManageGroupService.list`** —— 见下面那段括号警告,形状是: + +```java + public List list(Long createdById, List companyMemberIds) { + LambdaQueryWrapper qw = new LambdaQueryWrapper() + .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(Long)` 两支既有重载委托到它(`list()` 被同文件 `listAccessible:60` 调用,`list(Long)` 被 `ShopManageController.java:120` 调用——实查这两支都有活调用方,**删重载直接编译断**)。 + +**(d) `getCredentialById` 的闸门**(`ShopManageService.java:155-164`)—— 这是本任务里唯一一处"不做就是真越权"的东西:`:175-182` 的 `adminCredential(id)` 走 `requireOperator` = **`requireAdminOrInternal`**(`:50-52`),今天**任何**已认证后台账号(含内部令牌通道)拿一个 id 就能读到**别家店铺的明文账号密码**,连分组都不判。§6.1 那条"列表筛了、按 id 照读 = 越权"在这里是字面成立的,而且读出来的是凭据。 + +```java + public ShopManageCredentialVo getCredentialById(Long id, List companyMemberIds) { + if (id == null || id <= 0) { + throw new BusinessException("店铺 ID 不合法"); + } + ShopManageEntity entity = shopManageMapper.selectById(id); + if (entity == null) { + throw new BusinessException("店铺不存在"); + } + // 与列表同一把尺子:memberIds 非 null 时,行的 created_by_id 必须落得进去。 + // 抛 403 而不是静默返回 null —— 静默会让调用方以为"这店铺没配凭据",那是数据问题伪装成权限问题。 + if (companyMemberIds != null && !companyMemberIds.contains(entity.getCreatedById())) { + throw new BusinessException(403, "无权查看该店铺的凭据"); + } + return toCredentialVo(entity); + } +``` + +⚠️ **`getCredentialByShopName`(`:156-171`)这轮刻意不动**,理由与影响记进附B:它的调用方是 Python 自动化与 4.0.44 起的登录态客户端(`ShopManageCredentialAuthTest` 钉着那两条通道),`requireUser` 拿到的可能是**根本不是后台账号**的客户端用户 —— 那里没有"操作者公司"可推导,硬加闸门会把跟价机整片打停。它今天同样是跨公司的(按名字就能读凭据),**那是一期就存在的洞,不是本计划引入的**,要修得单独一张工单、单独授权。 + +- [ ] **Step 4: 写侧**——本任务**不动**它,并说明为什么(这是 2026-10-04 定下的口径,不是偷懒) + +`ShopManageController` 的 `create`(`:84`)/`update`(`:94`)/`delete`(`:105`) 与三个分组写入口**保持原样**:请求体不收 `company_id`,界面上也不给"所属公司"下拉。 + +⚠️ **先把草稿里一句说错的话改对**:原来写的是"归属继续由后端从操作者推导(`created_by_id = operator.getId()`)"——**不对**。实查 `ShopManageService.java:86` 是 `normalizePositiveId(request.getCreatedById(), "创建人不能为空")`,`:96` `entity.setCreatedById(createdById)` ⇒ **店铺的归属人今天就是请求体里那个 `createdById`,由调用方挑**(后台弹窗里那个"负责人"下拉就是它)。⇒ 三条后果,都得写在脸上: + +1. **"超管在别家 tab 下导入会落到自己公司"这句对店铺不成立**。超管把负责人选成 `users.id=1193`(第 2 家自己的 admin),店铺就归第 2 家 —— 这是**现成的、今天就能用的**路径,spec §6.3 那条副作用在店铺这页是"取决于你选谁当负责人",不是"恒落公司 1"。**Step 6 的提交信息与人工验收第 4 条按这个改**(那条原本写"确认没有跟着 tab 走",在店铺这页会把一次正常行为报成 bug)。 +2. **反向钉的口径要收窄**:钉的是"不收 `company_id`",不是"归属不可指定"。`createdById` 这个既有字段照旧收 —— 动它才是回归。Step 1 第四支用例的断言式因此只看 `company_id`/`companyId` 两个词,不看 `createdById`。 +3. **今天 `createdById` 没有任何公司校验**:任何已认证后台账号(含内部令牌通道)能把店铺挂到任意 `users.id` 名下。这跟 (d) 那个凭据读出口是同一类"一期就在的洞",本计划不顺手补(补它 = 给写侧加一条会 403 新老数据的校验,是要单独批的行为变更),**记进附B**。 + +为什么仍不给 `create` 加 `company_id`,三条理由: + +1. **新维度默认只做后端,界面暴露要单独批准**(memory,2026-10-04 与用户对二期那条线的同一轮定调)。让 `create` 收 `company_id` = 在弹窗里长出一个公司选择器,那是要单独批的界面暴露,不在本计划已批范围(已批的是:超管用的 tab 一条 + 公司配置入口收窄)。何况**归属已经能从"负责人"表达**——再加一个公司选择器就是两个控件说同一件事,且它们会互相矛盾(选了第 2 家 + 选了公司 1 的负责人,听谁的?)。 +2. **与建号同口径**:`AdminUserService.resolveTargetCompanyId`(`AdminUserService.java:201-207`)今天就是"前端不传 ⇒ 落操作者自己的公司",二期那条线还专门用 `tests/company-user-create.test.ts` 把它反向钉死了。店铺这边若单独改成"按 tab 选的公司落",同一后台就出现两套归属口径——那正是 memory「别自己定"全局统一默认值"口径」点名的坑。 +3. **实体没有可落的列**:`ShopManageEntity`/`ShopManageGroupEntity` 只有 `createdById`/`groupId`/`userId`,**没有 `company_id`**(实查 `modules/shopkey/model/entity/ShopManageEntity.java:16-28`、`common/model/entity/ShopManageGroupEntity.java:16-22`)。要让"这店铺属于第 2 家"成为一个可写的显式事实,只能给这两张表加列(那是 DDL,spec §13 排除)或加一条"负责人必须是那家成员"的校验(超管自己不在任何别家的成员集里 ⇒ **那条校验一旦上线,超管把负责人留成自己就 403**,比今天更糟)。 + +⇒ **本任务的诚实边界**:tab 是**纯读视图**,写侧的归属规则一行都没动。运维手册里要写清的是这一句(它比 spec §6.3 原文更准确): + +> 店铺/分组的归属由**负责人(`created_by_id`)**决定,不由顶部 tab 决定。要让数据归第 2 家,就把负责人选成第 2 家的账号(或用第 2 家自己的 admin 登录来建)。切 tab **不会**改变新建数据的归属。建号同理(`users.id=1193` 就是第 2 家自己的 admin 建的)。 + +这条对第 2 家公司当前**影响为零**(Task 5 Step 0 的 SQL 会给出它有几行数据;实查是 0 行业务数据),但对第 3 家开始就是运维手册里的一行字。**两处落点都已经写好,本步只需核对,不要再追加**:①spec §6.3 已按实查重写成"建号/店铺/分组"两段(17:5x 那轮订正,再追加一遍就是一份文档两个口径);②`operation-guides.ts` 店铺管理那句文案由 **Task 7 Step 7** 统一落地(它那一支用例的分母就是注册表,本任务补等于绕过护栏)。执行到这一步只做一个动作:`Grep` 一遍 spec §6.3 与 `admin_shop_manage` 的 text,确认这段口径各只有**一处**,多出来的那份删掉。 + +- [ ] **Step 5: 前端只带读参数** + +两页的取数入口形状不同,逐一写清楚(这页最容易出的错不是筛错,是**参数名对不上被静默丢掉**): + +- `src/pages/shop/shop-manage-api.ts:25-31`:`fetchShopManageList(params)` 的 query 由 `toShopManagePageQuery(normalizeShopListParams(params))` 产出(`shop-dto.ts:140-160`)。照 Task 8 Step 5 的形状,在 **builder 之后**补键,别去改 `ShopManageListParams`——`normalizeShopListParams`(`shop-dto.ts:140-146`)是白名单构造返回值,加进去的字段会被原样丢掉: + + ```ts + const query = toShopManagePageQuery(normalized) + if (params.companyId != null) query.company_id = params.companyId + ``` + + `ShopManagePageQuery`(同文件)加 `company_id?: number`。 +- `src/pages/account/shop-group-api.ts:14-17`:`fetchShopGroups()` **今天一个参数都没有**,`http.get(SHOP_GROUPS_ENDPOINT)` 也没带 `params`。⇒ 要新加 `companyId?: number | null` 入参并改成 `http.get(SHOP_GROUPS_ENDPOINT, { params: companyId != null ? { company_id: companyId } : {} })`,调用点 `GroupsPage.vue` 跟着传。**这一步漏掉的后果比筛错更坏**:分组列表继续返回全部公司可访问的分组,而店铺列表已经窄了,两页下拉对不上。 + +⚠️ **参数名一律写 `company_id`,后端对应 `@RequestParam(name = "company_id")` 必须显式带 `name=`**。这两页的邻居参数全是驼峰(`page`/`pageSize`/`groupId`/`shopName`/`createdById`,实读 `ShopManageController.java:66-71` 与 `:113-117`,它们靠方法参数名绑定),照抄邻居写法写成 `Long companyId` 的话,Spring 收的是 `companyId=`,而前端发的是 `company_id=` ⇒ 参数**永远为 null**、接口 200、列表永远不窄。这是本批次最难发现的一种红(它根本不红),Task 10 Step 4 同一条。 + +**不做**的事列清楚,免得执行时手滑: +- 不改 `GroupEditorDialog.vue` 的"负责人"下拉(那是界面暴露,未批;且 `AdminUserQuery` 侧已有公司收窄,选错人会被 Step 4 说的既有校验接住——执行时先 `Grep` 确认这个校验在,不在就**记进本任务的"已知不做"附B**,不要顺手加下拉)。 +- 不给店铺列表加"所属公司"列(也是界面暴露、Global Constraint 14 未批;且这页进 tab 后,列的语义本来就由 tab 承担)。 + + +- [ ] **Step 6: 跑 + 提交** + +```bash +mvn -q test 2>&1 | tail -10 +node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit +git add backend-java/src/main/java/com/nanri/aiimage/modules/shopkey \ + backend-java/src/test/java/com/nanri/aiimage/modules/shopkey \ + backend-java/src/test/java/com/nanri/aiimage/testutil/SourceScan.java \ + admin-frontend-vue/src/pages/shop admin-frontend-vue/src/pages/account +git commit -m "feat(公司tab): 店铺管理与数据权限分组按公司筛(纯读;凭据按 id 出口补闸门;写侧归属不动并反向钉)" +``` + +⚠️ `SourceScan.java` 是新建文件、`git add` 漏了它 ⇒ 本地全绿、别人拉下来编译红(Task 12 Step 4 依赖它)。`git status --short` 收笔前确认它不在 `??` 里。 + +--- + +## Task 12: 接线 —— 日志管理(按 `uid` 成员集筛,麦象日志恒可见) + +**先读这三条已确认现状(2026-10-04 实查,别再照记忆推):** + +1. `AdminDeviceLogController` 的**全部 9 个端点**第一行都是私有的 `requireSuperAdmin(request)`(`controller/AdminDeviceLogController.java:152-159`,非超管 403「仅超级管理员可访问日志管理」)。⇒ 这一页**根本不存在非超管调用方**,12:3x 那类"读端点挂闸门误伤管理员"的形状在这里不成立;tab 对这页只是超管的视图过滤器。 + (9 是逐行点 `@*Mapping` 数出来的:`/files:52`、`/content:70`、`/download:80`、`DELETE /{id}:93`、`/config:102`、`/devices:114`、`PUT /config/global:121`、`PUT /config/device:130`、`DELETE /config/device/{id}:142`。**spec §6.1 那句写的"10 个"是错的**,已同步改 spec;这条不是抠字眼——"9 个里有几个动了 operator"是 Step 4 那条反向钉的分母,分母错则断言漏。) +2. `DeviceLogService.page(source, uid, startDate, endDate, pageParam, pageSizeParam)`(`service/DeviceLogService.java:162`)把条件包在一个 `Function> wrapperBuilder` 里,**`selectCount` 与 `selectList` 共用它**(`:186`/`:190`)。⇒ 公司过滤必须加在 builder **内部**;加在外面任何一侧都会得到"total 与行集不同宽 = 分页错位"。 +3. 现有 `uid` 条件就是单条 `qw.eq(DeviceLogFileEntity::getUid, uid)`(`:176`),而端点文档自己写着「未登录/采集机的行 uid 为空,不匹配任何 uid」——`DeviceLogFileEntity.uid` 是 `Long`(`:27`),麦象上报的行恒为 NULL。⇒ **这就是 §9.2 那条静默丢数的现场**:直接叠 `uid IN 成员集` 会把跟价机的日志从所有 tab 里抹掉。 + +**Files:** +- Modify: `backend-java/.../modules/devicelog/controller/AdminDeviceLogController.java:52-68`(`files` 接 operator + 算成员集 + 透传;`devices`/`content`/`download`/`delete` **不动**,理由见 Step 4) +- Modify: `backend-java/.../modules/devicelog/service/DeviceLogService.java:162-205`(`page` 加末位参数 `List 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 memberUids)` —— `memberUids == null` 表示不筛(超管没选公司),非 null 空集表示"只放行麦象行" + +- [ ] **Step 0: 先定这页留不留在批次 1(只读取证)** + +spec §11.1 给批次 1 的数量留了一个判据:日志管理这页值不值得进 tab,取决于麦象行占比。跑这条只读 SQL(同 Task 5 Step 0 的通道): + +```sql +SELECT source, COUNT(*) FROM device_log_file GROUP BY source; +``` + +- 麦象占多数 ⇒ 公司 tab 只能筛掉小半边,"按公司看日志"这个诉求在这页基本落空 ⇒ **不声明 `companyScoped`,本批变 7 页**,同时把 `COMPANY_SCOPED_PAGES` 里那条删掉(G1 会跟着少一条正向断言——这是合法删除,不是"让红消失",两者区别见附A 最后一行)。 +- 客户端占多数 ⇒ 留在批次 1,Step 1 起往下做。 +- 结果抄进本任务的提交信息。**"0 命中"或只出一个 source 时先怀疑抓错表**:配一个 `SELECT COUNT(*) FROM device_log_file` 做非零对照(memory「grep -v 过滤器连 stdout 一起吞、0 命中≠没有」)。 + +- [ ] **Step 1: 写失败的测试(这条测试的价值全在"麦象行不许消失")** + +```java + @Test + @DisplayName("选了公司:客户端行按成员集筛,麦象行照常出现(uid 恒 NULL,叠等值就整类消失)") + void maixiangRowsSurviveCompanyFilter() { + when(mapper.selectCount(any())).thenReturn(1L); + when(mapper.selectList(any())).thenReturn(List.of(row(1024L, 2))); + + service().page(null, null, null, null, 1L, 20L, List.of(11L, 12L)); + + AbstractWrapper q = capturedCount(); + assertThat(q.getSqlSegment()) + .as("必须是 (source = ? OR uid IN (...)) 一整组,括号丢了就等于把麦象筛掉") + .contains(" OR ").contains("IN ("); + // 值落在 paramNameValuePairs 里,不在 getSqlSegment() 里——别写成 segment.contains("maixiang"), + // MP 渲染的是 #{ew.paramNameValuePairs.MPGENVAL1},那条断言恒假。 + assertThat(q.getParamNameValuePairs().values()).contains("maixiang", 11L, 12L); + } + + @Test + @DisplayName("成员集为空:退化成只看麦象,不许渲染 IN () 打炸 SQL") + void emptyMemberSetFallsBackToMaixiangOnly() { + when(mapper.selectCount(any())).thenReturn(0L); + + service().page(null, null, null, null, 1L, 20L, List.of()); + + AbstractWrapper q = capturedCount(); + // 只用 contains/doesNotContain:page 里还有 log_date >= ? 那条必带参数, + // 写 containsExactly(...) 会因为多一个 LocalDate 而恒红。 + assertThat(q.getParamNameValuePairs().values()) + .as("空集走 in() 会渲染出 IN (),MySQL 直接语法错;这里必须只看 maixiang") + .contains("maixiang") + .doesNotContain(11L); + assertThat(q.getSqlSegment()).doesNotContain("IN ("); + } + + @Test + @DisplayName("null = 不筛,保持今天的行为(超管没选公司时与上线前逐字一致)") + void nullMemberSetKeepsOldBehaviour() { + when(mapper.selectCount(any())).thenReturn(0L); + + service().page("client", 7L, null, null, 1L, 20L, null); + + AbstractWrapper q = capturedCount(); + assertThat(q.getSqlSegment()).doesNotContain(" OR "); + assertThat(q.getParamNameValuePairs().values()).doesNotContain("maixiang"); + assertThat(q.getParamNameValuePairs().values()).contains("client", 7L); + } + + @Test + @DisplayName("计数支与列表支必须同宽:total 与行集不一致就是分页错位") + void countAndListShareTheSameCondition() { + when(mapper.selectCount(any())).thenReturn(1L); + when(mapper.selectList(any())).thenReturn(List.of(row(1024L, 2))); + + service().page(null, null, null, null, 1L, 20L, List.of(11L)); + + // 比 paramNameValuePairs 而不是 getSqlSegment():列表那支在 builder 外面又叠了 + // orderByDesc(lastUploadAt)+orderByDesc(id)+last("limit o,s")(DeviceLogService.java:190-193), + // 两支的 segment 天生就不相等 ⇒ 断 isEqualTo(getSqlSegment()) 会红在排序上,而不是红在条件上。 + // 条件同宽的正确锚点是"参数绑定序列逐字相同"——排序与 limit 不往 pairs 里塞值。 + assertThat(capturedList().getParamNameValuePairs()) + .as("total 与行集按不同条件算出来的 = 页码跳空/重复行") + .isEqualTo(capturedCount().getParamNameValuePairs()); + } +``` + +**读法三条,都是这组用例能不能咬住实现的关键:** + +1. `selectCount` **一定**被打到,`selectList` 只在 `total != 0` 时才打(`DeviceLogService.java:189-193` 的三元)。所以凡是"看生成的条件"的用例,要么把 `selectCount` 桩成 `1L` 再捕两支,要么直接捕 `selectCount` 那支——别写一个"selectCount 桩 0 然后断言 selectList 的 wrapper"的用例,它捕到的是 null,红在断言之前。 +2. MP 把值放进 `paramNameValuePairs`,`getSqlSegment()` 里只有 `#{ew.paramNameValuePairs.MPGENVAL1}` 这种占位。⇒ **结构**(括号、`OR`、`IN`)从 segment 读,**值**(`"maixiang"`、`11L`)从 `getParamNameValuePairs().values()` 读。写成 `segment.contains("maixiang")` 是恒假断言(memory「字符串断言必须排他、解析断言必须可匹配」)。 +3. `capturedCount()` / `capturedList()` 各用一个 `ArgumentCaptor>` 捕(本文件已 import `ArgumentCaptor` 与 `AbstractWrapper`),捕获后 `(AbstractWrapper)` 转型取 `getSqlSegment()`。`row(1024L, 2)` 用文件里已有的助手即可——这几条测的是**生成的 SQL 形状**,不是返回内容,所以不需要给行设 `source`/`uid`。 + +- [ ] **Step 2: 跑,确认红** + +Run: `mvn -q test -Dtest=DeviceLogServiceTest` +Expected: 编译失败 —— 七参 `page` 不存在。这是预期红;若红在别的文件,先把它读干净再往下(不许为了绿而改断言方向,Global Constraint 13)。 + +- [ ] **Step 3: 实现(改 `wrapperBuilder` 内部,别改外面)** + +`DeviceLogService.page(...)` 末位加参数 `List memberUids`(实查只有一个调用方——`AdminDeviceLogController.java:67`——所以**不需要**留六参重载;加了就没人用,是死参数)。在闭包里 `uid` 那条 `eq`(`:176`)之后插入: + +```java + // memberUids:超管选了公司才非 null。麦象上报的行 uid 恒为 NULL, + // 叠等值会把跟价机的日志从每个 tab 里抹掉(spec §9.2),所以它必须走 OR 那半边。 + if (memberUids != null) { + if (memberUids.isEmpty()) { + qw.eq(DeviceLogFileEntity::getSource, "maixiang"); + } else { + qw.and(w -> w.eq(DeviceLogFileEntity::getSource, "maixiang") + .or(o -> o.in(DeviceLogFileEntity::getUid, memberUids))); + } + } +``` + +三点都要照做: + +1. 放在闭包**内部**——`selectCount` 与 `selectList` 共用这个 `Function`,放外面只作用于其中一支,得到"total 与行集不同宽"的分页错位,而且不报错。 +2. **不要**平铺成 `qw.or(...)`:MP 的 `or()` 不带 `wrapper ->` 时只接左半边,会把已有的 `source`/`log_date` 条件拆坏(与 Task 11 Step 3(c) 那条 `ShopManageGroupService.java:55-56` 同一个坑)。 +3. 空集单独走 `eq(source,'maixiang')` 分支——别赌 `.in(column, 空集合)` 的 MP 行为,它渲染出的 `IN ()` 在 MySQL 是语法错。空集的处置是"只看基础设施日志"而不是"整页空",这是 §12 第 2 条"默认不筛比默认丢日志安全"的落点。 + +`AdminDeviceLogController`:把 `requireSuperAdmin(request)` 的返回类型从 `void` 改成 `AdminUserEntity`(它本来就取了 `adminAuthSupport.requireAdmin(request)`,现在只是把已经拿到的东西传出来),`files(...)` 加参数 `@RequestParam(name = "company_id", required = false) Long companyId`: + +```java + AdminUserEntity operator = requireSuperAdmin(request); + ReadScope read = dataReadScope.readScope(operator, companyId); + List memberUids = read.isUnfiltered() ? null : read.userIds(); + return ApiResponse.success( + deviceLogService.page(source, uid, startDate, endDate, page, pageSize, memberUids)); +``` + +`requireSuperAdmin` 一共 9 个调用点(实查行号 66/76/84/97/106/117/125/137/145),**只有 `files` 那一处(`:66`)需要接住返回值**,其余 8 处本来就丢弃它、一行都不动;它内部那句 `log.warn("[device-log] 非超管访问日志管理被拒 ...")` 保持不动。 + +- [ ] **Step 4: `content`/`download`/`delete`/`devices` 刻意不加公司闸门(写明理由,免得下一个人"顺手补上")** + +- `content`(`:72`) / `download`(`:82`) / `delete`(`:95`) 按 `fileId` 动单行。这页只有超管进得来,列表已不含别家成员的行;按 id 的端点再判一次公司**只会误伤 `uid IS NULL` 的麦象行**——那是排障现场,不是越权面。**这里刻意不做行级闸门**,和 Task 8 的 `detail`/`download-zip` **必须**做闸门是两回事:那两页有 `requireAdminOrInternal` 的非超管/内部通道,这页没有。 +- `devices`(`:114` → `DeviceLogService.recentDevices():213`) 是 `GROUP BY source, device_id` 的去重列表、喂给「终端采集覆盖」选择器,行上没有账号归属,筛不动也不该筛。 +- 这两条决定不写进注释,写进一条实跑用例的 `@DisplayName`: + +```java + @Test + @DisplayName("按 fileId 的端点与 devices 刻意不收 company_id:这页无超管外调用方,收了只会误伤麦象日志") + void singleFileEndpointsStayUnscoped() { + String text = SourceScan.sourceText("AdminDeviceLogController.java"); + assertThat(SourceScan.methodBody(text, "content")).doesNotContain("dataReadScope"); + assertThat(SourceScan.methodBody(text, "download")).doesNotContain("dataReadScope"); + assertThat(SourceScan.methodBody(text, "delete")).doesNotContain("dataReadScope"); + assertThat(SourceScan.methodBody(text, "devices")).doesNotContain("dataReadScope"); + assertThat(SourceScan.methodBody(text, "files")).contains("dataReadScope"); // 取样非空自检 + } +``` + +`SourceScan.methodBody` 是 Task 11 Step 1 建的那个共用工具类(`com.nanri.aiimage.testutil.SourceScan`),**本任务直接 import 它,不许再切一份**。`methodBody` 找不到方法会抛 `AssertionError` ⇒ 反向钉不会因为方法被改名而悄悄恒绿;**不许用全文 `contains`**——那会因为 `files` 里出现一次而四条全部恒绿。 + +- [ ] **Step 5: 前端带参** + +`src/api/device-logs.ts` 的列表 query 构造处加 `if (params.companyId != null) q.company_id = params.companyId`(形状同 Task 8 Step 5,值由页面组件传入,不在 api 模块里裸调 Pinia store)。日志页组件加 Task 7 Step 5 那条 `watch`。 + +- [ ] **Step 6: 跑两支全量 + 提交** + +```bash +mvn -q test 2>&1 | tail -10 +node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit +git add backend-java/src/main/java/com/nanri/aiimage/modules/devicelog backend-java/src/test/java/com/nanri/aiimage/modules/devicelog admin-frontend-vue/src/api/device-logs.ts admin-frontend-vue/src/pages +git commit -m "feat(公司tab): 日志管理按 uid 成员集筛,麦象行走 OR 不被筛掉" +``` + +- [ ] **Step 7: 确认 G1 全套转绿** + +Run: `node --test tests/company-tab-wiring.test.ts` +Expected: 全 PASS(8 个页的正反两向都对上了)。若还有红,**说明某页只改了注册表或只改了 api 文件**——那就是 §6.1 的"半套",不许靠把该页从清单里删掉来让它绿。 + +--- + +## Task 13: 变异自证 + 发布与人工验收 + +**Files:** +- Create: `backend-java/docs/mutation-company-tab.md`(变异台账,照 `docs/` 既有惯例放正式目录,不塞 gitignore 的 tmp) + +- [ ] **Step 1: 七支护栏各配一个注入点,逐条验它真的会红** + +| 护栏 | 注入 | 期望 | +|---|---|---| +| G1(`company-tab-wiring.test.ts`) | 从 `COMPANY_SCOPED_PAGES` 删一行 / 从一个 api 文件删掉 `company_id` | 两支各红一条 | +| G2(`CompanyIdParamGoesThroughReadScopeTest`) | ① 把某 controller 的 `readScope(` 换成裸 `eq`;② 把某处的 `@RequestParam(name = "company_id")` 改成 `@RequestParam Long companyId`(驼峰静默失效的形状) | **两支各红一次**;② 特别要做——它注入后接口仍然 200、页面看不出异常,只有这条扫描会红 | +| G3(`DataReadScopeTest`) | 把"非超管传别家 → 空集"改成"忽略参数" | `adminPassingForeignCompanyGetsEmptyNot403` 红 | +| G4(`PermissionCompanyMenuHiddenTest`) | 三个出口里注释掉任意一处 `SUPER_ADMIN_ONLY_KEYS` | 红 | +| G5(`CompanyReadPathMenuGateTest`) | 让 `listVisible` 退回非超管可 | `hasSize(3)` 红 | +| G6(`CompanyScopeSupportTest`) | 把 `MEMBER_WARN_THRESHOLD` 改成 `Integer.MAX_VALUE` | 哨兵用例红 | +| **G7**(反向钉五支:`company-user-create` / `company-user-list:66` / Task 11 Step 1 第四支 / Task 12 Step 4 那条 / Task 7 Step 7 第 4 条) | ①给 `ShopManageController.create` 加一个 `company_id` 参数;②给 `AdminDeviceLogController.content` 加 `dataReadScope`;③把 `CompanyTabs.vue` 里加回一支 `当前公司:…`;④从 8 条引导文案里任意删掉那句"超级管理员可用页面上方的公司 tab 切换公司" | **各红一条**。③④ 各打在那支的两半上(③红反向那半、④红分母那半——所以一支用例里必须**两半都做变异**,只做③会让"文案其实没落地"看不出来)。G7 天生恒绿,所以它的变异**必须先做**:不做变异就不能声称钉住了(memory「护栏要做进代码出口」+「字符串断言必须排他」) | + +八条硬规矩逐字执行:每轮开跑前把被注入文件**写回 pristine**(还原只认注入前读进内存的字节,**不许 `git checkout`**——这个仓库有另一个会话在并行提交,`checkout` 会把你不认识的在飞改动一起抹掉,17:0x 那三笔就是这么进来的);CRLF 锚串先对齐行尾;分母只认本轮扫描结果;变异点若落在 mock 边界外必然存活,遇到"注入后仍绿"先判是不是注入根本没被执行到。 + +- [ ] **Step 2: 出包与发布(顺序不可颠倒)** + +```bash +# 批次 0(Task 1-4):admin-vue 先上,复验后 jar 才上 +# 批次 1(Task 5-12):jar 先上两台同版,复验后 admin-vue 再上 +``` +逐节点复验走主机 B 的 `127.0.0.1:19080`(**不是** `0.0.0.0:18080` 轮询池);admin-vue 用整树聚合摘要核"线上==本地构建"。 + +⚠️ **批次 1 的 jar 会把 V145 一起带上去,这是必须显式决定的一件事**(不是默认):V145 已在 `b7873209` 提交,但线上 jar 仍是 `e42b37c1…`、Flyway 停在 144。按 memory「要不要重启是可判定的」那条算一次差分: + +```bash +git diff --name-only e42b37c1..<本批次构建的commit> -- backend-java/src/main 'backend-java/src/main/resources/db' | wc -l +``` + +只要结果里含 `V145__brand_dedupe_company_scope.sql`,这一版 jar 一启动就会**在生产应用 V145**(两张规则库表补 `company_id` + 唯一键改每公司一套)。而二期 §13 记着"消费侧 Task 3–8 已叫停 ⇒ 跨公司串扰仍在发生"——也就是说迁移上了、消费端还没上。两个选择,**由用户定**,本计划不自决: + +| 选择 | 做法 | 代价 | +|---|---|---| +| A(默认,最小半径) | 批次 1 的构建树用 `git worktree` 从"Task 12 最后一笔但不含 V145"的提交拉出来——**实际做不到**,因为 V145 在历史里更早(`b7873209` 是 `00e5df02` 的后代)。真要做只能 `git revert b7873209` 出一个临时提交 | 反悔成本高、易出错;不建议 | +| B(推荐) | 让 V145 随批次 1 一起上,但**上线前**把二期的回滚脚本 `backend-java/docs/rollback-V145-company-scope.sql` 读一遍确认它仍是可执行路径,并把 §11.2 四条 SQL 在 V145 之前先跑一次留底 | 消费侧未上线 ⇒ 串扰窗口延长到批次 2/3;V145 本身是加列+改唯一键,属前向兼容 | + +> 若用户选"这次不带 V145",那批次 1 的 jar 就不能从 `master` 直接构建——**这件事必须在出包前说清并留下书面决定**,别到启动日志里看到 `Migrating schema … to version 145` 才发现。 + +- [ ] **Step 3: 人工实跑清单(`mvn test` 验不到生产长什么样,这批必须实跑)** + +1. **非超管回归**(批次 0 的账):一个 admin 账号登录 → 侧边栏无「公司管理」→ 直接手输 URL `/admin-vue/account/companies` 被弹回首屏 → 「用户管理」正常打开且 Network 无 `/api/admin/companies`。 +2. **越权实验**(G3 的真身):非超管带 `?company_id=<别家>` 请求 `/api/admin/user-secrets` → **200 + 空列表**,不是 403、不是别家数据。 +3. **tab 有效性**:超管切公司,八页各切一次,行数必须变;`overview` 计数与列表行集同宽(Task 10 Step 4 那五个端点如果漏了一个,这一步会露出来)。 +4. **写归属按 Task 11 Step 4 的口径实测(这条的预期与直觉相反,而且**建号与店铺两件事要分开验,别用一条验收覆盖两页**)**: + - **建号**:超管切到第 2 家 tab 建一个账号 → 查库确认新账号 `company_id` 是**1**(超管自己那家),没跟着 tab 走 —— 这是设计(`AdminUserService.resolveTargetCompanyId`,spec §6.3)。 + - **店铺**:⚠️ **这页的预期完全不同**。店铺的 `created_by_id` 来自请求体(Task 11 Step 4 那条更正),所以"新建店铺的归属跟着 tab 走吗"这个问题问错了。要验的是两件事:① 负责人选超管自己 ⇒ `created_by_id=超管`、这家账号所属公司为 1;② 负责人选 `users.id=1193` ⇒ 店铺**就归第 2 家**(今天已经能做,本轮没改它)。**别把 ② 报成"tab 生效了"**,那是负责人字段生效,与 tab 无关。 + - 两条都要再验一次"切 tab 不改变上述任何一条"。测完删掉测试行(只交付命令,用户执行)。 +5. **凭据读出口随 tab 收窄**(Task 11 Step 3(d) 的账,这条 `mvn test` 验不到):超管切到第 2 家 tab → 从 Network 里取一个**第 1 家**店铺的 id 直接请求 `GET /api/admin/shop-manages//credential` → **403**,不是 200 + 明文密码。反向再验一次:不切 tab(或切回第 1 家)同一请求必须 200,否则就是闸门写死成了"非当前 tab 全禁"。 +6. **麦象日志不消失**(Task 12 的账):切任意公司 tab,日志管理里 `source=maixiang` 的行必须还在。 +7. **保存权限不炸**(Task 4 的账):给一个历史带 `admin_companies` 授权的账号保存一次权限 → 成功 + 日志 `GRANT_SUPER_ADMIN_ONLY_STRIPPED`。 +8. **文案这三眼看**(§9.3 / §5 的账,`node --test` 只能验"字符串在不在",验不到"读的人怎么理解"):①超管在任意一页看到引导条那句"超级管理员可用页面上方的公司 tab 切换公司"时,tab 条**确实在它上方**(Task 7 Step 4 挂的是 `` 与 `` 之间,顺序反了这句话就指错了方向);②引导条被收起过的人看不见这句——找一个 `localStorage.shufuAdminGuideCollapsed='1'` 的浏览器确认这不是硬伤,并在运维手册里说明这句的位置;③非超管账号读同一句时不会去找那个他根本不会有的控件(这句以"超级管理员"开头就是为这一步,若真读着别扭,改法是加 `isSuperAdmin` 分支而不是改回祈使句)。 +- [ ] **Step 4: 更新两份文档 + 清掉我自己留下的临时件** + +- `docs/ops/company-tab-design-2026-10-04.md` 顶部状态改「已实施(批次 0-1)」,并把 §12 第 1 条的实际取舍(V145 带没带上、谁定的)补一句。 +- `docs/plans/` 里新开批次 2/3 的计划占位(只写前置闸门:§11.2 四条只读 SQL + 二期 V145 落地),**不写任务**——没有取证结果就写任务必然编造(writing-plans 的 No Placeholders)。 +- 删 `backend-java/tmp-probe.txt`(我 11:47 为取 V145 生产现状留的探针,无引用;删前 `git grep tmp-probe` 确认 0 消费者)。**不要**碰 `tmp/c8-build`——那是真 worktree。 + +```bash +git commit -m "docs(公司tab): 批次 0-1 出厂记录 + 批次 2/3 前置闸门占位" +``` + +--- + +## 附 A:只能同批改的配对(滞后一条就是线上事故) + +| 配对 | 为什么不能拆 | +|---|---| +| 批次 0 的 admin-vue 上线(现网那版早于 `85e1e92a`,仍在调公司目录)↔ Task 3(后端读端点 403) | 顺序反了 = 15 个管理员开「用户管理」即 403 → 整页踢回登录页(12:3x 原样重演);现网到底还调不调,由 Task 2 Step 4 的取证定,但**顺序本身不变** | +| Task 4 Step 5(剥离而非 403)↔ 保存权限这条链 | 整树提交里带一条历史授权就 403,会让"改密码/建号"整体回滚(09-16 的形状) | +| Task 10 Step 3 的 `allUsers=false` ↔ `USER_SCOPE_T/B` 的 `` | 选了公司还给超管留 `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)。要修它是单独一张工单。 +- **不重写 `listAccessibleGroupIds` / `listAccessible`**:非超管的分组可见口径不动(spec §13)。⇒ 本计划对非超管的跨公司保证,只在**真正经过 `DataReadScope` 的那几支列表**上成立,是**部分强度**(与二期 §9.4 同词)。验收时别把它说成"非超管已按公司锁死"。 +- 不做"tab 值进 URL / 可分享链接带公司上下文"(spec §12 第 4 条)。 +- 不碰二期的 V145 迁移文件(已在 `b7873209` 提交,本计划不改它、不替它决定上线时机——上线时机是 Task 13 Step 2 那条要用户拍板的显式决定)。