交易型 Outbox

events.cloud_events 立即且同步發送——在「完成工作」與「送出事件」之間若當機,事件就遺失;網路抖動也會 丟失(沒有持久化、沒有重試、沒有重播)。交易型 outbox 模式先持久化每個事件,稍後再以至少一次(at-least-once) 傳遞與死信上限來排空(drain),讓事件能在接收端故障時存活。

純標準函式庫(json);不匯入 PySide6。傳遞用的 sink 以注入方式提供,儲存為記憶體內並具 JSON 持久化,因此排空在 CI 中完全具決定性。

無頭 API

from je_auto_control import Outbox

box = Outbox()
box.enqueue({"type": "order.created", "id": 7})    # 已緩衝、待傳遞
box.enqueue({"type": "order.paid", "id": 7})

result = box.drain(post_to_webhook, max_batch=100, max_attempts=5)
# {"sent": 2, "failed": 0, "remaining": 0}

box.pending()        # 仍待傳遞的項目
box.dead_letters()   # 已用盡重試次數的項目

enqueue 將事件附加為待傳遞並回傳其 id。drain 透過注入的 sink 傳遞至多 max_batch 個待傳遞項目; sink 拋出例外時,該項目維持待傳遞以供重試,直到 max_attempts,之後被列為死信(連同錯誤一併記錄)。 傳遞為至少一次:若 sink 成功但在標記為已送出前被中斷,該項目會被重試。save / load 以 JSON 持久化整個緩衝區,讓事件能在行程結束後存活。

執行器命令

AC_outbox_enqueue 回傳 {id, pending};``AC_outbox_pending`` 回傳 {pending}。兩者使用具名實例登錄, 並以 MCP 工具(ac_outbox_enqueue / ac_outbox_pending)以及 Script Builder 中 Flow 分類下的命令提供。 排空需要可呼叫的 sink,因此維持為無頭 / API 操作。