# 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／唯讀）；範圍揭露 |