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
@@ -308,7 +308,20 @@ public class AdminApiGuardFilter extends OncePerRequestFilter {
return false;
}
private static boolean matchesPrefix(String uri, String prefix) {
/**
* 本过滤器实际看守的全部前缀,供启动期自检 {@link ApiGuardCoverageAuditor} 取用。
* 清单只在这里汇总一次——自检抄一份就会和守卫慢慢脱钩。
*/
public static java.util.List<String> guardedPrefixes() {
java.util.List<String> all = new java.util.ArrayList<>();
all.add(ADMIN_API_PREFIX);
all.add(DEBUG_PREFIX);
all.addAll(java.util.List.of(USER_TOOL_PREFIXES));
all.addAll(java.util.List.of(SELF_SERVICE_PREFIXES));
return all;
}
public static boolean matchesPrefix(String uri, String prefix) {
return uri.equals(prefix) || uri.startsWith(prefix + "/");
}
@@ -0,0 +1,132 @@
package com.nanri.aiimage.config;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.mvc.method.RequestMappingInfo;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
/**
* 启动期自检:把"有哪些已映射的端点既不在 {@link AdminApiGuardFilter} 的看守前缀里、
* 也不在明知公开的清单里"变成一条会进日志、会被巡检抓到的记录。
*
* <p>为什么需要它:SecurityConfig 全局 permitAll,鉴权只有两道——过滤器的前缀名单,和控制器里
* 散着的 {@code require*} 调用。前者是常量、后者没有清单,**没有任何东西在数"两道都不沾"是谁**。
* 于是新增一个 {@code @RestController} 挂在没人看守的前缀下时不报错、不变红,只是安静地匿名可达。
* 2026-10-08 按控制器盘出 13 个基路径不在名单里,其中 6 个与名单内那 15 条同形状,只是没人记账。
*
* <p>口径(前缀匹配语义与 {@link AdminApiGuardFilter#matchesPrefix} 完全一致,共用同一个方法):
* <ul>
* <li>{@code covered}——命中守卫名单(含开关后面那 15 条:受不受开关控制不改变"它在名单里");</li>
* <li>{@code public}——设计上匿名可达,列在 {@link #PUBLIC_BY_DESIGN};</li>
* <li>{@code pending}——数据按 user_id 归属却还没有认证要求的用户态前缀,是**待收欠账**不是许可,
* 列在这里只为让启动日志安静,每条都写明卡在什么上面;</li>
* <li>{@code uncovered}——以上都不是 ⇒ 打 {@value #ALERT_ANCHOR} 一行 WARN,
* 主机A/B 的巡检(scripts/_prod_watch.py 的 SIGNATURES)把它计入告警。</li>
* </ul>
*
* <p>自检只读不拦:不参与任何请求的放行判定,所以开它没有可用性风险。
*/
@Slf4j
@Component
@RequiredArgsConstructor
public class ApiGuardCoverageAuditor {
/** 巡检锚点:_prod_watch.py 按这个字面量 grep,改名要同时改那条签名。 */
public static final String ALERT_ANCHOR = "API_GUARD_UNCOVERED";
/** 设计上匿名可达的基路径。 */
static final Set<String> PUBLIC_BY_DESIGN = Set.of(
"/login", // 登录本身就是发凭据的入口
"/check_login", // 只回答"这个会话还有效吗",无效时不泄漏数据
"/logout",
"/api/version", // 客户端启动时拉最新版本号,必须先于登录
"/api/tutorial", // 后台可维护的使用教程,公开内容
"/api/kd-flow/verify", // 开店流程访问密码校验:它自己就是那道门
"/error");
/**
* 待收欠账:数据按 user_id 归属、却既不进守卫名单也没有 require* 的前缀。
* 划掉它们的条件是"进 USER_TOOL_PREFIXES、并在 user-tool-guard-enabled 打开后回归 covered",
* 不是"在这里加一行让它闭嘴"。每条的收敛前提写在下面,被测试逐条核对(新增而不写理由会红):
* <ul>
* <li>{@code /api/convert} —— 与 collect-data 同形状的桌面端任务,等带 X-Internal-Token 的客户端铺开</li>
* <li>{@code /api/convert/templates} —— 同一套桌面端模板读写,随 /api/convert 一起进名单</li>
* <li>{@code /api/dedupe} —— 去重库按 user_id 分库,桌面端执行器不带凭据,随客户端铺开收</li>
* <li>{@code /api/delete-brand} —— 删品牌任务单,与已在名单里的 /api/brand 同形状,等同一批客户端</li>
* <li>{@code /api/module-templates} —— 模板列表按 user_id 取,匿名可读他人模板</li>
* <li>{@code /api/split} —— 拆合单任务,随 /api/convert 那批一起收</li>
* </ul>
*/
static final Set<String> PENDING_CONVERGENCE = Set.of(
"/api/convert",
"/api/convert/templates",
"/api/dedupe",
"/api/delete-brand",
"/api/module-templates",
"/api/split");
private final RequestMappingHandlerMapping handlerMapping;
@EventListener(ApplicationReadyEvent.class)
public void auditOnBoot() {
Report report = audit(mappedPaths());
if (report.uncovered().isEmpty()) {
log.info("[api-guard-coverage] mapped={} covered={} public={} pending={} uncovered=0",
report.mapped(), report.covered(), report.publicPaths().size(), report.pending().size());
return;
}
log.warn("[api-guard-coverage] {} count={} endpoints={} —— 这些端点不在守卫前缀里、也不在公开/待收清单里,"
+ "匿名可达;请加进 AdminApiGuardFilter 的名单,或确认公开并登记进 PUBLIC_BY_DESIGN",
ALERT_ANCHOR, report.uncovered().size(), report.uncovered());
}
/** 纯函数:不依赖 Spring 上下文,也不产生副作用,供单测直接喂路径集合。 */
static Report audit(Collection<String> paths) {
List<String> uncovered = new ArrayList<>();
Set<String> publicPaths = new LinkedHashSet<>();
Set<String> pending = new LinkedHashSet<>();
int covered = 0;
for (String path : paths) {
if (matchesAny(path, AdminApiGuardFilter.guardedPrefixes())) {
covered++;
} else if (matchesAny(path, PUBLIC_BY_DESIGN)) {
publicPaths.add(path);
} else if (matchesAny(path, PENDING_CONVERGENCE)) {
pending.add(path);
} else {
uncovered.add(path);
}
}
return new Report(paths.size(), covered, List.copyOf(publicPaths), List.copyOf(pending),
List.copyOf(new LinkedHashSet<>(uncovered)));
}
private static boolean matchesAny(String path, Collection<String> prefixes) {
for (String prefix : prefixes) {
if (AdminApiGuardFilter.matchesPrefix(path, prefix)) {
return true;
}
}
return false;
}
private Set<String> mappedPaths() {
Set<String> paths = new LinkedHashSet<>();
for (RequestMappingInfo info : handlerMapping.getHandlerMethods().keySet()) {
paths.addAll(info.getPatternValues());
}
return paths;
}
record Report(int mapped, int covered, List<String> publicPaths, List<String> pending, List<String> uncovered) {
}
}