From 15094309cfdc4118a1f68008e4bc3f635bac480d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Fri, 9 Oct 2026 23:09:37 +0800 Subject: [PATCH] =?UTF-8?q?=E5=90=8E=E7=AB=AF(=E5=9B=9B=E9=9D=A29=E5=88=86?= =?UTF-8?q?=E6=89=B9=E6=AC=A1):=20=E9=94=81=E8=B7=B3=E8=BF=87=E7=95=99?= =?UTF-8?q?=E7=97=95=E3=80=81=E7=8A=B6=E6=80=81=E8=AF=8D=E8=A1=A8=E6=94=B6?= =?UTF-8?q?=E6=88=90=E5=8D=95=E7=82=B9=E3=80=81=E7=89=88=E6=9C=AC=E7=A1=AC?= =?UTF-8?q?=E5=9C=B0=E6=9D=BF=E8=BF=9B=20yml=20=E5=B9=B6=E8=AE=B0=E8=B4=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 14 处「拿不到锁就 continue」过去零日志,现统一带可聚合锚点并有留痕判据 (LockSkipWitnessTest 7 例 + LockSkipSilentExitGuardrailTest 4 例)。 - 任务状态词表:散落内联集合改由单一定义点判方向(TaskStatusVocabularyRatchetTest 7 例), CANCELED/CANCELLED 只做归一映射,没改库值也没改对外契约。 - 版本硬地板三键(min-supported / enforce / rejectUnreported)此前在任何 yml 里 0 处=出厂即惰性; 现在入册且 enforce=false 走记账模式(ClientVersionFloorConfigTest 9 例),真挡谁留给用户拍。 - 业务码→HTTP 状态只做映射单点 + 开关(默认关,开启前逐字节等价,BusinessErrorHttpStatusTest 8 例); 直接翻面会让三个前端把业务失败读成网络挂了。 - 验收:mvn -o test 这 5 个类 35 例 0 红(用 python subprocess 起 mvn——bash 里 cmd 包一层 开的是交互式 cmd,rc 是 cmd 的,会给出假的 rc=0)。 --- .../aiimage/common/api/PageDefaults.java | 83 +++++ .../exception/BusinessErrorHttpStatus.java | 180 ++++++++++ .../exception/GlobalExceptionHandler.java | 17 +- .../aiimage/common/task/TaskStatuses.java | 181 ++++++++++ .../aiimage/common/util/LockSkipWitness.java | 182 ++++++++++ .../config/ClientVersionGuardFilter.java | 28 ++ .../admin/controller/AdminUserController.java | 5 +- .../AppearancePatentController.java | 3 +- .../service/AppearancePatentTaskService.java | 6 + .../service/BrandTaskExpiredStopSpiImpl.java | 10 +- .../brand/service/BrandTaskService.java | 20 +- .../service/BrandTaskStaleRepairSpiImpl.java | 10 +- .../controller/CollectDataController.java | 7 +- .../service/CollectDataService.java | 3 + .../controller/DedupeTotalDataController.java | 5 +- .../service/DeleteBrandStaleTaskService.java | 5 + .../controller/AdminDeviceLogController.java | 5 +- .../controller/ImageHistoryController.java | 5 +- .../AdminImageVideoTaskController.java | 5 +- .../service/ImageVideoArchiveService.java | 2 + .../service/ImageVideoAsyncTaskService.java | 5 + .../controller/InvalidAsinDataController.java | 5 +- .../AdminNotificationController.java | 5 +- .../controller/NotificationController.java | 5 +- .../service/PatrolDeleteTaskService.java | 3 +- .../controller/PriceTrackController.java | 5 +- .../PriceTrackLoopRunStaleService.java | 3 +- .../service/PriceTrackTaskService.java | 3 +- .../controller/ProductCategoryController.java | 9 +- .../service/ProductRiskTaskService.java | 3 +- .../publish/controller/PublishController.java | 7 +- .../publish/service/PublishTaskService.java | 5 +- .../service/QueryAsinTaskService.java | 3 +- .../ShopDataCrawlTaskController.java | 5 +- .../service/ShopDataCrawlTaskService.java | 3 +- .../controller/QueryAsinController.java | 5 +- .../shopkey/controller/ShopKeyController.java | 5 +- .../controller/ShopManageController.java | 5 +- .../controller/SkipPriceAsinController.java | 5 +- .../controller/ShopMatchController.java | 5 +- .../service/ShopMatchTaskService.java | 3 +- .../controller/SimilarAsinController.java | 3 +- .../service/SimilarAsinTaskService.java | 6 + .../support/SimilarAsinPipelineSupport.java | 5 + .../controller/TaskFileJobController.java | 5 +- .../CompletedTaskActiveJobInspector.java | 2 +- .../ExpiredAccountTaskStopService.java | 2 + .../task/service/InspectionSqlReportTask.java | 2 + .../service/ModuleHistoryCleanupService.java | 3 +- .../task/service/TaskFileJobService.java | 14 +- .../service/TaskProgressSnapshotService.java | 3 +- .../service/TaskResultMissingInspector.java | 2 +- .../mapper/TaskCenterQueryMapper.java | 22 +- .../AdminUserApiSecretController.java | 5 +- .../AdminUserSecretUsageController.java | 5 +- .../withdraw/service/WithdrawTaskService.java | 3 +- .../src/main/resources/application.yml | 25 ++ .../common/api/PageDefaultsLedgerTest.java | 258 ++++++++++++++ .../BusinessErrorHttpStatusTest.java | 269 +++++++++++++++ .../task/TaskStatusVocabularyRatchetTest.java | 326 ++++++++++++++++++ .../util/LockSkipSilentExitGuardrailTest.java | 233 +++++++++++++ .../common/util/LockSkipWitnessTest.java | 182 ++++++++++ .../config/ClientVersionFloorConfigTest.java | 315 +++++++++++++++++ 63 files changed, 2454 insertions(+), 95 deletions(-) create mode 100644 backend-java/src/main/java/com/nanri/aiimage/common/api/PageDefaults.java create mode 100644 backend-java/src/main/java/com/nanri/aiimage/common/exception/BusinessErrorHttpStatus.java create mode 100644 backend-java/src/main/java/com/nanri/aiimage/common/task/TaskStatuses.java create mode 100644 backend-java/src/main/java/com/nanri/aiimage/common/util/LockSkipWitness.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/common/api/PageDefaultsLedgerTest.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/common/exception/BusinessErrorHttpStatusTest.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/common/task/TaskStatusVocabularyRatchetTest.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/common/util/LockSkipSilentExitGuardrailTest.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/common/util/LockSkipWitnessTest.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/config/ClientVersionFloorConfigTest.java diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/api/PageDefaults.java b/backend-java/src/main/java/com/nanri/aiimage/common/api/PageDefaults.java new file mode 100644 index 000000000..650a4b992 --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/common/api/PageDefaults.java @@ -0,0 +1,83 @@ +package com.nanri.aiimage.common.api; + +/** + * 分页与列表条数默认值的具名出处(2026-10-09 评审「可读 5.0 / 交互 5.5」项 5: + * {@code defaultValue} 里 15/20/50/1000 四种并存,31 处魔法数)。 + * + *

这里没有"全局统一默认页容量"这一说,而且是故意的。 + * 实测 49 处数字型 {@code defaultValue}(21 处页码 + 28 处条数)分属不同的真实用途: + * 用户端列表、超管台、任务历史、扫描上限、导出取全量——把它们拍成一个值是改行为, + * 不是清理。本类只做一件事:让每个数字有一个说明它为什么是这个数的名字, + * 并让"同一个用途冒出第二个默认值"变成判据红({@code PageDefaultsLedgerTest})。 + * + *

注解里的 {@code defaultValue} 必须是编译期字符串常量,所以常量声明成 {@link String}; + * 每个都配一个 {@code *_INT} 镜像,业务代码里要用数字时不必再 {@code Integer.parseInt}。 + * + *

命名口径:{@code <用途>_PAGE_SIZE} 是"一页几条",{@code <用途>_LIMIT} 是"本次最多返回几条" + * (不是分页,是扫描/返回截断)。两者不许混用——把 limit 当 pageSize 用会把上限调到用户可见的错位。 + */ +public final class PageDefaults { + + private PageDefaults() { + } + + // ---- 页码:21 处全是 1,这一族本来就是单一口径 ---- + + /** 起始页码。全树 21 处分页入口一致取 1(不是 0);改这个数等于把所有列表第一页翻空。 */ + public static final String FIRST_PAGE = "1"; + + /** {@link #FIRST_PAGE} 的数字镜像。 */ + public static final int FIRST_PAGE_INT = 1; + + // ---- 每页条数:现存 4 个不同的真实默认 ---- + + /** + * 用户端/超管列表页默认容量 = 15。现存 10 处(admin 用户、去重库、图片历史、 + * 无效 ASIN、ASIN 查询、店铺凭据、店铺管理、跳价 ASIN……)。 + */ + public static final String USER_LIST_PAGE_SIZE = "15"; + + /** {@link #USER_LIST_PAGE_SIZE} 的数字镜像。 */ + public static final int USER_LIST_PAGE_SIZE_INT = 15; + + /** 超管台列表默认容量 = 20。现存 6 处(设备日志、图视任务、通知×2、商品分类×2)。 */ + public static final String ADMIN_LIST_PAGE_SIZE = "20"; + + /** {@link #ADMIN_LIST_PAGE_SIZE} 的数字镜像。 */ + public static final int ADMIN_LIST_PAGE_SIZE_INT = 20; + + /** 上架/采集类任务历史列表默认容量 = 50。现存 2 处 {@code page_size}(collect-data、publish)。 */ + public static final String TASK_LIST_PAGE_SIZE = "50"; + + /** {@link #TASK_LIST_PAGE_SIZE} 的数字镜像。 */ + public static final int TASK_LIST_PAGE_SIZE_INT = 50; + + /** + * 一次性取全量的"页容量"= 1000。现存 2 处,都是用户端列表接口: + * {@code PriceTrackController}(价格追踪)与 {@code ShopMatchController}(店铺匹配)的 + * {@code page_size}。 + * + *

这一条是评审点名的疑似笔误:用户端下拉的默认页容量给到 1000,表现更像"根本没分页" + * 而不是"一页 1000 条"。单独一个常量、不复用 {@link #TASK_LIST_PAGE_SIZE},是为了让它 + * 在判据里数得出来(2 处);本轮没有改它,也不自行改成 50——改成多少、是不是保留 + * 客户端传参上限,需要产品/运维拍板。 + */ + public static final String FULL_EXPORT_PAGE_SIZE = "1000"; + + /** {@link #FULL_EXPORT_PAGE_SIZE} 的数字镜像。 */ + public static final int FULL_EXPORT_PAGE_SIZE_INT = 1000; + + // ---- 返回条数上限(不是分页)---- + + /** 单接口一次最多返回多少条 = 50。现存 4 处 {@code limit}(外观专利、采集数据、上架任务、相似 ASIN)。 */ + public static final String DEFAULT_RESULT_LIMIT = "50"; + + /** {@link #DEFAULT_RESULT_LIMIT} 的数字镜像。 */ + public static final int DEFAULT_RESULT_LIMIT_INT = 50; + + /** 超管扫描类接口的单次上限 = 100。现存 3 处 {@code limit}(店铺数据采集列表、结果作业列表×2)。 */ + public static final String ADMIN_SCAN_LIMIT = "100"; + + /** {@link #ADMIN_SCAN_LIMIT} 的数字镜像。 */ + public static final int ADMIN_SCAN_LIMIT_INT = 100; +} diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/exception/BusinessErrorHttpStatus.java b/backend-java/src/main/java/com/nanri/aiimage/common/exception/BusinessErrorHttpStatus.java new file mode 100644 index 000000000..2b400ef3d --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/common/exception/BusinessErrorHttpStatus.java @@ -0,0 +1,180 @@ +package com.nanri.aiimage.common.exception; + +import io.micrometer.core.instrument.Gauge; +import io.micrometer.core.instrument.MeterRegistry; +import lombok.extern.slf4j.Slf4j; +import com.nanri.aiimage.common.api.ApiResponse; +import org.springframework.beans.factory.ObjectProvider; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.http.HttpStatus; +import org.springframework.http.ResponseEntity; +import org.springframework.stereotype.Component; + +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.Map; +import java.util.concurrent.atomic.AtomicInteger; + +/** + * 业务码 → 真 HTTP 状态码的映射单点(2026-10-09 评审「交互 5.5」项 4)。 + * + *

现状实测:{@code GlobalExceptionHandler} 的 {@code BusinessException} 出口没有 + * {@code @ResponseStatus},于是 1,242 处业务失败全部以 HTTP 200 出。后果不是"不好看": + * 业务失败在 HTTP 指标里彻底隐形(2026-09-18 那次滚动重启期间丢心跳就是这么被记成 200 的, + * 见 {@code GlobalExceptionHandler} 里 503 那段注释),网关/监控/客户端拦截器都只能靠扒响应体猜。 + * + *

但这一轮不翻面。直接改状态码会让三个前端把"业务失败"当"网络挂了"处理—— + * 那是行为回归,不是修复。所以这里只做安全的一半: + *

    + *
  1. 映射表在这里,一处定完,判据钉死({@code BusinessErrorHttpStatusTest});
  2. + *
  3. 开关 {@code aiimage.api.business-error-http-status.enabled} 默认 false; + * 关闭时 {@link #render} 原样返回 {@code ApiResponse},序列化路径与今天逐字节一致;
  4. + *
  5. "哪些 code 会变成非 200"是显式白名单:白名单外(含 {@code code == null}) + * 永远走 200,所以翻开关不会把没预料到的码打成 4xx/5xx。
  6. + *
+ * + *

开启动作要用户拍板:至少要先确认 {@code frontend-vue}、{@code admin-frontend-vue} + * 与桌面端 {@code app_client} 三处拦截器都能吃非 200 + 同形响应体 + * (已实测 {@code admin-frontend-vue/src/api/envelope.ts} 对 401/403 同时读 + * {@code status}/{@code statusCode}/{@code code},这一族风险较低;其余两处本面无证据)。 + * + *

白名单的取数口径来自实测码分布({@code src/main/java} 里 {@code BusinessException(code)} 的字面量统计): + * 403×52、400×36、401×16、500×4、409×3、404×3、503×1,加 {@link BusinessCodes} 的 404xx/409xx 族、 + * {@code DeviceSessionPolicy.CODE_KICKED=4011}、{@code ClientVersionGuardFilter.CODE_TOO_OLD=4012}。 + */ +@Slf4j +@Component +public class BusinessErrorHttpStatus { + + /** 开关的配置键(写在 application.yml 里,默认 false)。 */ + public static final String ENABLED_KEY = "aiimage.api.business-error-http-status.enabled"; + + /** 记账指标:开关打开后每次真的把业务失败写成非 200 时 +1,按 code 打标签。 */ + public static final String METRIC = "aiimage.api.business.error.http_status"; + + /** 日志锚点:翻真之后现网靠这一条定位"哪个 code 在改状态码"。 */ + public static final String ANCHOR = "[business-http-status]"; + + /** + * 映射白名单。业务码 → 真 HTTP 状态。表外一律 200(见 {@link #statusFor})。 + * + *

3 位码是"码里已经写着 HTTP 语义"的那一族,照它的字面意思映射; + * 4 位 401x 与 5 位 404xx/409xx 是项目自造的族,按 {@link BusinessCodes} 注释里的语义映射。 + * + *

注意 {@link BusinessCodes#TASK_ALREADY_FINISHED}(40901) 不在表里: + * {@code GlobalExceptionHandler} 对它是幂等忽略、返回 {@code success=true}, + * 那是成功响应,不该被写成 409。 + */ + private static final Map MAPPINGS = buildMappings(); + + private static Map buildMappings() { + Map map = new LinkedHashMap<>(); + // —— 3 位族:码本身就是 HTTP 状态语义 + map.put(400, HttpStatus.BAD_REQUEST); + map.put(401, HttpStatus.UNAUTHORIZED); + map.put(403, HttpStatus.FORBIDDEN); + map.put(404, HttpStatus.NOT_FOUND); + map.put(409, HttpStatus.CONFLICT); + map.put(422, HttpStatus.UNPROCESSABLE_ENTITY); + map.put(500, HttpStatus.INTERNAL_SERVER_ERROR); + map.put(503, HttpStatus.SERVICE_UNAVAILABLE); + // —— 4 位 401x 族:鉴权/凭据 + map.put(4011, HttpStatus.UNAUTHORIZED); // DeviceSessionPolicy.CODE_KICKED:被顶下线 + map.put(4012, HttpStatus.BAD_REQUEST); // ClientVersionGuardFilter.CODE_TOO_OLD:客户端版本过低 + // —— 5 位 404xx/409xx 族:BusinessCodes + map.put(BusinessCodes.TASK_NOT_FOUND, HttpStatus.NOT_FOUND); // 40401 + map.put(BusinessCodes.TASK_BUSY, HttpStatus.CONFLICT); // 40902 + map.put(BusinessCodes.TASK_OWNER_FORWARD, HttpStatus.CONFLICT); // 40903 + return Collections.unmodifiableMap(map); + } + + /** 可为 null:没配 Micrometer 注册表时只留日志与映射判定。 */ + private static volatile MeterRegistry registry; + private static final AtomicInteger RENDER_COUNT = new AtomicInteger(); + + @Value("${" + ENABLED_KEY + ":false}") + private boolean enabled; + + /** 关掉时静态侧也必须是 false——判据与生产共用同一个开关值,不许两套默认。 */ + private static volatile boolean enabledFlag; + + public BusinessErrorHttpStatus() { + } + + @Autowired + public BusinessErrorHttpStatus(ObjectProvider meterRegistryProvider, + @Value("${" + ENABLED_KEY + ":false}") boolean enabled) { + registry = meterRegistryProvider == null ? null : meterRegistryProvider.getIfAvailable(); + enabledFlag = enabled; + log.info("{} 启动自检:{}={}({})映射白 {} 条,表外 code 恒走 200", + ANCHOR, ENABLED_KEY, enabled, + enabled ? "真改写 HTTP 状态" : "关闭:业务失败仍全部 HTTP 200,行为与改动前逐字节一致", + MAPPINGS.size()); + if (enabled && registry != null) { + Gauge.builder(METRIC + ".renders", RENDER_COUNT, AtomicInteger::get).register(registry); + } + } + + /** 单测接线用:显式设置开关与注册表,不依赖容器。 */ + public static void bindForTests(boolean enabled, MeterRegistry meterRegistry) { + enabledFlag = enabled; + registry = meterRegistry; + } + + /** 当前是否启用了真状态码。 */ + public static boolean isEnabled() { + return enabledFlag; + } + + /** 只改开关、不动映射(判据与回退用)。 */ + public void setEnabled(boolean value) { + this.enabled = value; + enabledFlag = value; + } + + public boolean isSwitchOn() { + return enabled; + } + + /** 映射表白名单的只读视图(判据③:"哪些 code 会被映射成非 200"就是这一份)。 */ + public static Map mappings() { + return MAPPINGS; + } + + /** + * 业务码对应的 HTTP 状态。 + * + *

三种落到 {@link HttpStatus#OK} 的情况,都是故意的: + * {@code code == null}(历史上大量 {@code ApiResponse.fail(message)} 不带码)、 + * 表外码、成功响应。返回 OK 时 {@link #render} 不会构造 {@code ResponseEntity}, + * 也就是不会碰 HTTP 状态。 + */ + public static HttpStatus statusFor(Integer code) { + if (code == null) { + return HttpStatus.OK; + } + return MAPPINGS.getOrDefault(code, HttpStatus.OK); + } + + /** + * 出站点:开关关闭 → 原样返回 body(与改动前同一序列化成败路径); + * 开关打开且 code 在白名单 → 包一层带状态码的 {@code ResponseEntity},响应体一个字节都不改。 + */ + public static Object render(ApiResponse body, Integer code) { + if (!enabledFlag) { + return body; + } + HttpStatus status = statusFor(code); + if (status == HttpStatus.OK || body == null) { + return body; + } + RENDER_COUNT.incrementAndGet(); + if (registry != null) { + registry.counter(METRIC, "code", String.valueOf(code), "httpStatus", + String.valueOf(status.value())).increment(); + } + log.info("{} code={} -> HTTP {}(响应体不变,只改状态行)", ANCHOR, code, status.value()); + return ResponseEntity.status(status).body(body); + } +} diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/exception/GlobalExceptionHandler.java b/backend-java/src/main/java/com/nanri/aiimage/common/exception/GlobalExceptionHandler.java index 526ab839a..5cee1dcea 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/common/exception/GlobalExceptionHandler.java +++ b/backend-java/src/main/java/com/nanri/aiimage/common/exception/GlobalExceptionHandler.java @@ -78,8 +78,8 @@ public class GlobalExceptionHandler { } @ExceptionHandler(BusinessException.class) - public ApiResponse handleBusinessException(BusinessException ex, HttpServletRequest request, - jakarta.servlet.http.HttpServletResponse response) { + public Object handleBusinessException(BusinessException ex, HttpServletRequest request, + jakarta.servlet.http.HttpServletResponse response) { // 停用/删除的成因走响应头而非新业务码:code 必须保持 401,改成新码会同时打断 // 两面前端拦截器与桌面端 app_client/main.py 里按 'code': 401 识别鉴权失败的判定 if (ex instanceof AccountDisabledException) { @@ -103,13 +103,18 @@ public class GlobalExceptionHandler { } if (Integer.valueOf(BusinessCodes.TASK_BUSY).equals(ex.getCode())) { // 锁竞争:必须如实返回失败 + 可重试码,否则 worker 会把「未落库」当成功而停止重试 - return ApiResponse.fail(BusinessCodes.TASK_BUSY, - UserMessages.orFallback(ex.getMessage(), "这个任务正在处理中,请稍后重试")); + return BusinessErrorHttpStatus.render( + ApiResponse.fail(BusinessCodes.TASK_BUSY, + UserMessages.orFallback(ex.getMessage(), "这个任务正在处理中,请稍后重试")), + BusinessCodes.TASK_BUSY); } String userMessage = UserMessages.orFallback(ex.getMessage(), chineseFallbackFor(ex.getCode())); + // 状态码出口只在 BusinessErrorHttpStatus 的开关为 true 时才改 HTTP 行;开关关时 render 原样 + // 返回同一个 ApiResponse 实例,序列化路径与 2026-10-09 之前逐字节一致(评审「交互 5.5」项 4, + // 翻真的开启动作要用户拍:三个前端的拦截器先要能吃非 200 + 同形响应体)。 return ex.getCode() == null - ? ApiResponse.fail(userMessage) - : ApiResponse.fail(ex.getCode(), userMessage); + ? BusinessErrorHttpStatus.render(ApiResponse.fail(userMessage), null) + : BusinessErrorHttpStatus.render(ApiResponse.fail(ex.getCode(), userMessage), ex.getCode()); } @ExceptionHandler(NoResourceFoundException.class) diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/task/TaskStatuses.java b/backend-java/src/main/java/com/nanri/aiimage/common/task/TaskStatuses.java new file mode 100644 index 000000000..ff576a21e --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/common/task/TaskStatuses.java @@ -0,0 +1,181 @@ +package com.nanri.aiimage.common.task; + +import java.util.List; +import java.util.Map; +import java.util.Set; + +/** + * 任务状态词表的唯一定义点(2026-10-09 评审「流程 6.0」项 2:状态字面量集合散落 33 处/17 文件、没有单一状态机)。 + * + *

先普查再说收口。2026-10-10 自己数出来的实际词表是 4 套自有 + 1 套外部 + 若干模块内小状态机, + * 不是一个"全局状态机"能覆盖的东西,所以这里按表分组,每组各留自己的口径: + *

    + *
  1. {@link FileTask}:{@code biz_file_task.status},大写。12 个客户端模块共用这一张表;
  2. + *
  3. {@link BrandTask}:{@code brand_crawl_tasks.status},小写(该表历史写法就是小写);
  4. + *
  5. {@link Job}:{@code task_file_job.status},结果作业自己的四态;
  6. + *
  7. {@link LoopRun}:{@code price_track_loop_run.status},比上面三套多一个 {@code STOPPED};
  8. + *
  9. 外部词表(Coze 工作流 {@code execute_status} 等,见 + * {@code ImageVideoAsyncTaskService}):不在这里定义——那是别人家的返回值, + * 收进来等于假装我们能改上游。
  10. + *
+ * + *

三条不动的边界(这是本类存在的约束,不是待办): + *

+ * + *

判据在 {@code TaskStatusVocabularyRatchetTest}:新增内联状态集合字面量、新增写死的状态常量声明、 + * 词表成员被改动都会红;现存例外按文件台账化。 + */ +public final class TaskStatuses { + + private TaskStatuses() { + } + + /** + * 词表 1:{@code biz_file_task.status}(大写)。12 个客户端模块的公共状态面。 + * + *

{@code ERROR} 与 {@code COMPLETED} 是历史值:{@code COMPLETED} 并入"成功"口径展示, + * {@code ERROR} 并入"失败"口径展示({@code TaskCenterQueryMapper} 的展开口径), + * 两者都不能从读侧集合里删——删了老行就在任务中心里凭空消失。 + */ + public static final class FileTask { + public static final String PENDING = "PENDING"; + public static final String RUNNING = "RUNNING"; + public static final String SCHEDULED = "SCHEDULED"; + public static final String SUCCESS = "SUCCESS"; + /** {@code SUCCESS} 的历史拼写;展示上已并入成功,读侧必须继续认。 */ + public static final String COMPLETED = "COMPLETED"; + public static final String FAILED = "FAILED"; + /** 失败口径的历史第二拼写(并入"失败"筛选项)。 */ + public static final String ERROR = "ERROR"; + public static final String CANCELLED = "CANCELLED"; + /** + * {@code CANCELLED} 的历史脏值拼写。当前 Java 代码从不写它 + * (实测:全树没有一处把 {@code CANCELED} 写进库),它只可能来自早期 jar/Python 侧留下的行, + * 所以只在读侧接受集合里出现,并由 SQL 的 {@code CASE WHEN} 归一后对外输出。 + */ + public static final String CANCELED = "CANCELED"; + + /** 在跑口径(任务中心「执行中」筛选项与"卡住"判定的同一集合)。 */ + public static final Set ACTIVE = Set.of(PENDING, RUNNING, SCHEDULED); + /** {@link #ACTIVE} 的固定顺序版:展开成 SQL {@code IN} 列表时文本要可断言。 */ + public static final List ACTIVE_ORDERED = List.of(PENDING, RUNNING, SCHEDULED); + + /** 终态集合(历史脏拼写 {@link #CANCELED} 也在内,少一个就有一行永远收不了尾)。 */ + public static final Set TERMINAL = Set.of(SUCCESS, FAILED, CANCELLED, CANCELED); + + /** 「跑完了」的可数口径(各模块历史页 success/failed 计数用;不含 {@code CANCELED},是原口径,别顺手加宽)。 */ + public static final List FINISHED_ORDERED = List.of(SUCCESS, FAILED); + + /** 前端「成功」筛选项的展开口径:{@code COMPLETED ≡ SUCCESS}。 */ + public static final List SUCCESS_VIEW_ORDERED = List.of(SUCCESS, COMPLETED); + + /** 前端「失败」筛选项的展开口径:{@code ERROR} 与取消都按「没成功」并入失败。 */ + public static final List FAILED_VIEW_ORDERED = List.of(FAILED, ERROR, CANCELLED); + + private FileTask() { + } + } + + /** + * 词表 2:{@code brand_crawl_tasks.status}(小写)。这张表从建表起状态就是小写, + * 与 {@link FileTask} 不是一个字符集,混用会让 brand 任务在 UNION 口径里整批消失。 + */ + public static final class BrandTask { + public static final String PENDING = "pending"; + public static final String RUNNING = "running"; + public static final String SUCCESS = "success"; + public static final String FAILED = "failed"; + /** brand 侧唯一的取消拼写就是这个小写;{@code canceled} 全树没有第二处写点。 */ + public static final String CANCELLED = "cancelled"; + + public static final Set ACTIVE = Set.of(PENDING, RUNNING); + public static final List ACTIVE_ORDERED = List.of(PENDING, RUNNING); + public static final Set TERMINAL = Set.of(SUCCESS, FAILED, CANCELLED); + public static final List TERMINAL_ORDERED = List.of(CANCELLED, FAILED, SUCCESS); + + private BrandTask() { + } + } + + /** 词表 3:{@code task_file_job.status}——结果作业四态,比任务少一个取消态。 */ + public static final class Job { + public static final String PENDING = "PENDING"; + public static final String RUNNING = "RUNNING"; + public static final String SUCCESS = "SUCCESS"; + public static final String FAILED = "FAILED"; + + /** 在跑口径(作业还在等结果)。 */ + public static final List ACTIVE_ORDERED = List.of(PENDING, RUNNING); + /** 可重跑口径:待办 + 失败但没打满重试次数。全树有 6 处,都是这一对。 */ + public static final List RETRYABLE_ORDERED = List.of(PENDING, FAILED); + + private Job() { + } + } + + /** 词表 4:{@code price_track_loop_run.status}——轮次运行态,比 {@link FileTask} 多一个 {@code STOPPED}。 */ + public static final class LoopRun { + public static final String RUNNING = "RUNNING"; + public static final String SUCCESS = "SUCCESS"; + public static final String FAILED = "FAILED"; + public static final String STOPPED = "STOPPED"; + + /** 轮次终态(巡检按这一组判"这一轮不会再自己动了")。 */ + public static final Set TERMINAL = Set.of(SUCCESS, FAILED, STOPPED); + + private LoopRun() { + } + } + + /** + * 取消拼写的归一映射——只用来判断,不用来改写值:不改库、不改对外字符串。 + * 键是"读到的原始值",值是"归一后的规范拼写"。 + * + *

为什么只做取消这一对:实测全树只有 {@code CANCELED}/{@code CANCELLED} 存在同义双拼, + * 其余(SUCCESS/COMPLETED、ERROR/FAILED)是并入展示口径而不是拼写错误, + * 混进同一张归一表会把"历史值"洗成"错别字",后面就没人敢信库值了。 + */ + public static final Map CANCEL_SPELLINGS = Map.of( + "CANCELED", FileTask.CANCELLED, + "CANCELLED", FileTask.CANCELLED, + "canceled", BrandTask.CANCELLED, + "cancelled", BrandTask.CANCELLED); + + /** 是不是"取消"这一族(两种拼写、大小写都认);用于判定,不用于改写。 */ + public static boolean isCancelSpelling(String status) { + return status != null && CANCEL_SPELLINGS.containsKey(status); + } + + /** + * 归一到规范拼写:两种取消拼写各归各家(大写值归 {@code CANCELLED}、小写值归 {@code cancelled}), + * 其它状态原样返回。 + * + *

刻意不做大小写统一:{@link FileTask} 是大写表、{@link BrandTask} 是小写表, + * 一刀切 upper/lower 会 cross 到对方词表里去。 + */ + public static String canonicalizeCancel(String status) { + String mapped = status == null ? null : CANCEL_SPELLINGS.get(status); + return mapped == null ? status : mapped; + } + + /** + * 大写词表的全部去重后取值(判据用它核对"没有第五套")。 + * + *

注意这里必须是去重集合:{@code Job.PENDING} 与 {@code FileTask.PENDING} 是同一个字符串, + * 直接 {@code Set.of(全部常量)} 会在类初始化时抛 {@code duplicate element}—— + * 这条判据 2026-10-10 就是这么被抓红的,留着当例子。 + */ + public static Set allUppercaseStatuses() { + return Set.copyOf(java.util.Arrays.asList( + FileTask.PENDING, FileTask.RUNNING, FileTask.SCHEDULED, FileTask.SUCCESS, + FileTask.COMPLETED, FileTask.FAILED, FileTask.ERROR, FileTask.CANCELLED, + FileTask.CANCELED, LoopRun.STOPPED)); + } +} diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/util/LockSkipWitness.java b/backend-java/src/main/java/com/nanri/aiimage/common/util/LockSkipWitness.java new file mode 100644 index 000000000..a1f495611 --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/common/util/LockSkipWitness.java @@ -0,0 +1,182 @@ +package com.nanri.aiimage.common.util; + +import io.micrometer.core.instrument.Gauge; +import io.micrometer.core.instrument.MeterRegistry; +import lombok.extern.slf4j.Slf4j; +import org.springframework.beans.factory.ObjectProvider; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.stereotype.Component; + +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ConcurrentMap; +import java.util.concurrent.atomic.AtomicLong; + +/** + * 分布式锁「没拿到就跳过」的可聚合出口(2026-10-09 评审「稳定 5.5」项)。 + * + *

此前 {@code if (lockHandle == null) { continue; }} 在全树有 27 处(12 个文件), + * 一处日志都不留。表现是:巡检任务每轮都跑、锁竞争越激烈被跳过的任务越多,而现网看不出任何痕迹 + * ——卡死任务没被收尾、结果作业没被续跑,日志里连一行都没有,只能靠人肉反推。跟 + * {@code TaskFileJobPublisher} 的 MQ 降级是同一个病:那条已经补了 {@code task.file.job.mq.degraded} + * 计数出口,这批锁跳过出口是它的同类。 + * + *

所以这里定的不是"把级别调大",而是可聚合: + *

+ * + *

{@code point} 是稳定字面量(形如 {@code brand:stale-running-scan}),不锚行号: + * 方法搬家、加几行注释都不该让一条已经在响的告警变成孤儿。新增调用点请同步 + * {@code LockSkipWitnessTest} 里的点位台账。 + * + *

静态 API 是有意的:这 12 个 Service 清一色 {@code @RequiredArgsConstructor}, + * 塞一个实例字段等于改 12 个构造器签名、打断几十支 {@code new XxxService(...)} 的既有判据。 + * 注册表由 Spring 在启动时绑一次({@link #LockSkipWitness});没起 Spring 的单测照样能调 + * {@link #record},台账与日志都不依赖容器。 + */ +@Slf4j +@Component +public class LockSkipWitness { + + /** 巡检/判据用的日志锚点。改这条字面量等于把现网告警规则删掉,动之前先对巡检。 */ + public static final String ANCHOR = "[lock-skip]"; + + /** 指标名:tag {@code point}/{@code outcome}/{@code moduleType}。 */ + public static final String METRIC = "aiimage.distributed.lock.skip"; + + /** outcome:循环里跳过这一项,后面还有别的(巡检批量扫描)。 */ + public static final String OUTCOME_SKIPPED = "skipped"; + + /** outcome:整次调用直接返回,本轮什么都没用做(含 try-with-resources 里锁没拿到)。 */ + public static final String OUTCOME_ABANDONED = "abandoned"; + + /** outcome:调用方没给结果类型——单独成桶,不折叠进上面两个真桶。 */ + public static final String OUTCOME_UNKNOWN = "unknown"; + + /** 台账键上限:point 是有限集合(调用点数),超上限后不再新增键,防无界增长。 */ + static final int LEDGER_KEYS_MAX = 256; + + private static final ConcurrentMap LEDGER = new ConcurrentHashMap<>(); + private static final AtomicLong TOTAL = new AtomicLong(); + + /** 可为 null:没配 Micrometer 注册表时只留日志 + 本地台账。 */ + private static volatile MeterRegistry registry; + + public LockSkipWitness() { + } + + /** 生产接线:注册表可选,缺席时不影响跳过语义与日志。 */ + @Autowired + public LockSkipWitness(ObjectProvider meterRegistryProvider) { + bind(meterRegistryProvider == null ? null : meterRegistryProvider.getIfAvailable()); + } + + /** 供 Spring 构造与单测显式接线;null 表示只用日志与本地台账。 */ + public static void bind(MeterRegistry meterRegistry) { + registry = meterRegistry; + if (meterRegistry != null) { + // 计数器按 point 现建现取,注册一次总览 gauge,便于「一个 point 都没命中」也能看到 0。 + Gauge.builder(METRIC + ".total", TOTAL, AtomicLong::get).register(meterRegistry); + } + } + + /** + * 记一次「没拿到锁所以跳过/放弃」。 + * + * @param point 稳定点位字面量(不要用行号/方法名+行号拼) + * @param outcome {@link #OUTCOME_SKIPPED} 或 {@link #OUTCOME_ABANDONED} + * @param moduleType 业务模块类型,可为 null(归一为 unknown) + * @param taskId 任务 id,可为 null + */ + public static void record(String point, String outcome, String moduleType, Long taskId) { + String key = point == null || point.isBlank() ? "unpointed" : point.trim(); + // outcome 缺失归一到 unknown 而不是猜一个真桶:折叠进 skipped/abandoned 会让聚合面说谎。 + String normalizedOutcome = outcome == null || outcome.isBlank() ? OUTCOME_UNKNOWN : outcome.trim(); + String normalizedModule = moduleType == null || moduleType.isBlank() ? "unknown" : moduleType.trim(); + long count = ledgerOf(key).incrementAndGet(); + long total = TOTAL.incrementAndGet(); + MeterRegistry current = registry; + if (current != null) { + current.counter(METRIC, + "point", key, + "outcome", normalizedOutcome, + "moduleType", normalizedModule) + .increment(); + } + log.warn("{} point={} outcome={} moduleType={} taskId={} skippedSoFar={} total={} —— " + + "未拿到分布式锁,本轮跳过(锁被其它实例持有或锁名不可用)", + ANCHOR, key, normalizedOutcome, normalizedModule, taskId, count, total); + } + + /** 最省事的写法:跳过(skipped)结果 + 不带模块上下文。 */ + public static void recordSkip(String point, String moduleType, Long taskId) { + record(point, OUTCOME_SKIPPED, moduleType, taskId); + } + + /** 最省事的写法:整次放弃(abandoned)结果 + 不带模块上下文。 */ + public static void recordAbandoned(String point, String moduleType, Long taskId) { + record(point, OUTCOME_ABANDONED, moduleType, taskId); + } + + /** 定时任务级作业锁没抢到:整轮直接返回,没有模块/任务上下文。 */ + public static void skipped(String point) { + record(point, OUTCOME_SKIPPED, null, null); + } + + /** 定时任务级作业锁没抢到且方法直接返回:本轮什么都没做。 */ + public static void abandoned(String point) { + record(point, OUTCOME_ABANDONED, null, null); + } + + private static AtomicLong ledgerOf(String key) { + AtomicLong existing = LEDGER.get(key); + if (existing != null) { + return existing; + } + if (LEDGER.size() >= LEDGER_KEYS_MAX) { + // 超出上限:仍计入总量与日志,只是不再为未知点位开新键。 + return LEDGER.computeIfAbsent("overflow", k -> new AtomicLong()); + } + return LEDGER.computeIfAbsent(key, k -> new AtomicLong()); + } + + /** 某个点位累计跳过次数;没记过就是 0。 */ + public static long countOf(String point) { + AtomicLong value = LEDGER.get(point); + return value == null ? 0L : value.get(); + } + + /** 全部点位的累计台账快照(不可变副本,按点位名排序)。 */ + public static Map snapshot() { + Map out = new LinkedHashMap<>(); + LEDGER.entrySet().stream() + .sorted(Map.Entry.comparingByKey()) + .forEach(e -> out.put(e.getKey(), e.getValue().get())); + return Collections.unmodifiableMap(out); + } + + /** 全部点位合计。 */ + public static long total() { + return TOTAL.get(); + } + + /** + * 测试专用:清空台账,返回清理前的快照。 + * + *

生产代码不要调——它会把巡检窗口里的计数抹平,看起来像"这段时间没人被锁挡"。 + * 之所以留着:判据要能钉住"走到这个分支留下了可查记录",而点位是全局静态计数, + * 不清就测不出单次增量(用 delta 也能测,但 27 个点位共用一张表,清一次比 27 处读基线更好读)。 + */ + public static Map resetLedgerForTests() { + Map before = snapshot(); + LEDGER.clear(); + TOTAL.set(0L); + return before; + } +} diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java b/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java index 46fd9d248..41620b2b5 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java +++ b/backend-java/src/main/java/com/nanri/aiimage/config/ClientVersionGuardFilter.java @@ -4,6 +4,7 @@ import com.fasterxml.jackson.databind.ObjectMapper; import com.nanri.aiimage.common.api.ApiResponse; import io.micrometer.core.instrument.Counter; import io.micrometer.core.instrument.MeterRegistry; +import jakarta.annotation.PostConstruct; import jakarta.servlet.FilterChain; import jakarta.servlet.ServletException; import jakarta.servlet.http.HttpServletRequest; @@ -116,6 +117,33 @@ public class ClientVersionGuardFilter extends OncePerRequestFilter { return minSupportedVersion != null && !minSupportedVersion.trim().isEmpty(); } + /** + * 启动自述:把"地板到底在不在跑"打成一条看得见的日志。 + * + *

此前这个类只有代码里的 {@code @Value} 默认值、任何 yml 里都没有这三键,于是"没配置" + * 和"配置成惰性"都长得跟"这个功能不存在"一样——评审数出来就是"版本硬地板出厂即惰性"。 + * 三键现在写进 {@code application.yml} 了,这条自述补上另一半:万一被覆盖回空值 + * (或被紧急回退清空),启动日志里点名说清楚闸门没在跑,而不是安静地跳过每个请求。 + */ + @PostConstruct + void reportFloorState() { + if (!isConfigured()) { + log.warn("[版本地板] 启动自检:min-supported-version 未配置 ⇒ 闸门惰性,逐请求跳过," + + "现网装机版本分布没有任何记账数据(enforce={} rejectUnreported={})", + enforce, rejectUnreported); + return; + } + if (parse(minSupportedVersion) == null) { + log.warn("[版本地板] 启动自检:min-supported-version=\"{}\" 解析不出数字段 ⇒ 全部上报按 " + + "unparsable 记账、永不拒绝,请把配置改回点分数字版本", minSupportedVersion); + return; + } + log.info("[版本地板] 启动自检:最低支持版本={} enforce={}({})rejectUnreported={}", + minSupportedVersion.trim(), enforce, + enforce ? "真拒绝:低于地板的装机会被挡在业务之前" : "记账模式:只计数与打日志,业务响应不变", + rejectUnreported); + } + @Override protected boolean shouldNotFilter(HttpServletRequest request) { return !isConfigured() || !isClientFacing(request.getRequestURI()); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/admin/controller/AdminUserController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/admin/controller/AdminUserController.java index 2c72ff8e5..245d1e446 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/admin/controller/AdminUserController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/admin/controller/AdminUserController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.admin.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.modules.admin.model.dto.AdminUserCreateRequest; import com.nanri.aiimage.modules.admin.model.dto.AdminUserUpdateRequest; import com.nanri.aiimage.modules.admin.model.vo.AdminUserListVo; @@ -33,8 +34,8 @@ public class AdminUserController { @GetMapping("/users") @Operation(summary = "分页查询用户列表") public ApiResponse listUsers(HttpServletRequest request, - @RequestParam(required = false, defaultValue = "1") Integer page, - @RequestParam(name = "page_size", required = false, defaultValue = "15") Integer pageSize, + @RequestParam(required = false, defaultValue = PageDefaults.FIRST_PAGE) Integer page, + @RequestParam(name = "page_size", required = false, defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Integer pageSize, @RequestParam(required = false) String username, @RequestParam(name = "search", required = false) String search, @RequestParam(name = "created_by_id", required = false) Long createdById, diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/controller/AppearancePatentController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/controller/AppearancePatentController.java index 034725048..5404c0aca 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/controller/AppearancePatentController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/controller/AppearancePatentController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.appearancepatent.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentParseRequest; import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentSubmitResultRequest; @@ -72,7 +73,7 @@ public class AppearancePatentController { @Parameter(description = "当前用户 ID,用于查询该用户自己的历史记录。", required = true, example = "1") @RequestParam("user_id") Long userId, @Parameter(description = "历史记录条数,默认 50,最大 100", example = "50") - @RequestParam(value = "limit", required = false, defaultValue = "50") Integer limit, + @RequestParam(value = "limit", required = false, defaultValue = PageDefaults.DEFAULT_RESULT_LIMIT) Integer limit, HttpServletRequest httpRequest) { userId = adminAuthSupport.resolveOwnershipUserId(httpRequest, userId); // 上限钳制(2026-09):文档写"最大 100"但此前无实际校验 diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentTaskService.java index ed0268147..2508ef787 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentTaskService.java @@ -12,6 +12,7 @@ import com.nanri.aiimage.modules.appearancepatent.service.support.AppearancePate import com.nanri.aiimage.common.exception.TaskOwnerMismatchException; import com.nanri.aiimage.common.service.DistributedJobLockService; import com.nanri.aiimage.common.util.GroupResultPropagator; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.common.util.FailedStatusRowFilter; import com.nanri.aiimage.common.util.StaleTaskDeathReason; import com.nanri.aiimage.config.AppearancePatentProperties; @@ -651,6 +652,7 @@ public class AppearancePatentTaskService { TaskDistributedLockService.LockHandle lockHandle = acquireTaskLock(task.getId(), 0L); if (lockHandle == null) { // 锁被 owner 实例/文件任务 worker 占用说明其仍活跃,静默跳过等下一轮 + LockSkipWitness.recordSkip("appearance-patent:running-stale-scan", MODULE_TYPE, task.getId()); continue; } try (lockHandle) { @@ -666,6 +668,7 @@ public class AppearancePatentTaskService { } TaskDistributedLockService.LockHandle lockHandle = acquireTaskLock(taskId, 0L); if (lockHandle == null) { + LockSkipWitness.recordAbandoned("appearance-patent:debug-finalize-stale", MODULE_TYPE, taskId); return; } try (lockHandle) { @@ -794,6 +797,8 @@ public class AppearancePatentTaskService { } TaskDistributedLockService.LockHandle neverReportedLock = acquireTaskLock(task.getId(), 0L); if (neverReportedLock == null) { + LockSkipWitness.recordSkip("appearance-patent:never-reported-stale-scan", + MODULE_TYPE, task.getId()); continue; } try (neverReportedLock) { @@ -817,6 +822,7 @@ public class AppearancePatentTaskService { } TaskDistributedLockService.LockHandle lockHandle = acquireTaskLock(task.getId(), 0L); if (lockHandle == null) { + LockSkipWitness.recordSkip("appearance-patent:no-result-shard-stale-scan", MODULE_TYPE, task.getId()); continue; } try (lockHandle) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskExpiredStopSpiImpl.java b/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskExpiredStopSpiImpl.java index 4132ecb8b..6b31d6262 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskExpiredStopSpiImpl.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskExpiredStopSpiImpl.java @@ -19,9 +19,13 @@ import java.util.List; @RequiredArgsConstructor public class BrandTaskExpiredStopSpiImpl implements ExpiredAccountTaskStopSpi { - private static final String STATUS_PENDING = "pending"; - private static final String STATUS_RUNNING = "running"; - private static final String STATUS_CANCELLED = "cancelled"; + // 词表唯一出处:TaskStatuses.BrandTask(brand_crawl_tasks 状态是小写)。 + private static final String STATUS_PENDING = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.PENDING; + private static final String STATUS_RUNNING = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.RUNNING; + private static final String STATUS_CANCELLED = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.CANCELLED; private final BrandCrawlTaskMapper brandCrawlTaskMapper; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskService.java index 801bfc2b5..b5d969626 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskService.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.brand.service; import com.nanri.aiimage.common.util.UserMessages; +import com.nanri.aiimage.common.util.LockSkipWitness; import cn.hutool.core.io.FileUtil; import cn.hutool.json.JSONUtil; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; @@ -101,11 +102,18 @@ public class BrandTaskService { return BLOCKED_SOURCE_HOSTS.contains(normalized) || normalized.endsWith(".localhost"); } private static final long RESULT_SUBMIT_WAIT_MILLIS = 5 * 60 * 1000L; - private static final String STATUS_PENDING = "pending"; - private static final String STATUS_RUNNING = "running"; - private static final String STATUS_SUCCESS = "success"; - private static final String STATUS_FAILED = "failed"; - private static final String STATUS_CANCELLED = "cancelled"; + // 状态词表唯一出处见 com.nanri.aiimage.common.task.TaskStatuses.BrandTask(brand_crawl_tasks 是小写表)。 + // 这里只留别名,不再抄字面量:这张表的值一旦和任务中心 UNION 的口径漂了,brand 任务会整批静默消失。 + private static final String STATUS_PENDING = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.PENDING; + private static final String STATUS_RUNNING = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.RUNNING; + private static final String STATUS_SUCCESS = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.SUCCESS; + private static final String STATUS_FAILED = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.FAILED; + private static final String STATUS_CANCELLED = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.CANCELLED; private static final String MODULE_TYPE = "BRAND"; /** 结果文件并发上传数:OSS/MinIO 上传互不依赖,3 并发平衡收益与内存占用。 */ private static final int RESULT_UPLOAD_CONCURRENCY = 3; @@ -1537,6 +1545,7 @@ public class BrandTaskService { for (BrandCrawlTaskEntity task : runningTasks) { TaskDistributedLockService.LockHandle taskLockHandle = acquireTaskLock(task.getId(), 0L); if (taskLockHandle == null) { + LockSkipWitness.recordSkip("brand:stale-running-scan", MODULE_TYPE, task.getId()); continue; } try (taskLockHandle) { @@ -1597,6 +1606,7 @@ public class BrandTaskService { for (BrandCrawlTaskEntity task : runningTasks) { TaskDistributedLockService.LockHandle taskLockHandle = acquireTaskLock(task.getId(), 0L); if (taskLockHandle == null) { + LockSkipWitness.recordSkip("brand:long-running-scan", MODULE_TYPE, task.getId()); continue; } try (taskLockHandle) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskStaleRepairSpiImpl.java b/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskStaleRepairSpiImpl.java index 49ce69421..1400d1984 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskStaleRepairSpiImpl.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/brand/service/BrandTaskStaleRepairSpiImpl.java @@ -18,9 +18,13 @@ import java.util.List; @RequiredArgsConstructor public class BrandTaskStaleRepairSpiImpl implements BrandTaskStaleRepairSpi { - private static final String STATUS_PENDING = "pending"; - private static final String STATUS_RUNNING = "running"; - private static final String STATUS_FAILED = "failed"; + // 词表唯一出处:TaskStatuses.BrandTask(brand_crawl_tasks 状态是小写)。 + private static final String STATUS_PENDING = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.PENDING; + private static final String STATUS_RUNNING = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.RUNNING; + private static final String STATUS_FAILED = + com.nanri.aiimage.common.task.TaskStatuses.BrandTask.FAILED; private final BrandCrawlTaskMapper brandCrawlTaskMapper; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/controller/CollectDataController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/controller/CollectDataController.java index 934f596ae..14e83f638 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/controller/CollectDataController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/controller/CollectDataController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.collectdata.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.collectdata.model.dto.CollectDataCountryPreferenceSaveRequest; import com.nanri.aiimage.modules.collectdata.model.dto.CollectDataParseRequest; @@ -88,9 +89,9 @@ public class CollectDataController { @Parameter(description = "用户 ID,可选;传入时会校验任务归属") @RequestParam(value = "user_id", required = false) Long userId, @Parameter(description = "页码,从 1 开始", example = "1") - @RequestParam(value = "page", required = false, defaultValue = "1") Integer page, + @RequestParam(value = "page", required = false, defaultValue = PageDefaults.FIRST_PAGE) Integer page, @Parameter(description = "每页条数,默认 50,最大 200", example = "50") - @RequestParam(value = "page_size", required = false, defaultValue = "50") Integer pageSize, + @RequestParam(value = "page_size", required = false, defaultValue = PageDefaults.TASK_LIST_PAGE_SIZE) Integer pageSize, HttpServletRequest httpRequest) { userId = adminAuthSupport.resolveOwnershipUserId(httpRequest, userId); return ApiResponse.success(service.getItemsPage(taskId, userId, page, pageSize)); @@ -121,7 +122,7 @@ public class CollectDataController { @Parameter(description = "当前用户 ID", required = true, example = "1") @RequestParam("user_id") Long userId, @Parameter(description = "返回数量上限,默认 50,最大 100", example = "50") - @RequestParam(value = "limit", required = false, defaultValue = "50") Integer limit, + @RequestParam(value = "limit", required = false, defaultValue = PageDefaults.DEFAULT_RESULT_LIMIT) Integer limit, HttpServletRequest httpRequest) { userId = adminAuthSupport.resolveOwnershipUserId(httpRequest, userId); return ApiResponse.success(service.history(userId, limit)); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/service/CollectDataService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/service/CollectDataService.java index 6d91ad8ab..4fd2838c7 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/service/CollectDataService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/collectdata/service/CollectDataService.java @@ -12,6 +12,7 @@ import com.nanri.aiimage.common.exception.BusinessCodes; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.util.ExcelStreamReader; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.modules.asincache.service.AsinResultCacheService; import com.nanri.aiimage.modules.collectdata.mapper.CollectDataCountryPrefMapper; import com.nanri.aiimage.modules.collectdata.mapper.CollectDataItemMapper; @@ -568,6 +569,7 @@ public class CollectDataService { try (TaskDistributedLockService.LockHandle lock = taskDistributedLockService.acquire(MODULE_TYPE, taskId, 0L)) { if (lock == null) { + LockSkipWitness.recordAbandoned("collect-data:stale-finalize", MODULE_TYPE, taskId); return; } FileTaskEntity task = fileTaskMapper.selectById(taskId); @@ -674,6 +676,7 @@ public class CollectDataService { try (TaskDistributedLockService.LockHandle lock = taskDistributedLockService.acquire(MODULE_TYPE, taskId, 0L)) { if (lock == null) { + LockSkipWitness.recordAbandoned("collect-data:no-upload-stale-finalize", MODULE_TYPE, taskId); return; } FileTaskEntity task = fileTaskMapper.selectById(taskId); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/dedupe/controller/DedupeTotalDataController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/dedupe/controller/DedupeTotalDataController.java index 5d272e6d1..39cd01681 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/dedupe/controller/DedupeTotalDataController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/dedupe/controller/DedupeTotalDataController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.dedupe.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.security.DeviceSessionPolicy; @@ -78,8 +79,8 @@ public class DedupeTotalDataController { @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = DedupeTotalDataPageVo.class))) }) public ApiResponse page( - @Parameter(description = "页码") @RequestParam(name = "page", defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(name = "page_size", defaultValue = "15") Long pageSize, + @Parameter(description = "页码") @RequestParam(name = "page", defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(name = "page_size", defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "数据值模糊搜索关键字") @RequestParam(name = "keyword", required = false) String keyword, @Parameter(description = "用户名模糊搜索关键字") @RequestParam(name = "username", required = false) String username, @Parameter(description = "开始日期(包含)") diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/service/DeleteBrandStaleTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/service/DeleteBrandStaleTaskService.java index 6654f8a6e..778bd7564 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/service/DeleteBrandStaleTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/service/DeleteBrandStaleTaskService.java @@ -3,6 +3,7 @@ package com.nanri.aiimage.modules.deletebrand.service; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper; import com.nanri.aiimage.common.service.DistributedJobLockService; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.config.DeleteBrandProgressProperties; import com.nanri.aiimage.modules.appearancepatent.service.AppearancePatentTaskService; import com.nanri.aiimage.modules.brand.service.BrandTaskService; @@ -236,6 +237,8 @@ public class DeleteBrandStaleTaskService { TaskDistributedLockService.LockHandle taskLockHandle = acquireTaskLock(MODULE_TYPE_DELETE_BRAND, task.getId()); if (taskLockHandle == null) { + LockSkipWitness.recordSkip("delete-brand:stale-heartbeat-scan", + MODULE_TYPE_DELETE_BRAND, task.getId()); continue; } boolean finalizeThrew; @@ -947,6 +950,8 @@ public class DeleteBrandStaleTaskService { for (FileTaskEntity task : runningTasks) { TaskDistributedLockService.LockHandle taskLockHandle = acquireTaskLock(MODULE_TYPE_DELETE_BRAND, task.getId()); if (taskLockHandle == null) { + LockSkipWitness.recordSkip("delete-brand:partial-result-scan", + MODULE_TYPE_DELETE_BRAND, task.getId()); continue; } try (taskLockHandle) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/devicelog/controller/AdminDeviceLogController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/devicelog/controller/AdminDeviceLogController.java index 1e305e8c8..52235f6c7 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/devicelog/controller/AdminDeviceLogController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/devicelog/controller/AdminDeviceLogController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.devicelog.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.model.entity.AdminUserEntity; import com.nanri.aiimage.common.security.AdminAuthSupport; @@ -66,8 +67,8 @@ public class AdminDeviceLogController { @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate, @Parameter(description = "结束日期(含)") @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate, - @RequestParam(defaultValue = "1") Long page, - @RequestParam(defaultValue = "20") Long pageSize, + @RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Long page, + @RequestParam(defaultValue = PageDefaults.ADMIN_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "公司 ID(超管 tab;不传=不筛)") @RequestParam(name = "company_id", required = false) Long companyId) { AdminUserEntity operator = requireSuperAdmin(request); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/imagehistory/controller/ImageHistoryController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/imagehistory/controller/ImageHistoryController.java index e7d0d8aa5..45b90c2a2 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/imagehistory/controller/ImageHistoryController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/imagehistory/controller/ImageHistoryController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.imagehistory.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.service.DataReadScope; @@ -34,8 +35,8 @@ public class ImageHistoryController { @GetMapping("/history") @Operation(summary = "分页查询所有用户生成历史") public ApiResponse listHistory(HttpServletRequest request, - @RequestParam(required = false, defaultValue = "1") Integer page, - @RequestParam(name = "page_size", required = false, defaultValue = "15") Integer pageSize, + @RequestParam(required = false, defaultValue = PageDefaults.FIRST_PAGE) Integer page, + @RequestParam(name = "page_size", required = false, defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Integer pageSize, @RequestParam(name = "user_id", required = false) Long userId, @RequestParam(name = "time_start", required = false) String timeStart, @RequestParam(name = "time_end", required = false) String timeEnd, diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/controller/AdminImageVideoTaskController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/controller/AdminImageVideoTaskController.java index 1ba09c1ef..35dfd2c06 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/controller/AdminImageVideoTaskController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/controller/AdminImageVideoTaskController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.imagevideo.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.model.entity.AdminUserEntity; import com.nanri.aiimage.common.service.DataReadScope; @@ -78,8 +79,8 @@ public class AdminImageVideoTaskController { @GetMapping @Operation(summary = "分页查询图生视频任务", description = "管理端按用户/任务状态/提交时间等条件分页查询近 3 天的工作流任务") public ApiResponse> page( - @RequestParam(defaultValue = "1") Integer page, - @RequestParam(name = "page_size", defaultValue = "20") Integer pageSize, + @RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Integer page, + @RequestParam(name = "page_size", defaultValue = PageDefaults.ADMIN_LIST_PAGE_SIZE) Integer pageSize, @RequestParam(name = "user_id", required = false) Long userId, @RequestParam(required = false) String username, @RequestParam(required = false) String status, diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/service/ImageVideoArchiveService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/service/ImageVideoArchiveService.java index 3b3fa3c14..b5e029ec2 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/service/ImageVideoArchiveService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/service/ImageVideoArchiveService.java @@ -5,6 +5,7 @@ import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper; import com.fasterxml.jackson.core.type.TypeReference; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.config.ImageVideoProperties; import com.nanri.aiimage.common.service.DistributedJobLockService; import com.nanri.aiimage.modules.file.service.oss.OssStorageService; @@ -115,6 +116,7 @@ public class ImageVideoArchiveService { DistributedJobLockService.LockHandle jobLock = distributedJobLockService.tryLock( "image-video:retention-cleanup", java.time.Duration.ofMinutes(20)); if (jobLock == null) { + LockSkipWitness.abandoned("image-video:retention-cleanup"); return; } try (jobLock) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/service/ImageVideoAsyncTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/service/ImageVideoAsyncTaskService.java index 107f0980d..0ae3ffff0 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/service/ImageVideoAsyncTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/imagevideo/service/ImageVideoAsyncTaskService.java @@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper; import com.fasterxml.jackson.core.type.TypeReference; import com.fasterxml.jackson.databind.ObjectMapper; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.exception.TaskOwnerMismatchException; import com.nanri.aiimage.config.InstanceMetadata; @@ -141,6 +142,7 @@ public class ImageVideoAsyncTaskService { DistributedJobLockService.LockHandle jobLock = distributedJobLockService.tryLock("image-video:dispatch", java.time.Duration.ofSeconds(5)); if (jobLock == null) { + LockSkipWitness.abandoned("image-video:dispatch"); return; } try (jobLock) { @@ -163,6 +165,7 @@ public class ImageVideoAsyncTaskService { DistributedJobLockService.LockHandle jobLock = distributedJobLockService.tryLock("image-video:poll", java.time.Duration.ofSeconds(30)); if (jobLock == null) { + LockSkipWitness.abandoned("image-video:poll"); return; } try (jobLock) { @@ -208,6 +211,7 @@ public class ImageVideoAsyncTaskService { DistributedJobLockService.LockHandle jobLock = distributedJobLockService.tryLock("image-video:owner-takeover", java.time.Duration.ofSeconds(30)); if (jobLock == null) { + LockSkipWitness.abandoned("image-video:owner-takeover"); return; } try (jobLock) { @@ -244,6 +248,7 @@ public class ImageVideoAsyncTaskService { DistributedJobLockService.LockHandle jobLock = distributedJobLockService.tryLock("image-video:failed-task-cleanup", java.time.Duration.ofSeconds(120)); if (jobLock == null) { + LockSkipWitness.abandoned("image-video:failed-task-cleanup"); return; } try (jobLock) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/invalidasin/controller/InvalidAsinDataController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/invalidasin/controller/InvalidAsinDataController.java index e7edef89b..99b85389e 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/invalidasin/controller/InvalidAsinDataController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/invalidasin/controller/InvalidAsinDataController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.invalidasin.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.security.DeviceSessionPolicy; @@ -57,8 +58,8 @@ public class InvalidAsinDataController { @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = InvalidAsinDataPageVo.class))) }) public ApiResponse page( - @Parameter(description = "页码") @RequestParam(name = "page", defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(name = "page_size", defaultValue = "15") Long pageSize, + @Parameter(description = "页码") @RequestParam(name = "page", defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(name = "page_size", defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "模糊搜索关键字") @RequestParam(name = "keyword", required = false) String keyword, @Parameter(description = "ASIN 模糊搜索") @RequestParam(name = "data_value", required = false) String dataValue, @Parameter(description = "品牌模糊搜索") @RequestParam(name = "brand", required = false) String brand, diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/notification/controller/AdminNotificationController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/notification/controller/AdminNotificationController.java index db4c345f3..750a025aa 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/notification/controller/AdminNotificationController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/notification/controller/AdminNotificationController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.notification.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.notification.model.dto.NotificationPageQuery; import com.nanri.aiimage.modules.notification.model.vo.NotificationPageVo; @@ -49,8 +50,8 @@ public class AdminNotificationController { + "startDate/endDate 为年月日闭区间。") public ApiResponse page( HttpServletRequest request, - @Parameter(description = "页码") @RequestParam(defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(defaultValue = "20") Long pageSize, + @Parameter(description = "页码") @RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(defaultValue = PageDefaults.ADMIN_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "只看未读") @RequestParam(required = false, defaultValue = "false") Boolean onlyUnread, @Parameter(description = "关键字(标题/内容)") @RequestParam(required = false) String keyword, @Parameter(description = "类型大类:system_error/task_error/config_error/system_notice") diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/notification/controller/NotificationController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/notification/controller/NotificationController.java index 63765029d..4ca69931b 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/notification/controller/NotificationController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/notification/controller/NotificationController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.notification.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.notification.model.dto.NotificationPageQuery; import com.nanri.aiimage.modules.notification.model.vo.NotificationPageVo; @@ -49,8 +50,8 @@ public class NotificationController { + "startDate/endDate 为年月日闭区间。") public ApiResponse page( HttpServletRequest request, - @Parameter(description = "页码") @RequestParam(defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(defaultValue = "20") Long pageSize, + @Parameter(description = "页码") @RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(defaultValue = PageDefaults.ADMIN_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "只看未读") @RequestParam(required = false, defaultValue = "false") Boolean onlyUnread, @Parameter(description = "关键字(标题/内容)") @RequestParam(required = false) String keyword, @Parameter(description = "类型大类:system_error/task_error/config_error/system_notice") diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/patroldelete/service/PatrolDeleteTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/patroldelete/service/PatrolDeleteTaskService.java index b50c568a3..fe8b24444 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/patroldelete/service/PatrolDeleteTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/patroldelete/service/PatrolDeleteTaskService.java @@ -105,7 +105,8 @@ public class PatrolDeleteTaskService { validateUserId(userId); ProductRiskDashboardVo vo = new ProductRiskDashboardVo(); vo.setCandidateCount(patrolDeleteResolveService.countCandidates(userId)); - vo.setProcessedTaskCount(countTasks(userId, List.of("SUCCESS", "FAILED"))); + vo.setProcessedTaskCount(countTasks(userId, + com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED)); vo.setSuccessTaskCount(countTasks(userId, List.of("SUCCESS"))); vo.setFailedTaskCount(countTasks(userId, List.of("FAILED"))); return vo; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/controller/PriceTrackController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/controller/PriceTrackController.java index 1f81661f3..5b4fda0f9 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/controller/PriceTrackController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/controller/PriceTrackController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.pricetrack.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.pricetrack.model.dto.PriceTrackCandidateAddRequest; import com.nanri.aiimage.modules.pricetrack.model.dto.PriceTrackCountryPreferenceSaveRequest; @@ -142,9 +143,9 @@ public class PriceTrackController { @Parameter(description = "任务编号", required = true, example = "200") @PathVariable Long taskId, @Parameter(description = "页码,从 1 开始", example = "1") - @RequestParam(value = "page", defaultValue = "1") Integer page, + @RequestParam(value = "page", defaultValue = PageDefaults.FIRST_PAGE) Integer page, @Parameter(description = "每页条数,默认 1000,最大 2000", example = "1000") - @RequestParam(value = "page_size", defaultValue = "1000") Integer pageSize, + @RequestParam(value = "page_size", defaultValue = PageDefaults.FULL_EXPORT_PAGE_SIZE) Integer pageSize, @Parameter(description = "店铺名称过滤条件,可重复传入,也可用英文逗号分隔;仅在任务关联店铺范围内生效", example = "测试店铺A") @RequestParam(value = "shop_name", required = false) List shopNames, @Parameter(description = "国家代码过滤条件,可重复传入,也可用英文逗号分隔;仅在任务国家范围内生效", example = "DE") diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/service/PriceTrackLoopRunStaleService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/service/PriceTrackLoopRunStaleService.java index 41a012a04..cc5ac37fd 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/service/PriceTrackLoopRunStaleService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/service/PriceTrackLoopRunStaleService.java @@ -65,7 +65,8 @@ public class PriceTrackLoopRunStaleService { private static final String STATUS_STOPPED = "STOPPED"; /** 子任务终态集合,与 PriceTrackLoopRunService.isChildTaskTerminal 口径一致。 */ - private static final Set CHILD_TERMINAL_STATUSES = Set.of("SUCCESS", "FAILED", "STOPPED"); + private static final Set CHILD_TERMINAL_STATUSES = + com.nanri.aiimage.common.task.TaskStatuses.LoopRun.TERMINAL; /** 单轮最多扫描的轮次数,其余留给下一轮(每 2 分钟一次),避免一次扫太多拖慢巡检。 */ static final int MAX_LOOP_RUNS_PER_SCAN = 200; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/service/PriceTrackTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/service/PriceTrackTaskService.java index 1af7b667a..d35e2dd34 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/service/PriceTrackTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/pricetrack/service/PriceTrackTaskService.java @@ -142,7 +142,8 @@ public class PriceTrackTaskService { Long processed = fileTaskMapper.selectCount(new LambdaQueryWrapper() .eq(FileTaskEntity::getModuleType, MODULE_TYPE) .eq(FileTaskEntity::getUserId, userId) - .in(FileTaskEntity::getStatus, List.of("SUCCESS", "FAILED"))); + .in(FileTaskEntity::getStatus, + com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED)); Long success = fileTaskMapper.selectCount(new LambdaQueryWrapper() .eq(FileTaskEntity::getModuleType, MODULE_TYPE) .eq(FileTaskEntity::getUserId, userId) diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/productcategory/controller/ProductCategoryController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/productcategory/controller/ProductCategoryController.java index 5f142a067..e79b9dc77 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/productcategory/controller/ProductCategoryController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/productcategory/controller/ProductCategoryController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.productcategory.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.model.entity.AdminUserEntity; import com.nanri.aiimage.common.util.DownloadHeaderUtil; import com.nanri.aiimage.common.security.AdminAuthSupport; @@ -61,8 +62,8 @@ public class ProductCategoryController { public ApiResponse children( HttpServletRequest request, @RequestParam(value = "parent_id", required = false) Long parentId, - @RequestParam(value = "page", defaultValue = "1") Long page, - @RequestParam(value = "page_size", defaultValue = "20") Long pageSize) { + @RequestParam(value = "page", defaultValue = PageDefaults.FIRST_PAGE) Long page, + @RequestParam(value = "page_size", defaultValue = PageDefaults.ADMIN_LIST_PAGE_SIZE) Long pageSize) { requireOperator(request); return ApiResponse.success(productCategoryService.children(parentId, page, pageSize)); } @@ -72,8 +73,8 @@ public class ProductCategoryController { public ApiResponse search( HttpServletRequest request, @RequestParam(value = "keyword", required = false) String keyword, - @RequestParam(value = "page", defaultValue = "1") Long page, - @RequestParam(value = "page_size", defaultValue = "20") Long pageSize) { + @RequestParam(value = "page", defaultValue = PageDefaults.FIRST_PAGE) Long page, + @RequestParam(value = "page_size", defaultValue = PageDefaults.ADMIN_LIST_PAGE_SIZE) Long pageSize) { requireOperator(request); return ApiResponse.success(productCategoryService.search(keyword, page, pageSize)); } diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/productrisk/service/ProductRiskTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/productrisk/service/ProductRiskTaskService.java index da094d006..eaf680886 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/productrisk/service/ProductRiskTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/productrisk/service/ProductRiskTaskService.java @@ -128,7 +128,8 @@ public class ProductRiskTaskService { Long processed = fileTaskMapper.selectCount(new LambdaQueryWrapper() .eq(FileTaskEntity::getModuleType, MODULE_TYPE) .eq(FileTaskEntity::getUserId, userId) - .in(FileTaskEntity::getStatus, List.of("SUCCESS", "FAILED"))); + .in(FileTaskEntity::getStatus, + com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED)); Long success = fileTaskMapper.selectCount(new LambdaQueryWrapper() .eq(FileTaskEntity::getModuleType, MODULE_TYPE) .eq(FileTaskEntity::getUserId, userId) diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/publish/controller/PublishController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/publish/controller/PublishController.java index e2c253724..f3f3fdeb0 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/publish/controller/PublishController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/publish/controller/PublishController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.publish.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.publish.model.dto.PublishParseRequest; import com.nanri.aiimage.modules.publish.model.dto.PublishSubmitResultRequest; @@ -94,9 +95,9 @@ public class PublishController { @Parameter(description = "任务内文件 ID", required = true, example = "9101") @RequestParam("file_id") Long fileId, @Parameter(description = "页码,从 1 开始", example = "1") - @RequestParam(value = "page", defaultValue = "1") Integer page, + @RequestParam(value = "page", defaultValue = PageDefaults.FIRST_PAGE) Integer page, @Parameter(description = "每页条数,默认 50,最大 200", example = "50") - @RequestParam(value = "page_size", defaultValue = "50") Integer pageSize, + @RequestParam(value = "page_size", defaultValue = PageDefaults.TASK_LIST_PAGE_SIZE) Integer pageSize, HttpServletRequest httpRequest) { return ApiResponse.success(publishTaskService.getItemsPage(taskId, adminAuthSupport.resolveOwnershipUserId(httpRequest, userId), fileId, page, pageSize)); @@ -164,7 +165,7 @@ public class PublishController { @Parameter(description = "当前登录用户 ID;服务端按会话身份校验,与登录账号不一致即拒绝", required = true, example = "1") @RequestParam("user_id") Long userId, @Parameter(description = "返回数量上限,默认 50,最大 100", example = "50") - @RequestParam(value = "limit", defaultValue = "50") Integer limit, + @RequestParam(value = "limit", defaultValue = PageDefaults.DEFAULT_RESULT_LIMIT) Integer limit, HttpServletRequest httpRequest) { // 上限钳制(2026-09):文档写"最多返回 100 条"但此前无实际校验 int safeLimit = limit == null ? 100 : Math.min(Math.max(1, limit), 100); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/publish/service/PublishTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/publish/service/PublishTaskService.java index 2a900a543..60c262fca 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/publish/service/PublishTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/publish/service/PublishTaskService.java @@ -12,6 +12,7 @@ import com.fasterxml.jackson.databind.ObjectMapper; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.exception.TaskOwnerMismatchException; import com.nanri.aiimage.common.security.AdminAuthSupport; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.config.InstanceMetadata; import com.nanri.aiimage.modules.file.service.LocalFileStorageService; import com.nanri.aiimage.modules.file.service.oss.OssStorageService; @@ -103,7 +104,7 @@ public class PublishTaskService { * PENDING/RUNNING 绝不在此列;PUBLISH 实际只会写 SUCCESS/FAILED,取消态是无害的超集。 */ private static final Set RETENTION_TERMINAL_STATUSES = - Set.of(STATUS_SUCCESS, STATUS_FAILED, "CANCELLED", "CANCELED"); + com.nanri.aiimage.common.task.TaskStatuses.FileTask.TERMINAL; private static final DateTimeFormatter TIME_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); private final LocalFileStorageService localFileStorageService; @@ -520,6 +521,7 @@ public class PublishTaskService { try (TaskDistributedLockService.LockHandle lock = taskDistributedLockService.acquire(MODULE_TYPE, candidate.getId(), 0L)) { if (lock == null) { + LockSkipWitness.recordSkip("publish:stale-heartbeat-scan", MODULE_TYPE, candidate.getId()); continue; } transactionTemplate.executeWithoutResult(status -> failStaleTaskLocked(candidate.getId(), threshold)); @@ -967,6 +969,7 @@ public class PublishTaskService { try (TaskDistributedLockService.LockHandle lock = taskDistributedLockService.acquire(MODULE_TYPE, candidate.getId(), 0L)) { if (lock == null) { + LockSkipWitness.recordAbandoned("publish:no-upload-stale-finalize", MODULE_TYPE, candidate.getId()); return; } transactionTemplate.executeWithoutResult(status -> failStaleTaskLockedInternal( diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/queryasin/service/QueryAsinTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/queryasin/service/QueryAsinTaskService.java index 0aa2e2e15..ef93145b6 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/queryasin/service/QueryAsinTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/queryasin/service/QueryAsinTaskService.java @@ -116,7 +116,8 @@ public class QueryAsinTaskService { validateUserId(userId); ProductRiskDashboardVo vo = new ProductRiskDashboardVo(); vo.setCandidateCount(queryAsinResolveService.countCandidates(userId)); - vo.setProcessedTaskCount(countTasks(userId, List.of("SUCCESS", "FAILED"))); + vo.setProcessedTaskCount(countTasks(userId, + com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED)); vo.setSuccessTaskCount(countTasks(userId, List.of("SUCCESS"))); vo.setFailedTaskCount(countTasks(userId, List.of("FAILED"))); return vo; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/controller/ShopDataCrawlTaskController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/controller/ShopDataCrawlTaskController.java index 07f507232..cc9df7d96 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/controller/ShopDataCrawlTaskController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/controller/ShopDataCrawlTaskController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.shopdatacrawl.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.productrisk.model.dto.ProductRiskCandidateAddRequest; import com.nanri.aiimage.modules.productrisk.model.dto.ProductRiskCountryPreferenceSaveRequest; @@ -158,9 +159,9 @@ public class ShopDataCrawlTaskController { in = ParameterIn.QUERY, example = "1") @RequestParam("user_id") Long userId, @Parameter(name = "page", description = "页号,从 1 开始", in = ParameterIn.QUERY, example = "1") - @RequestParam(value = "page", defaultValue = "1") int page, + @RequestParam(value = "page", defaultValue = PageDefaults.FIRST_PAGE) int page, @Parameter(name = "limit", description = "每页条数,最大 100;默认 100 与旧版返回最近 100 条的行为一致", in = ParameterIn.QUERY, example = "20") - @RequestParam(value = "limit", defaultValue = "100") int limit, + @RequestParam(value = "limit", defaultValue = PageDefaults.ADMIN_SCAN_LIMIT) int limit, HttpServletRequest httpRequest) { userId = adminAuthSupport.resolveOwnershipUserId(httpRequest, userId); return ApiResponse.success(taskService.listHistory(userId, page, limit)); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/service/ShopDataCrawlTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/service/ShopDataCrawlTaskService.java index 7d27ae97c..7eb1cd731 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/service/ShopDataCrawlTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/service/ShopDataCrawlTaskService.java @@ -345,7 +345,8 @@ public class ShopDataCrawlTaskService { validateUserId(userId); ProductRiskDashboardVo vo = new ProductRiskDashboardVo(); vo.setCandidateCount(shopDataCrawlResolveService.countCandidates(userId)); - vo.setProcessedTaskCount(countTasks(userId, List.of("SUCCESS", "FAILED"))); + vo.setProcessedTaskCount(countTasks(userId, + com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED)); vo.setSuccessTaskCount(countTasks(userId, List.of("SUCCESS"))); vo.setFailedTaskCount(countTasks(userId, List.of("FAILED"))); return vo; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/QueryAsinController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/QueryAsinController.java index 9e598ff0d..5377c11eb 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/QueryAsinController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/QueryAsinController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.shopkey.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.util.DownloadHeaderUtil; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.security.DeviceSessionPolicy; @@ -60,8 +61,8 @@ public class QueryAsinController { @Operation(summary = "分页查询 ASIN", description = "company_id 只收窄可见集、不放大,跨公司查看仅超管") public ApiResponse page( HttpServletRequest request, - @Parameter(description = "页码") @RequestParam(name = "page", defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(name = "page_size", defaultValue = "15") Long pageSize, + @Parameter(description = "页码") @RequestParam(name = "page", defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(name = "page_size", defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "分组ID") @RequestParam(name = "group_id", required = false) Long groupId, @Parameter(description = "店铺名") @RequestParam(name = "shop_name", required = false) String shopName, @Parameter(description = "商品 ASIN") @RequestParam(name = "asin", required = false) String asin, diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/ShopKeyController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/ShopKeyController.java index 44ed9f747..0a8c22204 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/ShopKeyController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/ShopKeyController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.shopkey.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.model.entity.AdminUserEntity; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.service.DataReadScope; @@ -58,8 +59,8 @@ public class ShopKeyController { }) public ApiResponse page( HttpServletRequest request, - @Parameter(description = "页码") @RequestParam(defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(defaultValue = "15") Long pageSize, + @Parameter(description = "页码") @RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "按公司筛选(仅超管生效;非超管一律按会话公司裁剪)") @RequestParam(name = "company_id", required = false) Long companyId, @Parameter(description = "备注名 / 紫鸟账号 模糊词") diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/ShopManageController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/ShopManageController.java index 68b13bfa7..af551446b 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/ShopManageController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/ShopManageController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.shopkey.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.security.DeviceSessionPolicy; import com.nanri.aiimage.common.model.entity.AdminUserEntity; @@ -79,8 +80,8 @@ public class ShopManageController { }) public ApiResponse page( HttpServletRequest request, - @Parameter(description = "页码") @RequestParam(defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(defaultValue = "15") Long pageSize, + @Parameter(description = "页码") @RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "分组 ID") @RequestParam(required = false) Long groupId, @Parameter(description = "店铺名称") @RequestParam(required = false) String shopName, @Parameter(description = "公司 ID") @RequestParam(name = "company_id", required = false) Long companyId) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/SkipPriceAsinController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/SkipPriceAsinController.java index c4399ca67..9530ca7ba 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/SkipPriceAsinController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopkey/controller/SkipPriceAsinController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.shopkey.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.util.DownloadHeaderUtil; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.security.DeviceSessionPolicy; @@ -60,8 +61,8 @@ public class SkipPriceAsinController { @Operation(summary = "分页查询跳过跟价 ASIN", description = "支持按分组、店铺名、ASIN 和当前操作人可见范围筛选。") public ApiResponse page( HttpServletRequest request, - @Parameter(description = "页码") @RequestParam(name = "page", defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(name = "page_size", defaultValue = "15") Long pageSize, + @Parameter(description = "页码") @RequestParam(name = "page", defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(name = "page_size", defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Long pageSize, @Parameter(description = "分组 ID") @RequestParam(name = "group_id", required = false) Long groupId, @Parameter(description = "店铺名称") @RequestParam(name = "shop_name", required = false) String shopName, @Parameter(description = "商品 ASIN") @RequestParam(name = "asin", required = false) String asin, diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/controller/ShopMatchController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/controller/ShopMatchController.java index c5afac0a9..5e9ee4a0a 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/controller/ShopMatchController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/controller/ShopMatchController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.shopmatch.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.productrisk.model.dto.ProductRiskCandidateAddRequest; import com.nanri.aiimage.modules.productrisk.model.dto.ProductRiskCountryPreferenceSaveRequest; @@ -186,9 +187,9 @@ public class ShopMatchController { public ApiResponse getTaskSkipAsinsPaginated( @Parameter(description = "任务编号", required = true, example = "200") @PathVariable Long taskId, @Parameter(description = "页码,从 1 开始", example = "1") - @RequestParam(value = "page", defaultValue = "1") Integer page, + @RequestParam(value = "page", defaultValue = PageDefaults.FIRST_PAGE) Integer page, @Parameter(description = "每页条数,默认 1000,最大 2000", example = "1000") - @RequestParam(value = "page_size", defaultValue = "1000") Integer pageSize, + @RequestParam(value = "page_size", defaultValue = PageDefaults.FULL_EXPORT_PAGE_SIZE) Integer pageSize, @Parameter(description = "店铺名称过滤条件,可重复传入,也可用英文逗号分隔", example = "测试店铺A") @RequestParam(value = "shop_name", required = false) List shopNames, @Parameter(description = "国家代码过滤条件,可重复传入,也可用英文逗号分隔", example = "DE") diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/service/ShopMatchTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/service/ShopMatchTaskService.java index 52b87246d..f1d6d4125 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/service/ShopMatchTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopmatch/service/ShopMatchTaskService.java @@ -204,7 +204,8 @@ public class ShopMatchTaskService { Long processed = fileTaskMapper.selectCount(new LambdaQueryWrapper() .eq(FileTaskEntity::getModuleType, MODULE_TYPE) .eq(FileTaskEntity::getUserId, userId) - .in(FileTaskEntity::getStatus, List.of("SUCCESS", "FAILED"))); + .in(FileTaskEntity::getStatus, + com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED)); Long success = fileTaskMapper.selectCount(new LambdaQueryWrapper() .eq(FileTaskEntity::getModuleType, MODULE_TYPE) .eq(FileTaskEntity::getUserId, userId) diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/controller/SimilarAsinController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/controller/SimilarAsinController.java index f147aecbf..37aa36c33 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/controller/SimilarAsinController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/controller/SimilarAsinController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.similarasin.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.modules.similarasin.model.dto.SimilarAsinFilterConditionAddRequest; import com.nanri.aiimage.modules.similarasin.model.dto.SimilarAsinParseRequest; @@ -129,7 +130,7 @@ public class SimilarAsinController { @Parameter(description = "当前用户 ID", required = true, example = "1") @RequestParam("user_id") Long userId, @Parameter(description = "历史记录条数,默认 50,最大 100", example = "50") - @RequestParam(value = "limit", required = false, defaultValue = "50") Integer limit, + @RequestParam(value = "limit", required = false, defaultValue = PageDefaults.DEFAULT_RESULT_LIMIT) Integer limit, HttpServletRequest httpRequest) { userId = adminAuthSupport.resolveOwnershipUserId(httpRequest, userId); return ApiResponse.success(service.history(userId, limit)); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/service/SimilarAsinTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/service/SimilarAsinTaskService.java index e2644737a..5fc8c8ec5 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/service/SimilarAsinTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/service/SimilarAsinTaskService.java @@ -11,6 +11,7 @@ import com.fasterxml.jackson.databind.node.ObjectNode; import com.nanri.aiimage.common.exception.BusinessException; import com.nanri.aiimage.common.exception.TaskOwnerMismatchException; import com.nanri.aiimage.common.security.AdminAuthSupport; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.common.service.DistributedJobLockService; import com.nanri.aiimage.common.util.FailedStatusRowFilter; import com.nanri.aiimage.common.util.StaleTaskDeathReason; @@ -877,6 +878,7 @@ public class SimilarAsinTaskService implements SimilarAsinPipelineHost { TaskDistributedLockService.LockHandle taskLockHandle = ownershipSupport().acquireTaskLock(task.getId(), 0L); if (taskLockHandle == null) { // 锁被 owner 实例/文件任务 worker 占用说明其仍活跃,静默跳过等下一轮(2 分钟后再判) + LockSkipWitness.recordSkip("similar-asin:heartbeat-stale-scan", MODULE_TYPE, task.getId()); continue; } try (taskLockHandle) { @@ -892,6 +894,7 @@ public class SimilarAsinTaskService implements SimilarAsinPipelineHost { } TaskDistributedLockService.LockHandle taskLockHandle = ownershipSupport().acquireTaskLock(taskId, 0L); if (taskLockHandle == null) { + LockSkipWitness.recordAbandoned("similar-asin:debug-finalize-stale", MODULE_TYPE, taskId); return; } try (taskLockHandle) { @@ -1023,6 +1026,7 @@ public class SimilarAsinTaskService implements SimilarAsinPipelineHost { TaskDistributedLockService.LockHandle neverReportedLock = ownershipSupport().acquireTaskLock(task.getId(), 0L); if (neverReportedLock == null) { + LockSkipWitness.recordSkip("similar-asin:never-reported-stale-scan", MODULE_TYPE, task.getId()); continue; } try (neverReportedLock) { @@ -1049,6 +1053,7 @@ public class SimilarAsinTaskService implements SimilarAsinPipelineHost { } TaskDistributedLockService.LockHandle taskLockHandle = ownershipSupport().acquireTaskLock(task.getId(), 0L); if (taskLockHandle == null) { + LockSkipWitness.recordSkip("similar-asin:no-result-shard-stale-scan", MODULE_TYPE, task.getId()); continue; } try (taskLockHandle) { @@ -1488,6 +1493,7 @@ public class SimilarAsinTaskService implements SimilarAsinPipelineHost { DistributedJobLockService.LockHandle lockHandle = distributedJobLockService.tryLock("similar-asin:llm-poll", Duration.ofMinutes(1)); if (lockHandle == null) { + LockSkipWitness.abandoned("similar-asin:llm-poll"); return; } try (lockHandle) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/service/support/SimilarAsinPipelineSupport.java b/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/service/support/SimilarAsinPipelineSupport.java index c86a87709..669a6ad77 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/service/support/SimilarAsinPipelineSupport.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/similarasin/service/support/SimilarAsinPipelineSupport.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.similarasin.service.support; import com.nanri.aiimage.common.util.UserMessages; +import com.nanri.aiimage.common.util.LockSkipWitness; import cn.hutool.crypto.digest.DigestUtil; import com.nanri.aiimage.modules.similarasin.model.dto.SimilarAsinParsedPayloadDto; import com.nanri.aiimage.modules.similarasin.model.dto.SimilarAsinResultGroupDto; @@ -984,6 +985,7 @@ public class SimilarAsinPipelineSupport { taskQueueExecutor.execute(() -> { TaskDistributedLockService.LockHandle taskLockHandle = ownershipSupport.acquireTaskLock(taskId, 0L); if (taskLockHandle == null) { + LockSkipWitness.recordAbandoned("similar-asin:direct-llm-poll-fallback", MODULE_TYPE, taskId); return; } try (taskLockHandle) { @@ -1014,6 +1016,7 @@ public class SimilarAsinPipelineSupport { } TaskDistributedLockService.LockHandle taskLockHandle = ownershipSupport.acquireTaskLock(taskId, 0L); if (taskLockHandle == null) { + LockSkipWitness.recordAbandoned("similar-asin:resubmit-pending-llm-states", MODULE_TYPE, taskId); return; } try (taskLockHandle) { @@ -1484,6 +1487,7 @@ public class SimilarAsinPipelineSupport { } TaskDistributedLockService.LockHandle lockHandle = ownershipSupport.acquireTaskLock(taskId, 0L); if (lockHandle == null) { + LockSkipWitness.recordAbandoned("similar-asin:maybe-finalize-llm-job", MODULE_TYPE, taskId); return; } try (lockHandle) { @@ -1509,6 +1513,7 @@ public class SimilarAsinPipelineSupport { DistributedJobLockService.LockHandle lockHandle = distributedJobLockService.tryLock("similar-asin:llm-finalize:" + taskId, Duration.ofMinutes(5)); if (lockHandle == null) { + LockSkipWitness.recordAbandoned("similar-asin:llm-finalize-job-lock", MODULE_TYPE, taskId); return; } try (lockHandle) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/controller/TaskFileJobController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/controller/TaskFileJobController.java index ef3c56b10..58225e8e7 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/controller/TaskFileJobController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/controller/TaskFileJobController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.task.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.modules.task.model.entity.TaskFileJobEntity; import com.nanri.aiimage.modules.task.service.TaskFileJobService; import io.swagger.v3.oas.annotations.Operation; @@ -30,7 +31,7 @@ public class TaskFileJobController { @RequestParam(value = "status", required = false) String status, @RequestParam(value = "module_type", required = false) String moduleType, @RequestParam(value = "task_id", required = false) Long taskId, - @RequestParam(value = "limit", defaultValue = "100") int limit) { + @RequestParam(value = "limit", defaultValue = PageDefaults.ADMIN_SCAN_LIMIT) int limit) { // 上限钳制(2026-09):该运维端点此前对 limit 无校验 return ApiResponse.success(taskFileJobService.listJobs(status, moduleType, taskId, Math.min(Math.max(1, limit), 1000))); @@ -47,7 +48,7 @@ public class TaskFileJobController { @Operation(summary = "手动扫描并复位卡住的 RUNNING Job") public ApiResponse> resetStuck( @RequestParam(value = "timeout_minutes", defaultValue = "30") int timeoutMinutes, - @RequestParam(value = "limit", defaultValue = "100") int limit) { + @RequestParam(value = "limit", defaultValue = PageDefaults.ADMIN_SCAN_LIMIT) int limit) { int reset = taskFileJobService.resetStuckRunningJobs(timeoutMinutes, limit); return ApiResponse.success(Map.of("reset", reset)); } diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/CompletedTaskActiveJobInspector.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/CompletedTaskActiveJobInspector.java index 3c0f73664..ae7155135 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/CompletedTaskActiveJobInspector.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/CompletedTaskActiveJobInspector.java @@ -40,7 +40,7 @@ public class CompletedTaskActiveJobInspector { public ActiveJobReport inspectTerminalTasksWithActiveJobs(int limit) { List tasks = fileTaskMapper.selectList(new LambdaQueryWrapper() - .in(FileTaskEntity::getStatus, List.of("SUCCESS", "FAILED")) + .in(FileTaskEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED) .orderByAsc(FileTaskEntity::getUpdatedAt) .last("limit " + Math.max(1, Math.min(limit, 500)))); if (tasks == null || tasks.isEmpty()) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/ExpiredAccountTaskStopService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/ExpiredAccountTaskStopService.java index 2fc53577f..a893a0272 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/ExpiredAccountTaskStopService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/ExpiredAccountTaskStopService.java @@ -7,6 +7,7 @@ import com.nanri.aiimage.common.mapper.ShopManageGroupMapper; import com.nanri.aiimage.common.model.entity.AdminUserEntity; import com.nanri.aiimage.common.service.CompanyScopeSupport; import com.nanri.aiimage.common.service.DistributedJobLockService; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.modules.task.mapper.FileTaskMapper; import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity; import com.nanri.aiimage.modules.task.spi.ExpiredAccountTaskStopSpi; @@ -62,6 +63,7 @@ public class ExpiredAccountTaskStopService { public void stopTasksOfExpiredAccounts() { var lock = distributedJobLockService.tryLock("expired-account-task-stop", Duration.ofSeconds(55)); if (lock == null) { + LockSkipWitness.abandoned("expired-account-task-stop"); return; } try (lock) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/InspectionSqlReportTask.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/InspectionSqlReportTask.java index ab6cc9743..a0509df83 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/InspectionSqlReportTask.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/InspectionSqlReportTask.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.task.service; import com.nanri.aiimage.common.service.DistributedJobLockService; +import com.nanri.aiimage.common.util.LockSkipWitness; import com.nanri.aiimage.config.InspectionProperties; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.ObjectProvider; @@ -59,6 +60,7 @@ public class InspectionSqlReportTask { return; } if (distributedJobLockService == null) { + LockSkipWitness.abandoned("inspection:sql-report-lock-service-missing"); return; } DistributedJobLockService.LockHandle lockHandle = diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/ModuleHistoryCleanupService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/ModuleHistoryCleanupService.java index ba5ae6f3e..c71a68589 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/ModuleHistoryCleanupService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/ModuleHistoryCleanupService.java @@ -40,7 +40,8 @@ import java.util.Set; @Service public class ModuleHistoryCleanupService { - private static final Set TERMINAL_STATUSES = Set.of("SUCCESS", "FAILED", "CANCELLED", "CANCELED"); + private static final Set TERMINAL_STATUSES = + com.nanri.aiimage.common.task.TaskStatuses.FileTask.TERMINAL; private static final Duration CLEANUP_LOCK_TTL = Duration.ofHours(2); private static final String COLLECT_DATA_MODULE_TYPE = "COLLECT_DATA"; private static final int DEFAULT_BATCH_SIZE = 500; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskFileJobService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskFileJobService.java index 8926da7fc..a81d62935 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskFileJobService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskFileJobService.java @@ -152,7 +152,7 @@ public class TaskFileJobService { public List listRunnableJobs(int limit) { return taskFileJobMapper.selectList(new LambdaQueryWrapper() - .in(TaskFileJobEntity::getStatus, List.of("PENDING", "FAILED")) + .in(TaskFileJobEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.Job.RETRYABLE_ORDERED) .lt(TaskFileJobEntity::getRetryCount, MAX_RETRY_COUNT) .orderByAsc(TaskFileJobEntity::getUpdatedAt) .last("limit " + Math.max(1, Math.min(limit, 100)))); @@ -178,7 +178,7 @@ public class TaskFileJobService { int safeLimit = Math.max(1, Math.min(limit, 100)); List ownerJobs = taskFileJobMapper.selectList(new LambdaQueryWrapper() - .in(TaskFileJobEntity::getStatus, List.of("PENDING", "FAILED")) + .in(TaskFileJobEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.Job.RETRYABLE_ORDERED) .lt(TaskFileJobEntity::getRetryCount, MAX_RETRY_COUNT) .in(TaskFileJobEntity::getModuleType, List.of("APPEARANCE_PATENT", "SIMILAR_ASIN", "PUBLISH", "SHOP_DATA_CRAWL")) .eq(TaskFileJobEntity::getOwner, normalizedOwner) @@ -188,7 +188,7 @@ public class TaskFileJobService { List candidates = new ArrayList<>(ownerJobs); if (ownerJobs.size() < safeLimit) { LambdaQueryWrapper genericWrapper = new LambdaQueryWrapper() - .in(TaskFileJobEntity::getStatus, List.of("PENDING", "FAILED")) + .in(TaskFileJobEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.Job.RETRYABLE_ORDERED) .lt(TaskFileJobEntity::getRetryCount, MAX_RETRY_COUNT) .and(wrapper -> wrapper .notIn(TaskFileJobEntity::getModuleType, List.of("APPEARANCE_PATENT", "SIMILAR_ASIN", "PUBLISH", "SHOP_DATA_CRAWL")) @@ -236,7 +236,7 @@ public class TaskFileJobService { int safeLimit = Math.max(1, Math.min(limit, 100)); List ownerJobs = taskFileJobMapper.selectList(new LambdaQueryWrapper() - .in(TaskFileJobEntity::getStatus, List.of("PENDING", "FAILED")) + .in(TaskFileJobEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.Job.RETRYABLE_ORDERED) .lt(TaskFileJobEntity::getRetryCount, MAX_RETRY_COUNT) .in(TaskFileJobEntity::getModuleType, List.of("APPEARANCE_PATENT", "SIMILAR_ASIN", "PUBLISH", "SHOP_DATA_CRAWL")) .eq(TaskFileJobEntity::getOwner, normalizedOwner) @@ -248,7 +248,7 @@ public class TaskFileJobService { List jobs = new ArrayList<>(ownerJobs); LambdaQueryWrapper genericWrapper = new LambdaQueryWrapper() - .in(TaskFileJobEntity::getStatus, List.of("PENDING", "FAILED")) + .in(TaskFileJobEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.Job.RETRYABLE_ORDERED) .lt(TaskFileJobEntity::getRetryCount, MAX_RETRY_COUNT) .and(wrapper -> wrapper .notIn(TaskFileJobEntity::getModuleType, List.of("APPEARANCE_PATENT", "SIMILAR_ASIN", "PUBLISH", "SHOP_DATA_CRAWL")) @@ -521,7 +521,7 @@ public class TaskFileJobService { } return taskFileJobMapper.update(null, new LambdaUpdateWrapper() .eq(TaskFileJobEntity::getId, jobId) - .in(TaskFileJobEntity::getStatus, List.of("PENDING", "FAILED")) + .in(TaskFileJobEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.Job.RETRYABLE_ORDERED) .and(wrapper -> wrapper.isNull(TaskFileJobEntity::getRetryCount) .or() .lt(TaskFileJobEntity::getRetryCount, MAX_RETRY_COUNT)) @@ -831,7 +831,7 @@ public class TaskFileJobService { .eq(TaskFileJobEntity::getTaskId, taskId) .eq(TaskFileJobEntity::getModuleType, moduleType) .eq(TaskFileJobEntity::getJobType, JOB_TYPE_ASSEMBLE_RESULT) - .in(TaskFileJobEntity::getStatus, List.of("PENDING", "RUNNING"))); + .in(TaskFileJobEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.Job.ACTIVE_ORDERED)); return count == null ? 0L : count; } diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskProgressSnapshotService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskProgressSnapshotService.java index 959f3a447..e45a6f38c 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskProgressSnapshotService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskProgressSnapshotService.java @@ -21,7 +21,8 @@ import java.util.concurrent.ConcurrentHashMap; @RequiredArgsConstructor public class TaskProgressSnapshotService { - private static final Set TERMINAL_STATUSES = Set.of("SUCCESS", "FAILED", "CANCELLED", "CANCELED"); + private static final Set TERMINAL_STATUSES = + com.nanri.aiimage.common.task.TaskStatuses.FileTask.TERMINAL; private final TaskProgressSnapshotMapper taskProgressSnapshotMapper; private final ObjectMapper objectMapper; diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskResultMissingInspector.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskResultMissingInspector.java index 498e329e1..008480fd4 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskResultMissingInspector.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskResultMissingInspector.java @@ -41,7 +41,7 @@ public class TaskResultMissingInspector { public MissingResultReport inspectTasksMissingResult(int limit) { List tasks = fileTaskMapper.selectList(new LambdaQueryWrapper() - .in(FileTaskEntity::getStatus, List.of("SUCCESS", "FAILED")) + .in(FileTaskEntity::getStatus, com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED) .orderByAsc(FileTaskEntity::getUpdatedAt) .last("limit " + Math.max(1, Math.min(limit, 500)))); if (tasks == null || tasks.isEmpty()) { diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter/mapper/TaskCenterQueryMapper.java b/backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter/mapper/TaskCenterQueryMapper.java index 7dd24adf8..9c2767e16 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter/mapper/TaskCenterQueryMapper.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter/mapper/TaskCenterQueryMapper.java @@ -39,17 +39,17 @@ public interface TaskCenterQueryMapper { + "'SIMILAR_ASIN','COLLECT_DATA','SHOP_DATA_CRAWL'"; /** - * 状态口径的单一来源。{@code @Select} 注解值必须是编译期常量,所以 SQL 里用下面 - * 的字符串字面量、Java 侧判卡住用这里的集合,两者由 - * {@code TaskCenterQueryMapperSqlTest.statusLiteralsStayInSyncWithSets} 守同步。 + * 状态口径的单一来源。{@code @Select} 注解值必须是编译期常量,所以 SQL 里的字符串字面量留在本接口, + * Java 侧判卡住用的集合一律取自 {@link com.nanri.aiimage.common.task.TaskStatuses}(唯一词表), + * 两边由 {@code TaskCenterQueryMapperSqlTest.statusLiteralsStayInSyncWithSets} 守同步。 */ - Set ACTIVE_STATUS_SET = Set.of("PENDING", "RUNNING", "SCHEDULED"); + Set ACTIVE_STATUS_SET = com.nanri.aiimage.common.task.TaskStatuses.FileTask.ACTIVE; /** * {@link #ACTIVE_STATUS_SET} 的固定顺序版本:前端「在跑」筛选项就是这个集合的合并口径, * 展开成 IN 列表后 SQL 文本要可断言({@code Set} 的迭代顺序不保证,不能直接下 SQL)。 */ - List ACTIVE_STATUSES_ORDERED = List.of("PENDING", "RUNNING", "SCHEDULED"); + List ACTIVE_STATUSES_ORDERED = com.nanri.aiimage.common.task.TaskStatuses.FileTask.ACTIVE_ORDERED; /** 状态筛选的合并哨兵值:它不是表里的状态,服务层负责展开成 {@link #ACTIVE_STATUSES_ORDERED}。 */ String ACTIVE_STATUS_SENTINEL = "ACTIVE"; @@ -58,19 +58,21 @@ public interface TaskCenterQueryMapper { * 前端「成功」筛选项的展开口径(2026-10-04 状态三态收敛:只留 执行中/成功/失败): * COMPLETED 是完成态的历史拼写,展示上已并入成功,筛选必须命中同样的行。 */ - List SUCCESS_STATUSES_ORDERED = List.of("SUCCESS", "COMPLETED"); + List SUCCESS_STATUSES_ORDERED = + com.nanri.aiimage.common.task.TaskStatuses.FileTask.SUCCESS_VIEW_ORDERED; /** 前端「失败」筛选项的展开口径:ERROR 与取消/出错都按「没成功」并入失败(SQL 里 CANCELED 已归一为 CANCELLED)。 */ - List FAILED_STATUSES_ORDERED = List.of("FAILED", "ERROR", "CANCELLED"); + List FAILED_STATUSES_ORDERED = + com.nanri.aiimage.common.task.TaskStatuses.FileTask.FAILED_VIEW_ORDERED; /** biz_file_task 终态(CANCELLED 与历史脏值 CANCELED 并存)。 */ - Set TERMINAL_STATUS_SET = Set.of("SUCCESS", "FAILED", "CANCELLED", "CANCELED"); + Set TERMINAL_STATUS_SET = com.nanri.aiimage.common.task.TaskStatuses.FileTask.TERMINAL; /** brand_crawl_tasks 进行中(该表状态小写)。 */ - Set BRAND_ACTIVE_STATUS_SET = Set.of("pending", "running"); + Set BRAND_ACTIVE_STATUS_SET = com.nanri.aiimage.common.task.TaskStatuses.BrandTask.ACTIVE; /** brand_crawl_tasks 终态。 */ - Set BRAND_TERMINAL_STATUS_SET = Set.of("success", "failed", "cancelled"); + Set BRAND_TERMINAL_STATUS_SET = com.nanri.aiimage.common.task.TaskStatuses.BrandTask.TERMINAL; /** * 逐行把「规范化后的店铺名」写进 {@code biz_file_result.source_filename} 的模块白名单 diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/usersecret/controller/AdminUserApiSecretController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/usersecret/controller/AdminUserApiSecretController.java index a828b3d51..cbf9a25dd 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/usersecret/controller/AdminUserApiSecretController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/usersecret/controller/AdminUserApiSecretController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.usersecret.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.config.UserSecretProperties; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.service.DataReadScope; @@ -55,8 +56,8 @@ public class AdminUserApiSecretController { @Parameter(description = "行级状态筛选:passed/failed/incomplete/error/unknown") @RequestParam(required = false) String checkStatus, @Parameter(description = "按数据权限分组筛选(仅超管生效)") @RequestParam(name = "group_id", required = false) Long groupId, @Parameter(description = "按公司筛选(仅超管生效;非超管一律按会话公司裁剪,越界公司为空页)") @RequestParam(name = "company_id", required = false) Long companyId, - @Parameter(description = "页码") @RequestParam(defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(defaultValue = "15") Long pageSize) { + @Parameter(description = "页码") @RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Long pageSize) { AdminUserEntity operator = adminAuthSupport.requireAdmin(request); AdminUserSecretQuery query = new AdminUserSecretQuery(); query.setKeyword(keyword); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/usersecret/controller/AdminUserSecretUsageController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/usersecret/controller/AdminUserSecretUsageController.java index dcacc58f8..ff0e042ab 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/usersecret/controller/AdminUserSecretUsageController.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/usersecret/controller/AdminUserSecretUsageController.java @@ -1,6 +1,7 @@ package com.nanri.aiimage.modules.usersecret.controller; import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.api.PageDefaults; import com.nanri.aiimage.common.security.AdminAuthSupport; import com.nanri.aiimage.common.service.DataReadScope; import com.nanri.aiimage.common.service.ReadScope; @@ -47,8 +48,8 @@ public class AdminUserSecretUsageController { @Parameter(description = "关键字:用户名") @RequestParam(required = false) String keyword, @Parameter(description = "按数据权限分组筛选(仅超管生效)") @RequestParam(name = "group_id", required = false) Long groupId, @Parameter(description = "按公司筛选(仅超管生效;非超管一律按会话公司裁剪,越界公司为空页)") @RequestParam(name = "company_id", required = false) Long companyId, - @Parameter(description = "页码") @RequestParam(defaultValue = "1") Long page, - @Parameter(description = "每页数量") @RequestParam(defaultValue = "15") Long pageSize) { + @Parameter(description = "页码") @RequestParam(defaultValue = PageDefaults.FIRST_PAGE) Long page, + @Parameter(description = "每页数量") @RequestParam(defaultValue = PageDefaults.USER_LIST_PAGE_SIZE) Long pageSize) { AdminUserEntity operator = adminAuthSupport.requireAdmin(request); AdminUserSecretUsageQuery query = new AdminUserSecretUsageQuery(); query.setStartDate(startDate); diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/withdraw/service/WithdrawTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/withdraw/service/WithdrawTaskService.java index 4db7ff933..d0186a6f3 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/withdraw/service/WithdrawTaskService.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/withdraw/service/WithdrawTaskService.java @@ -91,7 +91,8 @@ public class WithdrawTaskService { validateUserId(userId); ProductRiskDashboardVo vo = new ProductRiskDashboardVo(); vo.setCandidateCount(withdrawResolveService.countCandidates(userId)); - vo.setProcessedTaskCount(countTasks(userId, List.of("SUCCESS", "FAILED"))); + vo.setProcessedTaskCount(countTasks(userId, + com.nanri.aiimage.common.task.TaskStatuses.FileTask.FINISHED_ORDERED)); vo.setSuccessTaskCount(countTasks(userId, List.of("SUCCESS"))); vo.setFailedTaskCount(countTasks(userId, List.of("FAILED"))); return vo; diff --git a/backend-java/src/main/resources/application.yml b/backend-java/src/main/resources/application.yml index 16cdc535c..37b330a8b 100644 --- a/backend-java/src/main/resources/application.yml +++ b/backend-java/src/main/resources/application.yml @@ -114,6 +114,22 @@ aiimage: connect-timeout-millis: ${AIIMAGE_INSTANCE_ROUTE_CONNECT_TIMEOUT_MILLIS:3000} read-timeout-millis: ${AIIMAGE_INSTANCE_ROUTE_READ_TIMEOUT_MILLIS:300000} request-body-cache-limit-bytes: ${AIIMAGE_INSTANCE_ROUTE_REQUEST_BODY_CACHE_LIMIT_BYTES:1048576} + # ===== 客户端版本硬地板(三键显式化,2026-10-09 评审「流程 6.0」)===== + # 此前三键在代码里只有 @Value 默认值、任何 yml 里 0 处 ⇒ "没配置 = 惰性"是出厂默认态, + # 闸门等于不存在。现在把真实默认写在这里:配置存在、行为显式,是否翻真由记账模式量出来的数据决定。 + client-version: + # 最低支持的桌面客户端版本。取 4.0.47:它是第一个真会带 X-Client-Version 上报的装机 + # (4.0.46 及更早不发这个头,落在 unreported 桶里,不算"低于地板")。 + # 现网最新包是 app_client/version.txt 的 4.0.48。留空 = 整个闸门惰性(shouldNotFilter 直接跳过), + # 那正是紧急回退开关,也是启动时会被点名的一种状态(见 ClientVersionGuardFilter 的启动自述)。 + min-supported-version: ${AIIMAGE_CLIENT_VERSION_MIN_SUPPORTED_VERSION:4.0.47} + # false = 记账模式:低于地板的版本只进 aiimage.client.version.floor 指标 + + # 每个 (verdict,version) 至多一条 [版本地板] WARN,业务响应逐字节不变。 + # 这一档的作用是把"翻 true 会打到多少台、是哪几个版本"量出来,量完再拍板。 + enforce: ${AIIMAGE_CLIENT_VERSION_ENFORCE:false} + # false = 完全不报版本的老客户端(≤4.0.46)只进 unreported 计数、不挨拒。 + # 翻 true 等于用一次配置变更把存量装机全线打停,必须先看完 enforce=false 的记账数据。 + reject-unreported: ${AIIMAGE_CLIENT_VERSION_REJECT_UNREPORTED:false} oss: region: ${AIIMAGE_OSS_REGION:us-east-1} endpoint: ${AIIMAGE_OSS_ENDPOINT:https://oss.aishufu.top} @@ -272,6 +288,15 @@ aiimage: max-batches-per-run: ${AIIMAGE_TASK_IMAGE_CACHE_CLEANUP_MAX_BATCHES_PER_RUN:200} max-bytes: ${AIIMAGE_TASK_IMAGE_CACHE_CLEANUP_MAX_BYTES:2147483648} target-bytes: ${AIIMAGE_TASK_IMAGE_CACHE_CLEANUP_TARGET_BYTES:1073741824} + # ===== 业务失败的 HTTP 状态码出口(2026-10-09 评审「交互 5.5」项 4)===== + # 现状:1,242 处业务失败全部以 HTTP 200 出(GlobalExceptionHandler 的 BusinessException 出口没有 + # @ResponseStatus)。映射表白名单在 BusinessErrorHttpStatus 里,本键只决定"要不要真改状态行"。 + # 默认 false:响应体与状态行都和改动前逐字节一致。翻 true 之前必须先确认三个前端的拦截器 + # 能吃非 200 + 同形响应体(admin-frontend-vue/src/api/envelope.ts 已同时读 status/code, + # frontend-vue 与桌面端 app_client 本面无证据)——这个开启动作由人拍,不由这行配置替人做完。 + api: + business-error-http-status: + enabled: ${AIIMAGE_API_BUSINESS_ERROR_HTTP_STATUS_ENABLED:false} result-file-job: mq-enabled: ${AIIMAGE_RESULT_FILE_JOB_MQ_ENABLED:true} topic: ${AIIMAGE_RESULT_FILE_JOB_TOPIC:aiimage-result-file-job} diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/api/PageDefaultsLedgerTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/api/PageDefaultsLedgerTest.java new file mode 100644 index 000000000..b60139719 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/api/PageDefaultsLedgerTest.java @@ -0,0 +1,258 @@ +package com.nanri.aiimage.common.api; + +import static org.assertj.core.api.Assertions.assertThat; + +import com.nanri.aiimage.testutil.SourceScan; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Comparator; +import java.util.List; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Stream; +import org.junit.jupiter.api.Test; + +/** + * 分页/条数默认值的逐点台账 + 棘轮(2026-10-09 评审「可读 5.0 / 交互 5.5」项 5)。 + * + *

评审量到的是"15/20/50/1000 四种并存、31 处 {@code defaultValue}"。本轮实测更细: + * 数字型 {@code defaultValue} 共 49 处,其中 48 处是分页/条数口径(21 处页码 + 27 处容量与上限), + * 另有 1 处是 {@code timeout_minutes=30},不是分页。 + * + *

这里不规定"全局统一默认页容量"——把 15/20/50/1000 拍成一个数是改行为。判据只做两件事: + *

    + *
  1. 每个出站点当前用什么默认值,逐点钉死({@link #LEDGER}):改任一页的默认值会红, + * 新加分页参数没登记也会红;
  2. + *
  3. 同一个语义(page / page_size / limit)不许冒出台账之外的第二个默认值。
  4. + *
+ * + *

重跑:{@code mvn -o test -Dtest=PageDefaultsLedgerTest}(cwd = backend-java)。 + */ +class PageDefaultsLedgerTest { + + private static final Pattern NUMERIC_DEFAULT = Pattern.compile("defaultValue\\s*=\\s*\"([0-9]+)\""); + private static final Pattern CONST_DEFAULT = Pattern.compile("defaultValue\\s*=\\s*PageDefaults\\.([A-Z_]+)"); + private static final Pattern NAMED_PARAM = Pattern.compile("(?:name|value)\\s*=\\s*\"([a-z_]+)\""); + private static final Pattern TRAILING_VAR = Pattern.compile("\\b([A-Za-z_][A-Za-z0-9_]*)\\s*\\)?\\s*[,{)]?\\s*(?://.*)?$"); + + /** + * 出站点台账:{@code 文件#参数 -> 该页当前默认值的具名出处}。 + * 48 条,逐条对应一次真实翻页行为;加页要登记,改值要表态。 + */ + private static final List LEDGER = List.of( + "AdminUserController.java#page=FIRST_PAGE", + "AdminUserController.java#page_size=USER_LIST_PAGE_SIZE", + "AdminUserApiSecretController.java#page=FIRST_PAGE", + "AdminUserApiSecretController.java#pageSize=USER_LIST_PAGE_SIZE", + "AdminUserSecretUsageController.java#page=FIRST_PAGE", + "AdminUserSecretUsageController.java#pageSize=USER_LIST_PAGE_SIZE", + "AdminDeviceLogController.java#page=FIRST_PAGE", + "AdminDeviceLogController.java#pageSize=ADMIN_LIST_PAGE_SIZE", + "AdminImageVideoTaskController.java#page=FIRST_PAGE", + "AdminImageVideoTaskController.java#page_size=ADMIN_LIST_PAGE_SIZE", + "AdminNotificationController.java#page=FIRST_PAGE", + "AdminNotificationController.java#pageSize=ADMIN_LIST_PAGE_SIZE", + "AppearancePatentController.java#limit=DEFAULT_RESULT_LIMIT", + "CollectDataController.java#page=FIRST_PAGE", + "CollectDataController.java#page_size=TASK_LIST_PAGE_SIZE", + "CollectDataController.java#limit=DEFAULT_RESULT_LIMIT", + "DedupeTotalDataController.java#page=FIRST_PAGE", + "DedupeTotalDataController.java#page_size=USER_LIST_PAGE_SIZE", + "ImageHistoryController.java#page=FIRST_PAGE", + "ImageHistoryController.java#page_size=USER_LIST_PAGE_SIZE", + "InvalidAsinDataController.java#page=FIRST_PAGE", + "InvalidAsinDataController.java#page_size=USER_LIST_PAGE_SIZE", + "NotificationController.java#page=FIRST_PAGE", + "NotificationController.java#pageSize=ADMIN_LIST_PAGE_SIZE", + "PriceTrackController.java#page=FIRST_PAGE", + "PriceTrackController.java#page_size=FULL_EXPORT_PAGE_SIZE", + "ProductCategoryController.java#page=FIRST_PAGE", + "ProductCategoryController.java#page=FIRST_PAGE", + "ProductCategoryController.java#page_size=ADMIN_LIST_PAGE_SIZE", + "ProductCategoryController.java#page_size=ADMIN_LIST_PAGE_SIZE", + "PublishController.java#page=FIRST_PAGE", + "PublishController.java#page_size=TASK_LIST_PAGE_SIZE", + "PublishController.java#limit=DEFAULT_RESULT_LIMIT", + "QueryAsinController.java#page=FIRST_PAGE", + "QueryAsinController.java#page_size=USER_LIST_PAGE_SIZE", + "ShopDataCrawlTaskController.java#page=FIRST_PAGE", + "ShopDataCrawlTaskController.java#limit=ADMIN_SCAN_LIMIT", + "ShopKeyController.java#page=FIRST_PAGE", + "ShopKeyController.java#pageSize=USER_LIST_PAGE_SIZE", + "ShopManageController.java#page=FIRST_PAGE", + "ShopManageController.java#pageSize=USER_LIST_PAGE_SIZE", + "ShopMatchController.java#page=FIRST_PAGE", + "ShopMatchController.java#page_size=FULL_EXPORT_PAGE_SIZE", + "SimilarAsinController.java#limit=DEFAULT_RESULT_LIMIT", + "SkipPriceAsinController.java#page=FIRST_PAGE", + "SkipPriceAsinController.java#page_size=USER_LIST_PAGE_SIZE", + "TaskFileJobController.java#limit=ADMIN_SCAN_LIMIT", + "TaskFileJobController.java#limit=ADMIN_SCAN_LIMIT"); + + /** 不是分页、允许继续写字面量的那 1 处(分钟数,改动它要先看 worker 超时语义)。 */ + private static final List NON_PAGINATION_LITERALS = List.of( + "TaskFileJobController.java#timeout_minutes=LITERAL:30"); + + @Test + void everyPaginationDefaultIsNamedAndLedgered() { + List actual = sites(); + List constants = actual.stream().filter(s -> !s.contains("LITERAL")).sorted().toList(); + + assertThat(constants) + .as("48 处分页/条数出站点的具名默认值必须与台账一一对应") + .isEqualTo(LEDGER.stream().sorted().toList()); + // 同口径非零对照:台账不是空的,扫描器也确实数得出 48 处 + assertThat(constants).hasSize(48); + } + + @Test + void noPaginationOutletStillCarriesABareNumber() { + List literals = sites().stream().filter(s -> s.contains("LITERAL")).sorted().toList(); + assertThat(literals) + .as("还剩字面量的分页点(只许 timeout_minutes 那一条非分页的在这儿)") + .isEqualTo(NON_PAGINATION_LITERALS); + } + + @Test + void oneSemanticCannotGrowASecondDefault() { + List actual = sites(); + assertThat(kindsUsing(actual, "page", "FIRST_PAGE")) + .as("页码口径只有一套:全部从 1 起") + .isEqualTo(21); + for (String kind : List.of("page_size", "pageSize")) { + assertThat(distinctConstants(actual, kind)) + .as(kind + " 的默认容量集合:15/20/50/1000 四种各自登记,新来第五种要红") + .containsExactlyInAnyOrder("USER_LIST_PAGE_SIZE", "ADMIN_LIST_PAGE_SIZE", + "TASK_LIST_PAGE_SIZE", "FULL_EXPORT_PAGE_SIZE"); + } + assertThat(distinctConstants(actual, "limit")) + .as("limit 是「本次最多返回几条」,不许和 page_size 混用同一批常量") + .containsExactlyInAnyOrder("DEFAULT_RESULT_LIMIT", "ADMIN_SCAN_LIMIT"); + // limit 不许出现"页容量家族"的常量,反过来也不行:语义混用会让上限与分页互相打架 + assertThat(actual).noneMatch(s -> s.contains("#limit=") && s.contains("PAGE_SIZE")); + assertThat(actual).noneMatch(s -> (s.contains("#page_size=") || s.contains("#pageSize=")) + && (s.contains("RESULT_LIMIT") || s.contains("SCAN_LIMIT"))); + } + + @Test + void suspiciousFullExportDefaultStaysTwoSitesAndUnchanged() { + // 评审点名的疑似笔误:用户端列表默认 1000(价格追踪 + 店铺匹配两处)。 + // 本轮不改数值,只把它数出来钉住——真要改成 50/100,必须在这里显式表态而不是顺手改掉。 + assertThat(PageDefaults.FULL_EXPORT_PAGE_SIZE).isEqualTo("1000"); + assertThat(sites().stream().filter(s -> s.endsWith("=FULL_EXPORT_PAGE_SIZE")).toList()) + .containsExactlyInAnyOrder( + "PriceTrackController.java#page_size=FULL_EXPORT_PAGE_SIZE", + "ShopMatchController.java#page_size=FULL_EXPORT_PAGE_SIZE"); + } + + @Test + void stringAndIntMirrorsCannotDriftApart() { + // 具名常量给了 String 与 int 两个面,两者一旦漂开,注解上的默认值和代码里的兜底值就不是一个数 + assertPair(PageDefaults.FIRST_PAGE, PageDefaults.FIRST_PAGE_INT); + assertPair(PageDefaults.USER_LIST_PAGE_SIZE, PageDefaults.USER_LIST_PAGE_SIZE_INT); + assertPair(PageDefaults.ADMIN_LIST_PAGE_SIZE, PageDefaults.ADMIN_LIST_PAGE_SIZE_INT); + assertPair(PageDefaults.TASK_LIST_PAGE_SIZE, PageDefaults.TASK_LIST_PAGE_SIZE_INT); + assertPair(PageDefaults.FULL_EXPORT_PAGE_SIZE, PageDefaults.FULL_EXPORT_PAGE_SIZE_INT); + assertPair(PageDefaults.DEFAULT_RESULT_LIMIT, PageDefaults.DEFAULT_RESULT_LIMIT_INT); + assertPair(PageDefaults.ADMIN_SCAN_LIMIT, PageDefaults.ADMIN_SCAN_LIMIT_INT); + } + + @Test + void theFourCoexistingDefaultsAreStillFourDistinctValues() { + // 这条是"没被偷偷统一"的证明:15/20/50/1000 必须仍然互不相等。 + // 如果哪天有人"顺手统一"成一个值,这条会红——那是行为变更,得单独拍板。 + assertThat(PageDefaults.USER_LIST_PAGE_SIZE).isNotEqualTo(PageDefaults.ADMIN_LIST_PAGE_SIZE); + assertThat(PageDefaults.ADMIN_LIST_PAGE_SIZE).isNotEqualTo(PageDefaults.TASK_LIST_PAGE_SIZE); + assertThat(PageDefaults.TASK_LIST_PAGE_SIZE).isNotEqualTo(PageDefaults.FULL_EXPORT_PAGE_SIZE); + assertThat(List.of(PageDefaults.USER_LIST_PAGE_SIZE, PageDefaults.ADMIN_LIST_PAGE_SIZE, + PageDefaults.TASK_LIST_PAGE_SIZE, PageDefaults.FULL_EXPORT_PAGE_SIZE)).doesNotHaveDuplicates(); + } + + // ---------------------------------------------------------------- 助手 + + private static void assertPair(String literal, int mirror) { + assertThat(mirror).as("int 镜像必须等于注解上的字符串值").isEqualTo(Integer.parseInt(literal)); + } + + private static int kindsUsing(List sites, String kind, String constant) { + String needle = "#" + kind + "=" + constant; + return (int) sites.stream().filter(s -> s.contains(needle) && !s.contains("LITERAL")).count(); + } + + private static List distinctConstants(List sites, String kind) { + String needle = "#" + kind + "="; + return sites.stream().filter(s -> s.contains(needle) && !s.contains("LITERAL")) + .map(s -> s.substring(s.indexOf('=') + 1)) + .distinct().sorted().toList(); + } + + /** 扫出全部数字型 defaultValue 出站点,返回 {@code 文件#参数=常量} 或 {@code 文件#参数=LITERAL:值}。 */ + private static List sites() { + List rows = new ArrayList<>(); + for (Path file : mainSources()) { + String name = file.getFileName().toString(); + String source = SourceScan.withoutComments(read(file)); + for (String line : source.split("\n")) { + if (!line.contains("defaultValue")) { + continue; + } + String param = param(line); + Matcher c = CONST_DEFAULT.matcher(line); + if (c.find()) { + rows.add(name + "#" + param + "=" + c.group(1)); + continue; + } + Matcher n = NUMERIC_DEFAULT.matcher(line); + if (n.find()) { + rows.add(name + "#" + param + "=LITERAL:" + n.group(1)); + } + } + } + assertThat(rows).as("数字型/常典型 defaultValue 点位数(扫不到=路径或形状坏了)") + .hasSizeGreaterThanOrEqualTo(49); + return rows; + } + + private static String param(String line) { + Matcher named = NAMED_PARAM.matcher(line); + if (named.find()) { + return named.group(1); + } + Matcher tail = TRAILING_VAR.matcher(line.strip()); + return tail.find() ? tail.group(1) : "?"; + } + + private static List mainSources() { + Path root = moduleRoot().resolve("src/main/java"); + try (Stream walk = Files.walk(root)) { + List files = walk.filter(p -> p.toString().endsWith(".java")) + .sorted(Comparator.comparing(Path::toString)).toList(); + assertThat(files).as("src/main/java 扫到的 .java 数").hasSizeGreaterThan(900); + return files; + } catch (IOException e) { + throw new IllegalStateException("扫描失败: " + root, 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 + ")"); + } + + private static String read(Path file) { + try { + return Files.readString(file); + } catch (IOException e) { + throw new IllegalStateException("读不了 " + file, e); + } + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/exception/BusinessErrorHttpStatusTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/exception/BusinessErrorHttpStatusTest.java new file mode 100644 index 000000000..f19da8fdc --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/exception/BusinessErrorHttpStatusTest.java @@ -0,0 +1,269 @@ +package com.nanri.aiimage.common.exception; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.nanri.aiimage.common.api.ApiResponse; +import com.nanri.aiimage.common.service.TaskOwnerForwardService; +import io.micrometer.core.instrument.simple.SimpleMeterRegistry; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; +import java.io.InputStream; +import java.util.LinkedHashMap; +import java.util.Map; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import org.springframework.boot.env.YamlPropertySourceLoader; +import org.springframework.core.env.EnumerablePropertySource; +import org.springframework.core.env.PropertySource; +import org.springframework.core.io.ClassPathResource; +import org.springframework.http.HttpStatus; +import org.springframework.http.ResponseEntity; + +/** + * 业务码 → 真 HTTP 状态码的映射单点判据(2026-10-09 评审「交互 5.5」项 4,本轮只做安全的一半)。 + * + *

要钉住的三件事,缺一半都不算做完: + *

    + *
  1. 默认关:开关在 {@code application.yml} 里显式写着 false,且关掉时 + * {@link BusinessErrorHttpStatus#render} 返回同一个实例——不是"看起来一样", + * 是根本没构造 {@code ResponseEntity},序列化路径与改动前逐字节相同;
  2. + *
  3. 白名单是封闭的:表外 code(含历史大量不带码的 {@code ApiResponse.fail(message)}) + * 即使开关打开也恒走 200。这条是翻真时唯一的兜底——它保证"打开开关"的爆炸半径 + * 只有白名单里那 13 个码,而不是全部 1,242 处业务失败;
  4. + *
  5. 打开时只改状态行、不改响应体:body 实例不变,成功响应(40901 幂等忽略)不许被拖进映射。
  6. + *
+ * + *

重跑:{@code mvn -o test -Dtest=BusinessErrorHttpStatusTest}(cwd = backend-java)。 + */ +@ExtendWith(MockitoExtension.class) +class BusinessErrorHttpStatusTest { + + private static final Pattern PLACEHOLDER = Pattern.compile("^\\$\\{([^:}]+):([^}]*)\\}$"); + + @Mock private TaskOwnerForwardService taskOwnerForwardService; + @InjectMocks private GlobalExceptionHandler handler; + + @AfterEach + void switchBackOff() { + BusinessErrorHttpStatus.bindForTests(false, null); + } + + // ---------------------------------------------------------------- 1. 默认关 + + @Test + void switchShipsDeclaredAndOffInApplicationYml() { + Map flat = flatten("application.yml"); + assertThat(flat) + .as("开关必须显式写在 yml 里(「没写=隐式默认」就是版本地板踩过的坑)") + .containsKey(BusinessErrorHttpStatus.ENABLED_KEY); + assertThat(defaultOf(flat, BusinessErrorHttpStatus.ENABLED_KEY)).isEqualTo("false"); + // 组件构造时把配置值搬到静态判定上;默认态必须两处一致(两套默认值会漂) + @SuppressWarnings("unchecked") + org.springframework.beans.factory.ObjectProvider provider = + mock(org.springframework.beans.factory.ObjectProvider.class); + when(provider.getIfAvailable()).thenReturn(null); + new BusinessErrorHttpStatus(provider, false); + assertThat(BusinessErrorHttpStatus.isEnabled()) + .as("出厂态就是关:没人拍板之前不该有任何状态码变化") + .isFalse(); + } + + @Test + void disabledRenderReturnsTheExactSameInstance() { + BusinessErrorHttpStatus.bindForTests(false, null); + ApiResponse body = ApiResponse.fail(401, "未登录"); + + Object rendered = BusinessErrorHttpStatus.render(body, 401); + + // 关掉时不是"造一个等价的 ResponseEntity",是根本没造——否则就不是逐字节一致 + assertThat(rendered).isSameAs(body); + assertThat(rendered).isNotInstanceOf(ResponseEntity.class); + } + + // ---------------------------------------------------------------- 2. 白名单封闭 + + @Test + void whitelistIsExactlyThePinnedCodeList() { + assertThat(BusinessErrorHttpStatus.mappings().keySet()) + .as("会被映射成非 200 的 code 清单(改这里=改现网状态码契约,必须点名评审)") + .containsExactlyInAnyOrder(400, 401, 403, 404, 409, 422, 500, 503, + 4011, 4012, 40401, 40902, 40903); + + assertThat(BusinessErrorHttpStatus.statusFor(401)).isEqualTo(HttpStatus.UNAUTHORIZED); + assertThat(BusinessErrorHttpStatus.statusFor(403)).isEqualTo(HttpStatus.FORBIDDEN); + assertThat(BusinessErrorHttpStatus.statusFor(400)).isEqualTo(HttpStatus.BAD_REQUEST); + assertThat(BusinessErrorHttpStatus.statusFor(404)).isEqualTo(HttpStatus.NOT_FOUND); + assertThat(BusinessErrorHttpStatus.statusFor(4011)) + .as("被顶下线:码族是鉴权,翻真后是 401") + .isEqualTo(HttpStatus.UNAUTHORIZED); + assertThat(BusinessErrorHttpStatus.statusFor(4012)) + .as("客户端版本过低:让调用方看见 4xx 而不是 200") + .isEqualTo(HttpStatus.BAD_REQUEST); + assertThat(BusinessErrorHttpStatus.statusFor(BusinessCodes.TASK_BUSY)).isEqualTo(HttpStatus.CONFLICT); + assertThat(BusinessErrorHttpStatus.statusFor(BusinessCodes.TASK_OWNER_FORWARD)) + .isEqualTo(HttpStatus.CONFLICT); + assertThat(BusinessErrorHttpStatus.statusFor(BusinessCodes.TASK_NOT_FOUND)) + .isEqualTo(HttpStatus.NOT_FOUND); + } + + @Test + void idempotentSuccessCodeIsNeverMappedToAnErrorStatus() { + // 40901 在 handler 里是幂等忽略、返回 success=true。它是成功响应, + // 一旦被写进映射表,翻真后"重复提交"会从 200 变 409,客户端会当成失败重试。 + assertThat(BusinessErrorHttpStatus.mappings()) + .as("TASK_ALREADY_FINISHED 不在白名单里") + .doesNotContainKey(BusinessCodes.TASK_ALREADY_FINISHED); + assertThat(BusinessErrorHttpStatus.statusFor(BusinessCodes.TASK_ALREADY_FINISHED)) + .isEqualTo(HttpStatus.OK); + } + + @Test + void codesOutsideTheWhitelistStayOnTwoHundredEvenWhenSwitchIsOn() { + BusinessErrorHttpStatus.bindForTests(true, null); + try { + // 开关开着也不能碰没预料到的码:这是翻真时唯一的爆炸半径上限 + assertThat(BusinessErrorHttpStatus.statusFor(40999)).isEqualTo(HttpStatus.OK); + assertThat(BusinessErrorHttpStatus.statusFor(0)).isEqualTo(HttpStatus.OK); + assertThat(BusinessErrorHttpStatus.statusFor(200)).isEqualTo(HttpStatus.OK); + assertThat(BusinessErrorHttpStatus.statusFor(null)).isEqualTo(HttpStatus.OK); + + ApiResponse body = ApiResponse.fail(40999, "没登记过的业务码"); + assertThat(BusinessErrorHttpStatus.render(body, 40999)).isSameAs(body); + ApiResponse codeless = ApiResponse.fail("历史上大量不带码的失败"); + assertThat(BusinessErrorHttpStatus.render(codeless, null)).isSameAs(codeless); + } finally { + BusinessErrorHttpStatus.bindForTests(false, null); + } + } + + // ---------------------------------------------------------------- 3. 打开时只改状态行 + + @Test + void enabledRenderKeepsBodyInstanceAndOnlyChangesStatusLine() { + SimpleMeterRegistry registry = new SimpleMeterRegistry(); + BusinessErrorHttpStatus.bindForTests(true, registry); + ListAppender captured = capture(); + try { + ApiResponse body = ApiResponse.fail(403, "没有权限"); + Object rendered = BusinessErrorHttpStatus.render(body, 403); + + assertThat(rendered).isInstanceOfSatisfying(ResponseEntity.class, r -> { + assertThat(r.getStatusCode()).isEqualTo(HttpStatus.FORBIDDEN); + assertThat(r.getBody()).as("响应体必须是同一个实例,不改一个字节").isSameAs(body); + }); + + assertThat(captured.list.stream().map(ILoggingEvent::getFormattedMessage).toList()) + .as("改写状态行这件事本身要可 grep、可聚合") + .anySatisfy(line -> assertThat(line) + .contains(BusinessErrorHttpStatus.ANCHOR) + .contains("code=403") + .contains("HTTP 403")); + assertThat(registry.get(BusinessErrorHttpStatus.METRIC) + .tag("code", "403").tag("httpStatus", "403").counter().count()).isEqualTo(1.0); + } finally { + release(captured); + registry.close(); + BusinessErrorHttpStatus.bindForTests(false, null); + } + } + + // ---------------------------------------------------------------- 4. 出口真的接在 handler 上 + + @Test + void handlerKeepsHttpTwoHundredWhileSwitchOff() { + BusinessErrorHttpStatus.bindForTests(false, null); + Object result = handler.handleBusinessException( + new BusinessException(403, "无权访问"), request(), mock(HttpServletResponse.class)); + + // 关掉时 handler 的返回类型都必须是 ApiResponse 本体,不是 ResponseEntity 包一层 + assertThat(result).isInstanceOf(ApiResponse.class); + assertThat(result).isNotInstanceOf(ResponseEntity.class); + ApiResponse body = (ApiResponse) result; + assertThat(body.isSuccess()).isFalse(); + assertThat(body.getCode()).isEqualTo(403); + assertThat(body.getMessage()).isNotBlank(); + } + + @Test + void handlerEmitsRealStatusOnceSwitchIsOn() { + SimpleMeterRegistry registry = new SimpleMeterRegistry(); + BusinessErrorHttpStatus.bindForTests(true, registry); + try { + Object result = handler.handleBusinessException( + new BusinessException(403, "无权访问"), request(), mock(HttpServletResponse.class)); + + ResponseEntity response = (ResponseEntity) result; + assertThat(response.getStatusCode()).isEqualTo(HttpStatus.FORBIDDEN); + ApiResponse body = (ApiResponse) response.getBody(); + assertThat(body.getCode()).as("响应体一个字节都不许多改").isEqualTo(403); + + // 第二件:幂等忽略那条成功路径即使在开关开着时也必须还是 200/ApiResponse + Object finished = handler.handleBusinessException( + new BusinessException(BusinessCodes.TASK_ALREADY_FINISHED, "任务已结束"), + request(), mock(HttpServletResponse.class)); + assertThat(finished).isInstanceOf(ApiResponse.class); + assertThat(((ApiResponse) finished).isSuccess()).isTrue(); + } finally { + registry.close(); + BusinessErrorHttpStatus.bindForTests(false, null); + } + } + + // ---------------------------------------------------------------- 助手 + + private HttpServletRequest request() { + HttpServletRequest request = mock(HttpServletRequest.class); + when(request.getMethod()).thenReturn("POST"); + when(request.getRequestURI()).thenReturn("/api/publish/tasks"); + return request; + } + + private ListAppender capture() { + Logger logger = (Logger) org.slf4j.LoggerFactory.getLogger(BusinessErrorHttpStatus.class); + ListAppender appender = new ListAppender<>(); + appender.start(); + logger.addAppender(appender); + return appender; + } + + private void release(ListAppender appender) { + ((Logger) org.slf4j.LoggerFactory.getLogger(BusinessErrorHttpStatus.class)).detachAppender(appender); + } + + private Map flatten(String fileName) { + ClassPathResource resource = new ClassPathResource(fileName); + assertThat(resource.exists()).as("classpath 上找不到 " + fileName).isTrue(); + try (InputStream in = resource.getInputStream()) { + Map flat = new LinkedHashMap<>(); + for (PropertySource source : new YamlPropertySourceLoader().load(fileName, resource)) { + if (source instanceof EnumerablePropertySource enumerable) { + for (String name : enumerable.getPropertyNames()) { + Object value = enumerable.getProperty(name); + flat.put(name, value == null ? "" : String.valueOf(value)); + } + } + } + return flat; + } catch (Exception e) { + throw new IllegalStateException("读 " + fileName + " 失败", e); + } + } + + private String defaultOf(Map flat, String key) { + String raw = flat.get(key).trim(); + Matcher m = PLACEHOLDER.matcher(raw); + return m.matches() ? m.group(2).trim() : raw; + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/task/TaskStatusVocabularyRatchetTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/task/TaskStatusVocabularyRatchetTest.java new file mode 100644 index 000000000..3dcedcfd5 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/task/TaskStatusVocabularyRatchetTest.java @@ -0,0 +1,326 @@ +package com.nanri.aiimage.common.task; + +import static org.assertj.core.api.Assertions.assertThat; + +import com.nanri.aiimage.testutil.SourceScan; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Comparator; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.TreeMap; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Stream; +import org.junit.jupiter.api.Test; + +/** + * 状态词表收口判据(2026-10-09 评审「流程 6.0」项 2:状态字面量集合散落 33 处/17 文件、没有单一状态机)。 + * + *

普查结果先说清楚,因为"收成一套"这句话本身是错的:全树实际是 + * 4 套自有词表 + 1 套外部词表 + 一堆模块内小状态机—— + * {@code biz_file_task.status}(大写)、{@code brand_crawl_tasks.status}(小写)、 + * {@code task_file_job.status}(四态)、{@code price_track_loop_run.status}(多一个 {@code STOPPED}), + * 外加 Coze 工作流回传的 {@code execute_status}({@code SUCCESS/SUCCEEDED/COMPLETED/DONE/FINISHED/FAILED/FAIL/…}, + * 那是别人家的返回值)。所以做的是按表分组、一处定义,不是把四套强行洗成一套。 + * + *

四条判据,各管一件事: + *

    + *
  1. 词表成员钉死:改 {@link TaskStatuses} 里任何一个集合必须在这里同步表态;
  2. + *
  3. 新增"内联状态集合字面量"即红:现存 3 处逐条台账化({@link #LEDGER});
  4. + *
  5. 散落的 {@code STATUS_XXX = "字面量"} 标量声明数抬成棘轮(只许降),已收口的 brand 小写族点名归零;
  6. + *
  7. {@code CANCELED}/{@code CANCELLED} 只做归一映射、不改拼写:映射判、不误伤判、写侧零命中判(配非零对照)。
  8. + *
+ * + *

重跑:{@code mvn -o test -Dtest=TaskStatusVocabularyRatchetTest}(cwd = backend-java)。 + */ +class TaskStatusVocabularyRatchetTest { + + /** + * 判定"这是一个状态字面量"的词表——取自 {@link TaskStatuses} 本身,免得判据和被管对象各写一套。 + * 大写四套 + brand 小写一套都要覆盖:只扫大写的话,新抄一处 {@code Set.of("pending","running")} + * 就从判据底下滑过去了。 + */ + private static final Set VOCABULARY = java.util.stream.Stream + .concat(TaskStatuses.allUppercaseStatuses().stream(), + java.util.stream.Stream.of(TaskStatuses.BrandTask.PENDING, TaskStatuses.BrandTask.RUNNING, + TaskStatuses.BrandTask.SUCCESS, TaskStatuses.BrandTask.FAILED, + TaskStatuses.BrandTask.CANCELLED)) + .collect(java.util.stream.Collectors.toUnmodifiableSet()); + + private static final Pattern OPEN = Pattern.compile("\\b(?:Set|List|Collection|EnumSet)\\.of\\(|\\bArrays\\.asList\\("); + private static final Pattern QUOTED = Pattern.compile("\"([A-Za-z_]+)\""); + + /** + * 内联状态集合字面量的例外台账:文件 → 为什么留在这儿。 + * 加一行要写清理由;删一行就是真的收掉了一处。 + */ + private static final Map LEDGER = Map.of( + "ImageVideoAsyncTaskService.java", + "Coze 上游回传的 execute_status 词表(SUCCEEDED/DONE/FINISHED/FAIL 都是别人家的值)," + + "收进我们的词表等于假装能改上游", + "CompletedTaskActiveJobInspector.java", + "同一对状态的反序书写 List.of(\"RUNNING\",\"PENDING\");对 SQL 无意义," + + "但本仓有判据按 SQL 文本顺序断言(TaskCenterQueryMapperSqlTest),改序之前先承认它在台账里"); + + /** 标量 {@code STATUS_X = "字面量"} 声明的棘轮分母(本轮从 81 降到 70:brand 小写族 11 处已接进词表)。 */ + private static final int SCALAR_LITERAL_CEILING = 70; + + // ---------------------------------------------------------------- 1. 词表成员 + + @Test + void centralVocabularyMembersArePinned() { + assertThat(TaskStatuses.FileTask.TERMINAL) + .as("biz_file_task 终态:少一个历史拼写就有一行永远收不了尾") + .containsExactlyInAnyOrder("SUCCESS", "FAILED", "CANCELLED", "CANCELED"); + assertThat(TaskStatuses.FileTask.ACTIVE) + .containsExactlyInAnyOrder("PENDING", "RUNNING", "SCHEDULED"); + assertThat(TaskStatuses.FileTask.FINISHED_ORDERED) + .as("各模块历史页计数口径:只有 SUCCESS+FAILED,不含取消(原口径,别顺手加宽)") + .containsExactly("SUCCESS", "FAILED"); + assertThat(TaskStatuses.FileTask.SUCCESS_VIEW_ORDERED) + .as("COMPLETED ≡ SUCCESS 早有出处(2026-10-04 三态收敛),这里只是把它钉成一处") + .containsExactly("SUCCESS", "COMPLETED"); + assertThat(TaskStatuses.FileTask.FAILED_VIEW_ORDERED) + .containsExactly("FAILED", "ERROR", "CANCELLED"); + assertThat(TaskStatuses.BrandTask.TERMINAL) + .as("brand 表是小写词表,混进大写集合会让 UNION 少一整张表") + .containsExactlyInAnyOrder("success", "failed", "cancelled"); + assertThat(TaskStatuses.Job.RETRYABLE_ORDERED).containsExactly("PENDING", "FAILED"); + assertThat(TaskStatuses.Job.ACTIVE_ORDERED).containsExactly("PENDING", "RUNNING"); + assertThat(TaskStatuses.LoopRun.TERMINAL) + .containsExactlyInAnyOrder("SUCCESS", "FAILED", "STOPPED"); + + // 否定句也要有同口径非零对照:确认"终态里没有 DONE/FINISHED/INTERRUPTED 这类新造词"不是因为集合整个是空的 + assertThat(TaskStatuses.FileTask.TERMINAL).isNotEmpty(); + assertThat(TaskStatuses.FileTask.TERMINAL) + .as("不能发明第三个词表:DONE/FINISHED/SUCCEEDED 不属于我们") + .doesNotContain("DONE", "FINISHED", "SUCCEEDED", "INTERRUPTED", "ARCHIVED"); + } + + // ---------------------------------------------------------------- 2. 内联状态集合棘轮 + + @Test + void inlineStatusCollectionLiteralsStayLedgeredAndCannotGrow() { + Map found = inlineStatusCollections(); + + assertThat(found) + .as("内联状态集合字面量必须逐文件台账化;新出现一个文件就是新抄了一套状态口径") + .containsOnlyKeys(LEDGER.keySet().toArray(new String[0])); + // 总数硬钉:现在就是 3 处(2 处外部词表 + 1 处反序书写),不是"扫不到所以绿" + assertThat(found.values().stream().mapToInt(Integer::intValue).sum()) + .as("内联状态集合字面量总数(基线 3:ImageVideo 外部词表 2 处 + Inspector 反序 1 处)") + .isEqualTo(3); + assertThat(found).hasEntrySatisfying("ImageVideoAsyncTaskService.java", count -> + assertThat(count).as("Coze 外部词表两处都在").isEqualTo(2)); + assertThat(found).hasEntrySatisfying("CompletedTaskActiveJobInspector.java", count -> + assertThat(count).isEqualTo(1)); + } + + @Test + void theCollectionScannerActuallyFindsTheShape() { + // 自检:上一条判据全靠这个扫描器。扫描器坏了(恒返回空)就是整支护栏恒绿,所以先证明它抓得到这一形。 + String sample = SourceScan.withoutComments( + "class X { Set A = Set.of(\"SUCCESS\", \"FAILED\", \"CANCELLED\"); }"); + assertThat(countStatusLiterals(sample)) + .as("锚点自检:抓不到 Set.of(\"SUCCESS\",\"FAILED\",…) 的话,棘轮等于没写") + .isEqualTo(3); + assertThat(countStatusLiterals("class X { List A = List.of(\"PENDING\")); }")).isEqualTo(1); + assertThat(countStatusLiterals("class X { List A = List.of(\"DE\", \"UK\", \"FR\")); }")) + .as("国家码不是状态词,别把无关的 List.of 也算进分母") + .isZero(); + } + + // ---------------------------------------------------------------- 3. 标量声明棘轮 + + @Test + void handWrittenStatusScalarsRatchetDownAndBrandFamilyIsClosed() { + Map scalars = statusScalarDeclarations(); + int total = scalars.values().stream().mapToInt(Integer::intValue).sum(); + + assertThat(total) + .as("src/main 里写死字面量的 STATUS_XXX 标量声明数(棘轮:只许降。降法是接进 TaskStatuses)") + .isLessThanOrEqualTo(SCALAR_LITERAL_CEILING); + assertThat(total).as("扫描器必须真数得出东西;0 处不等于收口完成,等于扫描坏了").isGreaterThan(0); + + // 点名已收口的那一族:brand 小写词表 11 处标量全部改成引用词表,一处不许回来 + for (String closed : List.of("BrandTaskService.java", "BrandTaskExpiredStopSpiImpl.java", + "BrandTaskStaleRepairSpiImpl.java")) { + assertThat(scalars.getOrDefault(closed, 0)) + .as(closed + " 的状态常量必须引用 TaskStatuses.BrandTask,不许再写死字面量") + .isZero(); + } + } + + @Test + void brandTaskServiceAndHeartbeatStillSpeakTheLowercaseVocabulary() { + // 接进词表之后值不许变:brand_crawl_tasks 存的就是小写,改成大写等于把在跑任务判成不存在 + assertThat(TaskStatuses.BrandTask.PENDING).isEqualTo("pending"); + assertThat(TaskStatuses.BrandTask.RUNNING).isEqualTo("running"); + assertThat(TaskStatuses.BrandTask.CANCELLED).isEqualTo("cancelled"); + // 文件任务那张表仍是同一批大写值,两套不许互相"归一" + assertThat(TaskStatuses.FileTask.RUNNING).isEqualTo("RUNNING"); + assertThat(TaskStatuses.FileTask.RUNNING).isNotEqualTo(TaskStatuses.BrandTask.RUNNING); + } + + // ---------------------------------------------------------------- 4. CANCELED / CANCELLED + + @Test + void cancelSpellingIsOnlyNormalizedNeverRenamed() { + assertThat(TaskStatuses.CANCEL_SPELLINGS) + .as("两种拼写 × 两种大小写各归各家") + .containsEntry("CANCELED", "CANCELLED") + .containsEntry("canceled", "cancelled"); + + // 第二件:只动取消族,别的状态一个字节都不许多改(防止"归一"顺手把 COMPLETED 洗成 SUCCESS) + assertThat(TaskStatuses.canonicalizeCancel("CANCELED")).isEqualTo("CANCELLED"); + assertThat(TaskStatuses.canonicalizeCancel("RUNNING")).isEqualTo("RUNNING"); + assertThat(TaskStatuses.canonicalizeCancel("COMPLETED")).isEqualTo("COMPLETED"); + assertThat(TaskStatuses.canonicalizeCancel("success")).isEqualTo("success"); + assertThat(TaskStatuses.canonicalizeCancel(null)).isNull(); + assertThat(TaskStatuses.isCancelSpelling("CANCELED")).isTrue(); + assertThat(TaskStatuses.isCancelSpelling("CANCELLED")).isTrue(); + assertThat(TaskStatuses.isCancelSpelling("FAILED")).as("FAILED 不是取消的拼写变体").isFalse(); + } + + @Test + void backendNeverWritesTheLegacyCanceledSpellingIntoAnyTable() { + // 实测边界:当前 Java 侧从不写 CANCELED(大写单 L)进库——它只可能是早期 jar/Python 留下的历史脏值, + // 所以只在读侧接受集合与 SQL 的 CASE WHEN 归一里出现。 + Map writes = statusWrites("\"CANCELED\""); + int hits = writes.values().stream().mapToInt(Integer::intValue).sum(); + assertThat(hits).as("把 \"CANCELED\" 写进库的语句数(历史脏值不许被新代码继续生产)").isZero(); + + // 同口径非零对照:同一支扫描器必须抓得到"小写 cancelled"的真实写点,否则上面那句 0 是扫描坏了 + Map control = statusWrites("\"cancelled\""); + assertThat(control.values().stream().mapToInt(Integer::intValue).sum()) + .as("小写 cancelled 的写点数(brand 表确实在写这个值)") + .isGreaterThan(0); + } + + // ---------------------------------------------------------------- 扫描助手 + + /** 文件 → 含 ≥2 个状态词的内联集合字面量处数。 */ + private static Map inlineStatusCollections() { + Map byFile = new TreeMap<>(); + for (Path file : mainSources()) { + if ("TaskStatuses.java".equals(file.getFileName().toString())) { + continue; // 这里就是唯一定义点,不该进例外台账 + } + String source = SourceScan.withoutComments(read(file)); + Matcher m = OPEN.matcher(source); + while (m.find()) { + String args = arguments(source, m.end() - 1); + if (args != null && countStatusLiterals(args) >= 2) { + byFile.merge(file.getFileName().toString(), 1, Integer::sum); + } + } + } + return byFile; + } + + private static int countStatusLiterals(String text) { + Matcher m = QUOTED.matcher(text); + int n = 0; + while (m.find()) { + if (VOCABULARY.contains(m.group(1))) { + n++; + } + } + return n; + } + + /** 文件 → 匹配 {@code writeFragment} 的处数(用于"某状态值有没有被写进库"的取证)。 */ + private static Map statusWrites(String writeFragment) { + Map byFile = new TreeMap<>(); + Pattern p = Pattern.compile("set\\([^)]*Status[^)]*,\\s*" + Pattern.quote(writeFragment)); + for (Path file : mainSources()) { + Matcher m = p.matcher(SourceScan.withoutComments(read(file))); + int n = 0; + while (m.find()) { + n++; + } + if (n > 0) { + byFile.put(file.getFileName().toString(), n); + } + } + return byFile; + } + + private static Map statusScalarDeclarations() { + Map byFile = new TreeMap<>(); + Pattern p = Pattern.compile( + "static final String (?:STATUS|STATE)_[A-Z_]+\\s*=\\s*\"[A-Za-z_]+\""); + for (Path file : mainSources()) { + if ("TaskStatuses.java".equals(file.getFileName().toString())) { + continue; + } + Matcher m = p.matcher(SourceScan.withoutComments(read(file))); + int n = 0; + while (m.find()) { + n++; + } + if (n > 0) { + byFile.put(file.getFileName().toString(), n); + } + } + return byFile; + } + + /** 从左括号开始做深度配对,取括号内文本;配不平返回 null(宁可漏判一处也不要把判据搞成假红)。 */ + private static String arguments(String text, int openIndex) { + int depth = 0; + for (int i = openIndex; i < text.length(); i++) { + char c = text.charAt(i); + if (c == '(') { + depth++; + } else if (c == ')') { + depth--; + if (depth == 0) { + return text.substring(openIndex + 1, i); + } + if (depth < 0) { + return null; + } + } + } + return null; + } + + private static List mainSources() { + Path root = moduleRoot().resolve("src/main/java"); + try (Stream walk = Files.walk(root)) { + List files = walk.filter(p -> p.toString().endsWith(".java")) + .sorted(Comparator.comparing(Path::toString)) + .toList(); + assertThat(files).as("src/main/java 扫到的 .java 数(扫不到=路径坏了,护栏会假绿)") + .hasSizeGreaterThan(900); + return files; + } catch (IOException e) { + throw new IllegalStateException("扫描失败: " + root, 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 + ")"); + } + + private static String read(Path file) { + try { + return Files.readString(file); + } catch (IOException e) { + throw new IllegalStateException("读不了 " + file, e); + } + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/util/LockSkipSilentExitGuardrailTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/util/LockSkipSilentExitGuardrailTest.java new file mode 100644 index 000000000..0b1e14f90 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/util/LockSkipSilentExitGuardrailTest.java @@ -0,0 +1,233 @@ +package com.nanri.aiimage.common.util; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.fail; + +import com.nanri.aiimage.testutil.SourceScan; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Comparator; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Set; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Stream; +import org.junit.jupiter.api.Test; + +/** + * 锁跳过出口的逐处判据(2026-10-09 评审「稳定 5.5」项 1,权重 1.5)。 + * + *

要拦的行为很具体:{@code if (<某个 lock 变量> == null) { continue; }} / + * {@code { return; }} —— 巡检任务每轮跑、被锁挡掉的任务直接消失,一行日志都不留。 + * 实测基线(2026-10-10 自己数出来的,不是评审给的 14):全树 {@code src/main/java} 共 + * 29 处这种形状,28 处已接 {@link LockSkipWitness},1 处判定不该接(见 + * {@link #LEDGERED_EXCEPTIONS})。 + * + *

判据打在分支体上而不是打在"某个类里出现过锚点"上:分支体剥掉注释后必须只剩 + * {@code continue;} / {@code return;}(顶多一行 {@code LockSkipWitness.*} 调用)。 + * 这样"锚点方法存在但没人调"(2026-10-09 踩过的那坑)在这儿会直接红—— + * {@link #witnessedSiteCountCannotShrink} 把已接线的点位数钉成 28,掉一处就红, + * {@link #everyPointLiteralIsUsedByExactlyOneSite} 保证点位没有互相覆盖成一坨。 + */ +class LockSkipSilentExitGuardrailTest { + + /** 形如 lock / jobLock / taskLockHandle / neverReportedLock / distributedJobLockService 的变量判空。 */ + private static final Pattern LOCK_NULL_CHECK = + Pattern.compile("if\\s*\\(\\s*(\\w*[Ll]ock\\w*)\\s*==\\s*null\\s*\\)\\s*\\{"); + + /** 分支体剥掉出口调用后,只剩这两种语句就是「跳过但什么都不做」。 */ + private static final List BARE_EXITS = List.of("continue;", "return;"); + + private static final Pattern WITNESS_CALL = Pattern.compile("LockSkipWitness\\.\\w+\\s*\\(([^;]*)\\);"); + + /** + * 例外台账:文件名 -> 判定不该接的原因。加一行要有现网证据,删一行就是补了出口。 + * + *

{@code TaskDistributedLockService.close()} 里的 {@code heldLock == null} 不是"跳过任务": + * 它是重复 close 的幂等护栏(第二次 close 时本地登记已经没了,无事可做),不挡任何工作、 + * 也不丢数据。给它加锚点等于每次正常重复 close 都刷一条 WARN,把真正在响的那 28 处淹掉。 + */ + private static final Set LEDGERED_EXCEPTIONS = + Set.of("TaskDistributedLockService.java"); + + /** 已接线点位数的硬分母:只许升(新增出口),不许降(出口被摘)。 */ + private static final int MIN_WITNESSED_SITES = 28; + + @Test + void everyLockNullSkipBranchCarriesAVisibleWitness() { + List unwitnessed = new ArrayList<>(); + int witnessed = 0; + for (Path file : mainSources()) { + String source = SourceScan.withoutComments(read(file)); + for (String body : lockNullBranches(source)) { + if (!isSkipOnlyBranch(body)) { + continue; + } + if (body.contains("LockSkipWitness.")) { + witnessed++; + } else if (!LEDGERED_EXCEPTIONS.contains(file.getFileName().toString())) { + unwitnessed.add(file.getFileName() + " -> " + body.strip()); + } + } + } + + // 自检(否定句必须配同口径非零对照):扫描器真抓得到已接线的那批,否则下面那句 isEmpty() 是恒绿 + assertThat(witnessed) + .as("已接 LockSkipWitness 的锁跳过点位数(掉一处就是在摘出口)") + .isGreaterThanOrEqualTo(MIN_WITNESSED_SITES); + assertThat(unwitnessed) + .as("剩下「判空即跳过且零日志」的锁出口,必须全在例外台账里") + .isEmpty(); + } + + @Test + void lockedExceptionsStayExactlyOneAndCannotGrowQuietly() { + List bareExceptions = new ArrayList<>(); + for (Path file : mainSources()) { + if (!LEDGERED_EXCEPTIONS.contains(file.getFileName().toString())) { + continue; + } + String source = SourceScan.withoutComments(read(file)); + for (String body : lockNullBranches(source)) { + if (isSkipOnlyBranch(body) && !body.contains("LockSkipWitness.")) { + bareExceptions.add(file.getFileName() + ":" + body.strip()); + } + } + } + // 台账里那个例外只剩 1 处(close() 的幂等护栏)。变成 2 处说明同一个文件里又新写了一处裸跳过, + // 那不是"台账里已论证过的形状",必须停下来看。 + assertThat(bareExceptions) + .as("例外台账文件里的裸跳过分支数(基线:TaskDistributedLockService.close() 一处)") + .hasSize(1); + } + + /** + * 「跳过但什么都不做」的分支体:剥掉出口调用与空白后,只剩 {@code continue;} 或 {@code return;}。 + * 有别的语句(比如 {@code taskFileJobService.requeue(...)})就不是被拦的对象——那条路本来就留了痕。 + */ + private static boolean isSkipOnlyBranch(String body) { + String stripped = body.replaceAll("LockSkipWitness\\.\\w+\\s*\\([^;]*\\);", "").strip(); + return BARE_EXITS.contains(stripped); + } + + @Test + void everyPointLiteralIsUsedByExactlyOneSite() { + List points = new ArrayList<>(); + for (Path file : mainSources()) { + if ("LockSkipWitness.java".equals(file.getFileName().toString())) { + continue; + } + Matcher m = WITNESS_CALL.matcher(SourceScan.withoutComments(read(file))); + while (m.find()) { + String args = m.group(1); + String first = args.split(",")[0].strip(); + if (first.startsWith("\"") && first.endsWith("\"") && first.length() > 2) { + points.add(first); + } else if (!first.isBlank()) { + fail("点位字面量必须写死在第一个参数(不打行号、不拼变量),实际=" + args + + " @ " + file.getFileName()); + } + } + } + Set distinct = new LinkedHashSet<>(points); + assertThat(points) + .as("全树 LockSkipWitness 调用数") + .hasSizeGreaterThanOrEqualTo(MIN_WITNESSED_SITES); + assertThat(distinct) + .as("点位字面量必须一一对应:两个跳过处共用一个点位,现网就分不出是谁在被挡") + .hasSize(points.size()); + // 命名口径也钉一下:点位都是小写 kebab,允许带一个 ":用途" 后缀。 + // 带后缀的是任务级点位(模块内多处跳过要分得开);不带后缀的是作业锁点位, + // 它直接沿用 tryLock 已有的锁名(如 expired-account-task-stop),不去另起一套标识。 + assertThat(distinct).allSatisfy(point -> + assertThat(point).matches("\"[a-z0-9][a-z0-9.-]*(:[a-z0-9.-]+)?\"")); + } + + @Test + void anchorIsReusedFromTheSingleDefinitionPoint() { + // 锚点只有 LockSkipWitness 一处定义;业务侧禁止把 "[lock-skip]" 抄成字面量, + // 否则改了常量之后 grep 得到的是半套出口。 + String witnessSource = SourceScan.withoutComments(SourceScan.sourceText("LockSkipWitness.java")); + assertThat(witnessSource).contains("public static final String ANCHOR = \"[lock-skip]\""); + + List copycats = new ArrayList<>(); + for (Path file : mainSources()) { + if ("LockSkipWitness.java".equals(file.getFileName().toString())) { + continue; + } + if (SourceScan.withoutComments(read(file)).contains("[lock-skip]")) { + copycats.add(file.getFileName().toString()); + } + } + assertThat(copycats).as("[lock-skip] 字面量不得在业务侧被抄第二遍").isEmpty(); + } + + // ---- 扫描助手:抓 if ( == null) { … } 的分支体(含大括号配对,注释已剥) ---- + + private static List lockNullBranches(String sourceWithoutComments) { + List bodies = new ArrayList<>(); + Matcher m = LOCK_NULL_CHECK.matcher(sourceWithoutComments); + while (m.find()) { + int open = m.end() - 1; + int close = matchingBrace(sourceWithoutComments, open); + if (close > open) { + bodies.add(sourceWithoutComments.substring(open + 1, close)); + } + } + return bodies; + } + + /** 朴素大括号配对(剥注释后字符串字面量里的大括号仍可能干扰,够用即止:只在判空分支上用)。 */ + private static int matchingBrace(String text, int openIndex) { + int depth = 0; + for (int i = openIndex; i < text.length(); i++) { + char c = text.charAt(i); + if (c == '{') { + depth++; + } else if (c == '}') { + depth--; + if (depth == 0) { + return i; + } + } + } + return -1; + } + + private static List mainSources() { + Path root = moduleRoot().resolve("src/main/java"); + try (Stream walk = Files.walk(root)) { + List files = walk.filter(p -> p.toString().endsWith(".java")) + .sorted(Comparator.comparing(Path::toString)) + .toList(); + assertThat(files).as("src/main/java 扫到的 .java 数(扫不到就是路径坏了)") + .hasSizeGreaterThan(900); + return files; + } catch (IOException e) { + throw new IllegalStateException("扫描失败: " + root, 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 + ")"); + } + + private static String read(Path file) { + try { + return Files.readString(file); + } catch (IOException e) { + throw new IllegalStateException("读不了 " + file, e); + } + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/util/LockSkipWitnessTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/util/LockSkipWitnessTest.java new file mode 100644 index 000000000..d47df0258 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/common/util/LockSkipWitnessTest.java @@ -0,0 +1,182 @@ +package com.nanri.aiimage.common.util; + +import static org.assertj.core.api.Assertions.assertThat; + +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; +import io.micrometer.core.instrument.Measurement; +import io.micrometer.core.instrument.simple.SimpleMeterRegistry; +import java.util.ArrayList; +import java.util.List; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.Test; +import org.slf4j.LoggerFactory; + +/** + * 分布式锁跳过出口({@link LockSkipWitness})的判据(2026-10-09 评审「稳定 5.5」项 1)。 + * + *

这条判据要钉住的是两件事,不是两件里的一件: + *

    + *
  1. 锚点字面量真的打在日志上(能被巡检 grep);
  2. + *
  3. 调用它确实累计得出数(可聚合,不是"记了一行没人看的日志")。
  4. + *
+ * 只判第 1 件就会重演 2026-10-09 踩过的坑:锚点方法存在、零调用者,判据恒绿而现网照旧。 + * 调用面由 {@link LockSkipSilentExitGuardrailTest} 按点位台账逐处钉住,两支合起来才是"出口在响"。 + */ +class LockSkipWitnessTest { + + @AfterEach + void unbindRegistry() { + LockSkipWitness.bind(null); + } + + private ListAppender capture() { + Logger logger = (Logger) LoggerFactory.getLogger(LockSkipWitness.class); + ListAppender appender = new ListAppender<>(); + appender.start(); + logger.addAppender(appender); + return appender; + } + + private void release(ListAppender appender) { + ((Logger) LoggerFactory.getLogger(LockSkipWitness.class)).detachAppender(appender); + } + + @Test + void recordEmitsAnchorLineWithAggregationFields() { + ListAppender captured = capture(); + try { + long before = LockSkipWitness.total(); + LockSkipWitness.record("test:anchor-shape", LockSkipWitness.OUTCOME_SKIPPED, "PUBLISH", 123L); + List messages = captured.list.stream().map(ILoggingEvent::getFormattedMessage).toList(); + + assertThat(messages).as("走到跳过分支必须留下一行日志").hasSize(1); + String line = messages.get(0); + // 锚点 + 聚合维度都得在这一行里,巡检才分得出是哪个点位、挡了多少 + assertThat(line).contains(LockSkipWitness.ANCHOR) + .contains("point=test:anchor-shape") + .contains("outcome=skipped") + .contains("moduleType=PUBLISH") + .contains("taskId=123"); + assertThat(captured.list.get(0).getLevel().toString()).isEqualTo("WARN"); + assertThat(LockSkipWitness.total()).as("同一行也必须进台账计数").isEqualTo(before + 1); + } finally { + release(captured); + } + } + + @Test + void ledgerAggregatesPerPointAndSnapshotIsReadable() { + LockSkipWitness.resetLedgerForTests(); + LockSkipWitness.recordSkip("test:agg-a", "BRAND", 1L); + LockSkipWitness.recordSkip("test:agg-a", "BRAND", 2L); + LockSkipWitness.abandoned("test:agg-b"); + + assertThat(LockSkipWitness.countOf("test:agg-a")).isEqualTo(2); + assertThat(LockSkipWitness.countOf("test:agg-b")).isEqualTo(1); + assertThat(LockSkipWitness.countOf("test:never-recorded")).as("没记过的点位读数必须是 0 而不是抛").isZero(); + assertThat(LockSkipWitness.snapshot()) + .as("快照要能一次看全点位(巡检/告警的取数面)") + .containsEntry("test:agg-a", 2L) + .containsEntry("test:agg-b", 1L); + assertThat(LockSkipWitness.total()).isEqualTo(3); + } + + @Test + void skippedAndAbandonedAreTwoDifferentOutcomes() { + LockSkipWitness.resetLedgerForTests(); + ListAppender captured = capture(); + try { + LockSkipWitness.recordSkip("test:outcome-skipped", "PUBLISH", 7L); + LockSkipWitness.recordAbandoned("test:outcome-abandoned", "PUBLISH", 8L); + List lines = captured.list.stream().map(ILoggingEvent::getFormattedMessage).toList(); + + assertThat(lines).hasSize(2); + assertThat(lines.get(0)).contains("outcome=skipped"); + assertThat(lines.get(1)).contains("outcome=abandoned"); + // 两种结果都得进台账——只有一种被数到就等于另一种仍然没有出口 + assertThat(LockSkipWitness.snapshot()).containsKeys("test:outcome-skipped", "test:outcome-abandoned"); + } finally { + release(captured); + } + } + + @Test + void micrometerCounterCarriesPointAndOutcomeTagsWhenBound() { + LockSkipWitness.resetLedgerForTests(); + SimpleMeterRegistry registry = new SimpleMeterRegistry(); + LockSkipWitness.bind(registry); + try { + LockSkipWitness.record("test:metric-shape", LockSkipWitness.OUTCOME_ABANDONED, "SIMILAR_ASIN", 9L); + + List found = new ArrayList<>(); + for (var meter : registry.getMeters()) { + if (LockSkipWitness.METRIC.equals(meter.getId().getName())) { + found.add(meter.getId().getTag("point") + "/" + meter.getId().getTag("outcome") + + "/" + meter.getId().getTag("moduleType")); + } + } + assertThat(found).as("指标必须带得上点位/结果/模块三个聚合标签").containsExactly( + "test:metric-shape/abandoned/SIMILAR_ASIN"); + double value = registry.get(LockSkipWitness.METRIC) + .tag("point", "test:metric-shape") + .counter() + .count(); + assertThat(value).isEqualTo(1.0); + assertThat(registry.get(LockSkipWitness.METRIC + ".total").gauge().value()) + .as("总览 gauge 也在,读数为零时能区分「没人被挡」和「指标没接上」") + .isGreaterThanOrEqualTo(1.0); + } finally { + registry.close(); + } + } + + @Test + void missingContextLandsOnKnownBucketInsteadOfThrowing() { + LockSkipWitness.resetLedgerForTests(); + ListAppender captured = capture(); + try { + // 点位缺失 + 模块缺失:不能抛,也不能悄悄丢掉这次记录 + LockSkipWitness.record(null, null, " ", null); + assertThat(captured.list).hasSize(1); + assertThat(captured.list.get(0).getFormattedMessage()) + .contains("point=unpointed") + .as("缺失的 outcome 单独进 unknown 桶,不许折叠进 skipped/abandoned 那两个真桶") + .contains("outcome=unknown") + .contains("moduleType=unknown"); + assertThat(LockSkipWitness.countOf("unpointed")).isEqualTo(1); + assertThat(LockSkipWitness.snapshot()).containsKey("unpointed"); + } finally { + release(captured); + } + } + + @Test + void ledgerStopsGrowingPastItsKeyCeilingButKeepsCounting() { + LockSkipWitness.resetLedgerForTests(); + for (int i = 0; i < LockSkipWitness.LEDGER_KEYS_MAX + 60; i++) { + LockSkipWitness.record("test:flood-" + i, LockSkipWitness.OUTCOME_SKIPPED, null, null); + } + assertThat(LockSkipWitness.snapshot()) + .as("点位键数封顶,不被未知点位撑爆内存") + .hasSizeLessThanOrEqualTo(LockSkipWitness.LEDGER_KEYS_MAX + 1); + assertThat(LockSkipWitness.snapshot()).containsKey("overflow"); + assertThat(LockSkipWitness.total()) + .as("封顶只影响键的数量,不影响总次数:一次都不能少记") + .isEqualTo(LockSkipWitness.LEDGER_KEYS_MAX + 60L); + } + + @Test + void anchorLiteralIsTheContractInspectionGreps() { + // 巡检/告警按这条字面量匹配;改它等于删掉现网规则,所以这里钉死字面值 + assertThat(LockSkipWitness.ANCHOR).isEqualTo("[lock-skip]"); + assertThat(LockSkipWitness.METRIC).isEqualTo("aiimage.distributed.lock.skip"); + + // 另一半:锚点必须真被 record() 打进日志(不是只当常量挂着)——上一条用例已实测, + // 这里再钉一次源码形状,防止有人把 log.warn 里的 ANCHOR 换成写死的别的字符串。 + String source = com.nanri.aiimage.testutil.SourceScan.withoutComments( + com.nanri.aiimage.testutil.SourceScan.sourceText("LockSkipWitness.java")); + assertThat(source).as("record() 里的日志必须带锚点参数").contains("ANCHOR, key"); + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/config/ClientVersionFloorConfigTest.java b/backend-java/src/test/java/com/nanri/aiimage/config/ClientVersionFloorConfigTest.java new file mode 100644 index 000000000..eae9d34bb --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/config/ClientVersionFloorConfigTest.java @@ -0,0 +1,315 @@ +package com.nanri.aiimage.config; + +import static org.assertj.core.api.Assertions.assertThat; + +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; +import io.micrometer.core.instrument.Counter; +import io.micrometer.core.instrument.simple.SimpleMeterRegistry; +import java.io.InputStream; +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 org.junit.jupiter.api.Test; +import org.slf4j.LoggerFactory; +import org.springframework.boot.env.YamlPropertySourceLoader; +import org.springframework.core.env.EnumerablePropertySource; +import org.springframework.core.env.PropertySource; +import org.springframework.core.io.ClassPathResource; +import org.springframework.mock.web.MockFilterChain; +import org.springframework.mock.web.MockHttpServletRequest; +import org.springframework.mock.web.MockHttpServletResponse; +import org.springframework.test.util.ReflectionTestUtils; + +/** + * 版本硬地板三键的配置面判据(2026-10-09 评审「流程 6.0」项 3,服务端这一半)。 + * + *

评审量到的事实是:{@code min-supported} / {@code enforce} / {@code rejectUnreported} + * 三键在任何 yml 里 0 处,只有 {@link ClientVersionGuardFilter} 里的 {@code @Value} 默认值。 + * 后果不是"值不对",是出厂即惰性:{@code minSupportedVersion} 默认空串 ⇒ + * {@code shouldNotFilter} 每个请求直接跳过 ⇒ 连"记账"都不发生,谁也不知道翻 true 会打到谁。 + * + *

这一支钉四件事,每件都是能跑的断言不是文字: + *

    + *
  1. 三键在 {@code application.yml} 里真存在(打进 jar 的那份,读 classpath 不读工作区);
  2. + *
  3. 出厂默认值就是 {@code 4.0.47 / false / false},且 {@code enforce=false} 那一档 + * 确实在记账——旧版本被计数、被留日志,同时响应一个字节都不许多;
  4. + *
  5. 三键缺失(地板被改回空)时启动可见:一条点名"闸门惰性"的 WARN,而不是静默跳过;
  6. + *
  7. 其它 profile 没把地板偷偷改回空值。
  8. + *
+ * + *

翻真({@code enforce=true})这一轮没有发生,也不该由我拍:判据 2 量出来的 + * {@code verdict=below}/{@code unreported} 两个桶就是"翻上去会挡到谁"的现网答案。 + * + *

重跑:{@code mvn -o test -Dtest=ClientVersionFloorConfigTest}(cwd = backend-java)。 + */ +class ClientVersionFloorConfigTest { + + private static final String KEY_MIN = "aiimage.client-version.min-supported-version"; + private static final String KEY_ENFORCE = "aiimage.client-version.enforce"; + private static final String KEY_REJECT_UNREPORTED = "aiimage.client-version.reject-unreported"; + + /** {@code ${ENV:默认}} 形状;只取默认段,这样测试判的是出厂值,不受跑测试的机器上的环境变量影响。 */ + private static final Pattern PLACEHOLDER = Pattern.compile("^\\$\\{([^:}]+):([^}]*)\\}$"); + + private final List anchorLines = new ArrayList<>(); + + // ---------------------------------------------------------------- 1. 三键真的存在 + + @Test + void threeFloorKeysShipInsideApplicationYml() { + Map flat = flatten("application.yml"); + + assertThat(flat.keySet()) + .as("三键必须都在 application.yml 里(缺一个就又是出厂即惰性)") + .contains(KEY_MIN, KEY_ENFORCE, KEY_REJECT_UNREPORTED); + assertThat(shippedDefault(flat, KEY_MIN)).isEqualTo("4.0.47"); + assertThat(shippedDefault(flat, KEY_ENFORCE)).isEqualTo("false"); + assertThat(shippedDefault(flat, KEY_REJECT_UNREPORTED)).isEqualTo("false"); + } + + @Test + void shippedFloorIsANumberTheGateCanActuallyParse() { + // 地板写成 "v4.0" / "4.x" 这类形状时闸门只记账不拒,等于配了个假地板——这里把出厂值验到能解析 + Map flat = flatten("application.yml"); + String min = shippedDefault(flat, KEY_MIN); + long[] parsed = ClientVersionGuardFilter.parse(min); + assertThat(parsed).as("出厂地板 " + min + " 必须解析成数字段").isNotNull(); + assertThat(parsed).containsExactly(4L, 0L, 47L); + // 4.0.46(不报版本的上一个包)在地板之下,4.0.48(现网最新包)在地板之上 + assertThat(ClientVersionGuardFilter.compare(ClientVersionGuardFilter.parse("4.0.46"), parsed)) + .as("4.0.46 必须被判成低于地板,否则记账桶永远是空的").isNegative(); + assertThat(ClientVersionGuardFilter.compare(ClientVersionGuardFilter.parse("4.0.48"), parsed)) + .as("现网最新的 4.0.48 不能落在地板之下").isPositive(); + } + + @Test + void otherProfilesDoNotBlankTheFloor() { + // server profile 里若把地板覆盖成空串,打包上去了就等于把闸门关掉——这不允许悄悄发生 + for (String file : List.of("application-server.yml")) { + Map flat = flatten(file); + String min = flat.get(KEY_MIN); + if (min != null) { + assertThat(shippedDefault(flat, KEY_MIN)) + .as(file + " 把地板覆盖成了空值 = 关掉闸门") + .isNotEmpty(); + } + } + } + + // ---------------------------------------------------------------- 2. 记账模式真的在记账 + + @Test + void accountingModeRecordsOldClientWithoutTouchingResponse() throws Exception { + SimpleMeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("4.0.47", false, false, registry); + ListAppender captured = capture(); + try { + MockHttpServletRequest request = clientRequest("4.0.40"); + MockHttpServletResponse response = new MockHttpServletResponse(); + MockFilterChain chain = new MockFilterChain(); + + filter.doFilter(request, response, chain); + + // 记账 = 留痕 + 放行,两件事都得判:只判"放行了"就退化成"这个过滤器没干活" + assertThat(chain.getRequest()) + .as("enforce=false 必须原样放行到业务") + .isSameAs(request); + assertThat(response.getStatus()).isEqualTo(200); + assertThat(response.getContentAsString()) + .as("记账模式下响应体一个字节都不许多") + .isEmpty(); + assertThat(counterValue(registry, "below", "4.0.40")) + .as("低于地板的版本必须进 below 桶") + .isEqualTo(1L); + assertThat(messages(captured)) + .as("记账必须留下一条能 grep 的 WARN") + .anySatisfy(line -> assertThat(line) + .contains("[版本地板]") + .contains("自报版本=4.0.40") + .contains("verdict=below") + .contains("enforce=false") + .contains("记账模式,暂不拒绝")); + } finally { + release(captured); + registry.close(); + } + } + + @Test + void unreportedLegacyClientGoesToItsOwnBucketNotBelow() throws Exception { + SimpleMeterRegistry registry = new SimpleMeterRegistry(); + ClientVersionGuardFilter filter = filter("4.0.47", false, false, registry); + try { + // 4.0.46 及更早压根不发 X-Client-Version:它们进 unreported 桶,不冒充"低于地板" + MockHttpServletRequest request = clientRequest(null); + filter.doFilter(request, new MockHttpServletResponse(), new MockFilterChain()); + + // 没报版本时版本标签归一成 unknown(空串当标签会把同一批装机拆成看不见的两桶) + assertThat(counterValue(registry, "unreported", "unknown")).isEqualTo(1L); + assertThat(registry.find(ClientVersionGuardFilter.METRIC).tag("verdict", "below").counter()) + .as("没报版本不能记进 below 桶") + .isNull(); + } finally { + registry.close(); + } + } + + @Test + void defaultConfigCannotRejectAnyoneEvenWhenUnreportedFlagIsOn() throws Exception { + // 出厂 enforce=false 时,reject-unreported=true 也不该挡任何请求——拒绝动作只由 enforce 决定 + ClientVersionGuardFilter filter = filter("4.0.47", false, true, null); + MockHttpServletRequest request = clientRequest(null); + MockFilterChain chain = new MockFilterChain(); + filter.doFilter(request, new MockHttpServletResponse(), chain); + assertThat(chain.getRequest()).as("enforce=false 是唯一的总闸,谁都越不过它").isSameAs(request); + } + + // ---------------------------------------------------------------- 3. 缺失/惰性态启动可见 + + @Test + void blankFloorIsLoudAtStartupNotSilentlyInert() { + ListAppender captured = capture(); + try { + filter("", false, false, null).reportFloorState(); + assertThat(messages(captured)) + .as("地板被留空 = 闸门惰性,必须点名说清楚,不能和「这个功能不存在」长得一样") + .anySatisfy(line -> assertThat(line) + .contains("[版本地板]") + .contains("min-supported-version 未配置") + .contains("闸门惰性")); + assertThat(captured.list) + .as("这条自述得是 WARN 级,INFO 在生产日志级别下会被淹掉") + .allSatisfy(event -> assertThat(event.getLevel().toString()).isEqualTo("WARN")); + } finally { + release(captured); + } + } + + @Test + void accountingModeAnnouncesItselfAtStartup() { + ListAppender accounting = capture(); + ListAppender enforcing; + try { + // 出厂默认(4.0.47 / false / false)启动时把三键状态原样报出来,运维不用猜 + filter("4.0.47", false, false, null).reportFloorState(); + assertThat(messages(accounting)) + .anySatisfy(line -> assertThat(line) + .contains("[版本地板]") + .contains("最低支持版本=4.0.47") + .contains("enforce=false") + .contains("记账模式") + .contains("rejectUnreported=false")); + } finally { + release(accounting); + } + + // 同一支方法在 enforce=true 时得改口说「真拒绝」——只测一半就等于自述不可信 + enforcing = capture(); + try { + filter("4.0.47", true, true, null).reportFloorState(); + assertThat(messages(enforcing)) + .anySatisfy(line -> assertThat(line) + .contains("enforce=true") + .contains("真拒绝") + .contains("rejectUnreported=true")); + } finally { + release(enforcing); + } + } + + @Test + void unparsableFloorIsNamedAtStartup() { + ListAppender captured = capture(); + try { + filter("v4.0", false, false, null).reportFloorState(); + assertThat(messages(captured)) + .as("配置写坏(v4.0 解析不出数字段)要说出来,否则永远只记 unparsable 还没人知道") + .anySatisfy(line -> assertThat(line) + .contains("[版本地板]") + .contains("解析不出数字段") + .contains("v4.0")); + } finally { + release(captured); + } + } + + // ---------------------------------------------------------------- 助手 + + private ClientVersionGuardFilter filter(String minVersion, boolean enforce, boolean rejectUnreported, + SimpleMeterRegistry registry) { + ClientVersionGuardFilter filter = new ClientVersionGuardFilter( + new com.fasterxml.jackson.databind.ObjectMapper(), registry); + ReflectionTestUtils.setField(filter, "minSupportedVersion", minVersion); + ReflectionTestUtils.setField(filter, "enforce", enforce); + ReflectionTestUtils.setField(filter, "rejectUnreported", rejectUnreported); + return filter; + } + + private MockHttpServletRequest clientRequest(String reportedVersion) { + MockHttpServletRequest request = new MockHttpServletRequest("POST", "/api/publish/tasks"); + if (reportedVersion != null) { + request.addHeader(ClientVersionGuardFilter.HEADER, reportedVersion); + } + return request; + } + + private long counterValue(SimpleMeterRegistry registry, String verdict, String version) { + Counter counter = registry.find(ClientVersionGuardFilter.METRIC) + .tag("verdict", verdict).tag("version", version).counter(); + return counter == null ? 0L : (long) counter.count(); + } + + private ListAppender capture() { + Logger logger = (Logger) LoggerFactory.getLogger(ClientVersionGuardFilter.class); + ListAppender appender = new ListAppender<>(); + appender.start(); + logger.addAppender(appender); + return appender; + } + + private void release(ListAppender appender) { + ((Logger) LoggerFactory.getLogger(ClientVersionGuardFilter.class)).detachAppender(appender); + } + + private List messages(ListAppender appender) { + return appender.list.stream().map(ILoggingEvent::getFormattedMessage).toList(); + } + + /** 读打进 classpath 的那份 yml({@code src/main/resources} 会被拷进 target/classes),读不到就红。 */ + private Map flatten(String fileName) { + ClassPathResource resource = new ClassPathResource(fileName); + assertThat(resource.exists()) + .as("classpath 上找不到 " + fileName + " —— 判据读不到出厂配置就是空转") + .isTrue(); + try (InputStream in = resource.getInputStream()) { + Map flat = new LinkedHashMap<>(); + for (PropertySource source : new YamlPropertySourceLoader().load(fileName, resource)) { + if (source instanceof EnumerablePropertySource enumerable) { + for (String name : enumerable.getPropertyNames()) { + Object value = enumerable.getProperty(name); + flat.put(name, value == null ? "" : String.valueOf(value)); + } + } + } + assertThat(flat).as(fileName + " 解析出来的键数(0 就是解析坏了)").isNotEmpty(); + return flat; + } catch (Exception e) { + throw new IllegalStateException("读 " + fileName + " 失败", e); + } + } + + /** 取 {@code ${ENV:默认}} 的默认段;没占位符就按字面值返回。 */ + private String shippedDefault(Map flat, String key) { + assertThat(flat) + .as("三键缺一即判红(出厂即惰性的老坑)") + .containsKey(key); + String raw = flat.get(key).trim(); + Matcher m = PLACEHOLDER.matcher(raw); + return m.matches() ? m.group(2).trim() : raw; + } +}