From 95c7b2d15e34b9a798718ecdb06eb2a31d291cd7 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 04:05:46 +0800 Subject: [PATCH] =?UTF-8?q?test(=E5=85=AC=E5=8F=B8=E8=8C=83=E5=9B=B4):=20?= =?UTF-8?q?=E8=A1=A5=E9=BD=90=E5=86=85=E5=B1=82=E6=B1=82=E4=BA=A4=E4=B8=8E?= =?UTF-8?q?=20>0=20=E7=9C=8B=E5=AE=88,G2=20=E6=89=AB=E6=8F=8F=E9=99=8D?= =?UTF-8?q?=E5=88=B0=20handler=20=E7=B2=92=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 评审 5 条 Important + 3 条 Minor 的修复,生产语义一字未改(ReadScope.java 只加一句 javadoc): - adminIsAlwaysPinnedToOwnCompany 补 userIdsOr(null),看守 DataReadScope:40 的内层求交 (删掉内层求交时原用例 6/0/0 全绿,组长范围会被放大成整公司) - 新增 zeroCompanyIdIsNormalizedToNoFilter:>0 归一化支此前无人喂 - G2 断言改打在可执行行上(注释里写 readScope( 不算),沿用 CompanyReadPathMenuGateTest 口径 并自带"注释确被剔掉、滤完不空"自检 - G2 断言粒度从文件降到 handler(按 mapping 注解切块),一文件多 handler 只接一个不再蒙混; 切不进 handler 的残块显式判红,不静默跳过 - 白名单键改为相对 src/main/java 的路径(同名不同包不再自动豁免)+ 加 liveness 断言 - 取样键加"@RequestParam 与 companyId 同行"的驼峰形状(今天新样本 0 支,零假阳性) - 删掉 DataReadScopeTest 未使用的 static import eq --- .../aiimage/common/service/ReadScope.java | 9 +- ...ompanyIdParamGoesThroughReadScopeTest.java | 250 +++++++++++++++--- .../common/service/DataReadScopeTest.java | 17 +- 3 files changed, 235 insertions(+), 41 deletions(-) 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 index ff673fb19..3280330f0 100644 --- 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 @@ -37,7 +37,14 @@ public final class ReadScope { return userIds; } - /** 空集 = 调用方应当直接返回空页(各页服务本来就有这条分支,照它写)。 */ + /** + * 空集 = 调用方应当直接返回空页(各页服务本来就有这条分支,照它写)。 + * + *

返回的列表不得由调用方修改:三条分支给出的是三种所有权——{@code base == null} 时是 + * 本对象内部的不可变集({@code add(...)} 直接抛 {@code UnsupportedOperationException})、 + * {@code unfiltered} 时是调用方传进来的 {@code base} 引用本身(改它就是改调用方自己的列表)、 + * 两边都有值时才是新建的列表。当只读值用,要改请自己 {@code new ArrayList<>(...)} 复制。

+ */ public List userIdsOr(List base) { if (unfiltered) return base; if (base == null) return userIds; 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 index c44ae9378..3b7f5b613 100644 --- 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 @@ -6,72 +6,244 @@ import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Arrays; import java.util.List; import java.util.Set; +import java.util.regex.Pattern; import java.util.stream.Collectors; import java.util.stream.Stream; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; /** - * G2(spec §10):每个收 company_id 的 controller 必须走 readScope。 - * 漏一处 = 那一页的 tab 是假的,而且不报错。 + * G2(spec §10、全局约束 4):每个**收公司 id 参数的 handler** 必须走 readScope,参数还必须显式写 + * {@code name = "company_id"}。漏一处 = 那一页的 tab 是假的,而且不报错。 * - *

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

+ *

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

+ * + *

三条口径都是评审实测出的洞,逐条钉住:

+ *
    + *
  1. 断言只打在可执行行上。原先全文比对时,把 {@code readScope(} 与 {@code name = "company_id"} + * 只写进 javadoc、参数实际用驼峰 {@code Long companyId} 的 controller 照样绿(评审 I-4a: + * "接口 200、tab 切了不筛"这个它自己注释里称作"全批次唯一错了也不红的形状"原样过关)。 + * 过滤器沿用仓内既有口径({@code CompanyReadPathMenuGateTest:69-75}),并自带"注释确被剔掉、 + * 滤完不空"的自检——没有那条自检,过滤器一旦失配就是"扫不到东西而恒绿"。
  2. + *
  3. 断言粒度是 handler,不是文件。本计划让 controller 层调 {@code readScope(}, + * "一个文件多个 handler 只接一个"因此是默认形状,而 Task 8 明写 {@code detail}/{@code download-zip} + * 也要补(评审 I-4b:文件级比对下 list() 没收、detail() 收了 ⇒ 整文件仍绿)。 + * 所以按 mapping 注解把文件切成 handler 块,逐块跑两条断言;切不进 handler 的残块 + * (package/import/类级注解/字段)由一条显式断言看守,不许静默跳过。
  4. + *
  5. 白名单键是相对 src/main/java 的路径,不再是裸文件名。按裸文件名时任意包下的同名文件 + * 自动豁免(评审 I-5:{@code modules/tmpmutation/AdminUserController.java} 收 company_id、 + * 不走出口 ⇒ 绿)。另加 liveness:白名单每一项必须仍在取样集里,否则就是僵尸条目。
  6. + *
+ * + *

取样键(第 4 条修的是 Important 5):可执行行里出现 {@code company_id},或同一行同时出现 + * {@code @RequestParam} 与驼峰 {@code companyId}。只按下划线字面量取样时,一支纯驼峰的端点根本进不了 + * 样本,整条护栏被绕过。今天加了驼峰形状后新样本为 0 支(只有 {@code AdminUserController:43} 命中, + * 已在白名单),零假阳性,白名单不必重写。

*/ class CompanyIdParamGoesThroughReadScopeTest { + private static final Path MAIN_ROOT = Path.of("src/main/java"); + /** - * 点名白名单(精确到文件名,不许通配/前缀)。 + * 点名白名单(相对 {@code src/main/java} 的路径、统一正斜杠,精确匹配,不许通配/前缀/裸文件名; + * 今天唯一一项是 {@code com/nanri/aiimage/modules/admin/controller/AdminUserController.java})。 * - *

只放一条:{@code AdminUserController} 的 {@code GET /api/admin/users?company_id=} 是先于本计划 + *

只放一条:{@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 之后独立一笔。

+ * 正是全局约束 2 点名的参考形状。本批次不迁它:迁了等于把 140 值的 {@code id IN(...)} 换回 + * {@code company_id =} 直查,性能方向是负的;已另记为批次 1 之后独立一笔。

* - *

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

+ *

豁免语义(评审 Important 4 定稿):只豁免该文件各 handler 的 {@code readScope(} 断言, + * 不豁免取样(剔掉白名单再自检非空会当场红,全局约束 15 要的就是这条),也不豁免 + * {@code name = "company_id"}——驼峰参数名静默失效那一类错不能被白名单盖住。

*/ - private static final Set READ_SCOPE_ALLOWLIST = Set.of("AdminUserController.java"); + private static final Set READ_SCOPE_ALLOWLIST = + Set.of("com/nanri/aiimage/modules/admin/controller/AdminUserController.java"); + + private static final String READ_SCOPE_CALL = "readScope("; + private static final String EXPLICIT_PARAM_NAME = "name = \"company_id\""; + private static final String SNAKE_PARAM = "company_id"; + private static final String CAMEL_PARAM = "companyId"; + private static final String REQUEST_PARAM = "@RequestParam"; + + /** handler 的边界:这些注解组后面跟方法签名的是端点,跟类型声明的是类级。 */ + private static final List MAPPING_ANNOTATIONS = List.of( + "@GetMapping", "@PostMapping", "@PutMapping", "@DeleteMapping", "@PatchMapping", "@RequestMapping"); + + private static final Pattern TYPE_DECL = Pattern.compile("\\b(class|interface|enum)\\s+\\w"); + + /** 过滤器自检样本:两个关键符号只写在注释里,代码行是驼峰参数。 */ + private static final String COMMENT_FILTER_PROBE = """ + /** + * 文档说这页走了 readScope(,参数写成 @RequestParam(name = "company_id")。 + */ + // @RequestParam(name = "company_id", required = false) Long companyId + @GetMapping("/users") + public String list(@RequestParam(required = false) Long companyId) { + return "list=" + companyId; + } + """; @Test - void everyCompanyIdEndpointGoesThroughReadScope() throws IOException { + @DisplayName("每个收公司 id 参数的 handler 都走唯一出口,并且显式写了 name = \"company_id\"") + void everyCompanyIdHandlerGoesThroughReadScope() throws IOException { assertThat(READ_SCOPE_ALLOWLIST) - .as("白名单只允许 AdminUserController 一条:多一条 = 有人新开了一个不走唯一出口的 if") + .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) + + // 口径 1 的自检(全局约束 15):过滤器必须"注释被剔掉、代码行留下"。 + // 滤空或注释漏网 ⇒ 后面每条文本断言都恒绿,护栏等于没写。 + assertThat(executableLines(COMMENT_FILTER_PROBE)) + .as("executableLines 自检:注释行必须被剔除、代码行必须留下,否则整条护栏扫不到东西而恒绿") + .containsExactly( + "@GetMapping(\"/users\")", + "public String list(@RequestParam(required = false) Long companyId) {", + "return \"list=\" + companyId;", + "}"); + + List sampled = sampledControllers(); + assertThat(sampled) + .as("取样集非空自检:一条都没扫到说明扫描失效,护栏等于没写") + .isNotEmpty(); + + for (Path controller : sampled) { + String rel = relativeKey(controller); + List lines = executableLines(read(controller)); + assertThat(lines).as(rel + " 的可执行行为空:整份文件只剩注释,扫描无从判定").isNotEmpty(); + + Blocks blocks = splitBlocks(lines); + for (Block handler : blocks.handlers()) { + String where = rel + " 的 handler " + handler.header(); + // 断言 A:收了公司 id 参数的 handler 必须在该 handler 体内走唯一出口。 + if (handler.takesCompanyParam() && !READ_SCOPE_ALLOWLIST.contains(rel)) { + assertThat(handler.text()) + .as(where + " 收了公司 id 参数,但该 handler 体内没有出现 readScope( —— 文件里别处接了不算") + .contains(READ_SCOPE_CALL); + } + // 断言 B:块里出现 company_id 就必须写显式 name=(白名单不豁免这条)。 + if (handler.text().contains(SNAKE_PARAM)) { + assertThat(handler.text()) + .as(where + " 的 company_id 没写显式 name=,会和驼峰参数名混成两种拼写") + .contains(EXPLICIT_PARAM_NAME); + } + } + + // 残块(package/import/类级注解/字段)显式看守:公司 id 形状落在 handler 之外说明切块形状失效, + // 静默跳过 = 又一处惰护栏,所以这里必须红并交人工核对。 + List unattributed = blocks.residual().stream() + .filter(CompanyIdParamGoesThroughReadScopeTest::isCompanyShapeLine) + .collect(Collectors.toList()); + assertThat(unattributed) + .as(rel + " 的公司 id 形状落在 handler 之外(切块没覆盖到,可能是类级注解或字段)—— 必须显式核对,不许静默跳过") + .isEmpty(); + } + } + + @Test + @DisplayName("白名单每一项都仍在取样集里:条目一旦不再含公司 id 形状就红(防僵尸豁免)") + void allowlistEntriesAreStillSampled() throws IOException { + Set sampledKeys = sampledControllers().stream() + .map(CompanyIdParamGoesThroughReadScopeTest::relativeKey) + .collect(Collectors.toSet()); + assertThat(sampledKeys) + .as("白名单里的文件已经不含 company_id/companyId 端点了,请把这条豁免一起删掉") + .containsAll(READ_SCOPE_ALLOWLIST); + } + + /** 取样=可执行行里出现下划线字面量,或同一行的 @RequestParam 用了驼峰 companyId。 */ + private static List sampledControllers() throws IOException { + if (!Files.isDirectory(MAIN_ROOT)) fail("找不到 " + MAIN_ROOT + " —— 用例依赖以 backend-java 为工作目录"); + try (Stream walk = Files.walk(MAIN_ROOT)) { + return walk.filter(Files::isRegularFile) .filter(p -> p.getFileName().toString().endsWith("Controller.java")) - .filter(p -> read(p).contains("company_id")) + .filter(p -> executableLines(read(p)).stream() + .anyMatch(CompanyIdParamGoesThroughReadScopeTest::isCompanyShapeLine)) + .sorted() .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("); + } + + /** 断言 A 的触发条件:必须是"参数"形状(同一行有 @RequestParam),不是任意出现。 */ + private static boolean isCompanyParamLine(String line) { + return line.contains(REQUEST_PARAM) && (line.contains(SNAKE_PARAM) || line.contains(CAMEL_PARAM)); + } + + /** 取样与残块的触发条件。 */ + private static boolean isCompanyShapeLine(String line) { + return line.contains(SNAKE_PARAM) || (line.contains(REQUEST_PARAM) && line.contains(CAMEL_PARAM)); + } + + /** + * 按 mapping 注解切 handler 块:连续的注解行(含至少一个 mapping 注解)后面紧跟的不是类型声明, + * 就是一个端点;块尾=下一个端点的注解组首行(最后一个块到文件尾)。 + * 第一个端点之前的所有行(package/import/类级注解/字段)是残块,交给上面那条显式断言。 + */ + private static Blocks splitBlocks(List ex) { + List starts = new ArrayList<>(); + int i = 0; + while (i < ex.size()) { + if (!ex.get(i).startsWith("@")) { + i++; + continue; } - // 第二条:参数必须**显式**写 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\""); + int runEnd = i; + while (runEnd + 1 < ex.size() && ex.get(runEnd + 1).startsWith("@")) runEnd++; + boolean mappingRun = ex.subList(i, runEnd + 1).stream() + .anyMatch(line -> MAPPING_ANNOTATIONS.stream().anyMatch(line::startsWith)); + String signature = runEnd + 1 < ex.size() ? ex.get(runEnd + 1) : ""; + if (mappingRun && !signature.isEmpty() && !TYPE_DECL.matcher(signature).find()) { + starts.add(i); + } + i = runEnd + 1; } + List handlers = new ArrayList<>(); + for (int k = 0; k < starts.size(); k++) { + int from = starts.get(k); + int to = k + 1 < starts.size() ? starts.get(k + 1) : ex.size(); + handlers.add(new Block(ex.subList(from, to))); + } + int first = starts.isEmpty() ? ex.size() : starts.get(0); + return new Blocks(handlers, new ArrayList<>(ex.subList(0, first))); + } + + private record Block(List lines) { + String header() { + return lines.get(0); + } + + String text() { + return String.join("\n", lines); + } + + boolean takesCompanyParam() { + return lines.stream().anyMatch(CompanyIdParamGoesThroughReadScopeTest::isCompanyParamLine); + } + } + + private record Blocks(List handlers, List residual) { + } + + /** 剔空行、行注释、块注释起始行与以星号打头的注释续行;口径同 CompanyReadPathMenuGateTest:69-75。 */ + private static List executableLines(String text) { + return Arrays.stream(text.split("\n", -1)) + .map(String::trim) + .filter(line -> !line.isEmpty()) + .filter(line -> !line.startsWith("//") && !line.startsWith("/*") && !line.startsWith("*")) + .collect(Collectors.toList()); + } + + /** 白名单键:相对 src/main/java、统一正斜杠,与取样路径同源,避免平台分隔符造成静默不匹配。 */ + private static String relativeKey(Path controller) { + return MAIN_ROOT.relativize(controller).toString().replace('\\', '/'); } private static String read(Path path) { 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 index 9be60c4eb..557a9f125 100644 --- 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 @@ -2,7 +2,6 @@ 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; @@ -63,6 +62,17 @@ class DataReadScopeTest { assertThat(scope.userIdsOr(List.of(9L))).isEmpty(); } + @Test + @DisplayName("company_id=0 = 归一化成「没选公司」,超管照旧不筛,不是去查 0 号公司") + void zeroCompanyIdIsNormalizedToNoFilter() { + // DataReadScope:27 的 `requestedCompanyId > 0` 此前只有 null/2/99/7 喂过,归一化支无人看守。 + // 删掉 `> 0` ⇒ ?company_id=0 不再被折成"没选公司",而是去查 0 号公司的成员集: + // 超管那一页从"照旧不筛"变成"空页",方向错(与 §4"不传就保持今天的不筛行为"同一条口径)。 + ReadScope scope = dataReadScope.readScope(user(1L, "super_admin", 1L), 0L); + assertThat(scope.isUnfiltered()).isTrue(); + assertThat(scope.userIdsOr(null)).isNull(); + } + @Test @DisplayName("非超管永远锁本公司,不传也一样") void adminIsAlwaysPinnedToOwnCompany() { @@ -73,6 +83,11 @@ class DataReadScopeTest { ReadScope scope = dataReadScope.readScope(user(5L, "admin", 2L), null); // 与既有的分组可见集**求交**,不是替换:非超管的组长范围不能被公司 tab 放大。 assertThat(scope.userIdsOr(userDataScope.resolveVisibleUserIds(5L))).containsExactly(21L); + // 上面那行把同一个 resolveVisibleUserIds(5L) 既当桩又喂回 userIdsOr,两次求交幂等, + // 看守不到 DataReadScope:40 的**内层**那一刀(公司集 ∩ 组集)。userIdsOr(null) 才把 scope + // 自身摊开:内层求交一旦被删,这里是 [21, 22](整公司),而 Task 8-12 里以 base=null 消费的页 + // 就从"公司∩组"放大成"整公司"——正是计划明令禁止的放大方向。 + assertThat(scope.userIdsOr(null)).containsExactly(21L); } @Test