# Stale 任务收尾约束（公共心跳模块）

> 适用范围：所有使用 [TaskHeartbeatService](../src/main/java/com/nanri/aiimage/modules/task/service/TaskHeartbeatService.java) 的 file_task 模块
> （PRODUCT_RISK_RESOLVE / PRICE_TRACK / SHOP_MATCH / PATROL_DELETE / QUERY_ASIN /
>  APPEARANCE_PATENT / SIMILAR_ASIN / DELETE_BRAND）。

## 历史故障（2026-06-08）

SIMILAR_ASIN taskId=13102 的 file_job 长期持有 RUNNING 等待 Python 凑齐
batchSize 行再发 Coze。Python 端 13:20 异常掉线，但任务到下午 16 点仍卡在 12% 不前进，
30 分钟兜底失效。

链路：

1. [resetStuckJobs](../src/main/java/com/nanri/aiimage/modules/task/service/TaskResultFileJobWorker.java)
   每 60 秒扫一次，把 RUNNING 超 30 分钟的 file_job 改回 PENDING。
2. worker 立刻把它捞起来重跑 `processResultFileJob`。
3. 重跑分支命中 "等 Python 上传更多 row" → 调用 `touchJavaSideTaskActivity`，
   把 `file_task.updated_at` 刷成 now。
4. `finalizeStaleTasks` 用 `lt(updated_at, threshold)` 预过滤，于是这个任务
   永远进不到候选集，Redis 心跳判定那一步根本走不到。

→ Python 已断线 N 小时，任务仍在循环，永不收尾。

## 约束

### 1. stale-finalize 必须以 Redis 心跳为主信号

`TaskCacheService.touchTaskHeartbeat` 写的 Redis key 仅在 **Python 真实活动**
（心跳接口、上传 result chunk、提交 row）时刷新。Java 内部循环不应触碰它。

stale 判定时应：

- 以 Redis heartbeat 为主信号；
- 仅在 Redis 不可用 / 缺失时回落到 `file_task.updated_at`；
- 不要再用 `lt(file_task.updated_at, threshold)` 做预过滤
  （除非该模块 100% 不存在长期 RUNNING 等待循环）。

参考实现：[SimilarAsinTaskService.finalizeStaleTasks / isHeartbeatStale](../src/main/java/com/nanri/aiimage/modules/similarasin/service/SimilarAsinTaskService.java)
和 [AppearancePatentTaskService](../src/main/java/com/nanri/aiimage/modules/appearancepatent/service/AppearancePatentTaskService.java) 中 P1-7 注释段。

### 2. 不要在"等 Python"分支刷 file_task.updated_at

如果模块的 file_job 会持有 RUNNING 状态等待外部上传更多数据，
**这条等待路径上不允许调 `setUpdatedAt(now)` 类方法**。

否则会触发 [resetStuckJobs](../src/main/java/com/nanri/aiimage/modules/task/service/TaskResultFileJobWorker.java)
→ 重跑 → 续命 → 再 reset 的死循环。

如必须刷 `updated_at` 推动其他逻辑，应迁移到独立字段（例如
`file_job.updated_at`、Redis pendingScope 字段），与 stale 判定信号解耦。

### 3. 新增/修改 stale-finalize 流程的 PR 检查清单

- [ ] stale 判定的主信号是 Redis 心跳（不是 `file_task.updated_at`）
- [ ] 列出该模块所有刷 `file_task.updated_at` 的代码位置，
      其中没有任何一处会被 `processResultFileJob` 在"等 Python"分支重复触发
- [ ] 如果 file_job 会持有长 RUNNING（pull-style 工作流），明确写明 stuck-reset
      重跑后的幂等行为（不会续命 updated_at）
- [ ] 给 finalize 路径补一个 debug 接口（参考
      [DebugTaskRecoveryController](../src/main/java/com/nanri/aiimage/modules/debug/controller/DebugTaskRecoveryController.java)），
      绕过过滤直接对单 task 强制收尾，便于线上应急

## 当前各模块状态（2026-06-08 复核）

| 模块 | stale 入口 | 是否曾出现自我续命 | 是否需要改 |
|---|---|---|---|
| SIMILAR_ASIN | `SimilarAsinTaskService.finalizeStaleTasks` | 是（已修） | 已切 Redis-first |
| APPEARANCE_PATENT | `AppearancePatentTaskService.finalizeStaleTasks` | 是（已修） | 已切 Redis-first |
| PRODUCT_RISK_RESOLVE | `DeleteBrandStaleTaskService.failStaleProductRiskResolveTasks` | 否 | 当前不需要 |
| PRICE_TRACK | `DeleteBrandStaleTaskService.failStalePriceTrackTasks` | 否 | 当前不需要 |
| SHOP_MATCH | `DeleteBrandStaleTaskService.failStaleShopMatchTasks` | 否 | 当前不需要 |
| PATROL_DELETE | `DeleteBrandStaleTaskService.failStalePatrolDeleteTasks` | 否 | 当前不需要 |
| QUERY_ASIN | `DeleteBrandStaleTaskService.failStaleQueryAsinTasks` | 否 | 当前不需要 |
| DELETE_BRAND | `DeleteBrandStaleTaskService.failStaleDeleteBrandTasks` | 否 | 当前不需要 |
| BRAND | `BrandTaskService.failStaleRunningTasks`（独立心跳源） | 否 | 当前不需要 |

下次新增"等 row 凑批" / "pull-style 长 RUNNING file_job"型功能时，
请先读本约束。