test(phase-0): 1A 中断上报→进度快照终态同步契约钉上——markTerminal 此前零引用

重构蓝图 Phase 0 · 1A 那句「把心跳与进度接进 task contract 套件」逐条对撞后,心跳轴其实早被
别的路钉透了(TaskModuleHeartbeatSpiCoverageTest 12 支 SPI 与 moduleType 一一对上、
TaskHeartbeatServiceTest 进度随心跳转发、StaleTaskHeartbeatPolicyTest 首次心跳前的宽限、
TaskProgressSnapshotServiceThrottleTest 节流与终态豁免、三支 contract 用例 verify touchTaskHeartbeat)
⇒ 那一半本轮不重造,登记为「已闭·复用」。

真缺口在终态那一头:`TaskProgressSnapshotService.markTerminal` 在 src/test 里**一处引用都没有**,
而它对应的是一起真机事故(2026-09-13 客户端重启后店铺数据采集一直显示 28094「处理中」并阻塞该工具
后续任务——progress/batch 读缓存/快照,DB 行已终态而快照还停在 RUNNING)。Phase 2/3 抽公共管线时
这个出口最容易被当「顺手的小方法」漏在新契约之外,故补 10 例钉死:
- markTerminal:快照不存在不许凭空造行;同 status 同 message 幂等不空写;只换 message 也要落;
  非法入参一次库都不碰;写完必须摘限写窗(附对照组:不插终态时第二笔确被 500ms 窗吞掉,
  否则「三笔都落」说不清是摘窗摘对了还是限写窗压根没生效)。
- markInterrupted:DB 仍 RUNNING ⇒ 模块缓存与快照同步 FAILED 并带真因;DB 已终态 ⇒ 按现值自愈
  刷一遍快照(历史遗留旧缓存就是在这儿卡住前端的);快照写抛异常不得让中断接口本身失败;
  非法 taskId 不落到快照。

