diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/service/DeleteBrandStaleTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/service/DeleteBrandStaleTaskService.java
index fd0b880cd..5653eada6 100644
--- a/backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/service/DeleteBrandStaleTaskService.java
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/deletebrand/service/DeleteBrandStaleTaskService.java
@@ -133,7 +133,7 @@ public class DeleteBrandStaleTaskService {
// 周期每 2 分钟一轮,各模块 summary 合并为单行,避免定期刷屏
// 注意:每段占位符数量必须与实参一致——此前每段 5 个占位符只传 4 个参数,
// 导致 withdraw 之后的取值整体错位、末尾 elapsedMs/thread 打成字面量
- log.info("[stale-check] summary product-risk(s={} f={} x={} p={}) price-track(s={} f={} x={} p={}) price-track-loop(s={} f={} p={} r={} x={}) shop-match(s={} f={} x={} p={}) patrol-delete(s={} f={} x={} p={}) query-asin(s={} f={} x={} p={}) withdraw(s={} f={} x={} p={}) no-upload(c={} f={} x={}) resume(s={} r={} k={} u={}) elapsedMs={} thread={}",
+ log.info("[stale-check] summary product-risk(s={} f={} x={} p={}) price-track(s={} f={} x={} p={}) price-track-loop(s={} f={} p={} r={} x={}) shop-match(s={} f={} x={} p={}) patrol-delete(s={} f={} x={} p={}) query-asin(s={} f={} x={} p={}) withdraw(s={} f={} x={} p={}) no-upload(c={} f={} x={}) resume(ran={} s={} r={} k={} u={}) elapsedMs={} thread={}",
stats.scannedTaskCount, stats.finalizedTaskCount, stats.failedTaskCount, stats.skippedTaskCount,
priceTrackStats.scannedTaskCount, priceTrackStats.finalizedTaskCount, priceTrackStats.failedTaskCount, priceTrackStats.skippedTaskCount,
priceTrackLoopStats.scannedLoopRunCount, priceTrackLoopStats.failedLoopRunCount, priceTrackLoopStats.stoppedLoopRunCount, priceTrackLoopStats.finalizedLoopRunCount, priceTrackLoopStats.skippedLoopRunCount,
@@ -142,8 +142,10 @@ public class DeleteBrandStaleTaskService {
queryAsinStats.scannedTaskCount, queryAsinStats.finalizedTaskCount, queryAsinStats.failedTaskCount, queryAsinStats.skippedTaskCount,
withdrawStats.scannedTaskCount, withdrawStats.finalizedTaskCount, withdrawStats.failedTaskCount, withdrawStats.skippedTaskCount,
noUploadStats.scannedTaskCount, noUploadStats.failedTaskCount, noUploadStats.skippedTaskCount,
- resumeStats.scannedTaskCount, resumeStats.resumedTaskCount, resumeStats.skippedTaskCount,
- resumeStats.unsupportedTaskCount,
+ // ran 放在最前面:续跑默认是关的,没有它时"没跑"与"跑了没候选"都是 s=0 r=0 k=0 u=0,
+ // V129 上线以来一直全零就是这么被当成"恰好没有中断任务"的
+ resumeStats.ran, resumeStats.scannedTaskCount, resumeStats.resumedTaskCount,
+ resumeStats.skippedTaskCount, resumeStats.unsupportedTaskCount,
System.currentTimeMillis() - startedAt,
Thread.currentThread().getName());
}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskClientPullService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskClientPullService.java
index a388af299..b1f1d3d8a 100644
--- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskClientPullService.java
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskClientPullService.java
@@ -7,6 +7,7 @@ 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 jakarta.annotation.PostConstruct;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
@@ -80,6 +81,19 @@ public class TaskClientPullService {
log.info("[client-task-pull] 模块兜底实现注册完成 count={} modules={}", index.size(), index.keySet());
}
+ /**
+ * 启动时打印生效配置。
+ *
+ *
关闭时 {@link #pullPendingTasks(Long)} 直接返回空列表,HTTP 侧仍是 200 且响应体与
+ * "开启但没有候选"完全同形(线上实测 1 小时 4443 次 pull-pending 全空返回),
+ * 没有这一行就没法从日志判断兜底拉取到底有没有在用。
+ */
+ @PostConstruct
+ public void logEffectiveConfig() {
+ log.info("[client-task-pull] 生效配置 enabled={} moduleTypes={} minPendingMinutes={} limit={} handlers={}",
+ enabled, moduleTypes, minPendingMinutes, Math.max(1, Math.min(limit, MAX_LIMIT)), pullHandlers.keySet());
+ }
+
/** 拉取并认领该用户"长期未被领取"的任务,按创建时间升序返回,最多 limit 条。 */
public List pullPendingTasks(Long userId) {
if (!enabled) {
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskResumeService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskResumeService.java
index ba4144a8d..193cf1962 100644
--- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskResumeService.java
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/TaskResumeService.java
@@ -5,6 +5,7 @@ import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.spi.ClientTaskPullSpi;
+import jakarta.annotation.PostConstruct;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
@@ -45,7 +46,15 @@ public class TaskResumeService {
/** moduleType → 模块兜底载荷实现;只有注册了 SPI 的模块才能被自动续跑。 */
private final Map resumeHandlers;
- @Value("${aiimage.task-resume.enabled:true}")
+ /**
+ * 续跑总开关。默认值必须与 {@code application.yml} 的
+ * {@code ${AIIMAGE_TASK_RESUME_ENABLED:${AIIMAGE_CLIENT_TASK_PULL_ENABLED:false}}} 保持同一语义:
+ * 继承兜底拉取的开关、两者都没配时为 false。
+ *
+ * 这里曾经是 {@code :true},而 yml 永远会给出值,所以注解里的默认在生效路径上是死代码 ——
+ * 但它误导了读代码的人(以为默认开着),线上因此把「48 轮全零」当成了「恰好没有中断任务」。
+ */
+ @Value("${aiimage.task-resume.enabled:${aiimage.client-task-pull.enabled:false}}")
private boolean enabled;
/** 续跑代数上限:达到后不再重排队,任务保持 FAILED 等人工介入。 */
@@ -75,6 +84,18 @@ public class TaskResumeService {
log.info("[task-resume] 可自动续跑模块注册完成 count={} modules={}", index.size(), index.keySet());
}
+ /**
+ * 启动时打印本轮真正生效的配置,而不是让运维去反推 yml 的嵌套占位符。
+ *
+ *
{@code enabled=false} 会让巡检里的 resume 统计恒为 0,与"恰好没有中断任务"同形;
+ * 没有这一行,"续跑从未执行过"这件事在日志里是不可见的。
+ */
+ @PostConstruct
+ public void logEffectiveConfig() {
+ log.info("[task-resume] 生效配置 enabled={} maxAttempt={} windowMinutes={} limit={} modules={}",
+ enabled, maxAttempt, windowMinutes, limit, resumeHandlers.keySet());
+ }
+
/** 扫描一轮:把最近因客户端中断而失败、且未续跑过的任务重新排队。 */
public ResumeStats resumeInterruptedTasks() {
ResumeStats stats = new ResumeStats();
@@ -87,6 +108,7 @@ public class TaskResumeService {
}
LocalDateTime cutoff = LocalDateTime.now().minusMinutes(Math.max(1L, windowMinutes));
int safeLimit = Math.max(1, limit);
+ stats.ran = true;
List candidates = fileTaskMapper.selectList(new LambdaQueryWrapper()
.eq(FileTaskEntity::getStatus, STATUS_FAILED)
.likeRight(FileTaskEntity::getErrorMessage, CLIENT_INTERRUPT_PREFIX)
@@ -181,6 +203,11 @@ public class TaskResumeService {
/** 单轮统计(合并进 stale-check 的 summary 日志,避免定期刷屏)。 */
public static final class ResumeStats {
+ /**
+ * 本轮是否真的执行过扫描。开关关闭或模块未注册时为 false,此时其余计数虽同为 0,
+ * 含义却是"没跑"而不是"跑了没活" —— 必须让日志能把这两件事区分开。
+ */
+ public boolean ran;
public int scannedTaskCount;
public int resumedTaskCount;
public int skippedTaskCount;
diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/task/service/TaskClientPullServiceTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/task/service/TaskClientPullServiceTest.java
index 7c8592d11..9894fe2bf 100644
--- a/backend-java/src/test/java/com/nanri/aiimage/modules/task/service/TaskClientPullServiceTest.java
+++ b/backend-java/src/test/java/com/nanri/aiimage/modules/task/service/TaskClientPullServiceTest.java
@@ -1,5 +1,8 @@
package com.nanri.aiimage.modules.task.service;
+import ch.qos.logback.classic.Logger;
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.read.ListAppender;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.baomidou.mybatisplus.core.conditions.Wrapper;
import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
@@ -13,6 +16,7 @@ import org.apache.ibatis.builder.MapperBuilderAssistant;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
+import org.slf4j.LoggerFactory;
import org.springframework.test.util.ReflectionTestUtils;
import java.time.LocalDateTime;
@@ -156,6 +160,37 @@ class TaskClientPullServiceTest {
new StubHandler("SIMILAR_ASIN", payload("similar-asin-run"))));
}
+ /**
+ * 启动必须把兜底拉取的生效配置打出来。
+ *
+ * 它与续跑是一对({@code task-resume.enabled} 默认继承本开关),线上两个键都没配 → 都是关;
+ * 而关闭时 {@code pullPendingTasks} 直接返回空,接口 200 且响应与"开了但没候选"一模一样
+ * (实测 1 小时 4443 次 pull-pending 全空返回)。没有这一行日志就永远查不出来。
+ */
+ @Test
+ void 启动时打印生效配置() {
+ Logger logger = (Logger) LoggerFactory.getLogger(TaskClientPullService.class);
+ ListAppender appender = new ListAppender<>();
+ appender.start();
+ logger.addAppender(appender);
+ try {
+ TaskClientPullService service = service(new StubHandler("SIMILAR_ASIN", payload("similar-asin-run")));
+ ReflectionTestUtils.setField(service, "enabled", false);
+
+ service.logEffectiveConfig();
+
+ String line = appender.list.stream()
+ .map(ILoggingEvent::getFormattedMessage)
+ .filter(m -> m.contains("[client-task-pull] 生效配置"))
+ .findFirst()
+ .orElse("");
+ assertTrue(line.contains("enabled=false"), "启动必须说得清兜底拉取开没开:<" + line + ">");
+ assertTrue(line.contains("moduleTypes=SIMILAR_ASIN,COLLECT_DATA"), line);
+ } finally {
+ logger.detachAppender(appender);
+ }
+ }
+
private TaskClientPullService service(ClientTaskPullSpi... handlers) {
TaskClientPullService service = new TaskClientPullService(
fileTaskMapper, new InstanceMetadata("server-test"), List.of(handlers));
diff --git a/backend-java/src/test/java/com/nanri/aiimage/modules/task/service/TaskResumeServiceTest.java b/backend-java/src/test/java/com/nanri/aiimage/modules/task/service/TaskResumeServiceTest.java
index fff393d2e..1ce110306 100644
--- a/backend-java/src/test/java/com/nanri/aiimage/modules/task/service/TaskResumeServiceTest.java
+++ b/backend-java/src/test/java/com/nanri/aiimage/modules/task/service/TaskResumeServiceTest.java
@@ -1,10 +1,14 @@
package com.nanri.aiimage.modules.task.service;
+import ch.qos.logback.classic.Logger;
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.read.ListAppender;
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.spi.ClientTaskPullSpi;
import org.junit.jupiter.api.Test;
import org.mockito.ArgumentCaptor;
+import org.slf4j.LoggerFactory;
import org.springframework.test.util.ReflectionTestUtils;
import java.time.LocalDateTime;
@@ -12,6 +16,7 @@ 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.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.doThrow;
@@ -165,4 +170,80 @@ class TaskResumeServiceTest {
assertEquals(1, stats.skippedTaskCount);
verify(mapper, never()).insert(any(FileTaskEntity.class));
}
+
+ /**
+ * 开关关着时,统计必须说"本轮没跑",不能长得像"跑了但没活"。
+ *
+ * 线上 2026-09-28 实测:{@code resume(s=0 r=0 k=0 u=0)} 在两台连续 48 轮全零,
+ * 而 {@code aiimage.task-resume.enabled} 的真实默认是
+ * {@code ${AIIMAGE_TASK_RESUME_ENABLED:${AIIMAGE_CLIENT_TASK_PULL_ENABLED:false}}}(生产两个键都没设)
+ * —— 也就是说 V129 整套续跑从来没执行过,但从巡检日志上和"恰好没有中断任务"完全无法区分。
+ */
+ @Test
+ void 开关关闭时统计标记本轮未执行() {
+ FileTaskMapper mapper = mock(FileTaskMapper.class);
+ TaskResumeService service = service(mapper, List.of(spi("SIMILAR_ASIN")), false, 3);
+
+ TaskResumeService.ResumeStats stats = service.resumeInterruptedTasks();
+
+ assertFalse(stats.ran, "关闭时必须留得下「没跑」这个信息,否则日志里与「跑了没候选」同形");
+ assertEquals(0, stats.scannedTaskCount);
+ }
+
+ /** 真的查过库才算"本轮执行过",包括零候选的轮次。 */
+ @Test
+ void 查过库之后标记本轮已执行即使没有候选() {
+ FileTaskMapper mapper = mock(FileTaskMapper.class);
+ when(mapper.selectList(any())).thenReturn(List.of());
+ when(mapper.selectCount(any())).thenReturn(0L);
+ TaskResumeService service = service(mapper, List.of(spi("SIMILAR_ASIN")), true, 3);
+
+ TaskResumeService.ResumeStats stats = service.resumeInterruptedTasks();
+
+ assertTrue(stats.ran);
+ assertEquals(0, stats.scannedTaskCount);
+ }
+
+ /** 没有注册兜底实现等于跑不了:同样要标记未执行,不能报成"跑了没活"。 */
+ @Test
+ void 无模块注册时也算本轮未执行() {
+ FileTaskMapper mapper = mock(FileTaskMapper.class);
+ TaskResumeService service = service(mapper, List.of(), true, 3);
+
+ TaskResumeService.ResumeStats stats = service.resumeInterruptedTasks();
+
+ assertFalse(stats.ran);
+ }
+
+ /**
+ * 开机必须把续跑的生效配置打出来。
+ *
+ *
续跑是"功能写完了、测试全绿、线上默认关"的典型:光看代码里的
+ * {@code @Value(":true")} 会以为默认开着,实际 yml 把默认压成了 false。
+ * 所以启动那一行要直接说清 enabled 是什么、上限多少,别再让人去反推。
+ */
+ @Test
+ void 启动时打印生效配置() {
+ Logger logger = (Logger) LoggerFactory.getLogger(TaskResumeService.class);
+ ListAppender appender = new ListAppender<>();
+ appender.start();
+ logger.addAppender(appender);
+ try {
+ FileTaskMapper mapper = mock(FileTaskMapper.class);
+ TaskResumeService service = service(mapper, List.of(spi("SIMILAR_ASIN")), false, 3);
+ service.logEffectiveConfig();
+
+ String line = appender.list.stream()
+ .map(ILoggingEvent::getFormattedMessage)
+ .filter(m -> m.contains("[task-resume] 生效配置"))
+ .findFirst()
+ .orElse("");
+ assertTrue(line.contains("enabled=false"), "启动必须说得清续跑到底开没开:<" + line + ">");
+ assertTrue(line.contains("maxAttempt=3"), line);
+ assertTrue(line.contains("windowMinutes=30"), line);
+ assertTrue(line.contains("modules=[SIMILAR_ASIN]"), line);
+ } finally {
+ logger.detachAppender(appender);
+ }
+ }
}
diff --git a/docs/ops/prod-decisions-2026-09-28.md b/docs/ops/prod-decisions-2026-09-28.md
index 25c55d09e..4073bb4c3 100644
--- a/docs/ops/prod-decisions-2026-09-28.md
+++ b/docs/ops/prod-decisions-2026-09-28.md
@@ -702,6 +702,25 @@ health 200、Flyway 137 无新迁移、`ERROR` 0 条、`AIIMAGE_ROCKETMQ_NAME_SE
进程是 `nohup` 追加写、不能发信号重启 → 只能 `logrotate` 配 `copytruncate`(保留几轮 + 压缩)。
这是客户排障唯一的日志来源,保留策略要人点头,所以先记命令不执行。
+### 8.1 16:2x 复测:本节"别砍重试"那句已经不成立,套餐是彻底空了
+
+同一批口径在 16:19–16:23 重量了一遍,两处必须更正:
+
+- **上游零成功**:`nohup.out` 尾部 4MB(≈92 分钟,实测增速 726 B/s)里
+ `POST /brand_check` **3,443** / `Forbidden` **3,444** / `代理池为空` **3,444** / `套餐不存在` **3,444**
+ —— 四个数全等,`grep '待解密-->' | grep -v Forbidden` = **0 条**。
+ 上午那个样本里 310 次请求有 25 次没走到"套餐不存在"(约 8%),所以"每档还在救回 7–22%"当时成立,现在不成立。
+- **档位落差是预算截断,不是救回率**:主机A 45 分钟窗口 `distinct brand` **291** 个,
+ `重试耗尽判定查询失败` 覆盖 **290** 个 = **99.7% 最终失败**,同期 `整批耗时预算用尽` **290** 次。
+ attempt 直方图 342→242→220→192→157→124→116→88→69 的递减,几乎全部由 90 秒预算掐断重试链产生
+ (每次掐断紧跟一条"重试耗尽"),**不能当恢复率读**。
+- **服务与凭据都正常**(避免下次再往这个方向查):`:16890` 在听,loopback / 私网 / 公网 EIP 三条路都
+ **HTTP 200、0.7–2.2 秒**返回;带 `X-Token` 200、不带 422 → 36 位的 `AIIMAGE_BRAND_CHECK_TOKEN` 是对的。
+ 本节现象**不是**超时、不是 token、不是 §四 的公网带宽。
+- 因此上面"别顺手砍 java 的重试"这条**在套餐失效期无反对意见了**:10 次重试 × 递增等待现在只放大时延
+ (每分片回传最坏拖满 `total-timeout-millis=90000`),换不回任何品牌。是否临时压到 1 次待用户拍,
+ **套餐恢复后必须重新量 `distinct/exhausted` 两个数再决定重试档位**,别把止血参数留在永久位。
+
## 九、卡住自愈扫描会被一行的锁等待作废整轮(症状与根因两处都已修,取证在案)
§六 那轮复测顺手查出来的第二个缺陷,性质不同:**它不是网络,是我们自己的定时任务**。
@@ -1116,3 +1135,68 @@ RUNNING 行等满 5 分钟阈值"一致,是兜底在正常工作,没有作
(`Task is busy` + RUNNING),旧包靠 stuck 扫描按时间判死它,新包先由开机回收退回 PENDING、
再由 10 秒一轮的轮询重新捞起。两个修复接的是同一条链的两端。
+## 十三、V129 客户端中断自动续跑:功能上线至今从未执行过一次(**开关要不要开,待人决定**)
+
+查"客户端向已判死任务无限重推结果分片"时挖到的:**续跑整条链在线上一直是关的**,而日志上看不出来。
+
+### 13.1 取证(两台,16:3x)
+
+| 项 | 实测值 | 说明 |
+| --- | --- | --- |
+| 近 7 天「客户端异常中断」的 FAILED 任务 | 12 个 | 候选是有的,不是"恰好没活" |
+| `已自动重新排队` 日志 | **0 条** | 该文案只在真的建了续跑子任务时打 |
+| 巡检 `resume(s= r= k= u=)` | 48 轮全零 | 开关关了与没候选**同形**,这就是它藏了 10 天的原因 |
+| env `AIIMAGE_TASK_RESUME_ENABLED` | 两台都**没有** | 查了 `docker exec java-server env` + 宿主机 `/opt/1panel/runtime/java/java-server/.env` + `run.sh` |
+| env `AIIMAGE_CLIENT_TASK_PULL_ENABLED` | 两台都**没有** | 同上;续跑默认继承它 |
+| `GET /api/tasks/pull-pending` | 1 小时 **4443 次**、每次返回空列表 | 兜底拉取同样关着;客户端每分钟来领,领不到也不报错 |
+| 代码里 `@Value("${aiimage.task-resume.enabled:true}")` | 与 yml 相反 | yml 是 `${A:${B:false}}`,注解默认是死代码,但会把读代码的人带偏成"默认开着" |
+
+生效路径:`task-resume.enabled=false` → `resumeInterruptedTasks()` 第一行 `return`,
+所以那 12 个中断任务**一个都没被重新排队过**。
+
+后果实证(同一次排查里读到的):外观专利 29477 / 29478 / 29480 三个任务 0 分片落库、被标 FAILED 后,
+客户端在 15:16–15:44 仍每 ~3.7 分钟推 3 次分片、被拒约 18 次/小时 —— 任务已经判死,没人把它救回来。
+
+### 13.2 为什么开关我自己不拧(这不是技术判断,是产品语义)
+
+1. **兜底拉取的语义是"已解析但页面没推进队列的任务,客户端来领了直接跑"**。PENDING 的定义就是
+ 用户在页面点了"解析"、还没点"启动"(或点了但推送失败)—— 服务端**分不出这两者**。
+ 打开后,用户单纯解析出来放在那儿的任务会在 `min-pending-minutes`(默认 5 分钟)后自动真跑。
+ 白名单默认含 `APPEARANCE_PATENT`,而这个模块占平台 LLM 花费的 95%(后台「LLM 使用」口径)、
+ 扣的是**用户自己的次数**。
+2. 只开续跑、不开兜底拉取**没用**:续跑子任务落在 PENDING,线上唯一会消费它的就是兜底拉取,
+ 没人领就在 2 小时后被 `StaleTaskRepairService` 标失败 —— yml 那句注释"拉了没人领的话,续跑任务只会积压并被 stale 判死"就是这个意思。
+3. 双爬风险没排除:页面 activate 与拉取认领是同一行的 CAS(PENDING→RUNNING),互斥成立;
+ 但"客户端本地队列已在跑、服务端却还看到 PENDING"这种状态有没有过,**我没取证**,
+ 所以不能说开了之后一定不重复。
+
+一条已被否掉的替代修法(写在这是为了别再评估第二遍):**收到结果分片就把 FAILED 任务复活**。
+不行 —— 从中断到"复活后首次接受分片"之间被拒的那些分片永久缺失,而 `completeSubmittedChunk`
+不校验 `chunkTotal`,结果是一份**静默残缺的"成功**(比现在显式失败更坏,外观专利是判侵权用的)。
+
+### 13.3 这一版改了什么(只到"看得见"为止,不改行为)
+
+- `ResumeStats` 加 `ran`:本轮真的查过库才算跑过。开关关 / 模块未注册 → `ran=false`。
+- 巡检 summary 的续跑段位由 `resume(s= r= k= u=)` 改成 `resume(ran= s= r= k= u=)`。
+- `TaskResumeService` 与 `TaskClientPullService` 各加一行启动日志打生效配置
+ (`[task-resume] 生效配置 enabled=… maxAttempt=… windowMinutes=… limit=… modules=…` /
+ `[client-task-pull] 生效配置 enabled=… moduleTypes=… minPendingMinutes=… limit=… handlers=…`),
+ 以后发版后第一件能读到的就是"这两个开关到底是几"。
+- `@Value` 的 enabled 默认改成 `${aiimage.task-resume.enabled:${aiimage.client-task-pull.enabled:false}}`,
+ 与 yml 同语义(线上仍是 false,**本版发完续跑依然不会跑**,这是有意的)。
+
+### 13.4 待决定的两条路(选一条,或都不选)
+
+- **开**:`AIIMAGE_CLIENT_TASK_PULL_ENABLED=true`(写进宿主机 `/opt/1panel/runtime/java/java-server/.env`,
+ 必须 `export KEY="value"`,`/.env` 这一层要重启 java 才生效 —— 配方见本文第三节那条 env 说明)。
+ 建议同时收窄:白名单先只放 `SIMILAR_ASIN,COLLECT_DATA`(把 `APPEARANCE_PATENT` 摘出去,别一上来动 95% 的花费),
+ `min-pending-minutes` 从 5 抬到 30,`client-task-pull.limit` 保持 5。
+ 收益:长任务遇客户端更新自动续跑,用户不用手点。
+ 代价:解析后没点启动的任务会被自动跑,用户侧表现为"没点却跑了/次数被扣"。
+- **不开**:把每周约 12 个中断任务当成人工重跑成本(现状即如此)。
+ 若想少挨骂,代价更低的替代是在管理端/客户端加一个「重跑中断任务」按钮 —— 不改变自动行为,只省一次重新解析。
+
+**Why:** 这两件事(自动续跑要不要真跑用户没点的任务)不是我能替产品定的,而"日志上看不出来"是可以修的,所以只修了可观测。
+**How to apply:** 下次看到 `resume(ran=false …)` 别当 bug,那是开关没开;开了以后 `ran` 必须每轮都是 true,
+否则就是模块 SPI 没注册(`[task-resume] 可自动续跑模块注册完成 count=0` 会在启动行里)。
+