feat(PENDING 判死): 所有模块的等待中单超 24 小时判死,原地可重试(2026-11-06 产品拍板)

起因:现网 33462(uid=1245,数据采集 文档格式.xlsx,17 行)提交后 20 小时停在「等待中」,
updated_at 与 created_at 逐字相同、零分片回传;同批 33103 已挂 6 天。ONLINE 通道没有服务端认领方
(客户端拉取 SQL 硬性要求通道为 LOCAL、内部认领端点默认关闭且从不以 COLLECT_DATA 请求),
把这一单翻成 RUNNING 的唯一动作是界面发 activate——用户没点,"等待中"就成了事实终态:
界面不报错、后台不判死、无人通知。

- StaleTaskRepairService 新增 repairFileTaskStalePending():PENDING 且 updated_at 超 24h → FAILED,
  判死文案唯一出处 PENDING_UNCLAIMED_REASON 供 markers 引用(两处各写一遍就会改一处静默失效)
- TaskRetryEligibility 新增 Category.UNCLAIMED + UNCLAIMED_MARKERS ⇒ 这一档不进自动重试:
  否则会被复位成 PENDING、再等满 24 小时,白烧一轮排队与通知,还把"没人点启动"洗成"上游坏了"
- 三处刻意形状:基准用 updated_at 不用 created_at(重试复位过的单按最后一次状态变更起算);
  UPDATE 里复验 status+updated_at(查询与写入之间用户可能刚点启动,只按 id+status 会把刚被
  领走的单判死);不调 markDeadDownstream(这一档的定义就是没被领走,无结果行无出表作业)

口径冲突如实处理:2026-10-29 那条「PENDING 一律不判死」被本笔覆盖,但它防的是阈值太短
(按 2 小时清杀排队任务并连锁自动克隆重试,现网 2026-10-28 用户 1211 两条 829 行任务),
不是"PENDING 永远不该有终态";克隆放大那条早已被铁律 26 换成本地原地重试。剩下的已知代价
(排队真久的单也会被扫到)写进类注释,靠界面「重试」接回。

