feat(任务派发): 客户端兜底拉取页面未推送成功的任务 + 修店铺匹配定时任务误杀

问题:任务派发链路的"推送"只存在于页面里(Java 解析落库 PENDING → activate →
pywebview 桥 enqueue_json 推本机队列)。只解析没点启动、推送前关页面、在纯浏览器
打开,任务都会停在 PENDING,2 小时后被 StaleTaskRepairService 标失败
(「任务长期未被领取,已自动失败」,09-11 生产清理过 263 条同画像)。

- 服务端新增 GET /api/tasks/pull-pending(TaskClientPullController,身份从 JWT 取,
  不接受 user_id 参数):只挑创建超 5 分钟仍 PENDING 的本用户任务,逐条条件更新认领
  (PENDING→RUNNING + 接管 owner_instance_id)——与页面 activate 同一谓词,天然互斥,
  不会重复执行;认领后组装不出载荷则标 FAILED,不留 RUNNING 孤儿
- payload 由各业务模块实现 ClientTaskPullSpi 组装(task 侧不 import 业务模块,同 G5):
  首批 SIMILAR_ASIN / COLLECT_DATA / APPEARANCE_PATENT——这三个 Python 消费端会自行
  回拉明细,故载荷极简、客户端零模块知识;开关 aiimage.client-task-pull.enabled 默认 false
- 防双执行:三处 activate 由「非终态即可」收紧为只认 PENDING,未命中抛
  「任务已在执行中(可能已由客户端自动接管),无需重复启动」(顺带堵住整行 updateById
  把认领写入的 owner 覆盖回去的竞态);两个前端页 activate 失败即提示并停止入队
- 客户端:amazon/main.py 新增 pending_task_pull_worker,启动点挂在 app_client/main.py
  的 start_task_monitor(独立入口的 worker 线上并不生效);开关 pending_pull_enabled 用
  getattr 读取,避免 test/ 下的旧 config 缺键导致整包导入失败
- 同批修:StaleTaskRepairService 的 SCHEDULED 分支改按 scheduled_at + 120min 判死
  (原按 updated_at 会必杀排期 >2h 的店铺匹配定时任务,而 activate 又被 scheduledAt-90s 挡住)
- 测试:TaskClientPullServiceTest / StaleTaskRepairServiceTest / CollectDataTaskPullSpiImplTest /
  CollectDataActivateGuardTest 共 20 例;客户端 pending_task_pull_worker 7 例并更新启动顺序契约测试
