MutationPlan Grant Pipeline Architecture¶
概念概覽
五層架構分工¶
核心知識¶
五層架構分工¶
- PlanContext：同時凍結
Tables + NowMs + RNGSeed，光凍結 gamedata 不夠——time-limited item 的ExpireAt在 CAS retry 間會漂移 - MutationPlan（pure function planner）：P0 要求純函數，必須在 CAS retry 外先 plan 完整 reward graph，不能在 retry 內 re-roll random
- ExecuteMutationPlanTx：唯一寫入入口，auto-open 展開必須在 planning phase 完成，executor 只負責寫 DB，不做遞迴
- MutationSummary：只能由 executor 根據「實際提交的 mutation」產生，不能從 plan 推導——前者是 DB 實際改了什麼，後者是玩家看到什麼
- DisplayReward：從 plan 投影（
ProjectDisplayRewards(plan)合理），但BuildMutationSummary(plan)不合理，這是整份 spec 最關鍵的分界
data_version 規則¶
data_version/changelog 只能由最外層 use case bump 一次，executor 不 bump version，只回 MutationSummary。必須使用 BumpDataVersionAtomic() 而非手動 GetCurrentDataVersion + UpdateDataVersion。
落地順序¶
PlanContext/MutationPlan 型別
→ pure planner
→ ExecuteMutationPlanTx
→ Distributor 回 MutationSummary
→ 舊 handler 改薄 wrapper
→ 移除 RewardResult 雙重職責
→ public API guard + rename
→ schema migration（如需真 generic）
經驗教訓¶
-
MutationSummary 必須從 executor 產生，而非從 plan 推導——這是防止系統再次 split-brain 的核心邊界
-
文檔落地前必須對照實際 codebase 逐行驗證，尤其確認新引入的 field/method 是否真實存在
-
禁止雙軌過渡：舊 handler 只能變成薄 wrapper，不能留半套舊邏輯
-
AffectedDomains 在型別定義階段就要用 typed bitset，不要事後再改
常見陷阱¶
-
CAS retry 內重 roll random：導致同一次 grant 每次 retry 得到不同 reward（P0）
-
從 plan 建構 MutationSummary：plan 是意圖，summary 是事實，兩者混用會讓 client 看到幻象數據
-
PlanContext 只凍結 Tables 不凍結 NowMs：time-limited item 的 ExpireAt 在 retry 間漂移
-
executor 做遞迴展開 auto-open：造成 nested reward 丟失、recursion 無 guard、response 組裝不一致
最佳實踐¶
-
planner 必須是純函數（同輸入同輸出），PlanContext 凍結所有不確定性來源（Tables + NowMs + RNGSeed）
-
auto-open 展開必須在 planning phase 完全展開，executor 禁止遞迴
-
ConsumeSpec 要帶 isNonStackable flag，讓 validateNetCapacity 能正確算「淨新增槽位」
-
GrantItems 全 auto-open 也必須走 data_version/changelog，不能 early return
相關概念¶
- Activity Framework Settlement Idempotency
- cas-retry-determinism----dangling---
- ClaimMarker Pattern (PostgreSQL Idempotency)
- Pool Resource Stamina Routing
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Dungeon Reward Dual-Path Contract — 共享：
idempotency/ 獨特：dungeon,game-server - Hero Unlock Idempotency — 共享：
game-backend,idempotency/ 獨特：1m-ccu,distributed-system - Game Item Exemption Resource Architecture — 共享：
game-backend/ 獨特：architecture-pattern,item-system
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-10 | da5e38be-36d2-40ac-8b78-e37cc8e0dec9 | 定案五層分離架構（PlanContext → MutationPlan → ExecuteMutationPlanTx → MutationSummary → DisplayReward），解決 RewardResult 雙重職責造成的 split-brain 根因 |