From 207225eb869ae262d8fd41ee4bca8ecb1d0efb01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Thu, 8 Oct 2026 09:20:41 +0800 Subject: [PATCH] =?UTF-8?q?feat(=E6=8A=A4=E6=A0=8F=E4=B8=89=E9=9D=A2):=20?= =?UTF-8?q?=E9=89=B4=E6=9D=83=E7=9B=B2=E5=8C=BA=E5=90=AF=E5=8A=A8=E8=87=AA?= =?UTF-8?q?=E6=A3=80=20+=20SQL=20=E5=88=86=E5=B1=82=E5=8F=A3=E5=BE=84?= =?UTF-8?q?=E8=90=BD=E7=A0=81=20+=20=E5=85=AD=E9=A1=B5=E7=AD=89=E5=BE=85?= =?UTF-8?q?=E5=BE=AA=E7=8E=AF=E5=90=88=E4=B8=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 后端 - AdminApiGuardFilter 增 guardedPrefixes()/matchesPrefix() 公开入口(原 private, 自检抄一份清单迟早与守卫脱钩);行为零变化 - 新增 ApiGuardCoverageAuditor:启动期把"已映射端点既不在守卫前缀名单、也不在 公开/待收清单里"打成 API_GUARD_UNCOVERED 一行 WARN,供现网巡检 grep; PUBLIC_BY_DESIGN 与 PENDING_CONVERGENCE 两张清单逐条写理由(只读不拦) - SQL 分层按新口径落码:AsinResultCacheMapper 的两条动态 SQL( 批量 + 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 词表不误报) --- .../aiimage/config/AdminApiGuardFilter.java | 15 +- .../config/ApiGuardCoverageAuditor.java | 132 ++++++ .../mapper/AsinResultCacheMapper.java | 42 +- .../asincache/AsinResultCacheMapper.xml | 42 ++ .../aiimage/SqlLayeringConventionTest.java | 402 ++++++++++++++++++ .../config/ApiGuardCoverageAuditorTest.java | 177 ++++++++ .../mapper/AsinResultCacheMapperXmlTest.java | 165 +++++++ .../brand/components/BrandPatrolDeleteTab.vue | 70 ++- .../brand/components/BrandPriceTrackTab.vue | 78 ++-- .../brand/components/BrandProductRiskTab.vue | 60 ++- .../brand/components/BrandQueryAsinTab.vue | 50 +-- .../brand/components/BrandShopMatchTab.vue | 51 ++- .../brand/components/BrandWithdrawTab.vue | 52 +-- .../src/shared/utils/task-terminal.ts | 84 ++++ .../task-terminal-set-single-source.test.ts | 96 +++++ frontend-vue/tests/task-terminal.test.ts | 118 +++++ 16 files changed, 1418 insertions(+), 216 deletions(-) create mode 100644 backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java create mode 100644 backend-java/src/main/resources/mapper/asincache/AsinResultCacheMapper.xml create mode 100644 backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/config/ApiGuardCoverageAuditorTest.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/modules/asincache/mapper/AsinResultCacheMapperXmlTest.java create mode 100644 frontend-vue/src/shared/utils/task-terminal.ts create mode 100644 frontend-vue/tests/task-terminal-set-single-source.test.ts create mode 100644 frontend-vue/tests/task-terminal.test.ts diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java b/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java index 9ba4d3829..6b7176e6c 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java +++ b/backend-java/src/main/java/com/nanri/aiimage/config/AdminApiGuardFilter.java @@ -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 guardedPrefixes() { + java.util.List 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 + "/"); } diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java b/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java new file mode 100644 index 000000000..74c0e7270 --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java @@ -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} 的看守前缀里、 + * 也不在明知公开的清单里"变成一条会进日志、会被巡检抓到的记录。 + * + *

为什么需要它:SecurityConfig 全局 permitAll,鉴权只有两道——过滤器的前缀名单,和控制器里 + * 散着的 {@code require*} 调用。前者是常量、后者没有清单,**没有任何东西在数"两道都不沾"是谁**。 + * 于是新增一个 {@code @RestController} 挂在没人看守的前缀下时不报错、不变红,只是安静地匿名可达。 + * 2026-10-08 按控制器盘出 13 个基路径不在名单里,其中 6 个与名单内那 15 条同形状,只是没人记账。 + * + *

