fix(外观专利): 失败兜底出部分结果文件+WAIT_LLM 停放作业心跳续租(31302/31354)

线上两例死法修复,目标是「任务失败了也能下载」:
- 31354:组装作业在 WAIT_LLM 停放期执行线程已退出、Worker 执行期心跳
  已取消,job 级 stuck 扫描按 updated_at 判陈旧,5 分钟阈值×5 次重试
  耗尽后误判「文件生成任务运行超时」。客户端心跳经
  AppearancePatentTaskHeartbeatSpi#onHeartbeat 按
  dbJobTouchIntervalMillis(默认 60s,远小于 5 分钟阈值)节流续租
  (touchRunningAssembleJobsIfStale,与 SimilarAsin 同口径)。
- 31302:覆盖率闸门判红重试 5 次判死后,1196 行成品零交付且不能下载。
  接通 fallbackAssembleOnFailure 兜底钩子:作业判死后用已有分片出
  部分结果文件(validateCompleteLlmCoverage 加 allowPartial 旁路),
  写上 result.resultFileUrl 后前端下载按钮即恢复;兜底幂等(已有
  结果文件短 路)、不动任务终态、与补传恢复重跑兼容。
- 棘轮尺 STRICT_TOTAL 1003→1004、NOT_RETHROW 561→562 抬格并逐处
  记名(兜底自吞 catch 属接口契约要求的 fail-open 形状)。

