Dungeon Reward Dual-Path Contract¶
概念概覽
雙路徑架構¶
核心知識¶
雙路徑架構¶
Dungeon endBattle 存在兩條 reward 路徑，設計文件必須同時覆蓋：
- Victory path：正常勝利後的 reward grant
- InteractTypeDungeon defeat path：失敗後透過特定 InteractType 觸發的 reward
兩條路徑都必須使用相同的 idempotency key 格式：
Distributor Contract 必要欄位¶
每條路徑的 Distributor contract 規格必須包含：
- source：reward 來源標識
- idempotency_key：格式與 prefix 規範
- mismatch_threshold 行為：超過閾值時的 fail-closed 策略
qty≤0 語義決策¶
遷移後採用新語義：qty <= 0 => skip（而非舊 dungeon 的 force-to-1）。
這個語義改變需要 Gate 1 static config scan 作為 pre-rollout 保護，確認所有 config 中無非正數 quantity，才可執行 rollout。
經驗教訓¶
-
重構計畫中「影響範圍表」必須覆蓋所有 code path，dungeon 的 defeat path 容易被遺漏因為它不走主線 victory flow
-
語義改變（force-to-1 → skip）比 API 改變更危險，因為 compile-time 無法捕捉，必須配合 static config scan gate
常見陷阱¶
-
只測試 victory path，未測試 defeat path 的 grant/escrow 行為
-
假設 qty>0 是 invariant 而不做 static scan，導致 silent skip 影響玩家資產
最佳實踐¶
-
Reward 路徑設計文件必須明確列出所有觸發點（包含 defeat/edge case paths）
-
語義改變必須配合 pre-rollout gate（static scan 或 data audit）
相關概念¶
- ClaimMarker Pattern (PostgreSQL Idempotency)
- 設計文件四塊同步原則
- Hero Unlock Idempotency
- Immutable Settlement Contract
- PendingEvents Middleware Pattern for Real-time HUD
- Pool Resource Stamina Routing
- Reward Claims Architecture
- reward-pipeline-consolidation----dangling-------dangling---
- RPC Idempotency for Gacha / Random Pack Opening
- Twirp Error Code Single Channel Architecture
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- MutationPlan Grant Pipeline Architecture — 共享：
idempotency/ 獨特：game-backend,grant-pipeline - Redis Sorted-Set TTL GC Capacity Bomb — 共享：
game-server/ 獨特：capacity-planning,event-system
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-22 | 4d2cd4bd-d412-452e-8787-2ed0d493c165 | 識別 dungeon endBattle 存在 victory 與 defeat 雙路徑，兩者須共用相同 idempotency key 格式 |