CR #226 » CR-025_授權稽核軌跡查詢端點.md
CR-025 授權稽核軌跡查詢端點（補既有缺口）
| 項目 | 內容 |
|---|---|
| 文件編號 | CR-025 |
| 版本 | 1.0 |
| 提出日 | 2026-09-29 |
| 提出者 | WorkBuddy AI（開發團隊） |
| 緣起 | BEAM PMO 指示「桶 C 盤點後開工」。SDD-007 §5.1.2.3 之桶 C「稽核軌跡查詢」（/system/audit）原記「表存在但無查詢端點」——本 CR 即為該缺口之補實作 |
| 影響範圍 |
tools/gen_openapi.py → contracts/openapi/authorization-service.yaml（＋1 端點、＋2 schemas）；SCS-001 §7.9（新增）；SDD-007 §5.4.25（新增）；AuthorizationRepository／JdbcAuthorizationRepository／AuthorizationController；前端 api/authorizations.ts／pages/AuditConsole.tsx／App.tsx
|
| 狀態 | ✅ 已執行（2026-09-29）——規格先行：立 SCS-001 §7.9 → 改產生器 → 重生契約（79 端點、0 錯誤）→ 實作 → SDD-007 §5.4.25 → 頁面 |
1. 缺口之證據
兩張稽核表早已存在且有資料（CC_AUTH）：
| 表 | 產生者 | 欄位 | 資料 |
|---|---|---|---|
AUTH_OVERRIDES |
人工／強制核決（§7.8，#A-98） |
ID／AUTH_NO／DECISION／FORCE_FLAG／OPERATOR_ID／REASON／CREATED_AT
|
2 筆 |
AUTH_REVERSALS |
沖正（§7.6，#A-95/96） |
ID／AUTH_NO／REVERSAL_TYPE／AMOUNT／REASON／HOLD_ID／CREATED_AT
|
2 筆 |
但無任何查詢端點——資料寫得進去、讀不出來（稽核留痕形同虛設：出事時查不到）。
佐證：contracts/openapi/authorization-service.yaml 原 8 端點中無稽核相關端點；
AuthorizationRepository 亦無稽核查詢埠。
2. 變更內容
2.1 新增端點（1 支）
| 方法 | 路徑 | 語意 | 回應 |
|---|---|---|---|
GET |
/api/v1/authorizations/audits?eventType=&limit= |
稽核軌跡查詢（統一時間軸） | 200 AuthAuditEventList
|
eventType：ALL（預設）／OVERRIDE／REVERSAL。limit：預設 20、上限 200（程式中 Math.min(Math.max(limit,1),200) 硬性夾擠）。
2.2 新增 schema（2 支）
-
AuthAuditEvent：auditId／eventType／authNo／actor／action／amountMinor／reason／occurredAt -
AuthAuditEventList：AuthAuditEvent[]
2.3 設計決策
| 決策 | 理由 |
|---|---|
統一時間軸（兩表 UNION ALL 後依時間遞減） |
使用者關心「這筆授權發生過什麼」，而非「它屬於哪張表」；分開兩頁會迫使使用者自行拼湊時間序 |
action 值域正規化（reversal_type || '_REVERSAL'） |
使兩類事件之動作欄位同一值域（APPROVE／DECLINE／FULL_REVERSAL／PARTIAL_REVERSAL），畫面得以統一呈現 |
actor 對沖正回 null |
AUTH_REVERSALS 無操作者欄位——如實呈現，不臆造（CSP-001 §8 B2）；畫面顯示「未記錄」 |
| append-only 唯讀 | 稽核紀錄一旦可竄改即失去證據力，故不提供修改／刪除端點 |
3. 範圍（誠實揭露）
本端點涵蓋「授權服務」之稽核軌跡。其餘服務之稽核（如 party 管制碼異動、card 生命週期）
尚無查詢端點 → 已登記 C-46，待各自就緒後擴充。
→ 頁面須明載此範圍，不得讓使用者誤以為這是「全系統稽核」。
另：AUTH_REVERSALS 若要補「操作者」，須於沖正路徑加 operator_id 欄位（另立 CR，本次未做）。
4. 驗證
| 項 | 結果 |
|---|---|
| 契約重生 | ✅ 79 端點、0 錯誤（authorization-service 8 → 9） |
| 單元測試 | ✅ BUILD SUCCESSFUL
|
| 真機驗證 | 見 HANDOVER §3.A #A-102
|
5. 修訂記錄
| 版本 | 日期 | 說明 |
|---|---|---|
| 1.0 | 2026-09-29 | 初版：缺口證據（表有資料、端點全無）；新增 1 端點＋2 schemas；設計決策（統一時間軸／值域正規化／actor 如實 null／唯讀）；範圍揭露 |