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