全量 mvn -o test 4492 支 0 失败(9 skipped 为既有跳过)。
This commit is contained in:
2026-10-18 23:41:24 +08:00
parent 1be4d766bb
commit 49eee59a13
10 changed files with 424 additions and 8 deletions
@@ -6,7 +6,8 @@ import com.nanri.aiimage.modules.task.model.entity.TaskFileJobEntity;
/**
* APPEARANCE_PATENT 结果文件 Job Handler(04 注册表)。
* process 返回 Service 的 boolean(false=等待 LLM 异步结果,Worker 保持运行心跳);
* process 返回 Service 的 boolean(false=停放等待下一轮分片回传触发;此时执行线程已退出、
* Worker 的执行期心跳已取消,停放租约由客户端心跳经 AppearancePatentTaskHeartbeatSpi#onHeartbeat 续命);
* cleanup 委托 cleanupResultFileJob;支持异步 offload;owner scoped。
*/
public class AppearancePatentResultFileJobHandler implements ResultFileJobHandler {
@@ -32,6 +33,13 @@ public class AppearancePatentResultFileJobHandler implements ResultFileJobHandle
appearancePatentTaskService.cleanupResultFileJob(job);
}
@Override
public boolean fallbackAssembleOnFailure(TaskFileJobEntity job, String message) {
// 作业重试耗尽(含 WAIT_LLM 停放被 stuck 棘轮判死)时:用已有分片/结论尽力出
// 部分结果文件供下载,别让已跑完的检测一张表都不剩(线上任务 31302/31354)。
return appearancePatentTaskService.fallbackAssembleResultFile(job);
}
@Override
public boolean supportsAsyncOffload() {
return true;
@@ -1,6 +1,9 @@
package com.nanri.aiimage.modules.appearancepatent.service;
import com.nanri.aiimage.config.AppearancePatentProperties;
import com.nanri.aiimage.modules.task.model.dto.TaskHeartbeatRequest;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.service.TaskFileJobService;
import com.nanri.aiimage.modules.task.spi.TaskModuleHeartbeatSpi;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
@@ -10,12 +13,21 @@ import org.springframework.stereotype.Service;
*
* <p>心跳逻辑(缓存刷新 / 任务缓存回写)从 task 模块收回本模块,task 侧只依赖 SPI 接口,
* 消除 task → 业务模块的编译期依赖。
*
* <p>onHeartbeat 顺带给结果文件组装作业续租(与 {@code SimilarAsinTaskHeartbeatSpi} 同一套口径):
* 组装作业在 WAIT_LLM 停放期间(process 返回 false 等下一轮分片回传触发)执行线程已退出、
* Worker 的执行期心跳已随之取消,作业停在 RUNNING 无人续命,会被 job 级 stuck 扫描按
* updated_at 判陈旧、5 次重试耗尽后误判成「文件生成任务运行超时」(线上任务 31354)。
* 客户端在任务执行期持续上报心跳,经这里续租即可覆盖整个停放窗口;
* 客户端也停了的场景由 stale 收尾链路与失败兜底(fallbackAssembleResultFile)接住。
*/
@Service
@RequiredArgsConstructor
public class AppearancePatentTaskHeartbeatSpi implements TaskModuleHeartbeatSpi {
private final AppearancePatentTaskCacheService cacheService;
private final TaskFileJobService taskFileJobService;
private final AppearancePatentProperties appearancePatentProperties;
@Override
public String moduleType() {
@@ -26,4 +38,19 @@ public class AppearancePatentTaskHeartbeatSpi implements TaskModuleHeartbeatSpi
public void touchHeartbeat(Long taskId, TaskHeartbeatRequest request) {
cacheService.touchTaskHeartbeat(taskId);
}
@Override
public void onHeartbeat(FileTaskEntity task) {
if (task == null || task.getId() == null) {
return;
}
// touchRunningAssembleJobsIfStale 的 SQL 自带「距上次刷新超过间隔才写」的节流,
// 心跳再密也不会把库写爆,无需在这里另做节流。
taskFileJobService.touchRunningAssembleJobsIfStale(
task.getId(), moduleType(), jobTouchIntervalMillis());
}
private long jobTouchIntervalMillis() {
return Math.max(1_000L, appearancePatentProperties.getDbJobTouchIntervalMillis());
}
}
@@ -1889,6 +1889,67 @@ public class AppearancePatentTaskService {
return true;
}
/**
* 失败兜底:组装作业重试耗尽(WAIT_LLM 停放被 stuck 棘轮判死、或组装异常连吃 5 次重试)后调用,
* 用已回传的分片与已拿到结论的行尽力生成可下载的部分结果文件。
*
* <p>用户线上点名要的保证:「起码失败了也可以下载」。判死时已跑完的检测结论仍挂在分片里,
* 不出表就一张都不剩(线上任务 31302:1196 行成品困在判死作业里零交付)。
*
* <p>覆盖率闸门按「允许部分结果」放行(缺口只记行账);任务状态在这里**不收尾**——判死时
* 任务可能仍在跑、客户端仍在心跳(stuck 棘轮只判作业、不判任务),提前置终态会把活任务误杀;
* 任务终态仍由 stale 收尾链路 / 分片回传链路按既有口径落。文件挂上 result(result_file_url)
* 后前端下载按钮即出现,与任务/作业状态无关({@code AppearancePatentHistoryAssembler#attachFileJobState})。
*
* <p>幂等:结果文件已存在(result_file_url 非空)直接返回 true,不重做组装——stuck 扫描对
* 终态失败作业每轮都会重入兜底钩子,靠这里挡住重复组装。与补传恢复(maybeRecoverTerminalFailedAssemble)
* 的重跑并发时两边都只写合法结果文件,后写者覆盖,无中间态。
*
* <p>实现自吞异常(兜底失败只记日志,不影响作业已终态失败的事实),返回是否有可下载结果。
*/
public boolean fallbackAssembleResultFile(TaskFileJobEntity job) {
if (job == null || job.getTaskId() == null || job.getResultId() == null) {
return false;
}
try {
FileResultEntity result = fileResultMapper.selectById(job.getResultId());
if (result == null || !MODULE_TYPE.equals(result.getModuleType())) {
log.warn("[appearance-patent] fallback assemble skipped because result record missing taskId={} resultId={}",
job.getTaskId(), job.getResultId());
return false;
}
if (result.getResultFileUrl() != null && !result.getResultFileUrl().isBlank()) {
log.info("[appearance-patent] fallback assemble skipped because result file already exists taskId={} resultId={} jobStatus={}",
job.getTaskId(), job.getResultId(), job.getStatus());
return true;
}
FileTaskEntity task = fileTaskMapper.selectById(job.getTaskId());
if (task == null || !MODULE_TYPE.equals(task.getModuleType())) {
log.warn("[appearance-patent] fallback assemble skipped because task missing taskId={} resultId={}",
job.getTaskId(), job.getResultId());
return false;
}
// 与 processResultFileJobLocked 同一判法:非归属实例让给归属机(stuck 扫描两台都在跑,
// 不挡的话每台都会每 60 秒重入一次兜底钩子)。
job.setScopeKey(buildTaskOwnerScopeKey(task));
if (!isJobOwnedByCurrentInstance(job)) {
log.info("[appearance-patent] fallback assemble skipped because owner is another instance taskId={} resultId={}",
job.getTaskId(), job.getResultId());
return false;
}
AppearancePatentRowOutcome.Facts facts = assembleResultWorkbook(task, result, true);
fileResultMapper.updateById(result);
log.warn("[appearance-patent] fallback assemble produced partial result taskId={} resultId={} jobStatus={} expectedRows={} judgedRows={} missingRows={} noDataRows={}",
job.getTaskId(), job.getResultId(), job.getStatus(),
facts.expectedRows(), facts.judgedRows(), facts.missingRows(), facts.noDataRows());
return true;
} catch (Exception ex) {
log.warn("[appearance-patent] fallback assemble failed taskId={} resultId={} msg={}",
job.getTaskId(), job.getResultId(), ex.getMessage(), ex);
return false;
}
}
/** 返回真正落库的行键;没匹配到分片行的键不会出现在里面,调用方据此决定要不要撤销已检测标记。 */
private Set<String> mergeLlmRowsIntoSubmittedChunks(FileTaskEntity task,
List<AppearancePatentResultRowDto> llmRows,
@@ -2189,6 +2250,16 @@ public class AppearancePatentTaskService {
}
private AppearancePatentRowOutcome.Facts assembleResultWorkbook(FileTaskEntity task, FileResultEntity result) {
return assembleResultWorkbook(task, result, false);
}
/**
* @param allowPartial 供失败兜底路径({@link #fallbackAssembleResultFile})使用:
* 覆盖率闸门按「允许部分结果」放行——作业已判死,缺口不再有补齐窗口,
* 此刻拦下成品只会让用户连半张表都拿不到;缺口仍由行账锚点记数。
*/
private AppearancePatentRowOutcome.Facts assembleResultWorkbook(FileTaskEntity task, FileResultEntity result,
boolean allowPartial) {
AppearancePatentParsedPayloadDto parsed = readParsedPayload(task);
List<AppearancePatentParsedRowVo> parsedRows = parsed.getAllItems() == null
? List.of() : parsed.getAllItems();
@@ -2214,7 +2285,7 @@ public class AppearancePatentTaskService {
// 覆盖率先于「本文件无结果就跳过」判定:整源文件的 LLM 结果全丢(分片被跳过、
// 结果清空)时覆盖率是 0%,必须在这里判掉,不能让 zip 少一个文件还报任务成功。
deliveryFacts = deliveryFacts.plus(
validateCompleteLlmCoverage(task.getId(), item.rows(), resultMap));
validateCompleteLlmCoverage(task.getId(), item.rows(), resultMap, allowPartial));
List<AppearancePatentParsedRowVo> receivedRows = filterReceivedParsedRows(item.rows(), resultMap);
if (receivedRows.isEmpty()) {
resultMap.clear();
@@ -2417,6 +2488,13 @@ public class AppearancePatentTaskService {
private AppearancePatentRowOutcome.Facts validateCompleteLlmCoverage(Long taskId,
List<AppearancePatentParsedRowVo> parsedRows,
Map<String, AppearancePatentResultRowDto> resultMap) {
return validateCompleteLlmCoverage(taskId, parsedRows, resultMap, false);
}
private AppearancePatentRowOutcome.Facts validateCompleteLlmCoverage(Long taskId,
List<AppearancePatentParsedRowVo> parsedRows,
Map<String, AppearancePatentResultRowDto> resultMap,
boolean allowPartial) {
if (parsedRows == null || parsedRows.isEmpty()) {
return AppearancePatentRowOutcome.Facts.EMPTY;
}
@@ -2432,8 +2510,9 @@ public class AppearancePatentTaskService {
}
double minCoverage = properties.getLlmCoverageMinRatio();
// 已判失败的任务走的是"按已有分片出部分结果"这条既有口径,这里再抛会把成品彻底拿掉;
// 但它不再静默:上面的行账锚点必打,缺口由调用方写进任务错误信息,用户看得到「N 行没检测」。
if (!taskAlreadyFailed && minCoverage > 0 && facts.expectedRows() > 0
// 失败兜底路径(allowPartial=true,作业已判死)同理放行。
// 两者都不再静默:上面的行账锚点必打,缺口由调用方写进任务错误信息,用户看得到「N 行没检测」。
if (!taskAlreadyFailed && !allowPartial && minCoverage > 0 && facts.expectedRows() > 0
&& facts.coverage() + 1e-9 < minCoverage) {
throw new BusinessException("LLM 结果不完整:仅 " + facts.judgedRows() + "/" + facts.expectedRows()
+ " 行拿到检测结论(低于 " + Math.round(minCoverage * 100) + "% 覆盖率下限)"