feat(护栏三面): 鉴权盲区启动自检 + SQL 分层口径落码 + 六页等待循环合一

后端
- AdminApiGuardFilter 增 guardedPrefixes()/matchesPrefix() 公开入口(原 private,
  自检抄一份清单迟早与守卫脱钩);行为零变化
- 新增 ApiGuardCoverageAuditor:启动期把"已映射端点既不在守卫前缀名单、也不在
  公开/待收清单里"打成 API_GUARD_UNCOVERED 一行 WARN,供现网巡检 grep;
  PUBLIC_BY_DESIGN 与 PENDING_CONVERGENCE 两张清单逐条写理由(只读不拦)
- SQL 分层按新口径落码:AsinResultCacheMapper 的两条动态 SQL(<foreach> 批量 +
  ON DUPLICATE KEY UPDATE + 逐列 COALESCE)迁到 resources/mapper/asincache/,
  注解摘干净(注解+XML 同名会让启动期抛重复语句)
- 判据:SqlLayeringConventionTest(注解写 SQL 基线 16 接口/29 条只减不增、
  @Select 65 条/16 文件、wrapper 夹带函数级 SQL 4 文件/15 条,last("LIMIT n")
  205 处显式豁免并反向钉住豁免面)、ApiGuardCoverageAuditorTest(含清单腐烂与
  欠账/名单重叠两类反向失明)、AsinResultCacheMapperXmlTest(真解析 XML 向
  BoundSql 断言 28 个占位符与 5 个 COALESCE 列)

用户端 frontend-vue
- 终态集合合一:实测六页里 PriceTrack/ProductRisk 只认 SUCCESS|FAILED,
  而 COMPLETED≡SUCCESS 早有出处(task-status-text 两者都译「已完成」,
  后端 TaskCenterQueryMapper SUCCESS_STATUSES_ORDERED 也含 COMPLETED)
  ⇒ 窄集合页收到 COMPLETED 会空转到瞬断预算耗尽,PriceTrack 的轮询摘除路径
  同样窄 ⇒ 任务永不退出轮询、列表卡在"执行中"
- 新增 shared/utils/task-terminal.ts 循环骨架(disposed/瞬断预算/恢复提示/
  每轮 sleep/非瞬断上抛),六页全部接上;取数、文案、快照合并、DELETED 语义
  留在各页回调,没有顺手统一
- 判据两支:骨架 8 例契约 + 六页源码窄集合回归钉(含"判据自己先自证"一例,
  loop-run 的 STOPPED 词表不误报)
