PendingEvents Middleware Pattern for Real-time HUD

概念概覽

問題背景

核心知識

問題背景

Stamina HUD 顯示延遲：玩家消耗體力後，前端 HUD 未即時更新，因為 ConsumeStamina 等玩家資料異動操作沒有 emit PlayerDataUpdated event 到 EventStore。

兩種解法比較

方案 A（反模式）：在每個 response proto 加 current_stamina 欄位 - 缺點：每新增一種資源（金幣、鑽石、體力）都要修改所有相關 response proto；前端需要針對每個 API 分別處理更新邏輯

方案 B（正確架構）：PendingEvents middleware + EventStore

ConsumeStamina → emit PlayerDataUpdated{stamina: X} → EventStore
                                                          ↓
                                          PendingEvents middleware
                                                          ↓
                                          response header 夾帶 pending events
                                                          ↓
                                          前端統一處理 HUD 更新

- 優點：前端只需一套 PendingEvents 更新邏輯；新資源類型只需加 event type，不改 response schema

現有缺口

ConsumeStamina、AddCurrency 等玩家資料異動操作目前沒有 emit PlayerDataUpdated event，PendingEvents 機制覆蓋不完整。修法方向是在這些操作加入 event emission，而非修改 response proto。

經驗教訓

• 在每個 response 加資源欄位是短期方便但長期維護成本高的反模式

• PendingEvents middleware 讓前端維持一套統一的即時更新邏輯，新資源類型只需加 event，不改 API 合約

• EventStore emission 的缺口往往不明顯，需要明確追蹤哪些操作已覆蓋

常見陷阱

• 新增資源類型時只改 response proto 而不加 EventStore emission → 前端更新邏輯碎片化

• PendingEvents middleware 已實作但操作層未 emit event → middleware 存在但無法觸發，靜默無效

• ConsumeStamina 等操作漏掉 emit 導致 HUD 更新只在部分 API 後觸發，用戶體驗不一致

相關概念

• Activity Framework Settlement Idempotency
• Dungeon Reward Dual-Path Contract
• Game Resource Vertical Table

相關視角

以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：

• Pool Resource Stamina Routing — 共享：game-backend, stamina / 獨特：honest-boundary, pool-resource
• Time-Limited Pass Item Design — 共享：game-backend / 獨特：game-design, item-system

來源 Sessions

日期	Session	貢獻摘要

| 2026-04-02 | d088842d-abec-48fc-8a1a-779a5f74e05d | 提出以 PendingEvents middleware + EventStore emission 解決 Stamina HUD 顯示延遲問題，相較於在每個 response 加欄位的方案更具架構一致性 |

---

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-04-02