diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentRowOutcome.java b/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentRowOutcome.java
new file mode 100644
index 000000000..c06de797e
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentRowOutcome.java
@@ -0,0 +1,184 @@
+package com.nanri.aiimage.modules.appearancepatent.service.support;
+
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentResultRowDto;
+import com.nanri.aiimage.modules.appearancepatent.model.vo.AppearancePatentParsedRowVo;
+
+import java.util.ArrayList;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.function.Function;
+
+/**
+ * 一行「没出结论」到底是哪一种原因的唯一点径:交付表格的文案与覆盖率闸门的分母共用这里。
+ *
+ *
历史上两边各判各的:闸门按**用户上传表的解析行**有没有标题/图片决定这行算不算
+ * 「该被检测」,而表格按**客户端回传的结果行**有没有标题/图片决定这行有没有结论。
+ * 现网(2026-10-06~10-09 实测 6 份已交付文件)用户表常只给 id/ASIN/国家,标题与图片链接
+ * 全靠采集回传 ⇒ 解析行两列恒空 ⇒ 闸门分母为 0、整段不判,表里 20%–51% 的行写着
+ * 「未取得检测结果」而日志里一条覆盖率告警都没有。
+ */
+public final class AppearancePatentRowOutcome {
+
+ public enum Kind {
+ /** 三维结论齐了,正常交付。 */
+ JUDGED,
+ /** 该行有数据、本该检出,但没有可用结论:检测没跑到或结果丢了。 */
+ NOT_INSPECTED,
+ /** 连标题和图片都没采集到,无从检测。 */
+ NO_DATA
+ }
+
+ /**
+ * 「有数据却没检」的专用文案。它和 {@link AppearancePatentSheetBuilder#NO_RESULT_TEXT}
+ * 必须分开:后者意味着"检了但没答上",前者意味着"根本没跑到这一行",
+ * 用户拿到的处置动作完全不同(等补检 / 重新发起)。
+ */
+ public static final String NOT_INSPECTED_TEXT = "该行未完成检测(任务提前结束),重新运行可补检";
+
+ public static final String NO_DATA_TEXT = "该行未采集到数据(标题与图片都没有),无法检测";
+
+ private AppearancePatentRowOutcome() {
+ }
+
+ public static Kind classify(AppearancePatentParsedRowVo parsedRow,
+ AppearancePatentResultRowDto resultRow) {
+ if (isJudged(resultRow)) {
+ return Kind.JUDGED;
+ }
+ return hasCheckableData(parsedRow, resultRow) ? Kind.NOT_INSPECTED : Kind.NO_DATA;
+ }
+
+ /** 交付口径的"这行有结论":标题维、外观维、结论三列都得有可用文本(结论依赖前两者)。 */
+ public static boolean isJudged(AppearancePatentResultRowDto resultRow) {
+ return resultRow != null
+ && isUsableField(resultRow.getTitleRisk())
+ && isUsableField(resultRow.getAppearanceRisk())
+ && isUsableField(resultRow.getConclusion());
+ }
+
+ public static boolean isUsableField(String value) {
+ String normalized = AppearancePatentSheetBuilder.normalize(value);
+ return !normalized.isBlank() && !AppearancePatentSheetBuilder.isTechnicalLlmFailure(normalized);
+ }
+
+ /**
+ * 行上有没有任何能展示给用户的东西(三个维度、结论、错误原文)。
+ * 全空才由行级文案({@link #NOT_INSPECTED_TEXT} / {@link #NO_DATA_TEXT})接管;
+ * 只要带着错误原文,就让它照原样进格子——把「LLM http 503 模型过载」盖成泛化文案,
+ * 用户和运维都失去归因线索。
+ */
+ public static boolean carriesNothingToShow(AppearancePatentResultRowDto resultRow) {
+ return resultRow == null
+ || (isBlank(resultRow.getTitleRisk()) && isBlank(resultRow.getAppearanceRisk())
+ && isBlank(resultRow.getConclusion()) && isBlank(resultRow.getError()));
+ }
+
+ private static boolean isBlank(String value) {
+ return AppearancePatentSheetBuilder.normalize(value).isBlank();
+ }
+
+ /**
+ * 这行到底有没有东西可检——解析行与回传行**任一处**有标题或图片链接就算有。
+ * 只看解析行是历史缺陷:数据在回传行上,闸门因此对整份文件失明。
+ */
+ public static boolean hasCheckableData(AppearancePatentParsedRowVo parsedRow,
+ AppearancePatentResultRowDto resultRow) {
+ return !titleOf(parsedRow, resultRow).isBlank() || !urlOf(parsedRow, resultRow).isBlank();
+ }
+
+ public static String titleOf(AppearancePatentParsedRowVo parsedRow,
+ AppearancePatentResultRowDto resultRow) {
+ String fromResult = resultRow == null ? "" : AppearancePatentSheetBuilder.normalize(resultRow.getTitle());
+ String fromParsed = parsedRow == null ? "" : AppearancePatentSheetBuilder.normalize(parsedRow.getTitle());
+ return fromResult.isBlank() ? fromParsed : fromResult;
+ }
+
+ public static String urlOf(AppearancePatentParsedRowVo parsedRow,
+ AppearancePatentResultRowDto resultRow) {
+ String fromResult = resultRow == null ? "" : AppearancePatentSheetBuilder.normalize(resultRow.getUrl());
+ String fromParsed = parsedRow == null ? "" : AppearancePatentSheetBuilder.normalize(parsedRow.getUrl());
+ return fromResult.isBlank() ? fromParsed : fromResult;
+ }
+
+ /** 未完成检测的行在格子里写什么;已判定的行不走这里。 */
+ public static String missingText(Kind kind) {
+ return switch (kind) {
+ case NO_DATA -> NO_DATA_TEXT;
+ case NOT_INSPECTED -> NOT_INSPECTED_TEXT;
+ case JUDGED -> "";
+ };
+ }
+
+ /**
+ * 按交付口径数一遍行账。
+ *
+ * @param rows 真正会写进结果文件的行集(与出表同一集合,不许自挑)
+ * @param finder 与出表同一个取结果函数,保证"闸门看到的行"="表格里的行"
+ */
+ public static Facts summarize(List rows,
+ Function finder) {
+ int expected = 0;
+ int judged = 0;
+ int noData = 0;
+ Set missingKeys = new LinkedHashSet<>();
+ List rowsToRead = rows == null ? List.of() : rows;
+ for (AppearancePatentParsedRowVo parsedRow : rowsToRead) {
+ if (parsedRow == null) {
+ continue;
+ }
+ AppearancePatentResultRowDto resultRow = finder == null ? null : finder.apply(parsedRow);
+ Kind kind = classify(parsedRow, resultRow);
+ if (kind == Kind.NO_DATA) {
+ noData++;
+ continue;
+ }
+ expected++;
+ if (kind == Kind.JUDGED) {
+ judged++;
+ continue;
+ }
+ addIfPresent(missingKeys, AppearancePatentSheetBuilder.rowKey(parsedRow));
+ if (resultRow != null) {
+ addIfPresent(missingKeys, AppearancePatentSheetBuilder.rowKey(resultRow));
+ }
+ }
+ return new Facts(expected, judged, noData, List.copyOf(missingKeys));
+ }
+
+ private static void addIfPresent(Set target, String value) {
+ if (value != null && !value.isBlank()) {
+ target.add(value);
+ }
+ }
+
+ /**
+ * @param expectedRows 该被检测的行数(分母,交付口径)
+ * @param judgedRows 其中拿到完整结论的行数(分子)
+ * @param noDataRows 连数据都没采集到、无从检测的行数(进文案,不进分母)
+ * @param missingKeys 未完成检测行的行键,供补检轮撤销标记重新申领
+ */
+ public record Facts(int expectedRows, int judgedRows, int noDataRows, List missingKeys) {
+
+ public static final Facts EMPTY = new Facts(0, 0, 0, List.of());
+
+ public int missingRows() {
+ return Math.max(0, expectedRows - judgedRows);
+ }
+
+ /** 分母为 0 时按 1 计:一个该检的行都没有,不存在"覆盖率不足"。 */
+ public double coverage() {
+ return expectedRows <= 0 ? 1D : (double) judgedRows / expectedRows;
+ }
+
+ public Facts plus(Facts other) {
+ if (other == null) {
+ return this;
+ }
+ List keys = new ArrayList<>(missingKeys);
+ keys.addAll(other.missingKeys());
+ return new Facts(expectedRows + other.expectedRows(), judgedRows + other.judgedRows(),
+ noDataRows + other.noDataRows(), List.copyOf(new LinkedHashSet<>(keys)));
+ }
+ }
+}
diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentDeliveryGateTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentDeliveryGateTest.java
new file mode 100644
index 000000000..0244daf99
--- /dev/null
+++ b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentDeliveryGateTest.java
@@ -0,0 +1,310 @@
+package com.nanri.aiimage.modules.appearancepatent.service;
+
+import com.nanri.aiimage.common.exception.BusinessException;
+import com.nanri.aiimage.common.service.DistributedJobLockService;
+import com.nanri.aiimage.config.AppearancePatentProperties;
+import com.nanri.aiimage.config.InstanceMetadata;
+import com.nanri.aiimage.config.StorageProperties;
+import com.nanri.aiimage.modules.appearancepatent.client.AppearancePatentLlmClient;
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentResultRowDto;
+import com.nanri.aiimage.modules.appearancepatent.model.vo.AppearancePatentParsedRowVo;
+import com.nanri.aiimage.modules.appearancepatent.service.support.AppearancePatentRowOutcome;
+import com.nanri.aiimage.modules.appearancepatent.service.support.AppearancePatentSheetBuilder;
+import com.nanri.aiimage.modules.file.service.LocalFileStorageService;
+import com.nanri.aiimage.modules.task.mapper.FileResultMapper;
+import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
+import com.nanri.aiimage.modules.task.mapper.TaskChunkMapper;
+import com.nanri.aiimage.modules.task.mapper.TaskScopeStateMapper;
+import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
+import com.nanri.aiimage.modules.task.model.entity.TaskFileJobEntity;
+import com.nanri.aiimage.modules.task.service.TaskDistributedLockService;
+import com.nanri.aiimage.modules.task.service.TaskFileJobService;
+import com.nanri.aiimage.modules.task.service.TaskHeartbeatPositionService;
+import com.nanri.aiimage.modules.task.service.TaskProgressLightAssembler;
+import com.nanri.aiimage.modules.task.service.TaskProgressSnapshotService;
+import com.nanri.aiimage.modules.task.service.TransientPayloadStorageService;
+import com.nanri.aiimage.modules.usersecret.service.UserApiSecretService;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.transaction.PlatformTransactionManager;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyList;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.contains;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 交付闸门的分母与补检出口(2026-10-10 收口)。
+ *
+ * 旧判据按用户上传表的解析行有没有标题/图片决定这行算不算「该被检测」;现网用户表常只给
+ * id/ASIN/国家,标题与图片链接靠采集回传 ⇒ 分母恒 0 ⇒ 表里 20%–51% 空行、零告警
+ * (六份已交付 xlsx 实测)。这里钉四件事:分母换成"解析行或回传行有数据"的交付口径;
+ * 判失败的任务不再整段跳过闸门;有缺口时先补检一轮再出表;补检排不上队才按已有结果交付。
+ */
+class AppearancePatentDeliveryGateTest {
+
+ private static final long TASK_ID = 30516L;
+
+ private final FileTaskMapper fileTaskMapper = mock(FileTaskMapper.class);
+ private final FileResultMapper fileResultMapper = mock(FileResultMapper.class);
+ private final TaskScopeStateMapper taskScopeStateMapper = mock(TaskScopeStateMapper.class);
+ private final TaskChunkMapper taskChunkMapper = mock(TaskChunkMapper.class);
+ private final LocalFileStorageService localFileStorageService = mock(LocalFileStorageService.class);
+ private final AppearancePatentLlmClient llmClient = mock(AppearancePatentLlmClient.class);
+ private final AppearancePatentTaskCacheService taskCacheService = mock(AppearancePatentTaskCacheService.class);
+ private final AppearancePatentProperties properties = mock(AppearancePatentProperties.class);
+ private final StorageProperties storageProperties = mock(StorageProperties.class);
+ private final TaskFileJobService taskFileJobService = mock(TaskFileJobService.class);
+ private final TaskProgressSnapshotService taskProgressSnapshotService = mock(TaskProgressSnapshotService.class);
+ private final TransientPayloadStorageService transientPayloadStorageService = mock(TransientPayloadStorageService.class);
+ private final PlatformTransactionManager transactionManager = mock(PlatformTransactionManager.class);
+ private final DistributedJobLockService distributedJobLockService = mock(DistributedJobLockService.class);
+ private final TaskDistributedLockService taskDistributedLockService = mock(TaskDistributedLockService.class);
+ private final InstanceMetadata instanceMetadata = mock(InstanceMetadata.class);
+
+ private AppearancePatentTaskService service;
+
+ @BeforeEach
+ void setUp() {
+ when(properties.getLlmCoverageMinRatio()).thenReturn(0.95D);
+ service = new AppearancePatentTaskService(
+ localFileStorageService, null,
+ mock(com.nanri.aiimage.common.service.ResultDownloadResolver.class),
+ storageProperties, fileTaskMapper, fileResultMapper,
+ taskScopeStateMapper, taskChunkMapper, new ObjectMapper(), llmClient, taskCacheService,
+ properties, taskFileJobService, taskProgressSnapshotService,
+ mock(TaskHeartbeatPositionService.class), transientPayloadStorageService, transactionManager,
+ distributedJobLockService, taskDistributedLockService, instanceMetadata,
+ mock(TaskProgressLightAssembler.class), mock(UserApiSecretService.class));
+ }
+
+ /** 用户表只给 id/ASIN/国家的行。 */
+ private static AppearancePatentParsedRowVo sheetRow(String id, String asin) {
+ AppearancePatentParsedRowVo row = new AppearancePatentParsedRowVo();
+ row.setDisplayId(id);
+ row.setSourceId(id);
+ row.setAsin(asin);
+ row.setCountry("英国");
+ return row;
+ }
+
+ private static List sheetRows(int count) {
+ List rows = new ArrayList<>();
+ for (int i = 1; i <= count; i++) {
+ rows.add(sheetRow(String.valueOf(i), "B0A" + i));
+ }
+ return rows;
+ }
+
+ /**
+ * 造客户端回传的结果行集合:前 judgedCount 行有结论,其余为空;
+ * withData=false 时连标题/图片都没有(=采集没拿到数据)。
+ */
+ private static Map submittedRows(List rows,
+ int judgedCount,
+ boolean withData) {
+ Map map = new LinkedHashMap<>();
+ for (int i = 0; i < rows.size(); i++) {
+ AppearancePatentParsedRowVo parsed = rows.get(i);
+ AppearancePatentResultRowDto row = new AppearancePatentResultRowDto();
+ row.setId(parsed.getDisplayId());
+ row.setAsin(parsed.getAsin());
+ row.setCountry(parsed.getCountry());
+ if (withData) {
+ row.setTitle("T-Shirt " + parsed.getDisplayId());
+ row.setUrl("https://img/" + parsed.getDisplayId() + ".jpg");
+ row.setPrice("19.90");
+ }
+ if (i < judgedCount) {
+ row.setTitleRisk("无侵权");
+ row.setAppearanceRisk("无侵权");
+ row.setConclusion("无侵权");
+ }
+ map.put(AppearancePatentSheetBuilder.rowKey(row), row);
+ }
+ return map;
+ }
+
+ private static AppearancePatentRowOutcome.Facts summarize(List rows,
+ Map map) {
+ return AppearancePatentRowOutcome.summarize(rows,
+ parsed -> map.get(AppearancePatentSheetBuilder.rowKey(parsed)));
+ }
+
+ private static FileTaskEntity task(String status) {
+ FileTaskEntity task = new FileTaskEntity();
+ task.setId(TASK_ID);
+ task.setModuleType("APPEARANCE_PATENT");
+ task.setStatus(status);
+ task.setUserId(7L);
+ return task;
+ }
+
+ private static TaskFileJobEntity job(Long id) {
+ TaskFileJobEntity job = new TaskFileJobEntity();
+ job.setId(id);
+ job.setTaskId(TASK_ID);
+ job.setModuleType("APPEARANCE_PATENT");
+ return job;
+ }
+
+ private AppearancePatentRowOutcome.Facts validate(List rows,
+ Map resultMap)
+ throws Exception {
+ Method method = AppearancePatentTaskService.class.getDeclaredMethod(
+ "validateCompleteLlmCoverage", Long.class, List.class, Map.class);
+ method.setAccessible(true);
+ try {
+ return (AppearancePatentRowOutcome.Facts) method.invoke(service, TASK_ID, rows, resultMap);
+ } catch (InvocationTargetException ex) {
+ if (ex.getCause() instanceof RuntimeException runtime) {
+ throw runtime;
+ }
+ throw ex;
+ }
+ }
+
+ private boolean requestRecheck(FileTaskEntity task, TaskFileJobEntity job,
+ AppearancePatentRowOutcome.Facts facts) throws Exception {
+ Method method = AppearancePatentTaskService.class.getDeclaredMethod(
+ "requestRecheckForMissingRows", FileTaskEntity.class, TaskFileJobEntity.class,
+ AppearancePatentRowOutcome.Facts.class);
+ method.setAccessible(true);
+ return (boolean) method.invoke(service, task, job, facts);
+ }
+
+ private String appendGap(String existingError, AppearancePatentRowOutcome.Facts facts) throws Exception {
+ Method method = AppearancePatentTaskService.class.getDeclaredMethod(
+ "appendDeliveryGapMessage", String.class, AppearancePatentRowOutcome.Facts.class);
+ method.setAccessible(true);
+ return (String) method.invoke(service, existingError, facts);
+ }
+
+ // ---------- 分母 ----------
+
+ @Test
+ void denominatorCountsRowsWhoseDataOnlyLivesOnSubmittedRow() throws Exception {
+ // 现网形状:解析行没有标题/图片列,数据全在回传行上;旧口径把这种行整个排除在分母外
+ List rows = sheetRows(10);
+ when(fileTaskMapper.selectById(TASK_ID)).thenReturn(task("FAILED"));
+ AppearancePatentRowOutcome.Facts facts = validate(rows, submittedRows(rows, 0, true));
+ assertEquals(10, facts.expectedRows());
+ assertEquals(0, facts.judgedRows());
+ assertEquals(10, facts.missingRows());
+ }
+
+ @Test
+ void belowFloorThrowsWithBothCountersInTheMessage() {
+ List rows = List.of(sheetRow("1", "B0A1"), sheetRow("2", "B0A2"),
+ sheetRow("3", "B0A3"));
+ Map map = new LinkedHashMap<>();
+ map.putAll(submittedRows(List.of(sheetRow("1", "B0A1")), 1, true));
+ map.putAll(submittedRows(List.of(sheetRow("2", "B0A2")), 0, true));
+ map.putAll(submittedRows(List.of(sheetRow("3", "B0A3")), 0, false));
+ when(fileTaskMapper.selectById(TASK_ID)).thenReturn(task("RUNNING"));
+ // 3 行里 1 行有结论、1 行没跑到、1 行连数据都没采到 ⇒ 分母 2、缺 1 ⇒ 50% < 95%
+ BusinessException ex = assertThrows(BusinessException.class, () -> validate(rows, map));
+ assertTrue(ex.getMessage().contains("1/2 行拿到检测结论"), ex.getMessage());
+ assertTrue(ex.getMessage().contains("低于 95% 覆盖率下限"), ex.getMessage());
+ assertTrue(ex.getMessage().contains("另有 1 行未采集到数据"), ex.getMessage());
+ }
+
+ @Test
+ void aboveFloorReturnsFactsWithoutThrowing() throws Exception {
+ List rows = sheetRows(25);
+ when(fileTaskMapper.selectById(TASK_ID)).thenReturn(task("RUNNING"));
+ AppearancePatentRowOutcome.Facts facts = validate(rows, submittedRows(rows, 24, true));
+ assertEquals(25, facts.expectedRows());
+ assertEquals(1, facts.missingRows());
+ }
+
+ @Test
+ void failedTaskNoLongerSkipsTheGateSilently() throws Exception {
+ // 判失败走「按已有分片出部分结果」这条既有口径:不抛(否则用户连半成品都拿不到),
+ // 但缺口必须被数出来、交给调用方写进任务消息,不再整段早退
+ when(fileTaskMapper.selectById(TASK_ID)).thenReturn(task("FAILED"));
+ List rows = sheetRows(10);
+ AppearancePatentRowOutcome.Facts facts = validate(rows, submittedRows(rows, 3, true));
+ assertEquals(7, facts.missingRows());
+ }
+
+ @Test
+ void allNoDataFileIsNotTreatedAsZeroCoverage() throws Exception {
+ when(fileTaskMapper.selectById(TASK_ID)).thenReturn(task("RUNNING"));
+ List rows = sheetRows(5);
+ AppearancePatentRowOutcome.Facts facts = validate(rows, submittedRows(rows, 0, false));
+ assertEquals(0, facts.expectedRows());
+ assertEquals(5, facts.noDataRows());
+ }
+
+ // ---------- 补检出口 ----------
+
+ @Test
+ void recheckClearsBothMarksAndRequeuesTheJob() throws Exception {
+ List rows = sheetRows(2);
+ AppearancePatentRowOutcome.Facts facts = summarize(rows, submittedRows(rows, 1, true));
+ assertEquals(1, facts.missingRows());
+ when(taskFileJobService.requeue(eq(500L), contains("未完成检测"))).thenReturn(true);
+
+ assertTrue(requestRecheck(task("SUCCESS"), job(500L), facts));
+ // 两态标记都从这一条出口撤(release 里一起清):只撤处理中,"落过库又读不回来"的行永远补不回来
+ verify(taskCacheService).releaseRowInspection(eq(TASK_ID), anyList(), eq(true));
+ verify(taskFileJobService).requeue(eq(500L), contains("补检一轮"));
+ }
+
+ @Test
+ void recheckRefusalFallsBackToDeliveringWhatWeHave() throws Exception {
+ List rows = sheetRows(2);
+ AppearancePatentRowOutcome.Facts facts = summarize(rows, submittedRows(rows, 1, true));
+ when(taskFileJobService.requeue(anyLong(), any())).thenReturn(false);
+
+ assertFalse(requestRecheck(task("SUCCESS"), job(500L), facts));
+ verify(taskCacheService).releaseRowInspection(eq(TASK_ID), anyList(), eq(true));
+ }
+
+ @Test
+ void completeDeliveryRequestsNoRecheck() throws Exception {
+ List rows = sheetRows(1);
+ AppearancePatentRowOutcome.Facts facts = summarize(rows, submittedRows(rows, 1, true));
+ assertFalse(requestRecheck(task("SUCCESS"), job(500L), facts));
+ verify(taskCacheService, never()).releaseRowInspection(anyLong(), anyList(), eq(true));
+ verify(taskFileJobService, never()).requeue(anyLong(), any());
+ }
+
+ // ---------- 任务消息 ----------
+
+ @Test
+ void gapMessageIsWrittenOnceAndKeepsTheOriginalCause() throws Exception {
+ List rows = sheetRows(6);
+ when(fileTaskMapper.selectById(TASK_ID)).thenReturn(task("FAILED"));
+ AppearancePatentRowOutcome.Facts facts = validate(rows, submittedRows(rows, 4, true));
+
+ String first = appendGap("有 1 组抓取失败(重试均未取得数据):646", facts);
+ assertTrue(first.startsWith("有 1 组抓取失败"), first);
+ assertTrue(first.contains("2 行未完成检测"), first);
+ // 同一单被多轮作业反复收尾时不能把缺口句子越接越长
+ assertEquals(first, appendGap(first, facts));
+ assertEquals("原样保留", appendGap("原样保留", AppearancePatentRowOutcome.Facts.EMPTY));
+ // 没有"未采集到数据"的行时,消息里不该冒出"0 行未采集到数据"这种半句话
+ String onlyGap = appendGap(null, facts);
+ assertTrue(onlyGap.startsWith("有 2 行未完成检测"), onlyGap);
+ assertFalse(onlyGap.contains("0 行"), onlyGap);
+ }
+}
diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentRowOutcomeTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentRowOutcomeTest.java
new file mode 100644
index 000000000..ba155b299
--- /dev/null
+++ b/backend-java/src/test/java/com/nanri/aiimage/modules/appearancepatent/service/support/AppearancePatentRowOutcomeTest.java
@@ -0,0 +1,347 @@
+package com.nanri.aiimage.modules.appearancepatent.service.support;
+
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentResultRowDto;
+import com.nanri.aiimage.modules.appearancepatent.model.vo.AppearancePatentParsedRowVo;
+import org.apache.poi.ss.usermodel.Row;
+import org.apache.poi.ss.usermodel.Sheet;
+import org.apache.poi.ss.usermodel.Workbook;
+import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 外观专利「这行为什么没结论」的唯一判据:分类器 + 覆盖率分母。
+ *
+ * 钉的是 2026-10-10 取证到的那条洞:现网用户表常只给 id/ASIN/国家,标题与图片链接靠采集回传,
+ * 而旧闸门按**解析行**有没有标题/图片决定这行算不算「该被检测」⇒ 分母恒 0 ⇒ 表里 20%–51% 空行、
+ * 一条告警都没有(六份已交付 xlsx 实测)。这里要求:判"该不该检"看解析行**或**回传行,
+ * 并且闸门数出来的行集必须等于表格里真被标成未完成的那些行——两边共用同一个 finder。
+ */
+class AppearancePatentRowOutcomeTest {
+
+ private static final int COL_TITLE = 6;
+ private static final int COL_URL = 7;
+ private static final int COL_TITLE_RISK = 9;
+ private static final int COL_APPEARANCE_RISK = 10;
+ private static final int COL_CONCLUSION = 11;
+ private static final int COL_STATUS = 12;
+
+ /** 用户上传表里的一行:只给 id/ASIN/国家,没有标题列,也没有图片列。 */
+ private static AppearancePatentParsedRowVo sheetRowOnlyId(String id, String asin) {
+ AppearancePatentParsedRowVo row = new AppearancePatentParsedRowVo();
+ row.setDisplayId(id);
+ row.setSourceId(id);
+ row.setAsin(asin);
+ row.setCountry("英国");
+ Map values = new LinkedHashMap<>();
+ values.put("品牌", "Brand: Acme");
+ row.setValues(values);
+ return row;
+ }
+
+ private static AppearancePatentParsedRowVo sheetRowWithData(String id, String asin, String title, String url) {
+ AppearancePatentParsedRowVo row = sheetRowOnlyId(id, asin);
+ row.setTitle(title);
+ row.setUrl(url);
+ return row;
+ }
+
+ private static AppearancePatentResultRowDto resultRow(String id, String asin, String title, String url) {
+ AppearancePatentResultRowDto row = new AppearancePatentResultRowDto();
+ row.setId(id);
+ row.setAsin(asin);
+ row.setCountry("英国");
+ row.setTitle(title);
+ row.setUrl(url);
+ row.setPrice("19.90");
+ return row;
+ }
+
+ /** 检出结论的行。 */
+ private static AppearancePatentResultRowDto judgedRow(String id, String asin, String title, String url) {
+ AppearancePatentResultRowDto row = resultRow(id, asin, title, url);
+ row.setTitleRisk("无侵权");
+ row.setAppearanceRisk("无侵权");
+ row.setConclusion("无侵权");
+ return row;
+ }
+
+ private static List sheetRows(int count) {
+ List rows = new ArrayList<>();
+ for (int i = 1; i <= count; i++) {
+ rows.add(sheetRowOnlyId(String.valueOf(i), "B0ASIN" + i));
+ }
+ return rows;
+ }
+
+ /** 按行键取结果:闸门与表格必须走同一个取行函数,否则"同一行集"这句不成立。 */
+ private static Function
+ rowKeyFinder(Map byRowKey) {
+ return parsed -> byRowKey.get(AppearancePatentSheetBuilder.rowKey(parsed));
+ }
+
+ @Test
+ void llmErrorTextSurvivesTheRowLevelOutcome() throws Exception {
+ // 行级文案不能盖掉错误原文:那是用户和运维唯一的归因线索;但它仍然是"没结论的行",闸门照数
+ List all = List.of(sheetRowWithData("1", "B0A", "T-Shirt", "https://img/1.jpg"));
+ AppearancePatentResultRowDto row = resultRow("1", "B0A", "T-Shirt", "https://img/1.jpg");
+ row.setError("LLM http 503: This model is currently overloaded");
+ Map byRowKey = new LinkedHashMap<>();
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(all.get(0)), row);
+
+ try (Workbook workbook = render(all, byRowKey)) {
+ Sheet sheet = workbook.getSheet("外观专利检测结果");
+ assertEquals("LLM http 503: This model is currently overloaded", cell(sheet, 1, COL_TITLE_RISK));
+ assertEquals("失败", cell(sheet, 1, COL_STATUS));
+ }
+ AppearancePatentRowOutcome.Facts facts =
+ AppearancePatentRowOutcome.summarize(all, rowKeyFinder(byRowKey));
+ assertEquals(1, facts.expectedRows());
+ assertEquals(1, facts.missingRows());
+ }
+
+ private static String cell(Sheet sheet, int row, int col) {
+ Row r = sheet.getRow(row);
+ if (r == null || r.getCell(col) == null) {
+ return "";
+ }
+ return r.getCell(col).getStringCellValue().trim();
+ }
+
+ private static Workbook render(List rows,
+ Map byRowKey) {
+ Workbook workbook = new XSSFWorkbook();
+ AppearancePatentSheetBuilder.buildResultSheet(workbook, rows, Map.of(), rowKeyFinder(byRowKey));
+ return workbook;
+ }
+
+ // ---------- 1. 三种原因各判各的 ----------
+
+ @Test
+ void judgedRowIsJudged() {
+ assertEquals(AppearancePatentRowOutcome.Kind.JUDGED, AppearancePatentRowOutcome.classify(
+ sheetRowWithData("1", "B0A", "T-Shirt", "https://img/1.jpg"),
+ judgedRow("1", "B0A", "T-Shirt", "https://img/1.jpg")));
+ }
+
+ @Test
+ void rowWithCrawledDataButNoConclusionIsNotInspected() {
+ // 用户表没有标题列(解析行两列全空),标题/图片在回传行上 —— 旧口径把这种行整个排除在分母外
+ assertEquals(AppearancePatentRowOutcome.Kind.NOT_INSPECTED, AppearancePatentRowOutcome.classify(
+ sheetRowOnlyId("1", "B0A"), resultRow("1", "B0A", "T-Shirt", "https://img/1.jpg")));
+ }
+
+ @Test
+ void rowWithNoDataAnywhereIsNoData() {
+ assertEquals(AppearancePatentRowOutcome.Kind.NO_DATA, AppearancePatentRowOutcome.classify(
+ sheetRowOnlyId("1", "B0A"), resultRow("1", "B0A", "", "")));
+ assertEquals(AppearancePatentRowOutcome.Kind.NO_DATA,
+ AppearancePatentRowOutcome.classify(sheetRowOnlyId("1", "B0A"), null));
+ }
+
+ @Test
+ void unsubmittedRowWithDataStillCounts() {
+ assertEquals(AppearancePatentRowOutcome.Kind.NOT_INSPECTED, AppearancePatentRowOutcome.classify(
+ sheetRowWithData("1", "B0A", "T-Shirt", ""), null));
+ }
+
+ @Test
+ void technicalFailureTextIsNotAJudgement() {
+ AppearancePatentParsedRowVo parsed = sheetRowWithData("1", "B0A", "T-Shirt", "https://img/1.jpg");
+ AppearancePatentResultRowDto row = judgedRow("1", "B0A", "T-Shirt", "https://img/1.jpg");
+ row.setTitleRisk("LLM 调用超时");
+ assertEquals(AppearancePatentRowOutcome.Kind.NOT_INSPECTED,
+ AppearancePatentRowOutcome.classify(parsed, row));
+ }
+
+ @Test
+ void usableFieldRuleKeepsBrandWordsAndDropsTechnicalFailures() {
+ // 历史反例:按 "coze" 子串判失败会把品牌 "Cozee Bay" 的结论整格清空
+ assertTrue(AppearancePatentRowOutcome.isUsableField("Cozee Bay 未发现明显侵权"));
+ assertTrue(AppearancePatentRowOutcome.isUsableField("无侵权"));
+ assertFalse(AppearancePatentRowOutcome.isUsableField(""));
+ assertFalse(AppearancePatentRowOutcome.isUsableField("结果不完整"));
+ assertFalse(AppearancePatentRowOutcome.isUsableField("request timeout"));
+ }
+
+ // ---------- 2. 三句文案不许互相顶替 ----------
+
+ @Test
+ void theThreeMissingReasonsAreDistinctTexts() {
+ String notInspected = AppearancePatentRowOutcome.missingText(AppearancePatentRowOutcome.Kind.NOT_INSPECTED);
+ String noData = AppearancePatentRowOutcome.missingText(AppearancePatentRowOutcome.Kind.NO_DATA);
+ assertTrue(notInspected.contains("未完成检测"), notInspected);
+ assertTrue(noData.contains("未采集到"), noData);
+ assertNotEquals(notInspected, noData);
+ // "检了没答上"这句只留给已判定行里单列为空的格子,不再承担整行没跑到的语义
+ assertNotEquals(notInspected, AppearancePatentSheetBuilder.NO_RESULT_TEXT);
+ assertNotEquals(noData, AppearancePatentSheetBuilder.NO_RESULT_TEXT);
+ assertEquals("", AppearancePatentRowOutcome.missingText(AppearancePatentRowOutcome.Kind.JUDGED));
+ }
+
+ // ---------- 3. 表格里渲染出来的,必须与闸门数出来的同一批行 ----------
+
+ @Test
+ void sheetRendersOutcomeTextPerRow() throws Exception {
+ List all = List.of(
+ sheetRowWithData("1", "B0A", "T-Shirt", "https://img/1.jpg"),
+ sheetRowOnlyId("2", "B0B"),
+ sheetRowOnlyId("3", "B0C"));
+ Map byRowKey = new LinkedHashMap<>();
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(all.get(0)), judgedRow("1", "B0A", "T-Shirt", "https://img/1.jpg"));
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(all.get(1)), resultRow("2", "B0B", "Mug", "https://img/2.jpg"));
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(all.get(2)), resultRow("3", "B0C", "", ""));
+
+ try (Workbook workbook = render(all, byRowKey)) {
+ Sheet sheet = workbook.getSheet("外观专利检测结果");
+ assertEquals("无侵权", cell(sheet, 1, COL_TITLE_RISK));
+ assertEquals("成功", cell(sheet, 1, COL_STATUS));
+ String notInspected = AppearancePatentRowOutcome.missingText(AppearancePatentRowOutcome.Kind.NOT_INSPECTED);
+ String noData = AppearancePatentRowOutcome.missingText(AppearancePatentRowOutcome.Kind.NO_DATA);
+ assertEquals(notInspected, cell(sheet, 2, COL_TITLE_RISK));
+ assertEquals(notInspected, cell(sheet, 2, COL_CONCLUSION));
+ assertEquals(notInspected, cell(sheet, 2, COL_APPEARANCE_RISK));
+ assertEquals(noData, cell(sheet, 3, COL_TITLE_RISK));
+ assertEquals(noData, cell(sheet, 3, COL_CONCLUSION));
+ assertEquals("失败", cell(sheet, 2, COL_STATUS));
+ assertEquals("失败", cell(sheet, 3, COL_STATUS));
+ // 采到的标题照常写出来(用户得知道是哪一行),没采到的不能凭空造
+ assertEquals("Mug", cell(sheet, 2, COL_TITLE));
+ assertEquals("", cell(sheet, 3, COL_TITLE));
+ assertEquals("", cell(sheet, 3, COL_URL));
+ }
+ }
+
+ @Test
+ void gateDenominatorMatchesDeliveredNotInspectedRows() throws Exception {
+ // 现网 30516 的形状:493 行里 240 行有结论,253 行整片没跑到,旧闸门一条告警都没打
+ List all = sheetRows(493);
+ Map byRowKey = new LinkedHashMap<>();
+ for (int i = 0; i < all.size(); i++) {
+ AppearancePatentParsedRowVo parsed = all.get(i);
+ boolean judged = i < 240;
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(parsed), judged
+ ? judgedRow(parsed.getDisplayId(), parsed.getAsin(), "T" + i, "https://img/" + i + ".jpg")
+ : resultRow(parsed.getDisplayId(), parsed.getAsin(), "T" + i, "https://img/" + i + ".jpg"));
+ }
+ AppearancePatentRowOutcome.Facts facts =
+ AppearancePatentRowOutcome.summarize(all, rowKeyFinder(byRowKey));
+ assertEquals(493, facts.expectedRows());
+ assertEquals(240, facts.judgedRows());
+ assertEquals(253, facts.missingRows());
+ assertEquals(0, facts.noDataRows());
+ assertTrue(facts.coverage() < 0.95, "覆盖率必须低到能被闸门拦下:" + facts.coverage());
+
+ try (Workbook workbook = render(all, byRowKey)) {
+ Sheet sheet = workbook.getSheet("外观专利检测结果");
+ int rendered = 0;
+ for (int r = 1; r <= all.size(); r++) {
+ if (AppearancePatentRowOutcome.missingText(AppearancePatentRowOutcome.Kind.NOT_INSPECTED)
+ .equals(cell(sheet, r, COL_TITLE_RISK))) {
+ rendered++;
+ }
+ }
+ assertEquals(facts.missingRows(), rendered);
+ }
+ // 补检轮要拿这些行键去撤销标记
+ assertEquals(253, facts.missingKeys().size());
+ }
+
+ @Test
+ void noDataRowsStayOutOfTheDenominatorButAreCounted() {
+ List all = sheetRows(10);
+ Map byRowKey = new LinkedHashMap<>();
+ for (int i = 0; i < all.size(); i++) {
+ AppearancePatentParsedRowVo parsed = all.get(i);
+ // 前 7 行采到了数据(其中前 3 行有结论),后 3 行连标题带图都没采到
+ String title = i < 7 ? "T" : "";
+ String url = i < 7 ? "https://img" : "";
+ AppearancePatentResultRowDto row = resultRow(parsed.getDisplayId(), parsed.getAsin(), title, url);
+ if (i < 3) {
+ row.setTitleRisk("无侵权");
+ row.setAppearanceRisk("无侵权");
+ row.setConclusion("无侵权");
+ }
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(parsed), row);
+ }
+ AppearancePatentRowOutcome.Facts facts =
+ AppearancePatentRowOutcome.summarize(all, rowKeyFinder(byRowKey));
+ assertEquals(7, facts.expectedRows());
+ assertEquals(3, facts.judgedRows());
+ assertEquals(4, facts.missingRows());
+ assertEquals(3, facts.noDataRows());
+ }
+
+ @Test
+ void emptyDenominatorIsNotATargetForTheGate() {
+ // 全是没采集到数据的行:分母 0 不能读成"覆盖率 0",否则一张空表会永久卡在补检里
+ List all = sheetRows(4);
+ Map byRowKey = new LinkedHashMap<>();
+ for (AppearancePatentParsedRowVo parsed : all) {
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(parsed),
+ resultRow(parsed.getDisplayId(), parsed.getAsin(), "", ""));
+ }
+ AppearancePatentRowOutcome.Facts facts =
+ AppearancePatentRowOutcome.summarize(all, rowKeyFinder(byRowKey));
+ assertEquals(0, facts.expectedRows());
+ assertEquals(1.0, facts.coverage());
+ assertEquals(4, facts.noDataRows());
+ assertTrue(facts.missingKeys().isEmpty());
+ }
+
+ @Test
+ void factsAggregateAcrossSourceFiles() {
+ AppearancePatentRowOutcome.Facts a =
+ new AppearancePatentRowOutcome.Facts(10, 8, 2, List.of("1::B0A::英国", "2::B0B::英国"));
+ AppearancePatentRowOutcome.Facts b = new AppearancePatentRowOutcome.Facts(5, 5, 0, List.of());
+ AppearancePatentRowOutcome.Facts sum = a.plus(b);
+ assertEquals(15, sum.expectedRows());
+ assertEquals(13, sum.judgedRows());
+ assertEquals(2, sum.noDataRows());
+ assertEquals(2, sum.missingKeys().size());
+ assertEquals(b.coverage(), b.plus(AppearancePatentRowOutcome.Facts.EMPTY).coverage());
+ }
+
+ @Test
+ void titleAndUrlFallBackFromResultRowToSheetRow() {
+ AppearancePatentParsedRowVo parsed = sheetRowWithData("1", "B0A", "表格里的标题", "");
+ assertEquals("回传的标题",
+ AppearancePatentRowOutcome.titleOf(parsed, resultRow("1", "B0A", "回传的标题", "")));
+ assertEquals("表格里的标题",
+ AppearancePatentRowOutcome.titleOf(parsed, resultRow("1", "B0A", "", "")));
+ assertEquals("", AppearancePatentRowOutcome.urlOf(null, null));
+ }
+
+ @Test
+ void reasonSheetCarriesTheSameOutcome() throws Exception {
+ List all = List.of(sheetRowOnlyId("1", "B0A"), sheetRowOnlyId("2", "B0B"));
+ Map byRowKey = new LinkedHashMap<>();
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(all.get(0)), resultRow("1", "B0A", "T", "https://img"));
+ byRowKey.put(AppearancePatentSheetBuilder.rowKey(all.get(1)), resultRow("2", "B0B", "", ""));
+ try (Workbook workbook = render(all, byRowKey)) {
+ Sheet reason = workbook.getSheet("原因");
+ // 按 ASIN 找行:原因 sheet 的行号不参与判定
+ assertTrue(cell(reason, rowIndexByAsin(reason, "B0A"), 1).contains("未完成检测"));
+ assertTrue(cell(reason, rowIndexByAsin(reason, "B0B"), 1).contains("未采集到"));
+ }
+ }
+
+ private static int rowIndexByAsin(Sheet sheet, String asin) {
+ for (Row row : sheet) {
+ if (row != null && row.getCell(0) != null && asin.equals(row.getCell(0).getStringCellValue())) {
+ return row.getRowNum();
+ }
+ }
+ throw new AssertionError("原因 sheet 里没有 ASIN=" + asin + " 的行");
+ }
+}
diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/similarasin/service/support/SimilarAsinDeliveryLedgerTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/similarasin/service/support/SimilarAsinDeliveryLedgerTest.java
new file mode 100644
index 000000000..e66375eea
--- /dev/null
+++ b/backend-java/src/test/java/com/nanri/aiimage/modules/similarasin/service/support/SimilarAsinDeliveryLedgerTest.java
@@ -0,0 +1,50 @@
+package com.nanri.aiimage.modules.similarasin.service.support;
+
+import com.nanri.aiimage.modules.similarasin.model.dto.SimilarAsinResultRowDto;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 货源面的交付口径(2026-10-10 先只做度量入口):结果表给用户看的判定列是「相似度」与「是否同款」,
+ * 两个都得有可用文本才算这行给出了结论。
+ *
+ * 既有 {@code hasResolvedLlmFields} 是"十一个字段任一可用",只填上 category 或 status 的行
+ * 会被读成"已经检测"——它在表格里两列是空的,而这条判据永远不会报警(外观专利那面刚为同一个形状
+ * 数出 20%~51% 空行)。这里先钉住交付口径本身,阈值等本面实测分布出来再定。
+ */
+class SimilarAsinDeliveryLedgerTest {
+
+ private static SimilarAsinResultRowDto row(String similarity, String isConform) {
+ SimilarAsinResultRowDto row = new SimilarAsinResultRowDto();
+ row.setSimilarity(similarity);
+ row.setIsConform(isConform);
+ return row;
+ }
+
+ @Test
+ void bothVerdictColumnsRequired() {
+ assertTrue(SimilarAsinResultTextSupport.hasDeliverableResult(row("92%", "符合")));
+ assertFalse(SimilarAsinResultTextSupport.hasDeliverableResult(row("", "符合")));
+ assertFalse(SimilarAsinResultTextSupport.hasDeliverableResult(row("92%", "")));
+ assertFalse(SimilarAsinResultTextSupport.hasDeliverableResult(null));
+ }
+
+ @Test
+ void technicalFailureTextIsNotADeliverableVerdict() {
+ assertFalse(SimilarAsinResultTextSupport.hasDeliverableResult(row("LLM 调用超时", "符合")));
+ assertFalse(SimilarAsinResultTextSupport.hasDeliverableResult(row("92%", "结果不完整")));
+ }
+
+ @Test
+ void aRowFilledOnlyByNonVerdictColumnsIsNotDeliverable() {
+ // 这条就是"十一字段任一可用"会漏判的形状:category/status 有值、两列判定空着
+ SimilarAsinResultRowDto row = row("", "");
+ row.setCategory(" Shoes");
+ row.setStatus("DONE");
+ assertTrue(SimilarAsinResultTextSupport.hasResolvedLlmFields(row),
+ "旧口径把这行读成已检测——正是需要被数出来的那类空行");
+ assertFalse(SimilarAsinResultTextSupport.hasDeliverableResult(row));
+ }
+}