feat(llm-arrears): 上游 LLM 欠费的提示落到任务界面并让货源链欠费即判死

现网两处叠加的洞:归因文案早在 2026-10-27 就写进了 biz_file_task.error_message,
但两支历史装配器只读结果行的错误、buildActiveItem 连任务级那条都不带,用户在列表
里只看到「失败」两字;货源链更是只有行级归因、任务停在 RUNNING,采集端读不到
心跳的 alive=false,就继续为永远进不了 LLM 的行按次付费买出口 IP。

- 新增 modules/task/service/TaskVisibleFailureNotice:界面出口的单一判据。认出本仓
  写下的欠费/密钥失效归因就换成 TASK_TERMINAL_GUIDANCE 那句中文动作,库里原文一字
  不改(英文响应体与上游账户号不进界面,对齐 RawExceptionMessageSinkGuardTest)。
  刻意不用 TaskRetryEligibility.BALANCE 当显示判据——那一类还涵盖 jikip 代理欠费,
  拿它换句子会把「出口没钱」说成「LLM 账户欠费」,正是 10-27 要避免的误导。
- 两支 HistoryAssembler 共用该出口:行级为空时兜底任务级归因,欠费压过行级副产品。
- 货源链补 terminalizeOnFatalLlmFailure(口径逐字对齐外观专利):判据取 BALANCE、
  非终态才写、可重入;并让 finalizeTask 不许用空/二次错误串盖掉整单结论。
- 用例:TaskVisibleFailureNoticeTest 11 例、SimilarAsinLlmArrearsTerminalTest 16 例
  (含 502/429/连接失败/心跳超时不许误杀、已终态不改写、收尾覆盖保护、接线源码钉子),
  两支装配器各补 4/3 例。后端整量 5,127 例/0 失败/19 skipped。
