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(null, null)`;`list()` 有活调用方 `listAccessible`,删了编译断。原稿点名的单参 `list(Long)` 落地后无人调用,**已删**——见 Step 3(c) 那条执行期订正)
- `ShopManageCredentialVo getCredentialById(Long id, Long operatorId, boolean superAdmin)` —— 非超管时行的 `created_by_id ∈ 可访问创建人集` **或** `group_id ∈ 可访问分组集` 才放行,两腿都不认 ⇒ `BusinessException(403, ...)`;超管短路不查可见集。**为什么不是原稿那个成员集版**见 Step 3(d) 的执行期定案(用账号集合当闸门会把"建在我可访问分组里、创建人是别人"的行 403 掉 = 静默删掉正当访问)
- 写侧**不新增任何参数**——见 Step 4 的口径与它那条反向钉
- [ ] **Step 1: 写失败的测试(读侧一条 + 分组括号一条 + 凭据闸门一条 + 写侧"不得回流"一条)**
先建那个共用的测试工具类(Task 12 Step 4 用它,本任务的反向钉也用它;**放在 `testutil` 包而不是各写一份**):
`backend-java/src/test/java/com/nanri/aiimage/testutil/SourceScan.java`
```java
package com.nanri.aiimage.testutil;
import static org.junit.jupiter.api.Assertions.fail;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
/** 源码扫描式护栏的取文助手。路径解析照抄 {@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()` 被同文件 `listAccessible` 调用)。**执行期订正**:原稿说的 `list(Long)` 单参重载并没有活调用方——controller 那一支从一开始就要传公司成员集,落地时调的是二参 `list(createdById, memberIds)`(`ShopManageController.java:129`),单参那支成了死代码,已随修复轮删除(`grep` 全仓 `src/main` + `src/test` 零命中)。零参 `list()` 仍在用,删它才会编译断。
**(d) `getCredentialById` 的闸门**(`ShopManageService.java:155-164`)—— 这是本任务里唯一一处"不做就是真越权"的东西:`:175-182` 的 `adminCredential(id)` 走 `requireOperator` = **`requireAdminOrInternal`**(`:50-52`),今天**任何**已认证后台账号(含内部令牌通道)拿一个 id 就能读到**别家店铺的明文账号密码**,连分组都不判。§6.1 那条"列表筛了、按 id 照读 = 越权"在这里是字面成立的,而且读出来的是凭据。
(下面这段代码块是**执行期定案后的实际形状**,原稿设想的 `companyMemberIds` 版已被替换,理由见代码块之后。)
**执行期定案(与原稿不同,差异是实质性的,照原稿写会静默删掉正当访问)**:闸门不收 `companyMemberIds`,
收 `(Long id, Long operatorId, boolean superAdmin)`,判据用 `page()` 那把尺子的**两腿**——
`created_by_id ∈ 可访问创建人集` **或** `group_id ∈ 可访问分组集`:
```java
public ShopManageCredentialVo getCredentialById(Long id, Long operatorId, boolean superAdmin) {
if (id == null || id <= 0) {
throw new BusinessException("店铺 ID 不合法");
}
ShopManageEntity entity = shopManageMapper.selectById(id);
if (entity == null) {
throw new BusinessException("店铺不存在");
}
// 尺子必须与 page() 那一条同形:created_by_id IN creators OR group_id IN groups。
// 账号集合表达不了分组那一腿(店铺建在我可访问的分组里、创建人却不在我的账号集),
// 拿它当闸门会把列表看得见的行读凭据时 403 掉——那是把正当访问静默删掉。
if (!superAdmin) {
Set creators = shopManageGroupService.listAccessibleCreatorUserIds(operatorId, false);
Set groups = shopManageGroupService.listAccessibleGroupIds(operatorId, false);
boolean visible = (entity.getCreatedById() != null && creators.contains(entity.getCreatedById()))
|| (entity.getGroupId() != null && groups.contains(entity.getGroupId()));
if (!visible) {
throw new BusinessException(403, "无权查看该店铺的凭据");
}
}
return toCredentialVo(entity);
}
```
为什么不能用原稿那个 `companyMemberIds.contains(created_by_id)`:这一页的列表口径本来就是"创建人集 ∪ 分组集"两条腿
(`page()` 里那条 `... OR group_id IN (...)`),而成员集只表达前一条腿。用它当闸门 ⇒ 超管选了公司时、以及管理员读
"建在自己分组里、创建人是别人"的店铺时会被 403,**症状是列表看得见、点开除凭据报无权**,而这类"把正当访问筛没了"
的错误不会有任何接口红。钉这个差异的用例是 `ShopManageServiceTest.credentialByIdKeepsGroupVisibleRowsReadable`
(分组可见、创建人不在账号集 ⇒ 必须 200),它是防误伤的正样本;反向越权由
`credentialByIdRejectsRowOutsideBothVisibleSets` 钉(两腿都不认 ⇒ 403)。超管仍走 `superAdmin` 短路不查可见集
(tab 不是安全边界,这一页的既定口径)。
⚠️ **`getCredentialByShopName`(`:156-171`)这轮刻意不动**,理由与影响记进附B:它的调用方是 Python 自动化与 4.0.44 起的登录态客户端(`ShopManageCredentialAuthTest` 钉着那两条通道),`requireUser` 拿到的可能是**根本不是后台账号**的客户端用户 —— 那里没有"操作者公司"可推导,硬加闸门会把跟价机整片打停。它今天同样是跨公司的(按名字就能读凭据),**那是一期就存在的洞,不是本计划引入的**,要修得单独一张工单、单独授权。
- [ ] **Step 4: 写侧**——本任务**不动**它,并说明为什么(这是 2026-10-04 定下的口径,不是偷懒)
`ShopManageController` 的 `create`(`:84`)/`update`(`:94`)/`delete`(`:105`) 与三个分组写入口**保持原样**:请求体不收 `company_id`,界面上也不给"所属公司"下拉。
⚠️ **先把草稿里一句说错的话改对**:原来写的是"归属继续由后端从操作者推导(`created_by_id = operator.getId()`)"——**不对**。实查 `ShopManageService.java:86` 是 `normalizePositiveId(request.getCreatedById(), "创建人不能为空")`,`:96` `entity.setCreatedById(createdById)` ⇒ **店铺的归属人今天就是请求体里那个 `createdById`,由调用方挑**(后台弹窗里那个"负责人"下拉就是它)。⇒ 三条后果,都得写在脸上:
1. **"超管在别家 tab 下导入会落到自己公司"这句对店铺不成立**。超管把负责人选成 `users.id=1193`(第 2 家自己的 admin),店铺就归第 2 家 —— 这是**现成的、今天就能用的**路径,spec §6.3 那条副作用在店铺这页是"取决于你选谁当负责人",不是"恒落公司 1"。**Step 6 的提交信息与人工验收第 4 条按这个改**(那条原本写"确认没有跟着 tab 走",在店铺这页会把一次正常行为报成 bug)。
2. **反向钉的口径要收窄**:钉的是"不收 `company_id`",不是"归属不可指定"。`createdById` 这个既有字段照旧收 —— 动它才是回归。Step 1 第四支用例的断言式因此只看 `company_id`/`companyId` 两个词,不看 `createdById`。
3. **今天 `createdById` 没有任何公司校验**:任何已认证后台账号(含内部令牌通道)能把店铺挂到任意 `users.id` 名下。这跟 (d) 那个凭据读出口是同一类"一期就在的洞",本计划不顺手补(补它 = 给写侧加一条会 403 新老数据的校验,是要单独批的行为变更),**记进附B**。
为什么仍不给 `create` 加 `company_id`,三条理由:
1. **新维度默认只做后端,界面暴露要单独批准**(memory,2026-10-04 与用户对二期那条线的同一轮定调)。让 `create` 收 `company_id` = 在弹窗里长出一个公司选择器,那是要单独批的界面暴露,不在本计划已批范围(已批的是:超管用的 tab 一条 + 公司配置入口收窄)。何况**归属已经能从"负责人"表达**——再加一个公司选择器就是两个控件说同一件事,且它们会互相矛盾(选了第 2 家 + 选了公司 1 的负责人,听谁的?)。
2. **与建号同口径**:`AdminUserService.resolveTargetCompanyId`(`AdminUserService.java:201-207`)今天就是"前端不传 ⇒ 落操作者自己的公司",二期那条线还专门用 `tests/company-user-create.test.ts` 把它反向钉死了。店铺这边若单独改成"按 tab 选的公司落",同一后台就出现两套归属口径——那正是 memory「别自己定"全局统一默认值"口径」点名的坑。
3. **实体没有可落的列**:`ShopManageEntity`/`ShopManageGroupEntity` 只有 `createdById`/`groupId`/`userId`,**没有 `company_id`**(实查 `modules/shopkey/model/entity/ShopManageEntity.java:16-28`、`common/model/entity/ShopManageGroupEntity.java:16-22`)。要让"这店铺属于第 2 家"成为一个可写的显式事实,只能给这两张表加列(那是 DDL,spec §13 排除)或加一条"负责人必须是那家成员"的校验(超管自己不在任何别家的成员集里 ⇒ **那条校验一旦上线,超管把负责人留成自己就 403**,比今天更糟)。
⇒ **本任务的诚实边界**:tab 是**纯读视图**,写侧的归属规则一行都没动。运维手册里要写清的是这一句(它比 spec §6.3 原文更准确):
> 店铺/分组的归属由**负责人(`created_by_id`)**决定,不由顶部 tab 决定。要让数据归第 2 家,就把负责人选成第 2 家的账号(或用第 2 家自己的 admin 登录来建)。切 tab **不会**改变新建数据的归属。建号同理(`users.id=1193` 就是第 2 家自己的 admin 建的)。
这条对第 2 家公司当前**影响为零**(Task 5 Step 0 的 SQL 会给出它有几行数据;实查是 0 行业务数据),但对第 3 家开始就是运维手册里的一行字。**两处落点都已经写好,本步只需核对,不要再追加**:①spec §6.3 已按实查重写成"建号/店铺/分组"两段(17:5x 那轮订正,再追加一遍就是一份文档两个口径);②`operation-guides.ts` 店铺管理那句文案由 **Task 7 Step 7** 统一落地(它那一支用例的分母就是注册表,本任务补等于绕过护栏)。执行到这一步只做一个动作:`Grep` 一遍 spec §6.3 与 `admin_shop_manage` 的 text,确认这段口径各只有**一处**,多出来的那份删掉。
- [ ] **Step 5: 前端只带读参数**
两页的取数入口形状不同,逐一写清楚(这页最容易出的错不是筛错,是**参数名对不上被静默丢掉**):
- `src/pages/shop/shop-manage-api.ts:25-31`:`fetchShopManageList(params)` 的 query 由 `toShopManagePageQuery(normalizeShopListParams(params))` 产出(`shop-dto.ts:140-160`)。照 Task 8 Step 5 的形状,在 **builder 之后**补键,别去改 `ShopManageListParams`——`normalizeShopListParams`(`shop-dto.ts:140-146`)是白名单构造返回值,加进去的字段会被原样丢掉:
```ts
const query = toShopManagePageQuery(normalized)
if (params.companyId != null) query.company_id = params.companyId
```
`ShopManagePageQuery`(同文件)加 `company_id?: number`。
- `src/pages/account/shop-group-api.ts:14-17`:`fetchShopGroups()` **今天一个参数都没有**,`http.get(SHOP_GROUPS_ENDPOINT)` 也没带 `params`。⇒ 要新加 `companyId?: number | null` 入参并改成 `http.get(SHOP_GROUPS_ENDPOINT, { params: companyId != null ? { company_id: companyId } : {} })`,调用点 `GroupsPage.vue` 跟着传。**这一步漏掉的后果比筛错更坏**:分组列表继续返回全部公司可访问的分组,而店铺列表已经窄了,两页下拉对不上。
⚠️ **参数名一律写 `company_id`,后端对应 `@RequestParam(name = "company_id")` 必须显式带 `name=`**。这两页的邻居参数全是驼峰(`page`/`pageSize`/`groupId`/`shopName`/`createdById`,实读 `ShopManageController.java:66-71` 与 `:113-117`,它们靠方法参数名绑定),照抄邻居写法写成 `Long companyId` 的话,Spring 收的是 `companyId=`,而前端发的是 `company_id=` ⇒ 参数**永远为 null**、接口 200、列表永远不窄。这是本批次最难发现的一种红(它根本不红),Task 10 Step 4 同一条。
**不做**的事列清楚,免得执行时手滑:
- 不改 `GroupEditorDialog.vue` 的"负责人"下拉(那是界面暴露,未批;且 `AdminUserQuery` 侧已有公司收窄,选错人会被 Step 4 说的既有校验接住——执行时先 `Grep` 确认这个校验在,不在就**记进本任务的"已知不做"附B**,不要顺手加下拉)。
- 不给店铺列表加"所属公司"列(也是界面暴露、Global Constraint 14 未批;且这页进 tab 后,列的语义本来就由 tab 承担)。
- [ ] **Step 6: 跑 + 提交**
```bash
mvn -q test 2>&1 | tail -10
node --test tests/company-tab-wiring.test.ts && npx vue-tsc --noEmit
git add backend-java/src/main/java/com/nanri/aiimage/modules/shopkey \
backend-java/src/test/java/com/nanri/aiimage/modules/shopkey \
backend-java/src/test/java/com/nanri/aiimage/testutil/SourceScan.java \
admin-frontend-vue/src/pages/shop admin-frontend-vue/src/pages/account
git commit -m "feat(公司tab): 店铺管理与数据权限分组按公司筛(纯读;凭据按 id 出口补闸门;写侧归属不动并反向钉)"
```
⚠️ `SourceScan.java` 是新建文件、`git add` 漏了它 ⇒ 本地全绿、别人拉下来编译红(Task 12 Step 4 依赖它)。`git status --short` 收笔前确认它不在 `??` 里。
---
## Task 12: 接线 —— 日志管理(按 `uid` 成员集筛,麦象日志恒可见)
**先读这三条已确认现状(2026-10-04 实查,别再照记忆推):**
1. `AdminDeviceLogController` 的**全部 9 个端点**第一行都是私有的 `requireSuperAdmin(request)`(`controller/AdminDeviceLogController.java:152-159`,非超管 403「仅超级管理员可访问日志管理」)。⇒ 这一页**根本不存在非超管调用方**,12:3x 那类"读端点挂闸门误伤管理员"的形状在这里不成立;tab 对这页只是超管的视图过滤器。
(9 是逐行点 `@*Mapping` 数出来的:`/files:52`、`/content:70`、`/download:80`、`DELETE /{id}:93`、`/config:102`、`/devices:114`、`PUT /config/global:121`、`PUT /config/device:130`、`DELETE /config/device/{id}:142`。**spec §6.1 那句写的"10 个"是错的**,已同步改 spec;这条不是抠字眼——"9 个里有几个动了 operator"是 Step 4 那条反向钉的分母,分母错则断言漏。)
2. `DeviceLogService.page(source, uid, startDate, endDate, pageParam, pageSizeParam)`(`service/DeviceLogService.java:162`)把条件包在一个 `Function> 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 命中≠没有」)。
✅ **已实跑(2026-10-05 15:1x,主机 A 业务库只读,非零对照齐全)**:`COUNT(*)` = **1028**;`GROUP BY source` = `client` **831** / `maixiang` **197**(831+197=1028,与对照逐数相符)⇒ **客户端占多数 ⇒ 这页留在批次 1,`companyScoped` 照声明,Step 1 起往下做**。另有一条本任务要用:`WHERE uid IS NULL GROUP BY source` = `client` **22** / `maixiang` **197** ⇒ 那 22 行是"有 source=client 但没有账号可归属"的一族,`(maixiang OR uid IN (成员集))` 那个形状照样会把它们抹掉 ⇒ Step 1 的用例要替它们说句话(放行还是接受消失,二选一写进附B,不许沉默)。
- [ ] **Step 1: 写失败的测试(这条测试的价值全在"麦象行不许消失")**
```java
@Test
@DisplayName("选了公司:客户端行按成员集筛,麦象行照常出现(uid 恒 NULL,叠等值就整类消失)")
void maixiangRowsSurviveCompanyFilter() {
when(mapper.selectCount(any())).thenReturn(1L);
when(mapper.selectList(any())).thenReturn(List.of(row(1024L, 2)));
service().page(null, null, null, null, 1L, 20L, List.of(11L, 12L));
AbstractWrapper, ?, ?> q = capturedCount();
assertThat(q.getSqlSegment())
.as("必须是 (source = ? OR uid IN (...)) 一整组,括号丢了就等于把麦象筛掉")
.contains(" OR ").contains("IN (");
// 值落在 paramNameValuePairs 里,不在 getSqlSegment() 里——别写成 segment.contains("maixiang"),
// MP 渲染的是 #{ew.paramNameValuePairs.MPGENVAL1},那条断言恒假。
assertThat(q.getParamNameValuePairs().values()).contains("maixiang", 11L, 12L);
}
@Test
@DisplayName("成员集为空:退化成只看麦象,不许渲染 IN () 打炸 SQL")
void emptyMemberSetFallsBackToMaixiangOnly() {
when(mapper.selectCount(any())).thenReturn(0L);
service().page(null, null, null, null, 1L, 20L, List.of());
AbstractWrapper, ?, ?> q = capturedCount();
// 只用 contains/doesNotContain:page 里还有 log_date >= ? 那条必带参数,
// 写 containsExactly(...) 会因为多一个 LocalDate 而恒红。
assertThat(q.getParamNameValuePairs().values())
.as("空集走 in() 会渲染出 IN (),MySQL 直接语法错;这里必须只看 maixiang")
.contains("maixiang")
.doesNotContain(11L);
assertThat(q.getSqlSegment()).doesNotContain("IN (");
}
@Test
@DisplayName("null = 不筛,保持今天的行为(超管没选公司时与上线前逐字一致)")
void nullMemberSetKeepsOldBehaviour() {
when(mapper.selectCount(any())).thenReturn(0L);
service().page("client", 7L, null, null, 1L, 20L, null);
AbstractWrapper, ?, ?> q = capturedCount();
assertThat(q.getSqlSegment()).doesNotContain(" OR ");
assertThat(q.getParamNameValuePairs().values()).doesNotContain("maixiang");
assertThat(q.getParamNameValuePairs().values()).contains("client", 7L);
}
@Test
@DisplayName("计数支与列表支必须同宽:total 与行集不一致就是分页错位")
void countAndListShareTheSameCondition() {
when(mapper.selectCount(any())).thenReturn(1L);
when(mapper.selectList(any())).thenReturn(List.of(row(1024L, 2)));
service().page(null, null, null, null, 1L, 20L, List.of(11L));
// 比 paramNameValuePairs 而不是 getSqlSegment():列表那支在 builder 外面又叠了
// orderByDesc(lastUploadAt)+orderByDesc(id)+last("limit o,s")(DeviceLogService.java:190-193),
// 两支的 segment 天生就不相等 ⇒ 断 isEqualTo(getSqlSegment()) 会红在排序上,而不是红在条件上。
// 条件同宽的正确锚点是"参数绑定序列逐字相同"——排序与 limit 不往 pairs 里塞值。
assertThat(capturedList().getParamNameValuePairs())
.as("total 与行集按不同条件算出来的 = 页码跳空/重复行")
.isEqualTo(capturedCount().getParamNameValuePairs());
}
```
**读法三条,都是这组用例能不能咬住实现的关键:**
1. `selectCount` **一定**被打到,`selectList` 只在 `total != 0` 时才打(`DeviceLogService.java:189-193` 的三元)。所以凡是"看生成的条件"的用例,要么把 `selectCount` 桩成 `1L` 再捕两支,要么直接捕 `selectCount` 那支——别写一个"selectCount 桩 0 然后断言 selectList 的 wrapper"的用例,它捕到的是 null,红在断言之前。
2. MP 把值放进 `paramNameValuePairs`,`getSqlSegment()` 里只有 `#{ew.paramNameValuePairs.MPGENVAL1}` 这种占位。⇒ **结构**(括号、`OR`、`IN`)从 segment 读,**值**(`"maixiang"`、`11L`)从 `getParamNameValuePairs().values()` 读。写成 `segment.contains("maixiang")` 是恒假断言(memory「字符串断言必须排他、解析断言必须可匹配」)。**同一条还有后半截:`paramNameValuePairs` 是惰性填的**——MP 3.5.7 把值装进 `() -> formatParam(null, val)` 这样的 lambda,只有 `getSqlSegment()` 被求值过一次,pairs 里才落值。所以凡断 pairs 的用例必须**先取一次 segment** 再读 pairs;反过来写(Task 12 实跑撞过)会拿到 `[]`,于是 `doesNotContain(...)` 恒真、`两支的 pairs 相等` 变成「两个空 map 相等」也恒真——尺子绿着,什么都没钉住。
3. `capturedCount()` / `capturedList()` 各用一个 `ArgumentCaptor>` 捕(本文件已 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「护栏要做进代码出口」+「字符串断言必须排他」) |
### Step 1b:执行期补的注入点(Task 8-12 评审累积,跑 Step 1 之前先落 ① 那条新守卫)
| # | 注入 | 期望 —— 以及"如果没人红"意味着什么 |
|---|---|---|
| ① | 把 controller 传给 `readScope(operator, companyId)` / `resolveScope(request, companyId)` 的**实参**从 `companyId` 改成 `null`(绑定与 `readScope(` 都还在) | **今天七支尺子全杀不掉**:G1 只看前端文件;G2 的 A/B/C 只问"`readScope(` 在不在、`@RequestParam(name = "company_id")` 字面量在不在、那个变量的值有没有被喂进某支调用"——传 `null` 三条都还满足。症状是切 tab 一动不动、接口 200、`sqlUserIds()` 交 `null`。⇒ **先给 G2 加一条 D**:`readScope(` 的单层括号实参表里必须出现从 `@RequestParam(name = "company_id")` 绑来的那个变量名(`null` 字面量不算)。加完 D 再注入 ⇒ 期望红;不注入的对照轮 ⇒ 期望绿。**这条是 8 页共用的一处形状,不是本页的事**,所以它排在变异轮前面 |
| ② | `ShopManageGroupService.list` 里两处平铺:把 `qw.and(w -> w.in(getCreatedById, companyMemberIds))` 改成 `qw.in(...)`;或把 `and(w -> eq(createdById).or(x -> eq(userId)))` 改成平铺 `.eq().or(...)` | 各红 `ShopManageGroupServiceTest.groupListWrapsTheOrBeforeNarrowing`(结构断 `getSqlSegment()`、值断 `getParamNameValuePairs()`)。这是 Task 11 评审 I-1 那支新用例的自证——**没做过这轮变异就不许声称括号被钉住了** |
| ③ | 删掉 `ShopManageController.page` 签名里的 `@RequestParam(name = "company_id")` 整条参数,但**留着** `@Operation` 描述里那句"company_id 只收窄可见集" | 期望红 `writeEntryPointsCarryNoCompanyId` 的取样自检(本轮锚点已从 `contains("company_id")` 换成 `contains("@RequestParam(name = \"company_id\"")`)。若锚点退回旧写法 ⇒ 这条注入恒绿,正是评审 I-2 说的"文案满足断言" |
| ④ | 删掉 `fetchTaskCenterOverview` / `fetchTaskCenterShopOptions` 新补的第二个实参 `{ params: query }`(把 `http.get(url, { params })` 改回 `http.get(url)`) | G1 **看不见**:它按文件文本查 `company_id = companyId`,那串还在。⇒ 本轮给 `task-center` 补一支用例断"`http.get(` 之后必须跟着带 `params` 的第二实参",否则症状是"前端发了、URL 里根本没有",而接口照样 200 |
| ⑤ | 删掉任一**新增**用例的 `@Test`(保留 `@DisplayName` 与方法体) | **没有任何尺子会红**:方法体还在、G1 的文本断言还在,只是 surefire 不再跑它 ⇒「1726 例全绿」与"那支根本没跑"同形。新增人工步骤:**本轮新建/改动的每个测试文件,`grep -c "@Test"` 必须等于 surefire 该类 `Tests run:` 的数**(Task 11 已对齐:`ShopManageServiceTest` 8=8、`ShopManageGroupServiceTest` 3=3) |
| ⑥ | 页面侧 reach:删掉某页组件里的 `watch(() => companyTab.activeId, …)`,或把 `companyTab.requestCompanyId` 换成 `companyTab.activeId` | 各红 G1 正向那支的两半(原表 G1 行只写了"从 api 文件删 `company_id`",没覆盖页面侧;这是 Task 9 评审 I-3/I-4 的账)。`activeId` 那一刀只有当 store 里 `requestCompanyId` 与 `activeId` 语义不同才会红——先确认这两者在「默认第一家、不允许全部」下是否恒等,若恒等则这条要改成注入"删掉 getter 调用" |
十二条硬规矩(以 memory「变异自证脚本的十二条硬规矩」为准,本段原文写的「八条」是旧的;第十二条对本轮尤其致命——摘要解析要锚 `failed` 这个词,`^(\d+) (failed|passed)` 那种取第一个数字的写法会把 `2 passed` 读成"抓到了")逐字执行:每轮开跑前把被注入文件**写回 pristine**(还原只认注入前读进内存的字节,**不许 `git checkout`**——这个仓库有另一个会话在并行提交,`checkout` 会把你不认识的在飞改动一起抹掉,17:0x 那三笔就是这么进来的);CRLF 锚串先对齐行尾;分母只认本轮扫描结果;变异点若落在 mock 边界外必然存活,遇到"注入后仍绿"先判是不是注入根本没被执行到。
- [ ] **Step 2: 出包与发布(顺序不可颠倒)**
```bash
# 批次 0(Task 1-4):admin-vue 先上,复验后 jar 才上
# 批次 1(Task 5-12):jar 先上两台同版,复验后 admin-vue 再上
```
逐节点复验走主机 B 的 `127.0.0.1:19080`(**不是** `0.0.0.0:18080` 轮询池);admin-vue 用整树聚合摘要核"线上==本地构建"。
⚠️ **批次 1 的 jar 会把 V145 一起带上去,这是必须显式决定的一件事**(不是默认):V145 已在 `b7873209` 提交,但线上 jar 仍是 `e42b37c1…`、Flyway 停在 144。按 memory「要不要重启是可判定的」那条算一次差分:
```bash
git diff --name-only e42b37c1..<本批次构建的commit> -- backend-java/src/main 'backend-java/src/main/resources/db' | wc -l
```
只要结果里含 `V145__brand_dedupe_company_scope.sql`,这一版 jar 一启动就会**在生产应用 V145**(两张规则库表补 `company_id` + 唯一键改每公司一套)。而二期 §13 记着"消费侧 Task 3–8 已叫停 ⇒ 跨公司串扰仍在发生"——也就是说迁移上了、消费端还没上。两个选择,**由用户定**,本计划不自决:
| 选择 | 做法 | 代价 |
|---|---|---|
| A(默认,最小半径) | 批次 1 的构建树用 `git worktree` 从"Task 12 最后一笔但不含 V145"的提交拉出来——**实际做不到**,因为 V145 在历史里更早(`b7873209` 是 `00e5df02` 的后代)。真要做只能 `git revert b7873209` 出一个临时提交 | 反悔成本高、易出错;不建议 |
| B(推荐) | 让 V145 随批次 1 一起上,但**上线前**把二期的回滚脚本 `backend-java/docs/rollback-V145-company-scope.sql` 读一遍确认它仍是可执行路径,并把 §11.2 四条 SQL 在 V145 之前先跑一次留底 | 消费侧未上线 ⇒ 串扰窗口延长到批次 2/3;V145 本身是加列+改唯一键,属前向兼容 |
> 若用户选"这次不带 V145",那批次 1 的 jar 就不能从 `master` 直接构建——**这件事必须在出包前说清并留下书面决定**,别到启动日志里看到 `Migrating schema … to version 145` 才发现。
- [ ] **Step 3: 人工实跑清单(`mvn test` 验不到生产长什么样,这批必须实跑)**
1. **非超管回归**(批次 0 的账):一个 admin 账号登录 → 侧边栏无「公司管理」→ 直接手输 URL `/admin-vue/account/companies` 被弹回首屏 → 「用户管理」正常打开且 Network 无 `/api/admin/companies`。
2. **越权实验**(G3 的真身):非超管带 `?company_id=<别家>` 请求 `/api/admin/user-secrets` → **200 + 空列表**,不是 403、不是别家数据。
3. **tab 有效性**:超管切公司,八页各切一次,行数必须变;`overview` 计数与列表行集同宽(Task 10 Step 4 那五个端点如果漏了一个,这一步会露出来)。
4. **写归属按 Task 11 Step 4 的口径实测(这条的预期与直觉相反,而且**建号与店铺两件事要分开验,别用一条验收覆盖两页**)**:
- **建号**:超管切到第 2 家 tab 建一个账号 → 查库确认新账号 `company_id` 是**1**(超管自己那家),没跟着 tab 走 —— 这是设计(`AdminUserService.resolveTargetCompanyId`,spec §6.3)。
- **店铺**:⚠️ **这页的预期完全不同**。店铺的 `created_by_id` 来自请求体(Task 11 Step 4 那条更正),所以"新建店铺的归属跟着 tab 走吗"这个问题问错了。要验的是两件事:① 负责人选超管自己 ⇒ `created_by_id=超管`、这家账号所属公司为 1;② 负责人选 `users.id=1193` ⇒ 店铺**就归第 2 家**(今天已经能做,本轮没改它)。**别把 ② 报成"tab 生效了"**,那是负责人字段生效,与 tab 无关。
- 两条都要再验一次"切 tab 不改变上述任何一条"。测完删掉测试行(只交付命令,用户执行)。
5. **凭据读出口按会话收窄**(Task 11 Step 3(d) 的账,这条 `mvn test` 验不到)。⚠️ **2026-10-05 执行时订正原预期**:原写「超管切到第 2 家 tab → 按 id 请求 ⇒ 403」,实现做出来是**另一件事**,而那一件才是 §6.1 要的。理由:`adminCredential` 若靠调用方自己带 `company_id` 才收窄,**不带参数的请求就绕过闸门**——而按 id 读明文密码的越权面,越权的人本来就不会替你把 tab 的公司 id 带上;那等于"只拦老实人"的装饰,落进 memory「护栏要做进代码出口」的反面。本仓已有的范形是 Task 8 的 `AdminImageVideoTaskController.detail/download-zip`:私有 `scopeOf(operator)` = `readScope(operator, null)` ⇒ **超管不筛(tab 不是安全边界,Constraint 2),非超管与内部令牌按其可见成员集收窄**。⇒ 这条验收改成两读:① 用一个**主管**账号(不是超管)从 Network 里取一个不属于它可见集的店铺 id 请求 `GET /api/admin/shop-manages//credential` → **403**,不是 200 + 明文密码;② 超管在**任意 tab** 下同一请求必须 **200**——若这里红了,说明闸门被写死成"非当前 tab 全禁",那是回归不是收紧。③ 顺手确认这条**没有**波及 `GET /credential?shopName=`(4.0.44 客户端与 Python 自动化走的那条,本轮刻意不动)。
6. **麦象日志不消失**(Task 12 的账):切任意公司 tab,日志管理里 `source=maixiang` 的行必须还在。⚠️ 生产只读实测(10-05,`device_log_file` 共 1028 行):`client` 831 / `maixiang` 197,**但 `client` 里有 22 行 `uid IS NULL`**(22/831=2.6%)——这 22 行按「`source='maixiang' OR uid IN (成员集)`」的形状仍会被筛掉,Task 12 要么给它一条同族的"无法归属"放行腿,要么在附B 里明写这 22 行在各 tab 下消失是设计。
7. **保存权限不炸**(Task 4 的账):给一个历史带 `admin_companies` 授权的账号保存一次权限 → 成功 + 日志 `GRANT_SUPER_ADMIN_ONLY_STRIPPED`。
8. **文案这三眼看**(§9.3 / §5 的账,`node --test` 只能验"字符串在不在",验不到"读的人怎么理解"):①超管在任意一页看到引导条那句"超级管理员可用页面上方的公司 tab 切换公司"时,tab 条**确实在它上方**(Task 7 Step 4 挂的是 `` 与 `` 之间,顺序反了这句话就指错了方向);②引导条被收起过的人看不见这句——找一个 `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)。要修它是单独一张工单。
- **不补密钥管理页那两支按 id 的写出口的归属闸门**:`POST /api/admin/user-secrets/{userId}/check` 与 `DELETE /{userId}`(`AdminUserApiSecretController:72-89`)把 `requireAdmin(request)` 的返回值直接丢掉,service 侧 `adminCheckByUser(userId)` / `adminClearByUser(userId)` 不收操作者 —— 一期就没有闸门。本轮把那页的**读**接进公司 tab 之后,它成了同一页里唯一还开着的越权写点(别家管理员可一键清空任意 userId 的密钥,`check` 还会真打 LLM 与代理配额)。补它 = 给写侧加一条会 403 的校验,属未批的行为变更 ⇒ 单独一张工单。(Task 9 评审 I-1,2026-10-05 记)
- **不重写 `listAccessibleGroupIds` / `listAccessible`**:非超管的分组可见口径不动(spec §13)。⇒ 本计划对非超管的跨公司保证,只在**真正经过 `DataReadScope` 的那几支列表**上成立,是**部分强度**(与二期 §9.4 同词)。验收时别把它说成"非超管已按公司锁死"。
- 不做"tab 值进 URL / 可分享链接带公司上下文"(spec §12 第 4 条)。
- **生产里已有 4 行归属不到任何公司,上 tab 后它们在**每一个** tab 下都不出现(代码本轮不改,只能走数据)**:
2026-10-05 16:5x 主机 A 业务库只读实查(通道 `scripts/_prod_watch.py:171 db_sections`,非零对照齐全)——
`biz_shop_manage` 共 **86** 行,其中 **2** 行的 `created_by_id` 指向已不存在的账号(id **85** 店铺「鲍丽明」→ 账号 66、
id **86**「傅旭东」→ 账号 45,两行都挂在 `group_id=2`);`biz_shop_manage_group` 共 **12** 行,其中 **2** 行
`created_by_id IS NULL`(id **2**「周丽娥」、id **3**「郭亚芳」)。可归属分解:店铺 company 1 → 84(84+2=86 逐数相符),
分组 company 1 → 9、company 2 → 1(9+1+2=12 相符);`company` 表 3 行(1 厦门米椿花 / 2 德阳-团队 / 3 先锋-团队)。
⇒ 症状是**收窄顺手做出的静默删除**,不是权限修复:这 4 行在"还没有 tab 的今天"对超管可见,上了 tab 就哪家都不出现。
**为什么不放宽闸门**:给"归属不到"的行放行等于让它在家家 tab 都可见,与 tab 的语义正相反;把闸门退回全量等于撤销本批目的。
处置只有两条,都由用户决定:① 把这 4 行的 `created_by_id` 归到在职账号名下(`UPDATE`,我只交付命令不执行);
② 接受这 4 行只存在于库里、界面上不再出现。**注意这两行的凭据仍可按 id 读到**(超管走 `superAdmin` 短路、
`/{id}/credential` 不收 tab),所以"看不见"不等于"读不到",验收时别把这两件事混报(Task 11 评审遗留项,已取证)。
- **日志管理那 22 行 `source='client'` 且 `uid IS NULL` 的匿名客户端日志:选了公司就不出现(定案 (a),代码刻意不加 `IS NULL` 那条腿)**:
2026-10-05 15:1x 主机 A 业务库只读实查 `device_log_file` 共 **1028** 行(`client` **831** / `maixiang` **197**),其中 `uid IS NULL` 的
`client` **22** 行(22/831 = 2.6%,22/1028 = 2.1%)⇒ `(source='maixiang' OR uid IN (成员集))` 这个形状会把它们抹掉。
**为什么不放行**:麦象那 197 行能进每一家 tab,前提是它是**平台自己的采集机**(基础设施,不属于任何一家);这 22 行的性质是"桌面端没登录",
它们是某家的资产、只是没有账号替它们认领。给它们加一条 `uid IS NULL` 腿 = 让同一条**无归属**行在家家 tab 各出现一次,那是错的归属,
并且把"这家有多少条日志"这个数变成不可用;而且 `uid IS NULL` 对将来任何新来源同样成立(今天钉 22 行,明天就是"凡没账号的都全局可见")。
**代价要说比例,别只说"仍拿得到全量"**:① 这 22 行**在界面上点不回来**——tab 条按 §12 第 2 条没有「全部公司」那一枚,默认落在 `id` 最小的启用公司;
② 兜底只在后端成立:`GET /api/admin/device-logs/files` 的 `company_id` 是 `required = false`,不传 ⇒ unfiltered ⇒ 一条条件都不叠
(`nullMemberSetKeepsOldBehaviour` 钉着),要看全量只能走接口、不能走这页的界面;③ 这页 9 支端点全在 `requireSuperAdmin` 之后,
**不存在超管之外的读者**,所以"消失"是过滤器效果,既不是越权面收窄、也不影响任何账号的日常使用。
若将来要让它们在界面上可见,正路不是加 SQL 腿,而是给 tab 条补一枚「全部公司」⇒ 那是 §12 第 5 条**未批**的界面暴露,要单独授权。
(Task 12 定案,2026-10-05 记;钉住这个形状的实跑用例是 `DeviceLogServiceTest.anonymousClientRowsFallOutOfEveryCompanyTabByDecision`。)
- 不碰二期的 V145 迁移文件(已在 `b7873209` 提交,本计划不改它、不替它决定上线时机——上线时机是 Task 13 Step 2 那条要用户拍板的显式决定)。