From a5a9df650b1a1d8ab34c4bdfa4930f52e01164ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Mon, 5 Oct 2026 03:03:06 +0800 Subject: [PATCH] =?UTF-8?q?feat(=E5=85=AC=E5=8F=B8=E8=8C=83=E5=9B=B4):=20D?= =?UTF-8?q?ataReadScope=20=E5=94=AF=E4=B8=80=E8=AF=BB=E8=8C=83=E5=9B=B4?= =?UTF-8?q?=E5=87=BA=E5=8F=A3=20+=20G2=20=E6=89=AB=20company=5Fid=20?= =?UTF-8?q?=E7=AB=AF=E7=82=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ReadScope/DataReadScope 落在 common/service:超管不选公司=不筛、选公司=成员集替换、 选不存在公司=空页(不 403 不全量);非超管永远锁本公司且与分组可见集求交(只能收窄), 传别家得空结果,没公司归属则炸 - G2 护栏逐文件扫"含 company_id 的 controller 必须走 readScope( 且显式 name=", 带取样非空自检;白名单点名只放先于本计划存在的 AdminUserController, 且只豁免 readScope 那一条、不豁免取样与显式 name= --- .../aiimage/common/service/DataReadScope.java | 42 ++++++++ .../aiimage/common/service/ReadScope.java | 48 +++++++++ ...ompanyIdParamGoesThroughReadScopeTest.java | 84 ++++++++++++++++ .../common/service/DataReadScopeTest.java | 99 +++++++++++++++++++ 4 files changed, 273 insertions(+) create mode 100644 backend-java/src/main/java/com/nanri/aiimage/common/service/DataReadScope.java create mode 100644 backend-java/src/main/java/com/nanri/aiimage/common/service/ReadScope.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/common/service/DataReadScopeTest.java diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/service/DataReadScope.java b/backend-java/src/main/java/com/nanri/aiimage/common/service/DataReadScope.java new file mode 100644 index 000000000..36e26da22 --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/common/service/DataReadScope.java @@ -0,0 +1,42 @@ +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)); + } +} diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/service/ReadScope.java b/backend-java/src/main/java/com/nanri/aiimage/common/service/ReadScope.java new file mode 100644 index 000000000..ff673fb19 --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/common/service/ReadScope.java @@ -0,0 +1,48 @@ +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; + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java new file mode 100644 index 000000000..c44ae9378 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java @@ -0,0 +1,84 @@ +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.Set; +import java.util.stream.Collectors; +import java.util.stream.Stream; +import org.junit.jupiter.api.Test; + +/** + * G2(spec §10):每个收 company_id 的 controller 必须走 readScope。 + * 漏一处 = 那一页的 tab 是假的,而且不报错。 + * + *

扫描对象是 controller 层,与计划的定案一致:有的页(如 {@code ShopManageService.page})手上只有 + * {@code operatorId} + 一个布尔、没有操作者实体,所以 {@code readScope(AdminUserEntity, Long)} 只能由 + * controller 调,再把算好的成员集当参数传进去(docs/plans/19-company-tab.md「Task 11 已确认现状」第 2 条)。 + * 因此"controller 里出现 readScope("就是这一页接了唯一出口的证据。

+ */ +class CompanyIdParamGoesThroughReadScopeTest { + + /** + * 点名白名单(精确到文件名,不许通配/前缀)。 + * + *

只放一条:{@code AdminUserController} 的 {@code GET /api/admin/users?company_id=} 是先于本计划 + * 存在、已在生产的那"第二个 if"——用户管理页不在本计划 8 个 tab 页里 + * ({@code admin-frontend-vue/src/config/company-scope.ts} 的 {@code COMPANY_SCOPED_PAGES} 无 + * {@code admin_users}),而它的实现({@code AdminUserService} 里"筛别家 = 空页、故意不报错也不越权") + * 正是全局约束 2 点名的参考形状。本批次不迁它:迁了等于把 140 值的 {@code id IN(...)} 换回 + * {@code company_id =} 直查,性能方向是负的;已另记为批次 1 之后独立一笔。

+ * + *

豁免只作用于第一条断言(必须含 {@code readScope(})。不作用于取样——今天非白名单的 + * 含 company_id controller 恰好 0 支,把白名单文件从取样列表里剔掉再自检非空,那条自检当场就红 + * (全局约束 15 要的正是这条自检,不能绕过)。也不豁免第二条:白名单内的文件仍然必须显式 + * {@code @RequestParam(name = "company_id")},驼峰参数名静默失效那一类错不能被白名单盖住。

+ */ + private static final Set READ_SCOPE_ALLOWLIST = Set.of("AdminUserController.java"); + + @Test + void everyCompanyIdEndpointGoesThroughReadScope() throws IOException { + assertThat(READ_SCOPE_ALLOWLIST) + .as("白名单只允许 AdminUserController 一条:多一条 = 有人新开了一个不走唯一出口的 if") + .hasSize(1); + 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); + if (!READ_SCOPE_ALLOWLIST.contains(controller.getFileName().toString())) { + 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); + } + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/service/DataReadScopeTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/service/DataReadScopeTest.java new file mode 100644 index 000000000..9be60c4eb --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/service/DataReadScopeTest.java @@ -0,0 +1,99 @@ +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 dataReadScope; + + 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()); + dataReadScope = 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, "当前账号没有所属公司")); + // brief 里这行外面还套了一层 assertThat(...):assertThat 拿到的是 AssertJ 的断言对象本身 + // 而不是异常,恒定红("but was instance of: org.assertj.core.api.ThrowableAssert")。 + // assertThatThrownBy 已返回可链式断言的对象,直接用即可——断言方向与消息不变。 + org.assertj.core.api.Assertions.assertThatThrownBy( + () -> dataReadScope.readScope(user(5L, "admin", null), null)) + .isInstanceOf(com.nanri.aiimage.common.exception.BusinessException.class); + } +}