门禁:`mvn -o test` 全量 4427 passed/0 failures/7 skipped(6:58,BUILD SUCCESS)。
This commit is contained in:
2026-10-18 12:25:20 +08:00
parent 660a1b7084
commit 56c8a4ff88
@@ -0,0 +1,277 @@
package com.nanri.aiimage.modules.task.contract;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.nanri.aiimage.modules.task.mapper.TaskProgressSnapshotMapper;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.dto.TaskHeartbeatRequest;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.model.entity.TaskProgressSnapshotEntity;
import com.nanri.aiimage.modules.task.model.vo.TaskHeartbeatVo;
import com.nanri.aiimage.modules.task.service.TaskHeartbeatLivenessService;
import com.nanri.aiimage.modules.task.service.TaskHeartbeatService;
import com.nanri.aiimage.modules.task.service.TaskProgressSnapshotService;
import com.nanri.aiimage.modules.task.spi.TaskModuleHeartbeatSpi;
import org.apache.ibatis.builder.MapperBuilderAssistant;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.ArgumentCaptor;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.mockito.junit.jupiter.MockitoSettings;
import org.mockito.quality.Strictness;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.ArgumentMatchers.isNull;
import static org.mockito.Mockito.doThrow;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.times;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
/**
* 中断上报 → 进度快照终态同步的跨模块契约(重构蓝图 Phase 0 · 1A)。
*
* 为什么这一格值得单独钉:心跳轴本身早被别的路钉透了——{@code TaskModuleHeartbeatSpiCoverageTest}
* (12 支 SPI 与 moduleType 一一对上)、{@code TaskHeartbeatServiceTest}(进度随心跳转发)、
* {@code StaleTaskHeartbeatPolicyTest}(首次心跳前的宽限)、
* {@code TaskProgressSnapshotServiceThrottleTest}(节流与终态豁免)。
* 但把终态写回快照的那个出口 {@code markTerminal} 在 {@code src/test} 里**一处引用都没有**,
* 而它对应的是一起真机事故:2026-09-13 客户端重启后店铺数据采集一直显示 28094「处理中」并阻塞
* 该工具后续任务——因为 progress/batch 读的是缓存/快照(Redis,跨实例共享、不随 JVM 重启清空),
* DB 行已终态而快照还停在 RUNNING。Phase 2/3 把管线四段抽成公共件时,这个出口最容易被当成
* 「顺手的小方法」漏在新契约之外,故在此钉死。
*
* 覆盖面:{@code markTerminal} 的幂等与「不凭空造行」、终态写完必须清节流记录(否则后续补写
* 被自己刚写的窗口吞掉),以及 {@code markInterrupted} 两条路径(DB 现值 RUNNING/已终态自愈)
* 都必须把终态同步到缓存与快照,且**快照写失败不得让中断接口本身失败**。
*/
@ExtendWith(MockitoExtension.class)
@MockitoSettings(strictness = Strictness.LENIENT)
class TerminalProgressSyncContractTest {
private static final Long TASK_ID = 28094L;
private static final String MODULE_TYPE = "SHOP_DATA_CRAWL";
@BeforeAll
static void initializeMybatisMetadata() {
MapperBuilderAssistant assistant = new MapperBuilderAssistant(new MybatisConfiguration(), "");
TableInfoHelper.initTableInfo(assistant, TaskProgressSnapshotEntity.class);
TableInfoHelper.initTableInfo(assistant, FileTaskEntity.class);
}
@Mock private TaskProgressSnapshotMapper snapshotMapper;
@Mock private FileTaskMapper fileTaskMapper;
private TaskProgressSnapshotService snapshotService() {
return new TaskProgressSnapshotService(snapshotMapper, new ObjectMapper());
}
private static TaskProgressSnapshotEntity snapshot(String status, String message) {
TaskProgressSnapshotEntity existing = new TaskProgressSnapshotEntity();
existing.setId(77L);
existing.setTaskId(TASK_ID);
existing.setModuleType(MODULE_TYPE);
existing.setStatus(status);
existing.setTotalCount(10);
existing.setSuccessCount(4);
existing.setFailedCount(1);
existing.setPendingCount(5);
existing.setCurrentScopeKey("scope-1");
existing.setMessage(message);
return existing;
}
// ---- markTerminal 自身 ----
@Test
void markTerminalDoesNotCreateSnapshotRowWhenAbsent() {
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(null);
snapshotService().markTerminal(TASK_ID, MODULE_TYPE, "FAILED", "客户端异常中断");
verify(snapshotMapper, never()).update(isNull(), any(LambdaUpdateWrapper.class));
verify(snapshotMapper, never()).insert(any(TaskProgressSnapshotEntity.class));
}
@Test
void markTerminalIsIdempotentOnSameStatusAndMessage() {
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class)))
.thenReturn(snapshot("FAILED", "客户端异常中断"));
snapshotService().markTerminal(TASK_ID, MODULE_TYPE, "FAILED", "客户端异常中断");
verify(snapshotMapper, never()).update(isNull(), any(LambdaUpdateWrapper.class));
}
@Test
void markTerminalWritesWhenOnlyMessageChanged() {
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class)))
.thenReturn(snapshot("FAILED", "旧文案"));
snapshotService().markTerminal(TASK_ID, MODULE_TYPE, "FAILED", "客户端异常中断: crash");
verify(snapshotMapper).update(isNull(), any(LambdaUpdateWrapper.class));
}
@Test
void markTerminalIgnoresInvalidArguments() {
for (Object[] args : List.of(
new Object[]{null, MODULE_TYPE, "FAILED", "x"},
new Object[]{0L, MODULE_TYPE, "FAILED", "x"},
new Object[]{TASK_ID, null, "FAILED", "x"},
new Object[]{TASK_ID, "", "FAILED", "x"},
new Object[]{TASK_ID, MODULE_TYPE, null, "x"},
new Object[]{TASK_ID, MODULE_TYPE, " ", "x"})) {
snapshotService().markTerminal((Long) args[0], (String) args[1], (String) args[2], (String) args[3]);
}
verify(snapshotMapper, never()).update(isNull(), any(LambdaUpdateWrapper.class));
verify(snapshotMapper, never()).selectOne(any(LambdaQueryWrapper.class));
}
/**
* 终态写完必须把节流记录一起清掉。限写窗(默认 500ms)按 {@code taskId:moduleType} 记:
* 若终态不摘这条记录,紧随其后那笔非终态补写(纠正文案、或同一 key 复用的下一轮进度)
* 会被自己刚写的窗口吞掉,前端就又回到「永远处理中」。
* 本用例把三步摆在一起:进度写(顺带武装限写窗)⇒ 终态写(必须摘窗)⇒ 补写(必须还落得下去)。
*/
@Test
void markTerminalClearsThrottleWindowForFollowingWrites() {
TaskProgressSnapshotService service = snapshotService();
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class)))
.thenReturn(snapshot("RUNNING", "processing"));
service.save(TASK_ID, MODULE_TYPE, "RUNNING", 10, 4, 1, "scope-1", "第一步", null);
service.markTerminal(TASK_ID, MODULE_TYPE, "FAILED", "客户端异常中断");
service.save(TASK_ID, MODULE_TYPE, "RUNNING", 10, 5, 0, "scope-1", "第二步", null);
verify(snapshotMapper, times(3)).update(isNull(), any(LambdaUpdateWrapper.class));
}
/**
* 上一条的对照组:同样两笔进度写之间**不**插终态写,第二笔就被限写窗吞掉。
* 没有这条对照,上一条的「三笔都落」说不清是摘窗摘对了,还是限写窗压根没生效。
*/
@Test
void followUpWriteIsThrottledWhenNoTerminalSyncHappens() {
TaskProgressSnapshotService service = snapshotService();
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class)))
.thenReturn(snapshot("RUNNING", "processing"));
service.save(TASK_ID, MODULE_TYPE, "RUNNING", 10, 4, 1, "scope-1", "第一步", null);
service.save(TASK_ID, MODULE_TYPE, "RUNNING", 10, 5, 0, "scope-1", "第二步", null);
verify(snapshotMapper, times(1)).update(isNull(), any(LambdaUpdateWrapper.class));
}
// ---- markInterrupted 与快照的接线 ----
private static final class RecordingSpi implements TaskModuleHeartbeatSpi {
private final List<FileTaskEntity> cacheWrites = new java.util.ArrayList<>();
@Override
public String moduleType() {
return MODULE_TYPE;
}
@Override
public void touchHeartbeat(Long taskId, TaskHeartbeatRequest request) {
// 本支只验终态同步,心跳刷新另有归属用例
}
@Override
public void saveTaskCache(FileTaskEntity task) {
cacheWrites.add(task);
}
}
private TaskHeartbeatService heartbeatService(TaskProgressSnapshotService snapshotService, RecordingSpi spi) {
return new TaskHeartbeatService(fileTaskMapper, snapshotService,
mock(com.nanri.aiimage.modules.task.spi.BrandTaskHeartbeatSpi.class),
mock(TaskHeartbeatLivenessService.class), List.of(spi));
}
private static FileTaskEntity runningTask() {
FileTaskEntity task = new FileTaskEntity();
task.setId(TASK_ID);
task.setModuleType(MODULE_TYPE);
task.setStatus("RUNNING");
task.setUserId(7L);
return task;
}
@Test
void markInterruptedSyncsCacheAndSnapshotWhenTaskStillRunning() {
when(fileTaskMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(runningTask());
when(fileTaskMapper.update(isNull(), any(LambdaUpdateWrapper.class))).thenReturn(1);
TaskProgressSnapshotService snapshotService = mock(TaskProgressSnapshotService.class);
RecordingSpi spi = new RecordingSpi();
TaskHeartbeatVo vo = heartbeatService(snapshotService, spi).markInterrupted(TASK_ID, "客户端崩溃重启");
assertFalse(vo.isAlive());
assertEquals("FAILED", vo.getStatus());
ArgumentCaptor<String> message = ArgumentCaptor.forClass(String.class);
verify(snapshotService).markTerminal(eq(TASK_ID), eq(MODULE_TYPE), eq("FAILED"), message.capture());
assertEquals("客户端异常中断: 客户端崩溃重启", message.getValue());
assertEquals(1, spi.cacheWrites.size(), "模块缓存也得同步终态,否则读缓存的那侧仍是 RUNNING");
assertEquals("FAILED", spi.cacheWrites.get(0).getStatus());
}
/** DB 已是终态(重复上报)时仍要按 DB 现值自愈刷一遍快照——历史遗留的旧缓存就是在这儿卡住前端的。 */
@Test
void markInterruptedHealsStaleSnapshotWhenTaskAlreadyTerminal() {
FileTaskEntity terminal = runningTask();
terminal.setStatus("CANCELLED");
terminal.setErrorMessage("用户取消");
when(fileTaskMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(terminal);
when(fileTaskMapper.update(isNull(), any(LambdaUpdateWrapper.class))).thenReturn(0);
TaskProgressSnapshotService snapshotService = mock(TaskProgressSnapshotService.class);
TaskHeartbeatVo vo = heartbeatService(snapshotService, new RecordingSpi())
.markInterrupted(TASK_ID, "重复上报");
assertFalse(vo.isAlive());
assertEquals("CANCELLED", vo.getStatus());
verify(snapshotService, times(1)).markTerminal(TASK_ID, MODULE_TYPE, "CANCELLED", "用户取消");
}
/** 快照/缓存写失败只该告警:中断接口本身的成功语义不能被它拖下水。 */
@Test
void markInterruptedStillSucceedsWhenSnapshotWriteFails() {
when(fileTaskMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(runningTask());
when(fileTaskMapper.update(isNull(), any(LambdaUpdateWrapper.class))).thenReturn(1);
TaskProgressSnapshotService snapshotService = mock(TaskProgressSnapshotService.class);
doThrow(new IllegalStateException("redis down"))
.when(snapshotService).markTerminal(any(), any(), any(), any());
TaskHeartbeatVo vo = heartbeatService(snapshotService, new RecordingSpi())
.markInterrupted(TASK_ID, "客户端崩溃重启");
assertFalse(vo.isAlive());
assertEquals("FAILED", vo.getStatus(), "快照写失败不得让中断上报变成失败");
}
@Test
void markInterruptedIgnoresInvalidTaskId() {
TaskProgressSnapshotService snapshotService = mock(TaskProgressSnapshotService.class);
// List.of 不收 null,非法值只能走 Arrays.asList
for (Long taskId : java.util.Arrays.asList(null, 0L, -1L)) {
TaskHeartbeatVo vo = heartbeatService(snapshotService, new RecordingSpi()).markInterrupted(taskId, "x");
assertFalse(vo.isAlive(), "非法 taskId 也必须回「不活着」,不能让客户端以为任务还在跑");
}
verify(snapshotService, never()).markTerminal(any(), any(), any(), any());
verify(fileTaskMapper, never()).selectOne(any(LambdaQueryWrapper.class));
}
}