test(公司范围): 补齐内层求交与 >0 看守,G2 扫描降到 handler 粒度

评审 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
This commit is contained in:
2026-10-05 04:05:46 +08:00
parent a5a9df650b
commit 95c7b2d15e
3 changed files with 235 additions and 41 deletions
@@ -37,7 +37,14 @@ public final class ReadScope {
return userIds;
}
/** 空集 = 调用方应当直接返回空页(各页服务本来就有这条分支,照它写)。 */
/**
* 空集 = 调用方应当直接返回空页(各页服务本来就有这条分支,照它写)。
*
* <p><b>返回的列表不得由调用方修改</b>:三条分支给出的是三种所有权——{@code base == null} 时是
* 本对象内部的不可变集({@code add(...)} 直接抛 {@code UnsupportedOperationException})、
* {@code unfiltered} 时是调用方传进来的 {@code base} 引用本身(改它就是改调用方自己的列表)、
* 两边都有值时才是新建的列表。当只读值用,要改请自己 {@code new ArrayList<>(...)} 复制。</p>
*/
public List<Long> userIdsOr(List<Long> base) {
if (unfiltered) return base;
if (base == null) return userIds;
@@ -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 是假的,而且不报错。
*
* <p>扫描对象是 controller 层,与计划的定案一致:有的页(如 {@code ShopManageService.page})手上只有
* {@code operatorId} + 一个布尔、没有操作者实体,所以 {@code readScope(AdminUserEntity, Long)} 只能由
* controller 调,再把算好的成员集当参数传进去(docs/plans/19-company-tab.md「Task 11 已确认现状」第 2 条)。
* 因此"controller 里出现 readScope("就是这一页接了唯一出口的证据。</p>
* <p>扫描对象是 controller 层,与计划的定案一致:有的页(如 {@code ShopManageService.page})手上只有
* {@code operatorId} + 一个布尔、没有操作者实体,所以 {@code readScope(AdminUserEntity, Long)} 只能由
* controller 调,再把算好的成员集当参数传进去(docs/plans/19-company-tab.md「Task 11 已确认现状」第 2 条)。
* 因此"handler 体内出现 readScope("就是这一页接了唯一出口的证据。</p>
*
* <p>三条口径都是评审实测出的洞,逐条钉住:</p>
* <ol>
* <li><b>断言只打在可执行行上</b>。原先全文比对时,把 {@code readScope(} 与 {@code name = "company_id"}
* 只写进 javadoc、参数实际用驼峰 {@code Long companyId} 的 controller 照样绿(评审 I-4a:
* "接口 200、tab 切了不筛"这个它自己注释里称作"全批次唯一错了也不红的形状"原样过关)。
* 过滤器沿用仓内既有口径({@code CompanyReadPathMenuGateTest:69-75}),并自带"注释确被剔掉、
* 滤完不空"的自检——没有那条自检,过滤器一旦失配就是"扫不到东西而恒绿"。</li>
* <li><b>断言粒度是 handler,不是文件</b>。本计划让 controller 层调 {@code readScope(},
* "一个文件多个 handler 只接一个"因此是默认形状,而 Task 8 明写 {@code detail}/{@code download-zip}
* 也要补(评审 I-4b:文件级比对下 list() 没收、detail() 收了 ⇒ 整文件仍绿)。
* 所以按 mapping 注解把文件切成 handler 块,逐块跑两条断言;切不进 handler 的残块
* (package/import/类级注解/字段)由一条<b>显式</b>断言看守,不许静默跳过。</li>
* <li><b>白名单键是相对 src/main/java 的路径</b>,不再是裸文件名。按裸文件名时任意包下的同名文件
* 自动豁免(评审 I-5:{@code modules/tmpmutation/AdminUserController.java} 收 company_id、
* 不走出口 ⇒ 绿)。另加 liveness:白名单每一项必须仍在取样集里,否则就是僵尸条目。</li>
* </ol>
*
* <p>取样键(第 4 条修的是 Important 5):可执行行里出现 {@code company_id},<b>或</b>同一行同时出现
* {@code @RequestParam} 与驼峰 {@code companyId}。只按下划线字面量取样时,一支纯驼峰的端点根本进不了
* 样本,整条护栏被绕过。今天加了驼峰形状后新样本为 0 支(只有 {@code AdminUserController:43} 命中,
* 已在白名单),零假阳性,白名单不必重写。</p>
*/
class CompanyIdParamGoesThroughReadScopeTest {
private static final Path MAIN_ROOT = Path.of("src/main/java");
/**
* 点名白名单(精确到文件名,不许通配/前缀)。
* 点名白名单(<b>相对 {@code src/main/java} 的路径</b>、统一正斜杠,精确匹配,不许通配/前缀/裸文件名;
* 今天唯一一项是 {@code com/nanri/aiimage/modules/admin/controller/AdminUserController.java})。
*
* <p>只放一条:{@code AdminUserController} 的 {@code GET /api/admin/users?company_id=} 是<b>先于本计划
* <p>只放一条:{@code AdminUserController} 的 {@code GET /api/admin/users?company_id=} 是<b>先于本计划
* 存在、已在生产</b>的那"第二个 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 之后独立一笔。</p>
* 正是全局约束 2 点名的参考形状。本批次不迁它:迁了等于把 140 值的 {@code id IN(...)} 换回
* {@code company_id =} 直查,性能方向是负的;已另记为批次 1 之后独立一笔。</p>
*
* <p>豁免只作用于第一条断言(必须含 {@code readScope(})。<b>不作用于取样</b>——今天非白名单的
* 含 company_id controller 恰好 0 支,把白名单文件从取样列表里剔掉再自检非空,那条自检当场就红
* (全局约束 15 要的正是这条自检,不能绕过)。也<b>不豁免</b>第二条:白名单内的文件仍然必须显式
* {@code @RequestParam(name = "company_id")},驼峰参数名静默失效那一类错不能被白名单盖住。</p>
* <p>豁免语义(评审 Important 4 定稿):只豁免<b>该文件各 handler 的 {@code readScope(} 断言</b>,
* 不豁免取样(剔掉白名单再自检非空会当场红,全局约束 15 要的就是这条),也不豁免
* {@code name = "company_id"}——驼峰参数名静默失效那一类错不能被白名单盖住。</p>
*/
private static final Set<String> READ_SCOPE_ALLOWLIST = Set.of("AdminUserController.java");
private static final Set<String> 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<String> 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<Path> controllers;
try (Stream<Path> 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<Path> sampled = sampledControllers();
assertThat(sampled)
.as("取样集非空自检:一条都没扫到说明扫描失效,护栏等于没写")
.isNotEmpty();
for (Path controller : sampled) {
String rel = relativeKey(controller);
List<String> 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<String> 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<String> sampledKeys = sampledControllers().stream()
.map(CompanyIdParamGoesThroughReadScopeTest::relativeKey)
.collect(Collectors.toSet());
assertThat(sampledKeys)
.as("白名单里的文件已经不含 company_id/companyId 端点了,请把这条豁免一起删掉")
.containsAll(READ_SCOPE_ALLOWLIST);
}
/** 取样=可执行行里出现下划线字面量,或同一行的 @RequestParam 用了驼峰 companyId。 */
private static List<Path> sampledControllers() throws IOException {
if (!Files.isDirectory(MAIN_ROOT)) fail("找不到 " + MAIN_ROOT + " —— 用例依赖以 backend-java 为工作目录");
try (Stream<Path> 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<String> ex) {
List<Integer> 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<Block> 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<String> 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<Block> handlers, List<String> residual) {
}
/** 剔空行、行注释、块注释起始行与以星号打头的注释续行;口径同 CompanyReadPathMenuGateTest:69-75。 */
private static List<String> 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) {
@@ -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