This commit is contained in:
2026-10-31 17:34:54 +08:00
parent 1c179e0f2e
commit a4e4456b50
10 changed files with 754 additions and 3 deletions
@@ -8,6 +8,7 @@ import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.model.entity.TaskFileJobEntity;
import com.nanri.aiimage.modules.task.model.entity.TaskProgressSnapshotEntity;
import com.nanri.aiimage.modules.task.service.TaskProgressSnapshotService;
import com.nanri.aiimage.modules.task.service.TaskVisibleFailureNotice;
import java.time.LocalDateTime;
import java.util.function.Function;
@@ -15,7 +16,9 @@ import java.util.function.Function;
/**
* 任务 97:AppearancePatentHistoryAssembler 历史查询组装器。
* 历史列表 VO 拼装(toHistoryItem + 排序辅助 historyPriority/historyActivityTime +
* 文件进度链)从 AppearancePatentTaskService 原样搬移;只读不落库;输出与现状逐字段一致。
* 文件进度链)从 AppearancePatentTaskService 原样搬移;只读不落库;输出与现状逐字段一致
* (2026-10-31 唯一例外:{@code error} 改走 {@link TaskVisibleFailureNotice},行级为空时补上任务级归因,
* 欠费单在列表里不再只剩一个「失败」)。
* 进度百分比计算(calculateDisplayProgressPercent/extractSnapshotDisplayPercent)仍在
* 服务侧(与 saveFileBuildProgress 实时路径共享),以函数注入。
*/
@@ -54,7 +57,7 @@ public class AppearancePatentHistoryAssembler {
vo.setTaskStatus(task == null ? null : task.getStatus());
vo.setSuccess(row.getResultFileUrl() != null && !row.getResultFileUrl().isBlank()
|| row.getSuccess() != null && row.getSuccess() == 1);
vo.setError(row.getErrorMessage());
vo.setError(TaskVisibleFailureNotice.forHistoryRow(task, row.getErrorMessage()));
vo.setRowCount(row.getRowCount());
vo.setCreatedAt(fmt(row.getCreatedAt()));
// 任务开始时间复用 biz_file_task.created_at;缺 task 时回退到 result.createdAt 兜底
@@ -69,6 +72,7 @@ public class AppearancePatentHistoryAssembler {
vo.setTaskId(task.getId());
vo.setTaskStatus(task.getStatus());
vo.setSuccess(false);
vo.setError(TaskVisibleFailureNotice.forTask(task));
vo.setCreatedAt(fmt(task.getCreatedAt()));
vo.setStartedAt(fmt(task.getCreatedAt()));
vo.setFinishedAt(fmt(task.getFinishedAt()));
@@ -8,6 +8,7 @@ import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.nanri.aiimage.common.exception.BusinessException;
import com.nanri.aiimage.common.security.AdminAuthSupport;
import com.nanri.aiimage.common.retry.LlmBalanceGuard;
import com.nanri.aiimage.common.task.TaskStatuses;
import com.nanri.aiimage.common.task.LockSkipWitness;
import com.nanri.aiimage.common.service.DistributedJobLockService;
@@ -70,6 +71,8 @@ import com.nanri.aiimage.modules.task.service.TaskFileJobService;
import com.nanri.aiimage.modules.task.service.TaskDistributedLockService;
import com.nanri.aiimage.modules.task.service.TaskHeartbeatPositionService;
import com.nanri.aiimage.modules.task.service.TaskProgressSnapshotService;
import com.nanri.aiimage.modules.task.service.TaskRetryEligibility;
import com.nanri.aiimage.modules.task.service.TaskVisibleFailureNotice;
import com.nanri.aiimage.modules.task.service.TransientPayloadStorageService;
import com.nanri.aiimage.modules.usersecret.service.UserApiSecretService;
import lombok.RequiredArgsConstructor;
@@ -1342,6 +1345,12 @@ public class SimilarAsinTaskService implements SimilarAsinPipelineHost {
throw new IllegalStateException("Synchronous result assembly is not allowed in a database transaction");
}
}
// 欠费/密钥失效是整单的结论,后来的收尾(哪怕带空错误串)不许把它盖掉或翻成成功:
// 盖掉的后果是界面重新变成「只见失败、不见原因」,采集端也以为这单还能跑。
if (TaskVisibleFailureNotice.isWholeTaskVerdict(task.getErrorMessage())
&& !TaskVisibleFailureNotice.isWholeTaskVerdict(finalError)) {
finalError = task.getErrorMessage();
}
boolean failed = finalError != null && !finalError.isBlank();
boolean waitingForAssemble = !failed && assembleWorkbook && !shouldAssembleSynchronously();
task.setStatus(waitingForAssemble ? STATUS_RUNNING : (failed ? STATUS_FAILED : STATUS_SUCCESS));
@@ -1575,6 +1584,50 @@ public class SimilarAsinTaskService implements SimilarAsinPipelineHost {
return task.getId();
}
/**
* 上游 LLM 账户欠费/密钥失效 → 任务<b>立即</b>落终态 FAILED(2026-10-31,口径与外观专利 2026-10-27 那条一致)。
*
* <p>为什么必须由 Java 侧落终态:{@code maixiang similar_worker} 只看 {@code /task/heartbeat} 的
* {@code alive}({@code similar_worker.py:249}),任务还停在 RUNNING 它就看不到判决,会继续为
* 永远进不了 LLM 的行<b>按次付费买出口 IP</b>。任务一终态,{@code TaskHeartbeatService} 才对该任务
* 回 {@code alive=false},worker 下一跳收手。
*
* <p>判据只取 {@link TaskRetryEligibility.Category#BALANCE}(欠费与 LLM 密钥失效同族,复用既有唯一
* 判据、不抄第二份字面量表):连接不可达(SERVICE_DOWN)、429 限流、5xx 抖动、抓取缺口都属
* "外部会自己恢复或补传能救",判宽了就是拿用户的整单给一次网络抖动陪葬。写之前重读库里现状态,
* 已终态的一律不动(铁律 14),本方法因此可重入。
*/
@Override
public void terminalizeOnFatalLlmFailure(FileTaskEntity task, String failureMessage) {
if (task == null || task.getId() == null) {
return;
}
if (TaskRetryEligibility.forceMajeureCategory(failureMessage) != TaskRetryEligibility.Category.BALANCE) {
return;
}
FileTaskEntity current = fileTaskMapper.selectById(task.getId());
String currentStatus = current != null ? current.getStatus() : task.getStatus();
if (TaskStatuses.FileTask.TERMINAL.contains(currentStatus)) {
log.info("[similar-asin] 任务已是终态,欠费归因不改写状态 taskId={} status={}", task.getId(), currentStatus);
return;
}
String raw = failureMessage == null ? "" : failureMessage.trim();
task.setStatus(STATUS_FAILED);
task.setSuccessFileCount(0);
task.setFailedFileCount(1);
// 生产者原文一个字都不在这里重写(支持同学要对着上游响应体查根因);界面上那句中文由
// TaskVisibleFailureNotice 在出口处给,英文原文与上游账户号不进界面。
task.setErrorMessage(raw.isEmpty()
? LlmBalanceGuard.TASK_TERMINAL_GUIDANCE
: raw + ";" + LlmBalanceGuard.TASK_TERMINAL_GUIDANCE);
task.setUpdatedAt(LocalDateTime.now());
task.setFinishedAt(LocalDateTime.now());
fileTaskMapper.updateById(task);
taskCacheService.deleteTaskCache(task.getId());
log.warn("[similar-asin] LLM 上游欠费/密钥失效,任务落终态 FAILED 以停止为空转的行继续买出口 IP"
+ " taskId={} err={}", task.getId(), task.getErrorMessage());
}
@Override
public void finalizeExhaustedResultFileJob(TaskFileJobEntity job, String message) {
handleResultFileJobFailure(job, message);
@@ -22,6 +22,7 @@ import com.nanri.aiimage.modules.task.model.entity.TaskFileJobEntity;
import com.nanri.aiimage.modules.task.model.entity.TaskProgressSnapshotEntity;
import com.nanri.aiimage.modules.task.model.entity.TaskScopeStateEntity;
import com.nanri.aiimage.modules.task.service.TaskProgressSnapshotService;
import com.nanri.aiimage.modules.task.service.TaskVisibleFailureNotice;
import com.nanri.aiimage.modules.task.service.TransientPayloadStorageService;
import lombok.extern.slf4j.Slf4j;
@@ -121,6 +122,7 @@ public class SimilarAsinHistoryAssembler {
vo.setTaskId(task.getId());
vo.setTaskStatus(task.getStatus());
vo.setSuccess(false);
vo.setError(TaskVisibleFailureNotice.forTask(task));
vo.setCreatedAt(fmt(task.getCreatedAt()));
vo.setStartedAt(fmt(task.getCreatedAt()));
vo.setFinishedAt(fmt(task.getFinishedAt()));
@@ -137,7 +139,7 @@ public class SimilarAsinHistoryAssembler {
vo.setTaskStatus(resolveDisplayTaskStatus(task, row));
attachFileJobState(vo, row, job, task);
vo.setSuccess(row.getSuccess() != null && row.getSuccess() == 1);
vo.setError(row.getErrorMessage());
vo.setError(TaskVisibleFailureNotice.forHistoryRow(task, row.getErrorMessage()));
vo.setRowCount(row.getRowCount());
vo.setCreatedAt(fmt(row.getCreatedAt()));
// 任务开始时间复用 biz_file_task.created_at;缺 task 时回退到 result.createdAt 兜底
@@ -29,4 +29,12 @@ public interface SimilarAsinPipelineHost {
/** 结果文件任务重试耗尽后的失败处理(宿主侧带事务边界)。 */
void finalizeExhaustedResultFileJob(TaskFileJobEntity job, String message);
/**
* 上游 LLM 账户欠费/密钥失效的<b>任务级处置</b>出口:识别归流水线,落终态归宿主
* ({@code fileTaskMapper}/任务缓存清理都在宿主手里,判宽了也不该由 support 决定)。
* 口径与外观专利 2026-10-27 那条一致——任务不落终态,心跳就不回 {@code alive=false},
* Linux 采集端({@code similar_worker})会继续为永远进不了 LLM 的行按次付费买出口 IP。
*/
void terminalizeOnFatalLlmFailure(FileTaskEntity task, String failureMessage);
}
@@ -1308,6 +1308,9 @@ public class SimilarAsinPipelineSupport {
null,
markRowsFailed(batchRows, message),
allRowsByBaseId);
// 行级归因先落库,再把整单交出去:欠费/密钥失效这一类后面每一批都拿不到结论,
// 而采集端只看心跳的 alive——任务不落终态,它就会继续为这些行按次付费买出口 IP。
host.terminalizeOnFatalLlmFailure(task, message);
return false;
}
if (llmRows == null || llmRows.isEmpty()) {
@@ -0,0 +1,86 @@
package com.nanri.aiimage.modules.task.service;
import com.nanri.aiimage.common.retry.LlmBalanceGuard;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
/**
* 任务级失败归因交给用户界面前的那道出口。
*
* <p>{@code biz_file_task.error_message} 存的是给支持同学查根因的原文,带着上游响应体
* ({@code lastErr=LLM http 403: {"error":{"code":"insufficient_user_quota"…}}),把这一串直接摊到
* 界面上既读不懂、也漏出上游账户号——全仓尺子
* {@code RawExceptionMessageSinkGuardTest} 就是为此而存在。欠费/密钥失效恰好有现成的中文句子
* ({@link LlmBalanceGuard#TASK_TERMINAL_GUIDANCE}),所以出口认出<b>本仓自己写下的那条归因</b>就换成它,
* 库里原文一个字都不动。认别人写的"余额不足"不换——那句可能是 jikip 代理欠费,换成 LLM 的话就是说谎。
*
* <p>外观专利与货源两支历史装配器都走这里:优先级逻辑抄两份,改一处就静默失效。
*/
public final class TaskVisibleFailureNotice {
private TaskVisibleFailureNotice() {
}
/** 任务级归因的界面读法;任务没写过错误就返回 null(界面这一行不出现「错误:」)。 */
public static String forTask(FileTaskEntity task) {
return forStoredMessage(task == null ? null : task.getErrorMessage());
}
/**
* 历史行(一个结果文件一行)的界面读法。
*
* <p>欠费/密钥失效是<b>整单</b>的结论,压过行级文案——行级那句往往只是同一次欠费的副产品,
* 让用户先看到"充值或换密钥后重新发起"才是可执行的。其余情形维持既有形状:行级优先,
* 行级为空才用任务级兜底(兜不住时界面就只剩一个「失败」,2026-10-31 现网即卡在这里)。
*/
public static String forHistoryRow(FileTaskEntity task, String rowError) {
String stored = task == null ? null : task.getErrorMessage();
if (isFatalArrears(stored)) {
return forStoredMessage(stored);
}
String row = trimToNull(rowError);
return row != null ? row : forStoredMessage(stored);
}
private static String forStoredMessage(String stored) {
String raw = trimToNull(stored);
if (raw == null) {
return null;
}
return isFatalArrears(raw) ? LlmBalanceGuard.TASK_TERMINAL_GUIDANCE : raw;
}
/**
* 这条库里原文是不是<b>整单</b>的不可抗力结论(上游账户欠费 / LLM 密钥失效)。
*
* <p>收尾路径拿它决定「新文案能不能覆盖旧结论」:欠费判死的单后来被一次带空错误串的收尾
* 盖掉,界面上就又回到「只见失败、不见原因」,采集端也会以为这单还能跑。
*/
public static boolean isWholeTaskVerdict(String storedMessage) {
return isFatalArrears(storedMessage);
}
/**
* 这条库里原文是不是<b>本仓自己写下</b>的 LLM 欠费/密钥失效归因(生产者句 {@code REASON_LLM_BALANCE_DUE}
* 或终态句 {@code TASK_TERMINAL_GUIDANCE} 命中其一)。
*
* <p>刻意<b>不</b>用 {@link TaskRetryEligibility.Category#BALANCE} 当这里的判据:那一类还涵盖
* jikip <b>代理 IP</b>欠费与套餐过期("余额不足"/"套餐不存在"),拿它换句子会把"代理出口没钱了"
* 说成"上游 LLM 账户欠费"——正是 2026-10-27 用户点名要避免的那种误导。判死侧(是否落终态)仍用
* 那一类,因为两条链的调用点只会收到自己那类错误。
*/
private static boolean isFatalArrears(String errorMessage) {
if (errorMessage == null || errorMessage.isBlank()) {
return false;
}
return errorMessage.contains(LlmBalanceGuard.REASON_LLM_BALANCE_DUE)
|| errorMessage.contains(LlmBalanceGuard.TASK_TERMINAL_GUIDANCE);
}
private static String trimToNull(String value) {
if (value == null) {
return null;
}
String trimmed = value.trim();
return trimmed.isEmpty() ? null : trimmed;
}
}