Hero Unlock Idempotency¶
概念概覽
Idempotency Key 設計¶
核心知識¶
Idempotency Key 設計¶
角色解鎖操作在 1M CCU 環境下，網路重試是常態。必須在操作層加 idempotency key 防止重複扣款：
這個三元組唯一標識「某玩家對某角色的某解鎖階段」，重複請求命中同一 key 時直接回傳上次結果，不重複執行扣款邏輯。
Luban 配置整合¶
Luban 生成的 GameRoleConfig Go struct 已包含：
- RoleUnlockCondition：解鎖前置條件
- RoleUnlockReward：解鎖獎勵配置
企劃配置已完整更新，後端直接讀取即可，無需額外定義配置結構。
多階段解鎖架構要點¶
- 解鎖消耗的貨幣（DungeonToken）從
player_resources垂直表扣除，搭配 CAS 防超扣 - 每個 unlock_stage 獨立記錄，支援分階段解鎖進度查詢
- BooleanAutoOpen（領取後自動打開道具/禮包）是獨立功能議題，不在角色解鎖系統範疇內
經驗教訓¶
-
1M CCU 環境下角色解鎖必須加 idempotency key，(player_id, role_id, unlock_stage) 三元組是最小唯一標識
-
Luban GameRoleConfig 已內含 RoleUnlockCondition/RoleUnlockReward，整合前應先確認 struct 現況而非重新定義
-
BooleanAutoOpen 等外圍功能應明確劃定系統邊界，避免設計範疇蔓延
常見陷阱¶
-
未加 idempotency key 的解鎖操作在高 CCU 網路重試下會造成重複扣款
-
將 BooleanAutoOpen 等無關功能納入角色解鎖系統範疇，增加不必要的複雜度
最佳實踐¶
-
角色解鎖操作加 idempotency key（player_id + role_id + unlock_stage）
-
整合 Luban 配置前先讀取最新 struct 定義，不依賴對話中先前的讀取結果
相關概念¶
- ClaimMarker Pattern (PostgreSQL Idempotency)
- Dungeon Reward Dual-Path Contract
- Game Resource Vertical Table
- gRPC Proto Pool Resource Design
- JIT Test File Lifecycle Management
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Game Item Exemption Resource Architecture — 共享：
game-backend/ 獨特：architecture-pattern,item-system - JWT Stateless Design at Scale with Forced Logout Gaps — 共享：
1m-ccu,game-backend/ 獨特：auth,forced-logout - MutationPlan Grant Pipeline Architecture — 共享：
game-backend,idempotency/ 獨特：grant-pipeline,pure-function
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-19 | 04c2b73d-c00e-4eaf-959f-0dbf0f224e24 | 設計了 1M CCU 環境下角色多階段解鎖的 idempotency key 方案，以及確認 Luban GameRoleConfig 已完整包含解鎖配置 |