判据:StaleTaskRepairServiceTest 改写 1 格+新增 2 格(8 例),MarkersSnapshot 新增
「Category 全集必须逐个登记 markers 组」(加一档不登记即红——本笔实测三支既有测试 21 例
全绿,正是那个缺口的现场)。反向验过三处:摘 CAS updated_at 复验/摘 failure_category 写点/
摘判定分支,各出真红后还原全绿(前两次因 CRLF 未落地的"假反向"已被逐行定位断言挡下)。
This commit is contained in:
2026-11-06 13:27:42 +08:00
parent 48b961f0b2
commit 61ec324b2f
4 changed files with 185 additions and 22 deletions
@@ -25,11 +25,17 @@ import com.nanri.aiimage.modules.task.service.support.TaskFailureLedger;
* SCHEDULED / RUNNING 任务自动标终态失败,避免历史任务列表永久停留在中间状态。
* 分布式锁防双实例重复修复;注意 RUNNING 的存活判定基于 updatedAt 心跳,真活任务会不断刷新不会被误杀。
*
* <p><b>PENDING 不在本巡检的判死范围内(2026-10-29 产品口径)</b>:PENDING 是"排队等 worker 领取",
* 不是"卡死"。AP worker 串行跑大任务时,队列里的任务等再久也必须保留——按 2 小时判死把排队任务
* 误杀成「任务长期未被领取」,还会触发自动克隆重试,同一份活被放大成多条失败记录(现网 2026-10-28
* 用户 1211 的两条 829 行任务即此路)。排队任务一律等 {@code TaskClientPullService} 认领;
* 页面放弃的解析预览也一样保留,不在这里清。
* <p><b>PENDING 自 2026-11-06 起按 24 小时判死({@link #repairFileTaskStalePending()}),本段是那条口径的出处与代价。</b>
* 旧口径(2026-10-29)是「PENDING 一律不判死」:PENDING 是"排队等 worker 领取",不是"卡死"。AP worker
* 串行跑大任务时,队列里的任务等再久也必须保留——按 2 小时判死把排队任务误杀成「任务长期未被领取」,
* 还会触发自动克隆重试,同一份活被放大成多条失败记录(现网 2026-10-28 用户 1211 的两条 829 行任务即此路)。
* 那条口径防的是<b>阈值太短</b>,不是"PENDING 永远不该有终态":现网 33462 提交后 20 小时、33103 提交后 6 天
* 停在「等待中」,界面不报错、后台不判死、无人通知——ONLINE 通道根本没有服务端认领方,于是"等待中"
* 被当成了终态。两点接回旧口径担心的误杀:自动克隆重试那条早已被铁律 26 换成本地原地重试
* ({@code TaskInPlaceRetryService},同一份输入不再多出行),且 UNCLAIMED 档不进自动重试
* ({@link TaskRetryEligibility}),判死不会把排队任务放大成失败记录。
* 剩下的已知代价:排队真久的单也会被 24 小时这条扫到,靠界面上的「重试」接回来。
* 页面放弃的解析预览仍然保留,不在这里清。
*/
@Slf4j
@Service
@@ -39,11 +45,25 @@ public class StaleTaskRepairService {
private static final String STATUS_SCHEDULED = "SCHEDULED";
private static final String STATUS_RUNNING = "RUNNING";
private static final String STATUS_FAILED = "FAILED";
private static final String STATUS_PENDING = "PENDING";
/** SCHEDULED(到点未启动)/ RUNNING(心跳残留)超过该时长未更新即判死。真活任务心跳会不断刷新 updatedAt,不会被误杀。 */
private static final long STALE_IDLE_MINUTES = 120;
/**
* 「等待中」超过该时长仍无任何领取动作即判死。2026-11-06 产品拍板,覆盖 2026-10-29 那条
* 「PENDING 一律不判死」的口径(代价与接回方式写在 {@link #repairFileTaskStalePending()} 上)。
*/
static final long PENDING_UNCLAIMED_HOURS = 24;
/**
* 判死文案的唯一出处:{@link TaskRetryEligibility} 的 UNCLAIMED markers 也从这里取。
* 两处各写一遍就会改一处静默失效(同 {@code STOPPED_MARKERS} 引用 {@code DUPLICATE_STOP_REASON} 的理由)。
*/
public static final String PENDING_UNCLAIMED_REASON =
"任务提交后 " + PENDING_UNCLAIMED_HOURS + " 小时内没有采集端领取,已自动结束;在原任务上点「重试」可重新排队";
/** 单轮品牌陈旧任务处理上限(原实现内联 limit 500)。 */
private static final int MAX_BRAND_STALE_BATCH = 500;
@@ -69,6 +89,7 @@ public class StaleTaskRepairService {
try (lock) {
repairFileTaskStaleScheduled();
repairFileTaskStaleRunning();
repairFileTaskStalePending();
repairBrandStale();
} catch (Exception ex) {
log.warn("[stale-task-repair] 修护失败 msg={}", ex.getMessage(), ex);
@@ -145,6 +166,51 @@ public class StaleTaskRepairService {
}
}
/**
* 「等待中」超过 {@link #PENDING_UNCLAIMED_HOURS} 小时没有任何领取动作 → FAILED(原地可重试,不新建任务)。
*
* <p>为什么必须有这一条:ONLINE 通道的 PENDING 没有任何服务端认领方(客户端拉取 SQL 硬性要求通道为
* LOCAL,内部认领端点默认关闭且从不以 COLLECT_DATA 请求),把这一单翻成 RUNNING 的唯一动作是界面发
* activate。用户点完「提交」没点「启动」、或那一台客户端当天没上线,这一单就停在「等待中」成为事实终态
* ——现网 33462 挂 20 小时、33103 挂 6 天,`updated_at` 与 `created_at` 逐字相同、零分片回传、无人通知。
*
* <p>三处刻意的形状,改动前先读:
* ① <b>基准用 updated_at 不用 created_at</b>:被「重试」复位过的单要从最后一次状态变更起算,
* 否则一份反复重试的活会在第二次就撞上限;
* ② <b>UPDATE 里复验 updated_at</b>:查询与写入之间用户可能刚好点了启动(activate 是
* PENDING→RUNNING 的条件更新),只按 id+status 回写会把刚被领走的单判死;
* ③ <b>不调用 {@code markDeadDownstream}</b>:这一档的定义就是"从没被任何 worker 领走",
* 既无结果行也无出表作业,多两条按 taskId 的 UPDATE 只会把"下游已改口"的日志说成事实。
*
* <p>判死后的单进 {@code UNCLAIMED} 档因而<b>不</b>被 {@code TaskResumeService} 自动重试:
* 自动重试只会把它复位成 PENDING、再等满 24 小时,白烧一轮排队与通知,还把"没人点启动"洗成"上游坏了"。
*/
private void repairFileTaskStalePending() {
LocalDateTime cutoff = LocalDateTime.now().minusHours(PENDING_UNCLAIMED_HOURS);
List<FileTaskEntity> stale = fileTaskMapper.selectList(new LambdaQueryWrapper<FileTaskEntity>()
.select(FileTaskEntity::getId, FileTaskEntity::getModuleType)
.eq(FileTaskEntity::getStatus, STATUS_PENDING)
.lt(FileTaskEntity::getUpdatedAt, cutoff)
.last("limit 500"));
if (stale.isEmpty()) {
return;
}
List<Long> ids = stale.stream().map(FileTaskEntity::getId).toList();
int updated = fileTaskMapper.update(null, new LambdaUpdateWrapper<FileTaskEntity>()
.in(FileTaskEntity::getId, ids)
.eq(FileTaskEntity::getStatus, STATUS_PENDING)
.lt(FileTaskEntity::getUpdatedAt, cutoff)
.set(FileTaskEntity::getStatus, STATUS_FAILED)
.set(FileTaskEntity::getErrorMessage, PENDING_UNCLAIMED_REASON)
.set(FileTaskEntity::getFailureCategory, TaskFailureLedger.categoryOf(PENDING_UNCLAIMED_REASON))
.set(FileTaskEntity::getFinishedAt, LocalDateTime.now()));
if (updated > 0) {
log.warn("[stale-task-repair] 无人领取 PENDING 已标失败 count={} hours={} modules={} ids={}",
updated, PENDING_UNCLAIMED_HOURS,
stale.stream().map(FileTaskEntity::getModuleType).distinct().toList(), ids);
}
}
/**
* 把「服务端还一行心跳都没收到、且仍在未启动宽限内」的 RUNNING 任务从候选里摘掉。
*
@@ -32,7 +32,12 @@ public final class TaskRetryEligibility {
*/
DELIVERY("交付侧失败(重跑不改变结果)"),
/** 系统主动停掉的重复子任务:它不是"失败了要重跑",而是"这一份不该再跑",再克隆等于把双跑捡回来。 */
STOPPED("重复子任务已停止");
STOPPED("重复子任务已停止"),
/**
* 提交后长时间无人领取(2026-11-06 那条 24 小时 PENDING 判死的落点):重跑整单不会让用户的
* 客户端上线,也不会替他点「启动任务」。这一档等的是外部动作,不是外部条件坏了。
*/
UNCLAIMED("提交后无人领取");
private final String label;
@@ -82,6 +87,13 @@ public final class TaskRetryEligibility {
*/
private static final List<String> STOPPED_MARKERS = List.of(TaskResumeService.DUPLICATE_STOP_REASON);
/**
* 无人领取:文案的唯一出处在 {@link StaleTaskRepairService#PENDING_UNCLAIMED_REASON},这里不抄第二遍——
* 抄了就会改一处静默失效:判死文案或阈值一改,这一档认不出来,那单就会被 {@code TaskResumeService}
* 当成"可重试"反复复位成 PENDING、再等满 24 小时。
*/
private static final List<String> UNCLAIMED_MARKERS = List.of(StaleTaskRepairService.PENDING_UNCLAIMED_REASON);
private TaskRetryEligibility() {
}
@@ -98,6 +110,11 @@ public final class TaskRetryEligibility {
if (containsAny(text, STOPPED_MARKERS)) {
return Category.STOPPED;
}
// 无人领取排在停止之后、交付之前:同属"系统自己收的口",让后面的欠费/宕机档去抢这一条,
// 只会把"没人点启动"说成"服务不可用",运维据此调整反了方向。
if (containsAny(text, UNCLAIMED_MARKERS)) {
return Category.UNCLAIMED;
}
// 交付侧失败排在欠费之前:这类文案本身就是"采集已完成、组装失败",即便同一条
// 错误里还夹着欠费字样,重跑整单也修不好组装器,日志该按真实成因报。
if (containsAny(text, DELIVERY_MARKERS)) {
@@ -17,7 +17,6 @@ import org.mockito.ArgumentCaptor;
import org.springframework.test.util.ReflectionTestUtils;
import java.time.LocalDateTime;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
@@ -60,25 +59,76 @@ class StaleTaskRepairServiceTest {
TableInfoHelper.initTableInfo(new MapperBuilderAssistant(new MybatisConfiguration(), ""), FileResultEntity.class);
}
/**
* PENDING 判死(2026-11-06 产品拍板:所有模块的 PENDING 超 24 小时判死、原地可重试)。
*
* <p><b>本格原先钉的是 2026-10-29 那条「PENDING 一律不判死」,现按新口径改写而不是删掉</b>:旧口径防的是
* <b>阈值太短</b>——按 2 小时清杀会把排队任务误判成"长期未被领取",还连锁触发自动克隆重试(现网 2026-10-28
* 用户 1211 两条 829 行任务)。它从来不是"PENDING 永远不该有终态"。另一端也被现网证伪了:33462 提交后挂
* 20 小时、33103 挂 6 天停在「等待中」,界面不报错、后台不判死、无人通知——ONLINE 通道没有服务端认领方,
* "等待中"就此被当成终态。两条已知代价钉在下面四格里,别把它们当可放宽的实现细节:
* ① 基准必须 updated_at(重试复位过的单要从最后一次状态变更起算);
* ② 回写必须复验 status+updated_at(查询与写入之间用户可能刚好点了启动,activate 是 PENDING→RUNNING
* 的条件更新,少这一条就把刚被领走的单判死);
* ③ 写 error_message 必须紧邻配对 failure_category(B82-01 那条:列不写,这一族失败在按 source 出账的
* 报表里就是隐身);
* ④ 判死档必须落 UNCLAIMED 从而<b>不</b>进自动重试——自动重试只会把它复位成 PENDING、再等满 24 小时。
*/
@Test
void PENDING_排队超时不判死_判死入口不得回填() {
// 2026-10-29 产品口径:PENDING 是排队态,AP worker 串行跑大任务时队列再长也保留,
// 由 pull 认领;按更新时间清杀会把排队任务误判成「长期未被领取」,还会连锁触发自动重试。
assertNull(Arrays.stream(StaleTaskRepairService.class.getDeclaredMethods())
.filter(method -> "repairFileTaskStaleIdle".equals(method.getName()))
.findFirst().orElse(null),
"PENDING 判死入口不得回填:排队中的任务要一直留着等 worker 领取");
void PENDING_超24小时无人领取必须判死_基准与回写都按updated_at() {
when(fileTaskMapper.selectList(any())).thenReturn(List.of(task(33462L, "PENDING")));
when(fileTaskMapper.update(isNull(), any())).thenReturn(1);
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStalePending");
ArgumentCaptor<Wrapper<FileTaskEntity>> selectCaptor = wrapperCaptor();
verify(fileTaskMapper).selectList(selectCaptor.capture());
String select = selectCaptor.getValue().getSqlSegment();
assertTrue(select.contains("updated_at"), "判死基准必须用 updated_at,不是 created_at");
assertFalse(select.contains("created_at"),
"退回 created_at 会把反复重试的活第二次就判死——重试复位刷的是 updated_at");
assertTrue(paramsOf(selectCaptor.getValue()).containsValue("PENDING"),
"判死巡检必须扫得到 PENDING 这一档(2026-10-29 那格的口径已被 2026-11-06 覆盖)");
ArgumentCaptor<Wrapper<FileTaskEntity>> updateCaptor = wrapperCaptor();
verify(fileTaskMapper).update(isNull(), updateCaptor.capture());
String updateWhere = updateCaptor.getValue().getSqlSegment();
assertTrue(updateWhere.contains("status"), "回写必须带 status 条件:只认仍是 PENDING 的行");
assertTrue(updateWhere.contains("updated_at"),
"回写必须复验 updated_at:查询与写入之间被 activate 领走的单不许被判死");
Map<String, Object> params = paramsOf(updateCaptor.getValue());
assertTrue(params.containsValue("PENDING"), "CAS 的旧值必须是 PENDING");
assertTrue(params.containsValue("FAILED"), "终态写 FAILED");
}
@Test
void PENDING_判死必须登记failure_category_且不碰结果行与作业() {
when(fileTaskMapper.selectList(any())).thenReturn(List.of(task(33103L, "PENDING")));
when(fileTaskMapper.update(isNull(), any())).thenReturn(1);
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStalePending");
Map<String, Object> params = updateParams(1);
assertTrue(containsMessage(params, "没有采集端领取"), "文案要说出真实成因:没人领取,不是上游坏了");
assertTrue(params.containsValue("UNCLAIMED"),
"failure_category 必须落 UNCLAIMED:列不写这一族就在按 source 出账的报表里隐身");
// 判死档要挡住自动重试:UNCLAIMED 属不可抗力类,自动续跑不该把它复位成 PENDING 再等满 24 小时
String reason = StaleTaskRepairService.PENDING_UNCLAIMED_REASON;
assertEquals(TaskRetryEligibility.Category.UNCLAIMED, TaskRetryEligibility.forceMajeureCategory(reason),
"判死文案与 markers 一旦分叉(改了阈值或措辞),这一单会被自动重试反复复位");
// 这一档的定义就是"从没被任何 worker 领走":没有结果行、也没有出表作业。
// 调 markDeadDownstream 只会多两条按 taskId 的 UPDATE,并把「下游已改口」的日志说成事实。
verify(fileResultMapper, never()).update(any(), any());
verify(taskFileJobService, never()).failUnfinishedJobs(any(), any());
}
@Test
void 没有候选_PENDING_时不写库() {
when(fileTaskMapper.selectList(any())).thenReturn(List.of());
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStaleScheduled");
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStaleRunning");
ArgumentCaptor<Wrapper<FileTaskEntity>> captor = wrapperCaptor();
verify(fileTaskMapper, org.mockito.Mockito.times(2)).selectList(captor.capture());
for (Wrapper<FileTaskEntity> wrapper : captor.getAllValues()) {
assertFalse(paramsOf(wrapper).containsValue("PENDING"),
"判死巡检不得再扫 PENDING:排队任务既不许按 updated_at 清杀,也不许被别的分支误伤");
}
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStalePending");
verify(fileTaskMapper, never()).update(any(), any());
}
@@ -66,6 +66,31 @@ class TaskRetryEligibilityMarkersSnapshotTest {
// 停止文案不在这里抄字面量——引用 TaskResumeService 的同一份常量(抄一份改一处就静默失效)。
assertThat(markers("STOPPED_MARKERS"))
.containsExactly(TaskResumeService.DUPLICATE_STOP_REASON);
// 无人领取同理:唯一出处是 StaleTaskRepairService 的判死文案,抄第二份就会改一处静默失效
// ——阈值一改(那句里的"24 小时"跟着变),这一档认不出来,单会被自动重试反复复位。
assertThat(markers("UNCLAIMED_MARKERS"))
.containsExactly(StaleTaskRepairService.PENDING_UNCLAIMED_REASON);
}
/**
* Category 与 markers 组必须逐个对上:加一档而不在这里登记,本格即红。
*
* <p>上一格只做"已登记的 markers 是否被认出来",所以新增一档可以完全绕过它(2026-11-06 加
* UNCLAIMED 时三支既有测试 21 例全绿,正是这个缺口的现场)。判生死的东西不该靠"有人记得加一行"。
*/
@Test
void Category全集必须逐个有markers组_加一档不登记即红() {
java.util.Map<TaskRetryEligibility.Category, List<String>> registered = new java.util.LinkedHashMap<>();
registered.put(TaskRetryEligibility.Category.BALANCE, List.of("BALANCE_MARKERS", "KEY_MARKERS"));
registered.put(TaskRetryEligibility.Category.SERVICE_DOWN, List.of("SERVICE_MARKERS"));
registered.put(TaskRetryEligibility.Category.CREDENTIAL, List.of("CREDENTIAL_MARKERS"));
registered.put(TaskRetryEligibility.Category.DELIVERY, List.of("DELIVERY_MARKERS"));
registered.put(TaskRetryEligibility.Category.STOPPED, List.of("STOPPED_MARKERS"));
registered.put(TaskRetryEligibility.Category.UNCLAIMED, List.of("UNCLAIMED_MARKERS"));
assertThat(java.util.Arrays.stream(TaskRetryEligibility.Category.values())
.filter(category -> !registered.containsKey(category)).toList())
.as("有新档位没有登记 markers 组:它判得出类别却认不出文案,自动重试会照跑")
.isEmpty();
}
@Test
@@ -95,6 +120,11 @@ class TaskRetryEligibilityMarkersSnapshotTest {
.as("停止 marker %r 应判 STOPPED(再克隆等于把双跑捡回来)", marker)
.isEqualTo(TaskRetryEligibility.Category.STOPPED);
}
for (String marker : markers("UNCLAIMED_MARKERS")) {
assertThat(TaskRetryEligibility.forceMajeureCategory(marker))
.as("无人领取 marker %r 应判 UNCLAIMED(这一档不进自动重试)", marker)
.isEqualTo(TaskRetryEligibility.Category.UNCLAIMED);
}
}
@Test