[M-AI-03] 冻结统一 Job Engine、Registry、Outbox 与状态机 ADR #285

New Issue

wangdl · 2026-06-20T16:43:18+08:00

wangdl commented

2026-06-20 16:43:18 +08:00

类型 / 标签

architecture
adr
backend
queue

风险等级

P0

依赖

M-AI-03-01

目标

冻结本里程碑实现契约，后续 Issue 不得自行增加状态、队列、Job Definition 字段或执行阶段。

输出

docs/architecture/adr-003-unified-ai-job-engine.md

ADR 必须包含

状态机

完整状态；
允许迁移；
终态；
Legacy status Shadow Write；
非法迁移错误；
并发状态更新策略。

Job Definition

冻结 TypeScript 接口，包括：

metadata；
input/output schema；
executor；
validator；
projector；
queue policy；
timeout；
retry policy。

Queue

ai-interactive；
ai-background；
旧 ai-analysis；
Worker 进程注册边界；
Queue Payload；
BullMQ jobId。

Outbox

事件类型 ai.job.enqueue；
dedupeKey；
领取算法；
锁超时；
重试；
发布崩溃窗口；
未知 eventType 的处理。

Execution Engine

执行阶段；
错误分类；
timeout；
AbortSignal；
retry；
cancellation；
usage logging；
validatedOutput；
outputHash。

Projector

事务边界；
Artifact；
幂等；
重复执行；
失败回滚。

API

Job status；
cancel；
Admin query；
Admin retry；
权限；
公开错误。

安全

Credential；
Redis；
日志；
Snapshot；
Outbox payload。

验收标准

ADR 包含完整状态迁移表，含终态和非法迁移
Job Definition TypeScript 接口冻结，含所有必要字段
Queue 配置（ai-interactive / ai-background / ai-analysis）文档完整
Outbox 事件类型、dedupe 策略、领取算法、崩溃窗口处理明确
Execution Engine 管线阶段、错误分类、timeout/cancellation 策略明确
Projector 事务边界、Artifact 写入、幂等保证明确
API 设计覆盖 status / cancel / admin query / retry / 权限 / 公开错误
安全约束覆盖 Credential / Redis / 日志 / Snapshot / Outbox payload
ADR 包含模块图、时序图、接口草图、测试矩阵
ADR 确认无 Prisma 变更、无真实业务迁移

## 类型 / 标签 - architecture - adr - backend - queue ## 风险等级 P0 ## 依赖 - M-AI-03-01 ## 目标冻结本里程碑实现契约，后续 Issue 不得自行增加状态、队列、Job Definition 字段或执行阶段。 ## 输出 ``` docs/architecture/adr-003-unified-ai-job-engine.md ``` ## ADR 必须包含 ### 状态机 - 完整状态； - 允许迁移； - 终态； - Legacy status Shadow Write； - 非法迁移错误； - 并发状态更新策略。 ### Job Definition 冻结 TypeScript 接口，包括： - metadata； - input/output schema； - executor； - validator； - projector； - queue policy； - timeout； - retry policy。 ### Queue - ai-interactive； - ai-background； - 旧 ai-analysis； - Worker 进程注册边界； - Queue Payload； - BullMQ jobId。 ### Outbox - 事件类型 `ai.job.enqueue`； - dedupeKey； - 领取算法； - 锁超时； - 重试； - 发布崩溃窗口； - 未知 eventType 的处理。 ### Execution Engine - 执行阶段； - 错误分类； - timeout； - AbortSignal； - retry； - cancellation； - usage logging； - validatedOutput； - outputHash。 ### Projector - 事务边界； - Artifact； - 幂等； - 重复执行； - 失败回滚。 ### API - Job status； - cancel； - Admin query； - Admin retry； - 权限； - 公开错误。 ### 安全 - Credential； - Redis； - 日志； - Snapshot； - Outbox payload。 ## 验收标准 - [ ] ADR 包含完整状态迁移表，含终态和非法迁移 - [ ] Job Definition TypeScript 接口冻结，含所有必要字段 - [ ] Queue 配置（ai-interactive / ai-background / ai-analysis）文档完整 - [ ] Outbox 事件类型、dedupe 策略、领取算法、崩溃窗口处理明确 - [ ] Execution Engine 管线阶段、错误分类、timeout/cancellation 策略明确 - [ ] Projector 事务边界、Artifact 写入、幂等保证明确 - [ ] API 设计覆盖 status / cancel / admin query / retry / 权限 / 公开错误 - [ ] 安全约束覆盖 Credential / Redis / 日志 / Snapshot / Outbox payload - [ ] ADR 包含模块图、时序图、接口草图、测试矩阵 - [ ] ADR 确认无 Prisma 变更、无真实业务迁移

wangdl added this to the M-AI-03 统一 Job Engine、Registry 与 Outbox milestone 2026-06-20 16:44:53 +08:00

wangdl commented

2026-06-20 17:06:34 +08:00

开发完成评论

完成内容

