# ADR-008 · 投递队列的落地形态:sys.event_delivery 是队列本体,pg-boss 只管定时

- 状态:已决(M1)
- 日期:2026-07-27
- 上下文:编码规范 §7.1 要求「先持久后投递」= 信封写 `sys.event` 与 **pg-boss 入队在同一事务**。
  但 pg-boss 的 `send()` 走自己的连接池,无法参与我们打开的事务;若拆成两步,
  「先持久后投递」的原子性就落空(写了事件、没入队 = 事件永不推进)。

## 决定

1. **投递记录本身就是队列**:`sys.event_delivery` 每行一份投递(投递 ID / 事件 ID / 单目标 /
   attempt / state / next_attempt_at),与 `sys.event` 的信封写入**同一事务**落库。
   「先持久后投递」由此在一条事务里成立 —— 队列不是外部件,是事件存储的一部分。
2. **消费由派发器拉取**:派发 worker 按 `state='pending' and next_attempt_at <= now()` 取行,
   对目标 ID 取 **advisory lock** 串行执行 —— 这正是「同任务按序」的实现(§7.1)。
3. **幂等在消费侧**:`sys.event_consumption(event_id, consumer)` 唯一约束;
   `claimConsumption` 插入成功即首次消费,冲突即已消费 —— 「至少一次 + 幂等」。
4. **pg-boss 只承担定时**:监听时限扫描、周期触发器求值、蒸馏钩子等**时间驱动**的作业归 pg-boss
   (`queue` schema 自管)。它不承载事件投递,因此不需要与业务事务同源。
5. 重试与死信:`decideRetry`(纯函数)给退避阶梯,超限置 `dead-letter` 并经 `MessageFallback`
   端口送系统通知 —— 「处理有回执」。

## 后果

- 投递五诺全部有落点,且五条都可在集成测试里断言。
- 代价:多一个派发 worker(app 层),不能白嫖 pg-boss 的并发控制;换来的是原子性与可测性。
- `event` 模块因此不依赖 pg-boss;pg-boss 只出现在 `app/workers/`。