This commit is contained in:
2026-09-14 16:23:34 +08:00
parent 9b79d6b5db
commit 2d5ca99068
18 changed files with 1254 additions and 16 deletions
@@ -0,0 +1,149 @@
package com.nanri.aiimage.modules.task.service;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.baomidou.mybatisplus.core.conditions.Wrapper;
import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
import com.nanri.aiimage.common.service.DistributedJobLockService;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.spi.BrandTaskStaleRepairSpi;
import org.apache.ibatis.builder.MapperBuilderAssistant;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.springframework.test.util.ReflectionTestUtils;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.isNull;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyNoMoreInteractions;
import static org.mockito.Mockito.when;
/**
* 陈旧任务判死契约(2026-09-14 修订):
* PENDING 仍按 updated_at 判死;SCHEDULED(店铺匹配定时任务)改以 scheduled_at 为基准 ——
* 只按 updated_at 会误杀排期在 2 小时之后的定时任务,而 activate 又被「未到定时执行时间」挡住。
*/
class StaleTaskRepairServiceTest {
private final FileTaskMapper fileTaskMapper = mock(FileTaskMapper.class);
private final BrandTaskStaleRepairSpi brandTaskStaleRepairSpi = mock(BrandTaskStaleRepairSpi.class);
private final DistributedJobLockService distributedJobLockService = mock(DistributedJobLockService.class);
private final StaleTaskRepairService service = new StaleTaskRepairService(
fileTaskMapper, brandTaskStaleRepairSpi, distributedJobLockService);
@BeforeEach
void initTableInfo() {
// LambdaWrapper 需要实体列缓存,单测无 Spring/MyBatis 上下文,手动初始化
TableInfoHelper.initTableInfo(new MapperBuilderAssistant(new MybatisConfiguration(), ""), FileTaskEntity.class);
}
@Test
void PENDING_判死只命中_PENDING_不再波及_SCHEDULED() {
when(fileTaskMapper.selectList(any())).thenReturn(List.of(task(11L)));
when(fileTaskMapper.update(isNull(), any())).thenReturn(1);
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStaleIdle");
Map<String, Object> selectParams = selectParams();
assertTrue(selectParams.containsValue("PENDING"));
assertFalse(selectParams.containsValue("SCHEDULED"), "PENDING 分支命中 SCHEDULED 是定时任务被误杀的原因");
Map<String, Object> updateParams = updateParams(1);
assertTrue(updateParams.containsValue("FAILED"));
assertTrue(containsMessage(updateParams, "任务长期未被领取"));
}
@Test
void SCHEDULED_判死以_scheduled_at_为基准并保留_updated_at_兜底() {
when(fileTaskMapper.selectList(any())).thenReturn(List.of(task(21L)));
when(fileTaskMapper.update(isNull(), any())).thenReturn(1);
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStaleScheduled");
ArgumentCaptor<Wrapper<FileTaskEntity>> selectCaptor = wrapperCaptor();
verify(fileTaskMapper).selectList(selectCaptor.capture());
String segment = selectCaptor.getValue().getSqlSegment();
assertTrue(segment.contains("scheduled_at"), "SCHEDULED 判死必须用到 scheduled_at");
assertTrue(segment.contains("updated_at"), "scheduled_at 为空时要退回 updated_at 逻辑");
Map<String, Object> selectParams = paramsOf(selectCaptor.getValue());
assertTrue(selectParams.containsValue("SCHEDULED"), "只处理 SCHEDULED 状态");
long cutoffs = selectParams.values().stream().filter(LocalDateTime.class::isInstance).count();
assertEquals(2L, cutoffs, "updated_at 与 scheduled_at 两个分支各有一个判死时间点");
Map<String, Object> updateParams = updateParams(1);
assertTrue(updateParams.containsValue("FAILED"));
assertTrue(updateParams.containsValue("SCHEDULED"));
assertTrue(containsMessage(updateParams, "定时任务到点后长时间未启动"));
}
@Test
void 没有候选任务时不写库() {
when(fileTaskMapper.selectList(any())).thenReturn(List.of());
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStaleIdle");
ReflectionTestUtils.invokeMethod(service, "repairFileTaskStaleScheduled");
verify(fileTaskMapper, never()).update(any(), any());
verifyNoMoreInteractions(brandTaskStaleRepairSpi);
}
private Map<String, Object> selectParams() {
ArgumentCaptor<Wrapper<FileTaskEntity>> captor = wrapperCaptor();
verify(fileTaskMapper).selectList(captor.capture());
return paramsOf(captor.getValue());
}
private Map<String, Object> updateParams(int times) {
ArgumentCaptor<Wrapper<FileTaskEntity>> captor = wrapperCaptor();
verify(fileTaskMapper, org.mockito.Mockito.times(times)).update(isNull(), captor.capture());
return paramsOf(captor.getValue());
}
@SuppressWarnings("unchecked")
private static ArgumentCaptor<Wrapper<FileTaskEntity>> wrapperCaptor() {
return ArgumentCaptor.forClass(Wrapper.class);
}
/**
* 读取 wrapper 参数容器:用来断言判死谓词与写入值。
* 注意 MyBatis-Plus 是在生成 SQL 片段时才把参数写进 paramNameValuePairs,故先触发一次。
*/
@SuppressWarnings("unchecked")
private static Map<String, Object> paramsOf(Wrapper<FileTaskEntity> wrapper) {
wrapper.getSqlSegment();
if (wrapper instanceof LambdaUpdateWrapper) {
((LambdaUpdateWrapper<FileTaskEntity>) wrapper).getSqlSet();
}
Map<String, Object> params = (Map<String, Object>) ReflectionTestUtils.getField(wrapper, "paramNameValuePairs");
assertNotNull(params, "wrapper 参数容器字段名可能已变化(paramNameValuePairs)");
return params;
}
private static boolean containsMessage(Map<String, Object> params, String keyword) {
return params.values().stream()
.anyMatch(value -> value instanceof String text && text.contains(keyword));
}
private static FileTaskEntity task(Long id) {
FileTaskEntity task = new FileTaskEntity();
task.setId(id);
task.setModuleType("SHOP_MATCH");
task.setStatus("SCHEDULED");
task.setCreatedAt(LocalDateTime.now().minusHours(5));
task.setUpdatedAt(LocalDateTime.now().minusHours(5));
task.setScheduledAt(LocalDateTime.now().plusHours(3));
return task;
}
}
@@ -0,0 +1,260 @@
package com.nanri.aiimage.modules.task.service;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.baomidou.mybatisplus.core.conditions.Wrapper;
import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
import com.nanri.aiimage.config.InstanceMetadata;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.model.vo.TaskClientPullVo;
import com.nanri.aiimage.modules.task.spi.ClientTaskPullSpi;
import org.apache.ibatis.builder.MapperBuilderAssistant;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
import org.springframework.test.util.ReflectionTestUtils;
import java.time.LocalDateTime;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.anyLong;
import static org.mockito.ArgumentMatchers.isNull;
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.verifyNoInteractions;
import static org.mockito.Mockito.when;
/**
* 客户端兜底拉取契约:
* 开关关闭不查库;候选限定「本用户 + PENDING + 白名单模块 + 创建超过 N 分钟」;
* 认领走条件更新(限定 PENDING,写 RUNNING 与 owner)——与页面 activate 互斥,认领失败即返回空;
* 认领后组装不出载荷时把任务标失败(不留 RUNNING 孤儿);白名单未实现 SPI 的模块跳过;同模块重复注册直接报错。
*/
class TaskClientPullServiceTest {
private static final long USER_ID = 1095L;
private final FileTaskMapper fileTaskMapper = mock(FileTaskMapper.class);
@BeforeEach
void initTableInfo() {
// LambdaWrapper 需要实体列缓存,单测无 Spring/MyBatis 上下文,手动初始化
TableInfoHelper.initTableInfo(new MapperBuilderAssistant(new MybatisConfiguration(), ""), FileTaskEntity.class);
}
@Test
void 开关关闭时不查库也不返回任务() {
TaskClientPullService service = service(new StubHandler("SIMILAR_ASIN", payload("similar-asin-run")));
ReflectionTestUtils.setField(service, "enabled", false);
assertTrue(service.pullPendingTasks(USER_ID).isEmpty());
verifyNoInteractions(fileTaskMapper);
}
@Test
void 认领成功后返回载荷并写_RUNNING_与_owner() {
FileTaskEntity candidate = task(11L, "SIMILAR_ASIN");
when(fileTaskMapper.selectList(any())).thenReturn(List.of(candidate));
when(fileTaskMapper.update(isNull(), any())).thenReturn(1);
when(fileTaskMapper.selectById(11L)).thenReturn(candidate);
StubHandler handler = new StubHandler("SIMILAR_ASIN", payload("similar-asin-run"));
List<TaskClientPullVo> result = service(handler).pullPendingTasks(USER_ID);
assertEquals(1, result.size(), "应返回一条已认领任务");
assertEquals(11L, result.get(0).getTaskId());
assertEquals("similar-asin-run", result.get(0).getQueuePayload().get("type"));
assertEquals("SIMILAR_ASIN", result.get(0).getModuleType());
assertEquals(1, handler.claimedCalls, "认领成功后必须执行模块侧后置处理");
ArgumentCaptor<Wrapper<FileTaskEntity>> captor = wrapperCaptor();
verify(fileTaskMapper).update(isNull(), captor.capture());
Map<String, Object> params = paramsOf(captor.getValue());
assertTrue(params.containsValue("PENDING"), "认领条件必须限定 PENDING");
assertTrue(params.containsValue("RUNNING"), "认领必须写入 RUNNING");
assertTrue(sqlSetOf(captor.getValue()).contains("owner_instance_id"), "认领必须接管归属实例");
ArgumentCaptor<Wrapper<FileTaskEntity>> selectCaptor = wrapperCaptor();
verify(fileTaskMapper).selectList(selectCaptor.capture());
Map<String, Object> selectParams = paramsOf(selectCaptor.getValue());
assertTrue(selectParams.containsValue("PENDING"), "候选只挑 PENDING");
assertTrue(selectParams.containsValue(USER_ID), "候选限定任务所属用户");
assertTrue(selectCaptor.getValue().getSqlSegment().contains("created_at"), "候选要有创建时间窗口");
}
@Test
void 页面抢先认领后不再返回任务() {
when(fileTaskMapper.selectList(any())).thenReturn(List.of(task(11L, "SIMILAR_ASIN")));
when(fileTaskMapper.update(isNull(), any())).thenReturn(0);
StubHandler handler = new StubHandler("SIMILAR_ASIN", payload("similar-asin-run"));
List<TaskClientPullVo> result = service(handler).pullPendingTasks(USER_ID);
assertTrue(result.isEmpty(), "条件更新没命中说明页面已接管,不能再返回给客户端");
assertEquals(0, handler.buildCalls, "未认领成功时不应组装载荷");
verify(fileTaskMapper, never()).selectById(anyLong());
}
@Test
void 组装不出载荷时任务标失败() {
FileTaskEntity candidate = task(11L, "SIMILAR_ASIN");
when(fileTaskMapper.selectList(any())).thenReturn(List.of(candidate));
when(fileTaskMapper.update(isNull(), any())).thenReturn(1);
when(fileTaskMapper.selectById(11L)).thenReturn(candidate);
List<TaskClientPullVo> result = service(new StubHandler("SIMILAR_ASIN", null)).pullPendingTasks(USER_ID);
assertTrue(result.isEmpty());
Map<String, Object> failParams = secondUpdateParams();
assertTrue(failParams.containsValue("FAILED"), "组装失败必须标 FAILED,不留 RUNNING 孤儿");
assertTrue(containsMessage(failParams, "无法自动执行"));
}
@Test
void 组装抛异常时任务标失败且不抛出() {
FileTaskEntity candidate = task(11L, "SIMILAR_ASIN");
when(fileTaskMapper.selectList(any())).thenReturn(List.of(candidate));
when(fileTaskMapper.update(isNull(), any())).thenReturn(1);
when(fileTaskMapper.selectById(11L)).thenReturn(candidate);
StubHandler broken = new StubHandler("SIMILAR_ASIN", null, new IllegalStateException("boom"));
List<TaskClientPullVo> result = service(broken).pullPendingTasks(USER_ID);
assertTrue(result.isEmpty());
Map<String, Object> failParams = secondUpdateParams();
assertTrue(failParams.containsValue("FAILED"));
assertTrue(containsMessage(failParams, "无法自动执行"));
}
@Test
void 白名单模块未实现兜底时跳过且不改状态() {
when(fileTaskMapper.selectList(any())).thenReturn(List.of(task(21L, "COLLECT_DATA")));
List<TaskClientPullVo> result = service(new StubHandler("SIMILAR_ASIN", payload("similar-asin-run")))
.pullPendingTasks(USER_ID);
assertTrue(result.isEmpty());
verify(fileTaskMapper, never()).update(isNull(), any());
verify(fileTaskMapper, never()).selectById(anyLong());
}
@Test
void 同一模块重复注册直接报错() {
assertThrows(IllegalStateException.class, () -> service(
new StubHandler("SIMILAR_ASIN", payload("similar-asin-run")),
new StubHandler("SIMILAR_ASIN", payload("similar-asin-run"))));
}
private TaskClientPullService service(ClientTaskPullSpi... handlers) {
TaskClientPullService service = new TaskClientPullService(
fileTaskMapper, new InstanceMetadata("server-test"), List.of(handlers));
ReflectionTestUtils.setField(service, "enabled", true);
ReflectionTestUtils.setField(service, "moduleTypes", "SIMILAR_ASIN,COLLECT_DATA");
ReflectionTestUtils.setField(service, "minPendingMinutes", 5L);
ReflectionTestUtils.setField(service, "limit", 5);
return service;
}
private Map<String, Object> secondUpdateParams() {
ArgumentCaptor<Wrapper<FileTaskEntity>> captor = wrapperCaptor();
verify(fileTaskMapper, times(2)).update(isNull(), captor.capture());
return paramsOf(captor.getAllValues().get(1));
}
@SuppressWarnings("unchecked")
private static ArgumentCaptor<Wrapper<FileTaskEntity>> wrapperCaptor() {
return ArgumentCaptor.forClass(Wrapper.class);
}
/**
* 读取 MyBatis-Plus wrapper 里的参数容器:用来断言条件更新的谓词与写入值。
* 注意 MyBatis-Plus 是在生成 SQL 片段时才把参数写进 paramNameValuePairs,故先触发一次。
*/
@SuppressWarnings("unchecked")
private static Map<String, Object> paramsOf(Wrapper<FileTaskEntity> wrapper) {
wrapper.getSqlSegment();
if (wrapper instanceof LambdaUpdateWrapper) {
((LambdaUpdateWrapper<FileTaskEntity>) wrapper).getSqlSet();
}
Map<String, Object> params = (Map<String, Object>) ReflectionTestUtils.getField(wrapper, "paramNameValuePairs");
assertNotNull(params, "wrapper 参数容器字段名可能已变化(paramNameValuePairs)");
return params;
}
@SuppressWarnings("unchecked")
private static String sqlSetOf(Wrapper<FileTaskEntity> wrapper) {
return ((LambdaUpdateWrapper<FileTaskEntity>) wrapper).getSqlSet();
}
private static boolean containsMessage(Map<String, Object> params, String keyword) {
return params.values().stream()
.anyMatch(value -> value instanceof String text && text.contains(keyword));
}
private static Map<String, Object> payload(String type) {
Map<String, Object> data = new LinkedHashMap<>();
data.put("taskId", 11L);
return Map.of("type", type, "data", data);
}
private static FileTaskEntity task(Long id, String moduleType) {
FileTaskEntity task = new FileTaskEntity();
task.setId(id);
task.setModuleType(moduleType);
task.setTaskNo(moduleType + "-" + id);
task.setUserId(USER_ID);
task.setStatus("PENDING");
task.setCreatedAt(LocalDateTime.now().minusMinutes(10));
task.setUpdatedAt(LocalDateTime.now().minusMinutes(10));
return task;
}
private static final class StubHandler implements ClientTaskPullSpi {
private final String moduleType;
private final Map<String, Object> queuePayload;
private final RuntimeException failure;
private int buildCalls;
private int claimedCalls;
StubHandler(String moduleType, Map<String, Object> queuePayload) {
this(moduleType, queuePayload, null);
}
StubHandler(String moduleType, Map<String, Object> queuePayload, RuntimeException failure) {
this.moduleType = moduleType;
this.queuePayload = queuePayload;
this.failure = failure;
}
@Override
public String moduleType() {
return moduleType;
}
@Override
public Map<String, Object> buildQueuePayload(FileTaskEntity task) {
buildCalls++;
if (failure != null) {
throw failure;
}
return queuePayload;
}
@Override
public void onClaimed(FileTaskEntity task) {
claimedCalls++;
}
}
}