API-AI-002：AI Job 状态机与任务调度设计 #163

New Issue

wangdl · 2026-06-10T21:01:46+08:00

wangdl commented

2026-06-10 21:01:46 +08:00

目标

设计 AI Runtime Job 的状态机、任务类型、锁定机制、重试机制、超时机制和幂等规则。

Job 类型

learning_state_analysis
weak_point_analysis
next_action_planning
quiz_generation
flashcard_generation

Job 状态

pending
locked
running
succeeded
failed
cancelled
expired

必需字段

id
userId
jobType
targetType
targetId
snapshotId
status
priority
idempotencyKey
lockedBy
lockedAt
lockUntil
startedAt
finishedAt
retryCount
maxRetryCount
timeoutSeconds
errorCode
errorMessage
createdAt
updatedAt

状态流转

pending → locked → running → succeeded
pending → locked → running → failed
failed → pending
running → expired
pending → cancelled
locked → expired

验收标准

输出 Job 状态机设计文档。
明确每个状态的进入条件和退出条件。
明确 Runtime 如何锁定任务。
明确 lockUntil 超时后如何释放任务。
明确 retryCount / maxRetryCount 规则。
明确 idempotencyKey 用于防止重复创建任务。
明确 Admin 后续可重跑 failed job。
明确 cancelled / expired 不应被 Runtime 再次消费。

## 目标设计 AI Runtime Job 的状态机、任务类型、锁定机制、重试机制、超时机制和幂等规则。 ## Job 类型 - learning_state_analysis - weak_point_analysis - next_action_planning - quiz_generation - flashcard_generation ## Job 状态 - pending - locked - running - succeeded - failed - cancelled - expired ## 必需字段 - id - userId - jobType - targetType - targetId - snapshotId - status - priority - idempotencyKey - lockedBy - lockedAt - lockUntil - startedAt - finishedAt - retryCount - maxRetryCount - timeoutSeconds - errorCode - errorMessage - createdAt - updatedAt ## 状态流转 ``` pending → locked → running → succeeded pending → locked → running → failed failed → pending running → expired pending → cancelled locked → expired ``` ## 验收标准 1. 输出 Job 状态机设计文档。 2. 明确每个状态的进入条件和退出条件。 3. 明确 Runtime 如何锁定任务。 4. 明确 lockUntil 超时后如何释放任务。 5. 明确 retryCount / maxRetryCount 规则。 6. 明确 idempotencyKey 用于防止重复创建任务。 7. 明确 Admin 后续可重跑 failed job。 8. 明确 cancelled / expired 不应被 Runtime 再次消费。

wangdl added this to the M-API-AI-RUNTIME：API AI Runtime 调度与落库 milestone 2026-06-10 21:01:46 +08:00

wangdl added the

labels 2026-06-10 21:01:46 +08:00

wangdl commented

2026-06-11 20:44:00 +08:00

完成证据

产物: docs/ai-job-state-machine.md (233 行)
提交: 045e0b2 feat: AI Job 状态机与任务调度设计 (API-AI-002)

覆盖内容:

5 种 Job 类型：learning_state_analysis / weak_point_analysis / next_action_planning / quiz_generation / flashcard_generation
7 种状态：pending / locked / running / succeeded / failed / cancelled / expired
完整状态流转图
AiRuntimeJob 数据库字段定义（含 Prisma schema）
防并发锁定机制（DB 行级写 + lockUntil + heartbeat）
retryable vs non-retryable 分类
超时释放、幂等规则、Poll 调度策略

## 完成证据 **产物**: `docs/ai-job-state-machine.md` (233 行) **提交**: `045e0b2` feat: AI Job 状态机与任务调度设计 (API-AI-002) **覆盖内容**: - 5 种 Job 类型：learning_state_analysis / weak_point_analysis / next_action_planning / quiz_generation / flashcard_generation - 7 种状态：pending / locked / running / succeeded / failed / cancelled / expired - 完整状态流转图 - AiRuntimeJob 数据库字段定义（含 Prisma schema） - 防并发锁定机制（DB 行级写 + lockUntil + heartbeat） - retryable vs non-retryable 分类 - 超时释放、幂等规则、Poll 调度策略

wangdl closed this issue

2026-06-11 20:44:01 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#163