From 56c8a4ff8896cc484aa3915f02d457d7087baca9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Sun, 18 Oct 2026 12:25:20 +0800 Subject: [PATCH] =?UTF-8?q?test(phase-0):=201A=20=E4=B8=AD=E6=96=AD?= =?UTF-8?q?=E4=B8=8A=E6=8A=A5=E2=86=92=E8=BF=9B=E5=BA=A6=E5=BF=AB=E7=85=A7?= =?UTF-8?q?=E7=BB=88=E6=80=81=E5=90=8C=E6=AD=A5=E5=A5=91=E7=BA=A6=E9=92=89?= =?UTF-8?q?=E4=B8=8A=E2=80=94=E2=80=94markTerminal=20=E6=AD=A4=E5=89=8D?= =?UTF-8?q?=E9=9B=B6=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 重构蓝图 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)。 --- .../TerminalProgressSyncContractTest.java | 277 ++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 backend-java/src/test/java/com/nanri/aiimage/modules/task/contract/TerminalProgressSyncContractTest.java diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/task/contract/TerminalProgressSyncContractTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/task/contract/TerminalProgressSyncContractTest.java new file mode 100644 index 000000000..9984e3fa9 --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/modules/task/contract/TerminalProgressSyncContractTest.java @@ -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 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 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)); + } +}