This commit is contained in:
2026-10-08 09:20:41 +08:00
parent 5b310986bb
commit 207225eb86
16 changed files with 1418 additions and 216 deletions
@@ -0,0 +1,177 @@
package com.nanri.aiimage.config;
import org.junit.jupiter.api.Test;
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.List;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* {@link ApiGuardCoverageAuditor} 的守卫守卫。
*
* <p>自检本身有两个会静默失效的地方,这里逐个钉住:
* <ol>
* <li>清单腐烂——PUBLIC_BY_DESIGN / PENDING_CONVERGENCE 里的前缀对应的控制器早就没了,
* 条目却还"掩护"着以后随便挂上来的同名前缀端点;</li>
* <li>名单抄歪——守卫实际用的前缀数组(USER_TOOL_PREFIXES 等)与自检看到的必须是同一份,
* 少一条就会把"其实被看守"的端点报成欠账,多一条就会把没人看守的报成 covered。</li>
* </ol>
*/
class ApiGuardCoverageAuditorTest {
@Test
void classifiesEachOfTheFourBuckets() {
ApiGuardCoverageAuditor.Report report = ApiGuardCoverageAuditor.audit(List.of(
"/api/admin/users", // 名单内,无条件
"/api/notifications/summary", // 自助前缀,无条件
"/api/collect-data/pull", // 用户态前缀(在开关后面,但仍算"在名单里")
"/login", // 设计公开
"/api/dedupe/runs", // 待收欠账
"/api/brand-check-tasks/1")); // 谁都不沾
assertEquals(3, report.covered(), "守卫名单内应有 3 条:admin / 自助 / 用户态");
assertEquals(List.of("/login"), report.publicPaths());
assertEquals(List.of("/api/dedupe/runs"), report.pending());
assertEquals(List.of("/api/brand-check-tasks/1"), report.uncovered(),
"新端点必须落进 uncovered,否则这条护栏就是装饰");
}
@Test
void alertAnchorIsEmittedOnlyWhenSomethingIsUncovered() {
assertTrue(ApiGuardCoverageAuditor.audit(List.of("/api/admin/x")).uncovered().isEmpty(),
"全 covered 时不该报警");
List<String> uncovered = ApiGuardCoverageAuditor.audit(List.of("/api/yolo")).uncovered();
assertEquals(1, uncovered.size());
assertFalse(ApiGuardCoverageAuditor.ALERT_ANCHOR.isBlank(), "锚点为空的话巡检 grep 到的是空气");
}
@Test
void guardedPrefixesCarriesEveryGuardedList() {
List<String> guarded = AdminApiGuardFilter.guardedPrefixes();
assertTrue(guarded.contains("/api/admin"), "admin 前缀没进自检可见名单");
assertTrue(guarded.contains("/debug"), "debug 前缀没进自检可见名单");
// 这两组条数是实测基线(2026-10-08:用户态 15 条、自助 6 条)。
// 只钉"contains 某条"的话,从数组里删掉一整段都可能不红,所以钉总数。
assertEquals(22, count(guarded, "/api/"), () -> "以 /api/ 开头的守卫前缀数变了(基线 22 = admin 1 + 用户态 15 + 自助 6):" + guarded);
assertEquals(23, guarded.size(), "守卫前缀总数变了(22 条 /api/ + /debug):" + guarded);
assertTrue(guarded.contains("/api/publish"), "2026-10-07 补的上架前缀不能退回名单外");
assertTrue(guarded.contains("/api/tasks"), "心跳/打断前缀不能退回名单外");
assertTrue(guarded.contains("/api/internal"), "内部端点前缀不能退回名单外");
}
@Test
void everyDeclaredPublicOrPendingPrefixIsStillLive() throws IOException {
Set<String> controllerBases = controllerBasePaths();
List<String> dead = new ArrayList<>();
for (String prefix : ApiGuardCoverageAuditor.PUBLIC_BY_DESIGN) {
if (prefix.equals("/error")) {
continue; // Spring 自带的错误页,不是控制器映射
}
if (controllerBases.stream().noneMatch(base -> base.equals(prefix) || base.startsWith(prefix + "/"))) {
dead.add(prefix);
}
}
for (String prefix : ApiGuardCoverageAuditor.PENDING_CONVERGENCE) {
if (controllerBases.stream().noneMatch(base -> base.equals(prefix) || base.startsWith(prefix + "/"))) {
dead.add(prefix);
}
}
assertTrue(dead.isEmpty(), () -> "这些清单条目已经对不上任何控制器映射,条目还在就会掩护同名新端点:" + dead);
}
@Test
void pendingListDoesNotOverlapTheGuardedList() {
List<String> overlap = ApiGuardCoverageAuditor.PENDING_CONVERGENCE.stream()
.filter(prefix -> ApiGuardCoverageAuditor.audit(List.of(prefix)).covered() > 0)
.collect(Collectors.toList());
assertTrue(overlap.isEmpty(), () -> "欠账清单与守卫名单重叠,说明这一条早已收敛却还挂在欠账里:" + overlap);
}
@Test
void publicListDoesNotOverlapTheGuardedList() {
List<String> overlap = ApiGuardCoverageAuditor.PUBLIC_BY_DESIGN.stream()
.filter(prefix -> ApiGuardCoverageAuditor.audit(List.of(prefix)).covered() > 0)
.collect(Collectors.toList());
assertTrue(overlap.isEmpty(), () -> "这些前缀已被守卫看守,登记成『设计公开』会让欠账看起来已收口:" + overlap);
}
/** 从控制器源码取映射基路径:类级 @RequestMapping 优先,没有类级的才看方法级绝对路径。 */
private static Set<String> controllerBasePaths() throws IOException {
Set<String> out = new java.util.LinkedHashSet<>();
for (Path file : controllers()) {
String text = stripComments(read(file));
List<String> bases = new ArrayList<>();
Matcher klass = Pattern.compile("@RequestMapping\\(\\s*(?:value\\s*=\\s*)?\"([^\"]+)\"").matcher(text);
while (klass.find()) {
bases.add(klass.group(1));
}
if (bases.isEmpty()) {
Matcher method = Pattern.compile(
"@(?:Get|Post|Put|Delete|Request)Mapping\\(\\s*(?:value\\s*=\\s*)?\"([/][^\"]+)").matcher(text);
while (method.find()) {
String absolute = method.group(1);
while (absolute.endsWith("/")) {
absolute = absolute.substring(0, absolute.length() - 1);
}
String[] parts = absolute.split("/"); // "/login" -> ["", "login"]
for (int depth = 1; depth <= parts.length - 1 && depth <= 3; depth++) {
bases.add("/" + String.join("/", java.util.Arrays.copyOfRange(parts, 1, 1 + depth)));
}
bases.add(absolute);
}
}
out.addAll(bases);
}
return out;
}
private static int count(List<String> values, String startsWith) {
return (int) values.stream().filter(v -> v.startsWith(startsWith)).count();
}
private static List<Path> controllers() throws IOException {
try (Stream<Path> walk = Files.walk(moduleRoot().resolve("src/main/java"))) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().contains("Controller"))
.collect(Collectors.toList());
}
}
private static String stripComments(String text) {
return text.replaceAll("/\\*\\s*\\n[\\s\\S]*?\\*/", "")
.replaceAll("/\\*.*?\\*/", "")
.replaceAll("//[^\\n]*", "");
}
private static String read(Path path) {
try {
return Files.readString(path, StandardCharsets.UTF_8);
} catch (IOException e) {
throw new IllegalStateException("读取失败: " + path, e);
}
}
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 + ")");
}
}