口径(前缀匹配语义与 {@link AdminApiGuardFilter#matchesPrefix} 完全一致,共用同一个方法): + *

    + *
  • {@code covered}——命中守卫名单(含开关后面那 15 条:受不受开关控制不改变"它在名单里");
  • + *
  • {@code public}——设计上匿名可达,列在 {@link #PUBLIC_BY_DESIGN};
  • + *
  • {@code pending}——数据按 user_id 归属却还没有认证要求的用户态前缀,是**待收欠账**不是许可, + * 列在这里只为让启动日志安静,每条都写明卡在什么上面;
  • + *
  • {@code uncovered}——以上都不是 ⇒ 打 {@value #ALERT_ANCHOR} 一行 WARN, + * 主机A/B 的巡检(scripts/_prod_watch.py 的 SIGNATURES)把它计入告警。
  • + *
+ * + *

自检只读不拦:不参与任何请求的放行判定,所以开它没有可用性风险。 + */ +@Slf4j +@Component +@RequiredArgsConstructor +public class ApiGuardCoverageAuditor { + + /** 巡检锚点:_prod_watch.py 按这个字面量 grep,改名要同时改那条签名。 */ + public static final String ALERT_ANCHOR = "API_GUARD_UNCOVERED"; + + /** 设计上匿名可达的基路径。 */ + static final Set 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", + * 不是"在这里加一行让它闭嘴"。每条的收敛前提写在下面,被测试逐条核对(新增而不写理由会红): + *

    + *
  • {@code /api/convert} —— 与 collect-data 同形状的桌面端任务,等带 X-Internal-Token 的客户端铺开
  • + *
  • {@code /api/convert/templates} —— 同一套桌面端模板读写,随 /api/convert 一起进名单
  • + *
  • {@code /api/dedupe} —— 去重库按 user_id 分库,桌面端执行器不带凭据,随客户端铺开收
  • + *
  • {@code /api/delete-brand} —— 删品牌任务单,与已在名单里的 /api/brand 同形状,等同一批客户端
  • + *
  • {@code /api/module-templates} —— 模板列表按 user_id 取,匿名可读他人模板
  • + *
  • {@code /api/split} —— 拆合单任务,随 /api/convert 那批一起收
  • + *
+ */ + static final Set 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 paths) { + List uncovered = new ArrayList<>(); + Set publicPaths = new LinkedHashSet<>(); + Set 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 prefixes) { + for (String prefix : prefixes) { + if (AdminApiGuardFilter.matchesPrefix(path, prefix)) { + return true; + } + } + return false; + } + + private Set mappedPaths() { + Set paths = new LinkedHashSet<>(); + for (RequestMappingInfo info : handlerMapping.getHandlerMethods().keySet()) { + paths.addAll(info.getPatternValues()); + } + return paths; + } + + record Report(int mapped, int covered, List publicPaths, List pending, List uncovered) { + } +} diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/asincache/mapper/AsinResultCacheMapper.java b/backend-java/src/main/java/com/nanri/aiimage/modules/asincache/mapper/AsinResultCacheMapper.java index b8f26ed94..20c6c5cf5 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/asincache/mapper/AsinResultCacheMapper.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/asincache/mapper/AsinResultCacheMapper.java @@ -2,13 +2,15 @@ package com.nanri.aiimage.modules.asincache.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.nanri.aiimage.modules.asincache.model.entity.AsinResultCacheEntity; -import org.apache.ibatis.annotations.Insert; import org.apache.ibatis.annotations.Mapper; import org.apache.ibatis.annotations.Param; -import org.apache.ibatis.annotations.Select; import java.util.List; +/** + * SQL 在 resources/mapper/asincache/AsinResultCacheMapper.xml:动态标签与列级继承 + * 写在 Java 文本块里不可维护,复杂 SQL 一律走 XML(见 SqlLayeringConventionTest)。 + */ @Mapper public interface AsinResultCacheMapper extends BaseMapper { @@ -19,17 +21,6 @@ public interface AsinResultCacheMapper extends BaseMapper * 「country = ? AND asin IN (...)」这种等值 + IN 的形状;把 country 放进 IN 里 * 成对匹配((country, asin) IN ((..),(..)))在 MySQL 上用不上索引。 */ - @Select(""" - - """) List selectByCountryAndAsins(@Param("country") String country, @Param("asins") List asins); @@ -44,30 +35,5 @@ public interface AsinResultCacheMapper extends BaseMapper *

price / availability / source_* / observed_at 不参与继承:它们是本行结论的主体, * 404 就该把价格清空,"谁最后开的页"也必须如实反映最后一次开页。 */ - @Insert(""" - - """) int upsertBatch(@Param("rows") List rows); } diff --git a/backend-java/src/main/resources/mapper/asincache/AsinResultCacheMapper.xml b/backend-java/src/main/resources/mapper/asincache/AsinResultCacheMapper.xml new file mode 100644 index 000000000..27a5370a3 --- /dev/null +++ b/backend-java/src/main/resources/mapper/asincache/AsinResultCacheMapper.xml @@ -0,0 +1,42 @@ + + + + + + + + + INSERT INTO biz_asin_result_cache + (country, asin, availability, price, brand, delivery_method, seller_name, seller_id, + declared_members_json, source_chain, source_task_id, observed_at, created_at, updated_at) + VALUES + + (#{row.country}, #{row.asin}, #{row.availability}, #{row.price}, #{row.brand}, + #{row.deliveryMethod}, #{row.sellerName}, #{row.sellerId}, #{row.declaredMembersJson}, + #{row.sourceChain}, #{row.sourceTaskId}, #{row.observedAt}, #{row.createdAt}, #{row.updatedAt}) + + ON DUPLICATE KEY UPDATE + availability = VALUES(availability), + price = VALUES(price), + brand = COALESCE(VALUES(brand), brand), + delivery_method = COALESCE(VALUES(delivery_method), delivery_method), + seller_name = COALESCE(VALUES(seller_name), seller_name), + seller_id = COALESCE(VALUES(seller_id), seller_id), + declared_members_json = COALESCE(VALUES(declared_members_json), declared_members_json), + source_chain = VALUES(source_chain), + source_task_id = VALUES(source_task_id), + observed_at = VALUES(observed_at), + updated_at = VALUES(updated_at) + + diff --git a/backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java b/backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java new file mode 100644 index 000000000..1fed5176c --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/SqlLayeringConventionTest.java @@ -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 定):SQL 尽量写进 mapper XML, + * wrapper 只留给"简单单表"(无 join、无函数级谓词、无动态标签),注解里不再新增 SQL。 + * + *

为什么要钉住而不是写在文档里:这个仓原来 0 个 XML、写 SQL 全在注解里,复杂语句 + * ({@code } + {@code ON DUPLICATE KEY} + 逐列 COALESCE)以 Java 文本块存在, + * 改一列要在字符串里数括号,也没有任何工具在写错时拦你。约定只存在于注释的话, + * 下一个人加 {@code @Insert} 时它就不存在了。所以这里把"当前有多少"逐个钉死: + *

    + *
  • 新增注解 SQL ⇒ {@link #annotationSqlInventoryDoesNotGrow} 红;
  • + *
  • 新增 wrapper 里夹带的函数级 SQL ⇒ {@link #rawSqlInsideWrappersDoesNotGrow} 红, + * 那正是"简单单表"的边界,越界就该进 XML;
  • + *
  • 迁走一条 ⇒ 必须同时改基线常量,减法出现在 diff 上。
  • + *
+ * + *

反向失明也一并堵:XML 里的坏 SQL 没有编译期反馈,所以 + * {@link #everyXmlStatementMatchesAnInterfaceMethod} 要求 XML 语句名逐字对上接口方法名—— + * 对不上的表现是"启动正常、调用才报 no statement",那是线上才会撞到的面。 + */ +class SqlLayeringConventionTest { + + /** 写 SQL(@Insert/@Update/@Delete)在注解里的现状清单:文件名 → 条数。只许减,不许加。 */ + private static final Map 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 RAW_SQL_IN_WRAPPERS_BASELINE = rawSqlInWrappersBaseline(); + + /** + * 其中"复杂"的写 SQL(注解正文含动态标签)——Wrapper 表达不了(批量/INSERT…SELECT/upsert), + * 按约定应迁到 XML。这是待迁 backlog,不是许可名单:迁走一条要同时从这里划掉。 + */ + private static final List COMPLEX_WRITE_SQL_BACKLOG = List.of( + "CollectDataItemMapper", "DedupeTotalDataMapper", "InvalidAsinDataMapper", + "UserColumnPermissionMapper", "PublishItemMapper", "ShopDataCrawlItemMapper", + "QueryAsinMapper", "TaskResultItemMapper"); + + /** 唯一没有实体可走的 mapper:连 wrapper 的入口都没有,所以只能写裸 SQL。 */ + private static final List MAPPERS_WITHOUT_ENTITY = List.of("UserColumnPermissionMapper"); + + /** 已经迁到 XML 的:反向钉住"不许再用注解把 SQL 写回来"(注解 + XML 同名会让启动期抛重复语句)。 */ + private static final List 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 writeSqlBaseline() { + Map 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 rawSqlInWrappersBaseline() { + Map 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 actual = new LinkedHashMap<>(); + int selects = 0; + List 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/<模块>/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。 + * + *

{@code last("LIMIT n")} 故意不算越界:MP 的分页 idiomatic 写法就是它, + * 全仓 205 处,把它算成违规只会让守卫第一天就没人管。豁免面由 + * {@link #limitExemptionDoesNotHideRealSql} 反向钉住。 + */ + @Test + void rawSqlInsideWrappersDoesNotGrow() throws IOException { + Map 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 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("