Activity Framework Settlement Idempotency¶
概念概覽
Double-settle 風險的成立前提¶
核心知識¶
Double-settle 風險的成立前提¶
handler.SettlePlayer 若在 tx 之外執行不可回滾的副作用（HTTP 呼叫、MQ publish、push notification），才會產生 double-settle 的業務風險。Framework 本身以 tx 包覆 settlement 邏輯是安全的，問題在於 handler 是否遵守「tx 外無副作用」的規範。
ResumeSettlement 失敗語意¶
ResumeSettlement 可能因 slot 被其他合法 run 佔據而回傳失敗，這**不代表系統異常**。Runbook 應明確記載此語意，避免 on-call 誤判為需要人工介入。
RPC 契約落差分類¶
- 純文件同步：API 名稱不一致但語意相同，只需重命名
- 真實語意缺口：如
CreateManualActivity缺少source_key的 idempotency key，改名無法解決，需補充欄位設計
兩者混淆會導致誤判工作量或遺漏真正的功能缺口。
經驗教訓¶
-
handler interface 文件應明確標注 SettlePlayer 不應做 tx 外不可回滾副作用，否則冪等保證由 handler 自行負責
-
分析 RPC 落差時先分類「文件問題」vs「語意缺口」，避免把命名差異當功能缺失處理
常見陷阱¶
-
在 SettlePlayer 內直接呼叫 HTTP/MQ/push 而未處理冪等，當 framework 重試時會造成重複副作用
-
把 ResumeSettlement 的 slot 競爭失敗誤報為系統錯誤，觸發不必要的人工介入
最佳實踐¶
-
handler 副作用（HTTP/MQ/push）應在 tx commit 後以 outbox pattern 或 at-least-once queue 處理，而非直接在 tx 內呼叫
-
Runbook 中明確列出「預期的非錯誤失敗」語意，減少 on-call 誤判
相關概念¶
- activity-framework-phase3----dangling-------dangling---
- ClaimMarker Pattern (PostgreSQL Idempotency)
- ClosureBuilder Deterministic JSON Encoding
- Config Sync Advisory Lock Pattern
- MutationPlan Grant Pipeline Architecture
- PendingEvents Middleware Pattern for Real-time HUD
- Subagent Parallel Development Code Review
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Immutable Settlement Contract — 共享：
idempotency,settlement/ 獨特：frozen-config,game-server - Stub-to-Production Gap Risk — 共享：
activity-framework/ 獨特：production,risk - Activity Framework GameDataProvider Constructor Injection — 共享：
activity-framework/ 獨特：dependency-injection,game-server - Phase Readiness Blocker Classification — 共享：
activity-framework/ 獨特：blocker,methodology
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-02 | 157b6880-f9d3-466a-abf9-07af0459b5d5 | 明確了 double-settle 風險的成立前提，以及 framework tx 包覆與 handler 副作用責任邊界 |