Twirp Admin RPC Audit Architecture¶
概念概覽
錯誤的初始設計¶
核心知識¶
錯誤的初始設計¶
最初的 P0-3 任務是「發明 Auditor interface + BlockingAuditor 擋住所有 admin write RPC」。這是錯的——它會另起爐灶，與既有稽核路線並行存在造成技術債。
正確架構路線¶
專案已有完整的 admin 稽核路線：
- admin service 使用 CommandHandler 模式
- AuditHooks（before/after state、reason/ticket 強制驗證、11 欄位稽核）已覆蓋 admin write 操作
- Activity admin write RPC 應整合到此路線，不應另外發明 Auditor
正確的 Task 邊界調整¶
- #8（原 P0-3）降級並併入 #30（EXT-RBAC）的範圍
-
30 負責完整的 AuditHooks 整合（before/after state、強制欄位驗證）¶
- Activity admin write RPC 在 #30 完成前，應在 release readiness register 中標記為 Blocked，而非用 BlockingAuditor 暫時擋住
PD 操作流程¶
PD 透過 admin service 的 CommandHandler 模式新增、修改、關閉活動，這條路線自動繼承 AuditHooks 覆蓋，不需要在 Activity 模組內額外實作稽核邏輯。
經驗教訓¶
-
「用新 interface 擋住還沒實作的功能」是 tech debt workaround，正確做法是在 release register 標記 Blocked
-
稽核路線的統一性比快速上線更重要——兩套稽核機制並行比暫時無稽核更難維護
常見陷阱¶
- BlockingAuditor 模式（返回 twirp.Unimplemented）看似安全但實際上是技術債：它不屬於任何稽核路線，未來移除時沒有明確的替換目標
最佳實踐¶
-
新模組 admin write RPC 應複用既有 AuditHooks 路線，不應在模組內自行實作稽核
-
外部依賴未完成時，在 release readiness register 標記 Blocked 而非發明 placeholder 實作
相關概念¶
- Activity Framework GameDataProvider Constructor Injection
- rbac-audit-middleware----dangling---
- twirp-rpc-framework----dangling---
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- RPC Idempotency for Gacha / Random Pack Opening — 共享：
game-server,twirp/ 獨特：gacha,idempotency - Reward Claims Architecture — 共享：
game-server/ 獨特：reward-system,schema-design - Redis Sorted-Set TTL GC Capacity Bomb — 共享：
game-server/ 獨特：capacity-planning,event-system
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-10 | a7f313c0-2db2-4e32-8dc4-43117b1a66b8 | 釐清 Activity admin write RPC 應走現有 AuditHooks 路線而非發明 BlockingAuditor，並確認 PD 透過 admin service CommandHandler 模式操作活動框架 |