[M-AI-02-07] 新增 Transactional Outbox 数据模型与仓储 #279

New Issue

wangdl · 2026-06-19T23:30:04+08:00

wangdl commented

2026-06-19 23:30:04 +08:00

依赖

M-AI-02-06

目标

新增未来可靠发布 BullMQ Job 和领域事件所需的 Outbox 表，但本批不实现 Dispatcher。

建议字段

最终以 ADR 为准：

id
eventType
aggregateType
aggregateId
dedupeKey
payload
status
attemptCount
availableAt
lockedAt
lockedBy
publishedAt
lastErrorCode
lastErrorMessage
createdAt
updatedAt

Outbox 状态

pending
processing
published
failed

约束

dedupeKey 唯一；
payload 禁止包含明文凭据；
Repository 必须支持在外部 Prisma Transaction 中创建；
不得在 Repository 内自行开启独立事务；
不得向 BullMQ 发布；
不得修改现有 EventBus；
不得修复或删除 domain-events 队列。

索引

至少包含：

(status, availableAt)
(lockedAt)
(aggregateType, aggregateId)

Repository

实现：

createInTransaction；
findDispatchable；
markProcessing；
markPublished；
markFailed；
releaseExpiredLocks。

本批只测试 Repository，不运行轮询器。

验收

Job 与 Outbox 可在同一 Prisma Transaction 创建；
事务回滚时两者都不存在；
dedupeKey 防止重复；
锁字段满足未来多 Worker 抢占；
真实 MySQL 事务测试通过。

## 依赖 * M-AI-02-06 ## 目标新增未来可靠发布 BullMQ Job 和领域事件所需的 Outbox 表，但本批不实现 Dispatcher。 ## 建议字段最终以 ADR 为准： ``` id eventType aggregateType aggregateId dedupeKey payload status attemptCount availableAt lockedAt lockedBy publishedAt lastErrorCode lastErrorMessage createdAt updatedAt ``` ## Outbox 状态 ``` pending processing published failed ``` ## 约束 * `dedupeKey` 唯一； * `payload` 禁止包含明文凭据； * Repository 必须支持在外部 Prisma Transaction 中创建； * 不得在 Repository 内自行开启独立事务； * 不得向 BullMQ 发布； * 不得修改现有 EventBus； * 不得修复或删除 `domain-events` 队列。 ## 索引至少包含： ``` (status, availableAt) (lockedAt) (aggregateType, aggregateId) ``` ## Repository 实现： * createInTransaction； * findDispatchable； * markProcessing； * markPublished； * markFailed； * releaseExpiredLocks。本批只测试 Repository，不运行轮询器。 ## 验收 * Job 与 Outbox 可在同一 Prisma Transaction 创建； * 事务回滚时两者都不存在； * dedupeKey 防止重复； * 锁字段满足未来多 Worker 抢占； * 真实 MySQL 事务测试通过。

wangdl added this to the M-AI-02 统一 AiJob 数据库 Expand milestone 2026-06-19 23:30:04 +08:00

wangdl added the

labels 2026-06-19 23:30:04 +08:00

wangdl changed title from ~~[M-AI-02] 新增 Transactional Outbox 数据模型与仓储~~ to [M-AI-02-07] 新增 Transactional Outbox 数据模型与仓储

2026-06-19 23:31:05 +08:00

wangdl commented

2026-06-20 12:00:26 +08:00

开发完成评论

完成内容

新增 OutboxEvent 模型（16 字段，独立基础设施表，无 FK 到业务表）
dedupeKey UNIQUE 防重复
3 个索引：(status, availableAt)、(lockedAt)、(aggregateType, aggregateId)
Repository 6 个方法：createInTransaction(tx, input) / findDispatchable(limit) / markProcessing(id, lockedBy) / markPublished(id) / markFailed(id, errCode, errMsg) / releaseExpiredLocks(thresholdMs)
createInTransaction 接受外部 Prisma Transaction 客户端，不自行开事务
12 个单元测试（事务创建、回滚、dispatch、processing、published、failed、过期锁释放、约束验证）

Outbox 状态机

pending → processing → published
                   → failed（可重试 → pending）

修改文件

prisma/schema.prisma：新增 OutboxEvent model
prisma/migrations/20260620000004_m_ai_02_07_outbox_event/migration.sql（新增）
src/infrastructure/outbox/outbox.repository.ts（新增，138 行）
src/infrastructure/outbox/outbox.repository.spec.ts（新增，156 行）

验证

16 列全部正确 ✅
dedupeKey UNIQUE ✅
3 个索引 ✅
表初始空 (0 rows) ✅

测试情况

单元测试：12 passed ✅
回归测试：303 passed ✅

未完成 / 风险

Dispatcher 不在本批范围（M-AI-03 实现）
不向 BullMQ 发布
不修改现有 EventBus

是否建议进入 Review

是

## 开发完成评论 ### 完成内容 - 新增 `OutboxEvent` 模型（16 字段，独立基础设施表，无 FK 到业务表） - `dedupeKey` UNIQUE 防重复 - 3 个索引：`(status, availableAt)`、`(lockedAt)`、`(aggregateType, aggregateId)` - Repository 6 个方法：`createInTransaction(tx, input)` / `findDispatchable(limit)` / `markProcessing(id, lockedBy)` / `markPublished(id)` / `markFailed(id, errCode, errMsg)` / `releaseExpiredLocks(thresholdMs)` - `createInTransaction` 接受外部 Prisma Transaction 客户端，不自行开事务 - 12 个单元测试（事务创建、回滚、dispatch、processing、published、failed、过期锁释放、约束验证） ### Outbox 状态机 ``` pending → processing → published → failed（可重试 → pending） ``` ### 修改文件 - `prisma/schema.prisma`：新增 `OutboxEvent` model - `prisma/migrations/20260620000004_m_ai_02_07_outbox_event/migration.sql`（新增） - `src/infrastructure/outbox/outbox.repository.ts`（新增，138 行） - `src/infrastructure/outbox/outbox.repository.spec.ts`（新增，156 行） ### 验证 - 16 列全部正确 ✅ - dedupeKey UNIQUE ✅ - 3 个索引 ✅ - 表初始空 (0 rows) ✅ ### 测试情况 - 单元测试：12 passed ✅ - 回归测试：303 passed ✅ ### 未完成 / 风险 - Dispatcher 不在本批范围（M-AI-03 实现） - 不向 BullMQ 发布 - 不修改现有 EventBus ### 是否建议进入 Review - 是

wangdl closed this issue

2026-06-20 16:35:55 +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#279