# SCS-018　WebUI 前端（cardcore-web）程式設計規格（跨域）

| 項目 | 內容 |
|---|---|
| 文件編號 | SCS-018 |
| 版本 | 1.0 |
| 狀態 | **已核定（規格先行·跨域）** |
| 對應需求 | 全站 UI／操作需求（`SDD-007` 9 群 45 頁規範；客戶認可介面） |
| 技術棧 | React 18 + Vite + TypeScript（dev_port 5173，參 `spec/services.yaml`） |
| 套件根 | `cardcore-web`（前端，不由 `gen_service_skeleton` 處理） |
| 關聯文件 | `SDD-007_WebUI設計規範`、`GOV-005`、`CSP-006 §4` |

---

## 1. 對應需求與設計依據

- 本服務之前端規格**主體在 `SDD-007`**（設計 Token、版式、元件規範、頁面清單、權限矩陣、敏感欄位、API 串接規範）。本 SCS 為其與回溯 SCS 體系的銜接，不重複 `SDD-007` 內容。
- `BRD` 操作類需求經 `SDD-007` 落地為 45 頁 × 9 角色權限矩陣（100% 定義，參 `SDD-007 §5.2`）。

### 1.1 與其他 SCS 的關係

| 後端 SCS | 前端頁面 |
|---|---|
| `SCS-001` 授權 | 授權作業台（`/authorizations`） |
| `SCS-002` 額度 | 額度調整申請（`/limit-adjustments`） |
| `SCS-003` 卡片 | 卡片生命週期頁 |
| `SCS-004` 當事人 | 歸戶／持卡人頁 |
| `SCS-005~017` | 各對應業務頁 |

---

## 2. 範圍與職責

- **BFF 聚合層**（`bff-web`，port 8101）：前端專屬聚合，減少 N+1 呼叫。
- **設計系統**：色彩／字型／間距 Token（`SDD-007 §3`），確保與客戶認可介面一致。
- **元件規範**：DataTable、Filter Bar、Detail Drawer、Badge、KPI 卡、表單驗證（`SDD-007 §6`）。

---

## 3. 頁面與元件清單（引用 `SDD-007 §5.1`）

- **9 群 45 頁**：授權、額度、卡片、當事人、產品、繳款、分期、帳單、系統管理（參 `SDD-007 §5.1` 完整表）。
- **權限矩陣**：45 頁 × 9 角色（CSR／CSR_SUP／…），100% 定義（`SDD-007 §5.2`）。
- **敏感欄位**：PII 顯示規則（`SDD-007 §5.3`），遮罩經 `common-security` `PiiMasker`。

---

## 4. 關鍵頁面操作與按鈕定義（引用 `SDD-007 §5.4`）

- **已定義（2026-09-19 補建）**：授權作業台、額度調整申請——逐鈕列：按鈕｜功能｜觸發端點｜檢核規則｜所需角色｜成功／失敗回饋。
- **待補**：其餘 43 頁於開發時**依同一格式**增補（格式見 `SDD-007 §5.4` 表頭）。此為已知缺口，開發該頁前須先補按鈕定義。
- 規範：**每個按鈕都必須定義「觸發哪支 API、何種檢核、何種角色、成功／失敗回饋」**，否則視為未完成（對應 BEAM PMO 之追溯要求）。

---

## 5. 權限矩陣與敏感欄位遮蔽

- 權限：依 `SDD-007 §5.2` 之 9 角色矩陣；前端路由與按鈕可見性由 BFF 注入之權限決定。
- 遮蔽：`SDD-007 §5.3` 定義欄位層級；前端顯示一律經 `PiiMasker` 遮罩（卡號、證號、聯絡方式）。

---

## 6. 與後端介接

- 統一入口：`api-gateway`（port 8100）→ `bff-web`（port 8101）→ 各領域服務。
- API 串接規範：`SDD-007 §9`（分層、規則、反模式禁令——對應 `GOV-003 §6.2`）。

---

## 7. 測試案例（對應 `TRP-001`）

- 元件測試（DataTable／Filter Bar／表單驗證）
- 權限矩陣測試（角色可見性）、敏感欄位遮蔽測試
- 關鍵頁面按鈕 → API 觸發對應（依 `SDD-007 §5.4`）

---

## 8. 已知限制（誠實揭露）

- **`SDD-007 §5.4` 按鈕定義僅完成 2／45 頁**；其餘頁面按鈕定義須於開發前補齊（否則違反「無 SCS 不寫程式」之精神）。
- 前端 `cardcore-web` 目前為空目錄（參 `HANDOVER.md`），尚未產生骨架。
- 9 群 45 頁為設計規格，實際頁面與元件須待 `cardcore-web` 骨架產生後實作。