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,402 @@
package com.nanri.aiimage;
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.LinkedHashMap;
import java.util.List;
import java.util.Map;
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;
import static org.junit.jupiter.api.Assertions.fail;
/**
* SQL 分层约定的守卫。口径(2026-10-08 定):<b>SQL 尽量写进 mapper XML</b>,
* wrapper 只留给"简单单表"(无 join、无函数级谓词、无动态标签),注解里不再新增 SQL。
*
* <p>为什么要钉住而不是写在文档里:这个仓原来 0 个 XML、写 SQL 全在注解里,复杂语句
* ({@code <foreach>} + {@code ON DUPLICATE KEY} + 逐列 COALESCE)以 Java 文本块存在,
* 改一列要在字符串里数括号,也没有任何工具在写错时拦你。约定只存在于注释的话,
* 下一个人加 {@code @Insert} 时它就不存在了。所以这里把"当前有多少"逐个钉死:
* <ul>
* <li>新增注解 SQL ⇒ {@link #annotationSqlInventoryDoesNotGrow} 红;</li>
* <li>新增 wrapper 里夹带的函数级 SQL ⇒ {@link #rawSqlInsideWrappersDoesNotGrow} 红,
* 那正是"简单单表"的边界,越界就该进 XML;</li>
* <li>迁走一条 ⇒ 必须同时改基线常量,减法出现在 diff 上。</li>
* </ul>
*
* <p>反向失明也一并堵:XML 里的坏 SQL 没有编译期反馈,所以
* {@link #everyXmlStatementMatchesAnInterfaceMethod} 要求 XML 语句名逐字对上接口方法名——
* 对不上的表现是"启动正常、调用才报 no statement",那是线上才会撞到的面。
*/
class SqlLayeringConventionTest {
/** 写 SQL(@Insert/@Update/@Delete)在注解里的现状清单:文件名 → 条数。只许减,不许加。 */
private static final Map<String, Integer> WRITE_SQL_BASELINE = writeSqlBaseline();
/**
* 读侧注解 SQL 的总量与文件数(2026-10-08 实测 65 条 / 16 个接口)。
* 读侧按"尽量 XML"是主要待迁面,最重的是 TaskCenterQueryMapper;
* 钉总数而不是逐条清单,是因为逐条会把这份守卫变成迁移进度表——它该只做"别再加"的闸门。
*/
private static final int SELECT_ANNOTATION_TOTAL = 65;
private static final int SELECT_ANNOTATION_FILES = 16;
/**
* wrapper 里夹带函数级 SQL 的现状("这不是简单单表"的证据),文件名 → 条数:
* apply/inSql 是真谓词,last("FOR UPDATE") 是行锁。
*/
private static final Map<String, Integer> RAW_SQL_IN_WRAPPERS_BASELINE = rawSqlInWrappersBaseline();
/**
* 其中"复杂"的写 SQL(注解正文含动态标签)——Wrapper 表达不了(批量/INSERT…SELECT/upsert),
* 按约定应迁到 XML。这是待迁 backlog,不是许可名单:迁走一条要同时从这里划掉。
*/
private static final List<String> COMPLEX_WRITE_SQL_BACKLOG = List.of(
"CollectDataItemMapper", "DedupeTotalDataMapper", "InvalidAsinDataMapper",
"UserColumnPermissionMapper", "PublishItemMapper", "ShopDataCrawlItemMapper",
"QueryAsinMapper", "TaskResultItemMapper");
/** 唯一没有实体可走的 mapper:连 wrapper 的入口都没有,所以只能写裸 SQL。 */
private static final List<String> MAPPERS_WITHOUT_ENTITY = List.of("UserColumnPermissionMapper");
/** 已经迁到 XML 的:反向钉住"不许再用注解把 SQL 写回来"(注解 + XML 同名会让启动期抛重复语句)。 */
private static final List<String> MIGRATED_TO_XML = List.of("AsinResultCacheMapper");
private static final Pattern WRITE_ANNOTATION = Pattern.compile("@(Insert|Update|Delete)\\(");
private static final Pattern SELECT_ANNOTATION = Pattern.compile("@Select\\(");
private static final Pattern WRITE_ANNOTATION_BODY =
Pattern.compile("@(Insert|Update|Delete)\\(\\s*\"\"\"(.*?)\"\"\"", Pattern.DOTALL);
private static Map<String, Integer> writeSqlBaseline() {
Map<String, Integer> baseline = new LinkedHashMap<>();
baseline.put("CollectDataItemMapper", 1);
baseline.put("DedupeTotalDataMapper", 1);
baseline.put("DeviceLogFileMapper", 1);
baseline.put("ImageVideoAsyncTaskMapper", 3);
baseline.put("InvalidAsinDataMapper", 1);
baseline.put("UserNotificationMapper", 2);
baseline.put("UserColumnPermissionMapper", 4);
baseline.put("PriceTrackLoopRunMapper", 1);
baseline.put("PublishItemMapper", 1);
baseline.put("ShopDataCrawlItemMapper", 4);
baseline.put("ShopDataDuplicateScanMapper", 1);
baseline.put("QueryAsinMapper", 1);
baseline.put("SoftwareVersionMapper", 1);
baseline.put("TaskImageCacheMapper", 4);
baseline.put("TaskResultItemMapper", 1);
baseline.put("UserSecretUsageMapper", 2);
return baseline;
}
private static Map<String, Integer> rawSqlInWrappersBaseline() {
Map<String, Integer> baseline = new LinkedHashMap<>();
baseline.put("PublishTaskService", 6); // ownerInstanceId 的 JSON_EXTRACT 谓词
baseline.put("SimilarAsinTaskOwnershipSupport", 3); // 同上,state_json 维度
baseline.put("ShopDataCrawlDailyFileService", 4); // last("FOR UPDATE") 行锁
baseline.put("TaskScopePayloadStorageService", 1); // last("limit 1 FOR UPDATE") 混写
baseline.put("SimilarAsinTaskProgressSupport", 1); // inSql 子查询
return baseline;
}
@Test
void annotationSqlInventoryDoesNotGrow() throws IOException {
Map<String, Integer> actual = new LinkedHashMap<>();
int selects = 0;
List<String> selectFiles = new ArrayList<>();
for (Path file : mappers()) {
String text = stripComments(read(file));
int writes = count(WRITE_ANNOTATION, text);
if (writes > 0) {
actual.put(stem(file), writes);
}
int read = count(SELECT_ANNOTATION, text);
if (read > 0) {
selects += read;
selectFiles.add(stem(file));
}
}
assertEquals(WRITE_SQL_BASELINE, actual, () -> "注解里的写 SQL 清单变了。" + System.lineSeparator()
+ " 新增 → 写进 src/main/resources/mapper/<模块>/<Name>Mapper.xml;"
+ "简单单表才用 BaseMapper/实体(wrapper)。" + System.lineSeparator()
+ " 迁走 → 把这一项从 WRITE_SQL_BASELINE 里减掉,让减法出现在 diff 上。");
assertFalse(actual.isEmpty(), "清单为空说明本用例没扫到任何 mapper,判据本身坏了");
assertEquals(SELECT_ANNOTATION_TOTAL, selects,
() -> "注解里的 @Select 总数变了(读侧同样按 XML 优先)。迁一条就减一:" + selectFiles);
assertEquals(SELECT_ANNOTATION_FILES, selectFiles.size(),
"带注解 @Select 的接口个数变了:" + selectFiles);
}
/**
* wrapper 只该出现在"简单单表"上。函数级谓词(JSON_EXTRACT)、行锁(FOR UPDATE)、
* 子查询(inSql)都说明这条查询已经越过那条线——按口径应进 XML。
*
* <p>{@code last("LIMIT n")} 故意不算越界:MP 的分页 idiomatic 写法就是它,
* 全仓 205 处,把它算成违规只会让守卫第一天就没人管。豁免面由
* {@link #limitExemptionDoesNotHideRealSql} 反向钉住。
*/
@Test
void rawSqlInsideWrappersDoesNotGrow() throws IOException {
Map<String, Integer> actual = new LinkedHashMap<>();
for (Path file : mainSources()) {
int hits = countRawSqlInWrapper(stripComments(read(file)));
if (hits > 0) {
actual.put(stem(file), hits);
}
}
assertEquals(RAW_SQL_IN_WRAPPERS_BASELINE, actual, () -> "wrapper 里夹带的函数级 SQL 变了。"
+ System.lineSeparator()
+ " 新增 → 这条已经不是简单单表,SQL 写进 mapper XML;" + System.lineSeparator()
+ " 迁走 → 同步减 RAW_SQL_IN_WRAPPERS_BASELINE。当前实测:" + actual);
assertTrue(actual.values().stream().mapToInt(Integer::intValue).sum() >= 10,
"只数到 " + actual + " 条,多半是正则或目录坏了——恒 0 的闸门比没有闸门更糟");
}
@Test
void limitExemptionDoesNotHideRealSql() {
// 计数器必须"看见" JSON_EXTRACT / FOR UPDATE / inSql,但放过 LIMIT —— 四种形状各喂一条
assertEquals(1, countRawSqlInWrapper("q.apply(\"JSON_UNQUOTE(JSON_EXTRACT(a, '$.b')) = {0}\", v));"));
assertEquals(1, countRawSqlInWrapper("q.last(\"FOR UPDATE\"));"));
assertEquals(1, countRawSqlInWrapper("q.inSql(FileTaskEntity::getId, \"select id from t\"));"));
assertEquals(0, countRawSqlInWrapper("q.last(\"LIMIT \" + safeLimit));"),
"LIMIT 分页 idiomatic 写法不该计入,否则 205 处噪音会把这条守卫淹掉");
// 但 "LIMIT 1 FOR UPDATE" 这种混写必须计入——不能被前缀是 LIMIT 就放过
assertEquals(1, countRawSqlInWrapper("q.last(\"limit 1 FOR UPDATE\"));"));
}
@Test
void noNewComplexWriteSqlInAnnotations() throws IOException {
List<String> complex = new ArrayList<>();
for (Path file : mappers()) {
Matcher matcher = WRITE_ANNOTATION_BODY.matcher(stripComments(read(file)));
while (matcher.find()) {
String body = matcher.group(2);
if (body.contains("<script>") || body.contains("<if ")
|| body.contains("<foreach") || body.contains("<set>")) {
complex.add(stem(file));
}
}
}
List<String> unexpected = complex.stream().distinct()
.filter(name -> !COMPLEX_WRITE_SQL_BACKLOG.contains(name))
.collect(Collectors.toList());
assertTrue(unexpected.isEmpty(), () -> "这些 mapper 新写了带动态标签的 SQL 注解:" + unexpected
+ " —— 按约定放进 src/main/resources/mapper/<模块>/<Name>Mapper.xml");
assertEquals(COMPLEX_WRITE_SQL_BACKLOG.stream().sorted().collect(Collectors.toList()),
complex.stream().distinct().sorted().collect(Collectors.toList()),
"复杂写 SQL 的待迁清单变了:迁走一条就同时从 COMPLEX_WRITE_SQL_BACKLOG 划掉");
}
@Test
void everyMigratedMapperHasNoAnnotatedSqlLeft() {
for (String name : MIGRATED_TO_XML) {
Path file = findMapperInterface(name);
String text = stripComments(read(file));
assertFalse(count(WRITE_ANNOTATION, text) > 0,
() -> name + " 已迁到 XML,注解里却又出现写 SQL:同名会让 MyBatis 启动期抛重复语句");
assertFalse(count(SELECT_ANNOTATION, text) > 0,
() -> name + " 已迁到 XML,注解里却又出现 @Select:" + name);
assertFalse(text.contains("<script>"),
() -> name + " 的注解里还留着 <script>:迁移只做了一半,调用时会报 no statement");
assertTrue(xmlFiles().stream().anyMatch(x -> stem(x).equals(name)),
() -> name + " 声称已迁 XML,但 src/main/resources/mapper 下没有同名文件");
}
}
@Test
void everyXmlStatementMatchesAnInterfaceMethod() throws IOException {
List<Path> xmls = xmlFiles();
assertFalse(xmls.isEmpty(), "mapper XML 目录是空的——迁移通道没落地,本用例就成了恒绿");
for (Path xml : xmls) {
String text = read(xml);
String namespace = firstGroup(Pattern.compile("namespace=\"([^\"]+)\""), text,
xml + " 缺 namespace(MyBatis 无法把语句绑到接口)");
Path iface = findMapperInterfaceByFqn(namespace);
List<String> statementIds = allGroups(Pattern.compile(
"<(select|insert|update|delete)\\s+id=\"([^\"]+)\""), text, 2);
assertFalse(statementIds.isEmpty(), () -> xml + " 里没有任何语句");
for (String id : statementIds) {
assertTrue(declaredMethods(iface).contains(id),
() -> id + "(" + xml.getFileName() + ")在 " + namespace
+ " 上没有同名方法:启动不报错,调用时才报 no statement");
}
assertEquals(stem(iface), stem(xml), "XML 文件名应与接口名一致,便于按名找 SQL");
}
}
@Test
void newMappersMustBeEntityBacked() throws IOException {
List<String> offenders = new ArrayList<>();
for (Path file : mappers()) {
String text = stripComments(read(file));
if (count(WRITE_ANNOTATION, text) > 0 && !text.contains("BaseMapper<")) {
offenders.add(stem(file));
}
}
assertEquals(MAPPERS_WITHOUT_ENTITY, offenders.stream().distinct().sorted().collect(Collectors.toList()),
() -> "带写 SQL 又不继承 BaseMapper<T> 的 mapper 变了:没有实体就没有 wrapper 入口,"
+ "新 mapper 请 extends BaseMapper<XxxEntity>");
}
@Test
void xmlDirectoryIsActuallyOnTheLoadPath() throws IOException {
Path resources = moduleRoot().resolve("src/main/resources/mapper");
assertTrue(Files.isDirectory(resources), "src/main/resources/mapper 不存在,迁移无处可放");
String yml = read(moduleRoot().resolve("src/main/resources/application.yml"));
assertTrue(yml.replaceAll("\\s+", " ").contains("mapper-locations: classpath*:mapper/**/*.xml"),
"application.yml 的 mapper-locations 变了:XML 会被静默忽略,调用时才报 no statement");
}
// ---------- 判据本体(纯函数,喂字符串即可验,不依赖目录里恰好有什么) ----------
/** 数一段源码里"wrapper 夹带函数级 SQL"的次数;last("LIMIT …") 是允许的写法。 */
static int countRawSqlInWrapper(String text) {
int hits = 0;
Matcher m = Pattern.compile("\\.(apply|inSql|having|last)\\(\\s*(\"[^\"]*\"|[^,)\\n]+,\\s*\")")
.matcher(text);
while (m.find()) {
String tail = text.substring(m.start(), Math.min(text.length(), m.end() + 120));
String upper = tail.toUpperCase();
boolean realSql = upper.contains("JSON_") || upper.contains("FOR UPDATE")
|| upper.contains("SELECT ") || upper.contains("WHERE ")
|| m.group(1).equals("inSql") || m.group(1).equals("having");
if (realSql) {
hits++;
}
}
return hits;
}
// ---------- 取样 ----------
private static List<Path> mappers() throws IOException {
return mainSources().stream()
.filter(p -> p.getFileName().toString().endsWith("Mapper.java"))
.collect(Collectors.toList());
}
private static List<Path> mainSources() throws IOException {
Path root = moduleRoot().resolve("src/main/java");
if (!Files.isDirectory(root)) {
fail("找不到 " + root + " —— 用例依赖以 backend-java 为工作目录运行,别让守卫静默通过");
}
try (Stream<Path> walk = Files.walk(root)) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith(".java"))
.sorted()
.collect(Collectors.toList());
}
}
private static List<Path> xmlFiles() {
try (Stream<Path> walk = Files.walk(moduleRoot().resolve("src/main/resources/mapper"))) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith(".xml"))
.sorted()
.collect(Collectors.toList());
} catch (IOException e) {
throw new IllegalStateException("遍历 mapper XML 失败", e);
}
}
private static Path findMapperInterface(String simpleName) {
try {
return mappers().stream()
.filter(p -> stem(p).equals(simpleName))
.findFirst()
.orElseThrow(() -> new IllegalStateException("找不到 mapper 接口 " + simpleName));
} catch (IOException e) {
throw new IllegalStateException(e);
}
}
private static Path findMapperInterfaceByFqn(String fqn) {
String simpleName = fqn.substring(fqn.lastIndexOf('.') + 1);
Path file = findMapperInterface(simpleName);
assertTrue(read(file).contains("package " + fqn.substring(0, fqn.lastIndexOf('.')) + ";"),
() -> "XML namespace 指向 " + fqn + ",但 " + file + " 不在那个包里");
return file;
}
private static List<String> declaredMethods(Path iface) {
// 只要声明行:形如 "Xxx yyy(" 的方法签名,跳过注解与注释
List<String> names = new ArrayList<>();
for (String raw : stripComments(read(iface)).split("\n", -1)) {
String line = raw.trim();
if (line.isEmpty()) {
continue;
}
Matcher m = Pattern.compile("^[\\w<>?,.\\[\\]\\s]+?\\s(\\w+)\\s*\\(").matcher(line);
if (m.find()) {
names.add(m.group(1));
}
}
return names;
}
private static String firstGroup(Pattern pattern, String text, String message) {
Matcher m = pattern.matcher(text);
if (!m.find()) {
throw new IllegalStateException(message);
}
return m.group(1);
}
private static List<String> allGroups(Pattern pattern, String text, int group) {
List<String> out = new ArrayList<>();
Matcher m = pattern.matcher(text);
while (m.find()) {
out.add(m.group(group));
}
return out;
}
private static int count(Pattern pattern, String text) {
int hits = 0;
Matcher m = pattern.matcher(text);
while (m.find()) {
hits++;
}
return hits;
}
private static String stripComments(String text) {
return text.replaceAll("/\\*[\\s\\S]*?\\*/", "").replaceAll("//[^\\n]*", "");
}
private static String stem(Path path) {
String name = path.getFileName().toString();
return name.substring(0, name.length() - (name.endsWith(".java") ? 5 : 4));
}
private static String read(Path path) {
try {
return Files.readString(path, StandardCharsets.UTF_8);
} catch (IOException e) {
throw new IllegalStateException("读取失败: " + path, e);
}
}
/** surefire 的工作目录是模块目录;从仓库根或 IDE 跑时退到 backend-java/。 */
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 + ")");
}
}