状态机（§1）：5 状态（queued/running/succeeded/failed/cancelled）、6 允许迁移、6 非法迁移、唯一写入入口 AiJobLifecycleRepository、CAS 并发策略、Heartbeat/Reaper
Job Definition Registry（§2）：TypeScript JobDefinition 接口冻结（metadata/queue/execution/input/output/credential/projector/security 8 节）、JobDefinitionRegistry 类签名、注册生命周期
队列架构（§3）：ai-interactive/ai-background/ai-analysis 三队列配置、AiJobPayload 冻结、BullMQ jobId 格式、Worker 进程注册边界
Outbox（§4）：ai.job.enqueue 事件类型、dedupeKey 策略、先 CAS 后投递的修正领取算法（解决 #284 并发竞态）、锁超时/重试/崩溃窗口分析、未知 eventType 处理
Execution Engine（§5）：PREPARE/RESOLVE/EXECUTE/PROJECT/COMPLETE 五阶段管线、6 类错误分类、AbortSignal 实现、取消流程、重试分层、outputHash/validatedOutput
Result Projector（§6）：ResultProjector 接口冻结、事务边界（Projector + markSucceeded + Outbox 原子提交）、幂等保证（UNIQUE 约束 + catch）、失败回滚
API 设计（§7）：4 端点（status/cancel/admin query/admin retry）、JobStatusResponse 接口、6 公开错误码、Admin internalErrorMessage 权限
安全约束（§8）：Credential 加密、Redis ACL/Heartbeat Key/取消信号、日志脱敏、Snapshot 脱敏+过期、Outbox payload 最小化
模块图 + 时序图（§9–10）
测试矩阵（§11）：8 类测试覆盖到对应 Issue
非目标（§12）：7 项明确排除

修改文件

docs/architecture/adr-003-unified-ai-job-engine.md（新增，782 行）

验收标准对照

完整状态迁移表，含终态和非法迁移 → §1.1–1.3
Job Definition TypeScript 接口冻结 → §2.1
Queue 配置文档完整 → §3.1–3.3
Outbox 事件类型、dedupe、领取算法、崩溃窗口 → §4.1–4.5
Execution Engine 管线阶段、错误分类、timeout/cancellation → §5.1–5.7
Projector 事务边界、Artifact、幂等 → §6.1–6.4
API 设计覆盖 status/cancel/admin query/retry/权限/公开错误 → §7.1–7.4
安全约束覆盖 Credential/Redis/日志/Snapshot/Outbox payload → §8.1–8.5
模块图、时序图、接口草图、测试矩阵 → §9–11
确认无 Prisma 变更、无真实业务迁移 → §12

是否建议进入 Review

是 — 建议审查 ADR 完整性后进入 #286（状态机实现）

## 开发完成评论 ### 完成内容 - **状态机**（§1）：5 状态（queued/running/succeeded/failed/cancelled）、6 允许迁移、6 非法迁移、唯一写入入口 `AiJobLifecycleRepository`、CAS 并发策略、Heartbeat/Reaper - **Job Definition Registry**（§2）：TypeScript `JobDefinition` 接口冻结（metadata/queue/execution/input/output/credential/projector/security 8 节）、`JobDefinitionRegistry` 类签名、注册生命周期 - **队列架构**（§3）：`ai-interactive`/`ai-background`/`ai-analysis` 三队列配置、`AiJobPayload` 冻结、BullMQ jobId 格式、Worker 进程注册边界 - **Outbox**（§4）：`ai.job.enqueue` 事件类型、dedupeKey 策略、先 CAS 后投递的修正领取算法（解决 #284 并发竞态）、锁超时/重试/崩溃窗口分析、未知 eventType 处理 - **Execution Engine**（§5）：PREPARE/RESOLVE/EXECUTE/PROJECT/COMPLETE 五阶段管线、6 类错误分类、AbortSignal 实现、取消流程、重试分层、outputHash/validatedOutput - **Result Projector**（§6）：`ResultProjector` 接口冻结、事务边界（Projector + markSucceeded + Outbox 原子提交）、幂等保证（UNIQUE 约束 + catch）、失败回滚 - **API 设计**（§7）：4 端点（status/cancel/admin query/admin retry）、`JobStatusResponse` 接口、6 公开错误码、Admin internalErrorMessage 权限 - **安全约束**（§8）：Credential 加密、Redis ACL/Heartbeat Key/取消信号、日志脱敏、Snapshot 脱敏+过期、Outbox payload 最小化 - **模块图 + 时序图**（§9–10） - **测试矩阵**（§11）：8 类测试覆盖到对应 Issue - **非目标**（§12）：7 项明确排除 ### 修改文件 - `docs/architecture/adr-003-unified-ai-job-engine.md`（新增，782 行） ### 验收标准对照 - [x] 完整状态迁移表，含终态和非法迁移 → §1.1–1.3 - [x] Job Definition TypeScript 接口冻结 → §2.1 - [x] Queue 配置文档完整 → §3.1–3.3 - [x] Outbox 事件类型、dedupe、领取算法、崩溃窗口 → §4.1–4.5 - [x] Execution Engine 管线阶段、错误分类、timeout/cancellation → §5.1–5.7 - [x] Projector 事务边界、Artifact、幂等 → §6.1–6.4 - [x] API 设计覆盖 status/cancel/admin query/retry/权限/公开错误 → §7.1–7.4 - [x] 安全约束覆盖 Credential/Redis/日志/Snapshot/Outbox payload → §8.1–8.5 - [x] 模块图、时序图、接口草图、测试矩阵 → §9–11 - [x] 确认无 Prisma 变更、无真实业务迁移 → §12 ### 是否建议进入 Review - 是 — 建议审查 ADR 完整性后进入 #286（状态机实现）

wangdl referenced this issue

2026-06-20 17:17:37 +08:00

[M-AI-03] 实现 AiJob 状态机与原子状态仓储 #286

wangdl closed this issue

2026-06-21 12:37:49 +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#285