Reward Claims Architecture¶
概念概覽
核心結論¶
核心知識¶
核心結論¶
settlement_reward_ledger 的欄位（claiming_run_id、applied_run_id）語義強綁 settlement runs，不可直接泛化為通用 claim registry。正確做法是新建獨立的 reward_claims 表。
適用場景¶
OpenStickerPack（即時開包獎勵）和SettlePlayer（結算獎勵）兩條路徑都應寫reward_claims- 結算獎勵不應依賴 mutable aggregate（如
progress.sets_reward_claimed），真相必須收斂到 ledger 或 claims 表
判斷原則¶
當既有 ledger/log 表帶有強業務語義欄位時（如 run_id 綁定特定業務流程），不要為了省事泛化它——新建表的短期成本低於長期語義污染的修復成本。
經驗教訓¶
-
settlement_reward_ledger 是結算專用 ledger，claiming_run_id/applied_run_id 強綁 settlement_runs，語義不可泛化
-
通用 reward_claims 表應從零設計，讓不同 claim path（pack open、settlement、活動發放）都能寫入
-
結算獎勵的冪等性真相應在 claims 表而非業務 aggregate 欄位
常見陷阱¶
-
直接在 settlement_reward_ledger 加欄位來支援「非結算」場景，會導致 run_id 語義污染
-
依賴 progress.sets_reward_claimed 等 mutable field 作為已領獎依據，資料一致性無保證
最佳實踐¶
-
新建 generic reward_claims 表，以 claim_source（pack_open / settlement / activity）區分來源
-
所有 reward grant path 統一走 playerRewardGranter.GrantRewards，補 wiring 到 main.go
相關概念¶
- ClaimMarker Pattern (PostgreSQL Idempotency)
- Dungeon Reward Dual-Path Contract
- Game Item Exemption Resource Architecture
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Redis Sorted-Set TTL GC Capacity Bomb — 共享：
game-server/ 獨特：capacity-planning,event-system - Twirp Admin RPC Audit Architecture — 共享：
game-server/ 獨特：admin,audit - Activity Framework GameDataProvider Constructor Injection — 共享：
game-server/ 獨特：activity-framework,dependency-injection - Immutable Settlement Contract — 共享：
game-server/ 獨特：frozen-config,idempotency - RPC Idempotency for Gacha / Random Pack Opening — 共享：
game-server/ 獨特：gacha,idempotency
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-31 | c903e4ed-15e4-4a39-b7b8-30b428e38075 | 釐清 settlement_reward_ledger 語義邊界，確立通用 reward_claims 表的必要性與建表原則 |