# SDD-007　WebUI 設計規範 | 項目 | 內容 | |---|---| | 文件編號 | SDD-007 | | 版本 | **1.27**（**§5.4.31 歸戶 360（`/accounts`）補建**（`CR-032`；`#A-145`）。**緣由**：`CR-031 §4.5`／`SAD-004 §2.2.1.1` 誠實揭露「`BffAccountOverview` **尚無前端消費者**」——本節即該缺口之**閉環**（`#A-143` 投影 → `#A-144` 聚合 → **本頁呈現**）。**無契約變更、無後端變更**。★ **設計要點**：**降級呈現為本頁最重要規則**——四區塊**各自獨立降級**，`UNAVAILABLE` **必須明顯呈現並帶下游錯誤碼**，**嚴禁以 `0`／空白代替**（「取不到」≠「真的是 0」）；**空狀態 vs 不可用必須區分**（`cards` `OK` 且 `[]` ＝「尚無卡片」／`UNAVAILABLE` ＝「不可用」）；**唯讀**（異動指引至各作業頁）；**PII／PCI**（卡號僅遮罩，不含 PAN）。⚠️ **併誠實揭露**：本頁**超出 `§5.1` 之 59 頁清單**（第 2 頁超出者，先例 `/limit-adjustments`）。前版 **1.26**（**§5.4.30 分流比例管理（`/system/split-ratio`）補建——桶 C 解鎖**（`#A-120`）。**規格先行**：`SCS-020 §9.12` → 實作（gateway 自供 `GET`／`PUT /api/v1/gateway/split-ratio`）→ 逐鈕定義 → 頁面。**選頁理由**：`SAD-004 §2.4` 之分流機制（POC-13 已驗收）**完整存在**，缺的**只是管理面**——不需新領域模型、不會造空殼；「灰度放量與回退」為遷移期最高頻維運操作。**設計要點**：定點行替換（保留註解）／`ContextRefresher` 熱更新／**回讀驗證**（`effectiveMatchesRequest`，不以請求值冒充生效值）／失敗不靜默（`CC-PLT-5000`）。⚠️ **併更正 `v1.25` 之計數漏同步**：版本列已載「桶 C 30 → 29」而本節標題／清單／重盤總表**仍記 30**，且**漏計 `#A-114` 之 `/switch/auth/state`** → 本版校正為 **桶 C 29 → 28、已實作 19 → 20**（合計仍 **59 ✅**）。前版 **1.25**（**§5.4.29 交易狀態機檢視（`/switch/auth/state`）補建——桶 C 解鎖**（`#A-114`）。**規格先行**：`SCS-001 §7.11` → 改 `gen_openapi.py` → 契約 → 實作 → 逐鈕定義 → 頁面。**選頁理由**：`C-46` 建議延續 `authorization-service`；授權狀態機為本專案**建模最完整**之狀態機（`SCS-001 §3.2`／`SDD-005`）；來源資料全在 Oracle（免新領域模型）。**設計要點**：狀態機視角 vs `§5.4.25` 事件時間軸（互補不重複）／佔用 `null` 如實顯示／**冪等（Redis）如實揭露不重現**。**桶 C 30 → 29**。前版 **1.24**（**§5.4.28 營運總覽（`/dashboard`）補建——桶 C 解鎖**（BEAM PMO 2026-10-01 裁定「挑投報率最高者，先補後端、再規格先行、再實作」）。**規格先行**：`SCS-020 §9.11` → 改 `gen_openapi.py` → **契約 87 端點、0 錯誤** → 實作 → 逐鈕定義 → 頁面。★ **回訪查證**：17 服務**皆無統計端點** → **本版明訂為「系統營運面」**（服務健康／批次／端點連線摘要），**業務 KPI 屬第二階段**。**真機**：`DEGRADED`（4/17 UP）、`unavailable=4`、**`routes=null`**（不以 0 充數）；未帶 token → **401**。**測試 12 → 17 測 0 失敗**；側欄 **26 → 27 頁**）。前版 **1.23**（**桶 B 擴充（BEAM PMO 2026-10-01 裁定）**——`/onboarding/review`／`/onboarding/approval` **移入桶 B**：其核心流程**已由 `§5.4.9` 進件作業台涵蓋**（狀態機完整）→ **桶 B 9 → 11、桶 C 33 → 31**（合計仍 59）；差異項（照會記錄／製卡送件）**另立 CR**，不另造重複頁）。前版 **1.22**（**桶 C 就緒度重盤（產出修正後清單）**——①**頁數修正**：`§5.1` 原載「14 群 60 頁」與表列不符，逐列實測為 **59 頁**；②**桶 C 修正**：原記 34 頁且清單**仍含已解鎖之 11 頁** → **實餘 33 頁**；③**三桶重算**：桶 A **6**（已全數完成 ✅）／桶 B **9**／桶 C **33** ＝ **合計 59 ✅**；④**逐頁就緒度實測**（掃 `contracts/openapi/*.yaml`）：33 頁**均確認無對應語意端點**；⑤**待裁定**：`/onboarding/review`／`/onboarding/approval` 核心流程**已由 `§5.4.9` 涵蓋**，是否移桶 B 待 BEAM PMO 裁定）。前版 **1.21**（**桶 C 兩頁之來源端點補齊 ＋ 前端實作**——`§5.4.26 批次作業監控`／`§5.4.27 端點與連線管理`。⚠️ **實測揭露**：`§5.4.26` 之四個來源端點**原不存在**（僅有 `POST`，`GET` 回 405／404／404／404）→ 已**先行新增四支 `GET` 列表端點**（`SCS-011／013／015／017 §6.1`）並補宣告 `limit`（**每服務**上限，預設 10／上限 50）；`§5.4.27` 之 `/actuator/gateway/routes` **於本技術棧版本未註冊** → 改由 gateway 自供唯讀端點（`#A-103`）。前端新增 `pages/BatchConsole.tsx`／`pages/EndpointConsole.tsx`，側欄 **24 → 26 頁**）。前版 **1.20**（**§5.4.25 稽核軌跡查詢（`/system/audit`）補建**——桶 C 解鎖；`SCS-001 §7.9`（`CR-025`）規格先行立規、契約重生（79 端點）並實作後，本節補逐鈕定義。**設計三要點**：統一時間軸／`action` 值域正規化／**`actor` 對沖正如實回 `null`（不臆造）**。側欄 **23 → 24 頁**）。前版 **1.19**（**§5.4.24 健康檢查與監控（`/system/health`）補建**——桶 C 解鎖；`SCS-020 §9.8` 之端點規格先行立規、契約重生（78 端點）並實作後，本節補逐鈕定義。**★ 併釐清 `§5.1.2.3` 所載之「本頁定位須先釐清」**：定位為**作業台即時總覽**，**不取代** Prometheus／Grafana 之長期指標與告警。側欄 **22 → 23 頁**）。前版 **1.18**（**§5.4.23 離線授權與代授權（`/auth/stip`）補建**——`CR-022` 於 09-24 裁定 `advices` 採 **(A) 後送**並實作＋真機驗證後，該頁自**桶 C 解鎖**。**規格先行**併補後端：查證發現 `SCS-001 §7.7` 之三職責中「**查詢待補送佇列**」與「**批次手動上送**」**無端點可達**（實作僅有單筆）→ 先立規格（`CR-023`）→ 改 `tools/gen_openapi.py` 重生契約（**77 端點、驗證 0 錯誤**）→ 實作兩端點（`GET /authorizations/standin`／`POST /authorizations/standin/advices`）→ **§5.4.23 逐鈕定義** → 實作頁面（側欄 21 → **22 頁**）。前版 **1.17**（**清單補正：§5.1.2.1 桶 A 之過期殘留**——標題「8 頁」與「額度控管 ⬜」／「資料遷移作業」無標記**皆已過期**（批次五 §5.4.18／批次六 §5.4.20 已完成，見修訂記錄 1.14／1.15），已修正為 **6 頁全數完成 ✅**。**併註**：§5.1.2.3 之 `/auth/stip`（`advices`）原記「語意待裁定，裁定前不造頁」——**`CR-022` 已於 09-24 裁定採 (A) 並實作＋真機驗證 → 該頁解鎖**，逐鈕定義待補（§5.4.23））。前版 **1.16**（**批次八：§5.4.21 授權策略檢核／§5.4.22 沖正機制**——`CR-021` 補實作後端點已備，兩頁自桶 C 解鎖並實作（側欄 21 頁）；桶 C 35 → 33、可交付終點 18 → **20 頁**。⚠️ **版本欄於批次五／六漏了同步**（修訂記錄已有 1.14／1.15 而版本欄停在 1.13），本版逕升至 1.16）。前版 **1.13**（**`CR-020` 四項缺陷修正後之 §5.4.16 更新**——三要素**改為提供**（後端已確實驗證）／冪等**可宣稱**／查無卡片回 **404**／`status` 依 `SDD-005 §2.4` 映射同步；★ 併更正本節「不提供三要素」之**過時記載**）。前版 **1.12**（**`C-14` 批次四（2 頁）：卡片生命週期管理／虛擬卡與 Token 管理**——§5.4.16／§5.4.17 逐鈕定義＋實作＋真機實測；**桶 A 進度 4／11**；⚠️ 動工前查證以真機實測攔下**四項缺陷** → **`CR-020`**〔三要素未接收／標頭未綁定／查無卡片回 409／`status` 未同步〕，按鈕定義已據實調整）。前版 **1.11**（**`C-14` 批次三（2 頁）：產品與費率設定／參數設定**——`§5.4.14`／`§5.4.15` 逐鈕定義＋實作＋真機實測；**桶 A 進度 2／11**；併補 **1.10 之版本欄與修訂記錄未同步**〔§5.4 引言已引用 v1.11 而 1.11 列不存在〕）。前版 **1.10**（**§5.1.2 剩餘頁面之後端就緒度盤點**——48 頁中**可實作 11／重複 8／無端點 31**；★ 修正 `C-14` 剩餘工作量之認知） | | 狀態 | 已核定 | | 撰寫者 | SD / UX | | 審查者 | SA / TL / SEC | | 對應需求 | B.2 Front-end System / UI-UX / 支援多國語系 / Presentation Layer；SYS-4 | > **本版差異（1.3，2026-09-20）**：新增 **§5.4.9 進件作業台**（`/card-applications`）逐鈕定義 > ——依 BEAM PMO「WebUI 亦須規格先行」之要求，**前端尚未實作**，先立規格； > 對齊 `SCS-024`（後端已實作完成並測試通過）與 `SDD-005 §12` 申請案件狀態機。 > ⚠️ 特別定義「送徵信」之結果可能為 `REFER`（維持 `REVIEWING`、轉人工核決）—— > 畫面**不得**顯示為核准（fail-closed，見 `SCS-025 §6.4`）。 > > **本版差異（1.4，2026-09-20）**：§5.4.9 進件作業台**由「規格先行」轉為已實作** > （先立規格 → 再寫頁面 → 端到端實測，〔BEAM PMO「WebUI 亦須規格先行」〕之完整落地）。 > > **1.2（2026-09-19）**：配合 **`CR-003`** 補述三處「維度不得混用」之前端規則 > （§5.4.5 帳單／§5.4.6 繳款／§5.4.7 紅利點數）——狀態徽章不得跨維度共用對照表。 --- ## 1. 說明與依據 本規範依**客戶認可之操作介面**（`bank-core-react-standalone 1.html`， 「銀行核心系統 — 發卡營運管理平台」）訂定，作為 WebUI 實作之唯一視覺與互動依據。 > **重要**：參考檔案為**介面原型**，其資料為示意。 > 本專案實作**不得**沿用其資料產生方式；所有資料一律來自後端 API > （見 `GOV-003 §6.2` 反模式禁令）。 --- ## 2. 技術棧 | 項目 | 選型 | 版本 | |---|---|---| | 框架 | React | 18 | | 建置 | Vite | 5 | | 語言 | TypeScript | 5（strict） | | 路由 | React Router | 6 | | 狀態 | TanStack Query（伺服器狀態） | 5 | | 表單 | React Hook Form + Zod | 7 / 3 | | 圖表 | 自繪 SVG／輕量圖表元件 | — | | 測試 | Vitest + Testing Library | 2 | | 樣式 | CSS 變數 + CSS Modules | — | > **不使用**重量級 UI 框架：本專案之設計語彙已由客戶認可之原型定義， > 直接以 CSS 變數實作可確保視覺一致且無框架耦合。 --- ## 3. 設計 Token ### 3.1 色彩 | Token | 值 | 用途 | |---|---|---| | `--primary` | `#0f3374` | 主色（按鈕、標題、強調） | | `--primary-600` | `#1e40af` | 主色深（hover） | | `--primary-500` | `#2563eb` | 主色亮（focus、連結） | | `--primary-50` | `#eff6ff` | 主色極淺（選取底） | | `--fg` | `#0f172a` | 主文字 | | `--fg-muted` | `#64748b` | 次要文字 | | `--border` | `#e2e8f0` | 邊框 | | `--bg` | `#f1f5f9` | 頁面底色 | | `--card` | `#ffffff` | 卡片底色 | | `--sidebar-bg` | `#0a224a` | 側欄底色 | | `--sidebar-fg` | `#cbd5e1` | 側欄文字 | | `--sidebar-active` | `#1e40af` | 側欄選取 | | `--sidebar-hover` | `#0f2e63` | 側欄 hover | | `--success` | `#10b981` | 成功 | | `--warning` | `#f59e0b` | 警告 | | `--danger` | `#ef4444` | 危險 | | `--radius` | `8px` | 圓角 | **語意色使用規則** | 情境 | 色 | 範例 | |---|---|---| | 成功／核准 | `--success` | 授權核准、入帳成功、分期 ACTIVE | | 警告／待處理 | `--warning` | 待複核、補件中、差異待處理 | | 危險／拒絕 | `--danger` | 授權拒絕、逾期、爭議、卡片註銷 | | 中性／進行中 | `--fg-muted` | 處理中、已受理 | > **無障礙**：文字與底色對比須 ≥ 4.5:1（WCAG AA）。狀態**不得僅以顏色區分**， > 須同時有文字標示（色盲友善）。 ### 3.2 字型 | 項目 | 值 | |---|---| | 字型堆疊 | `-apple-system, BlinkMacSystemFont, "Segoe UI", "Microsoft JhengHei", "PingFang TC", sans-serif` | | 基準字級 | `14px` | | 行高 | `1.5` | | 標題 | 20px / 18px / 16px（H1 / H2 / H3），字重 700 | | 數字 | 表格數字使用等寬字型（`font-variant-numeric: tabular-nums`） | ### 3.3 間距與尺寸 | Token | 值 | |---|---| | 間距級距 | 4 / 8 / 12 / 16 / 24 / 32 px | | 側欄寬 | 260px（收合 64px） | | 頁首高 | 56px | | 卡片內距 | 16px | | 表格列高 | 44px | | 輸入框高 | 42px | --- ## 4. 版式結構 ### 4.1 登入頁 ```mermaid flowchart TD L["登入頁（置中卡片 420px）"] --> A["Logo 與系統名稱"] L --> B["帳號輸入"] L --> C["密碼輸入"] L --> D["MFA 驗證碼輸入"] L --> E["登入按鈕"] L --> F["錯誤訊息區"] ``` | 要求 | 說明 | |---|---| | 背景 | 深藍漸層（`--sidebar-bg` → `--primary`） | | 卡片 | 白底、圓角 12px、陰影 | | 驗證 | 連續 5 次失敗鎖定 15 分鐘，顯示剩餘時間 | | 語系切換 | 右上角（`zh-TW` / `en-US`） | ### 4.2 主版式 ```mermaid flowchart LR subgraph Layout["App Layout"] SB["側欄 260px
可收合 64px"] subgraph Main["主區"] HD["頁首 56px
麵包屑＋使用者＋語系"] CT["內容區
查詢列＋資料表＋明細"] end end SB --> Main ``` | 區域 | 內容 | |---|---| | 側欄 | 品牌區、9 大選單群（可展開）、收合鈕 | | 頁首 | 麵包屑、頁面標題、語系切換、使用者選單、登出 | | 內容區 | 頁面標題與說明、查詢條件列、資料表、分頁、明細抽屜 | | 浮水印 | 全頁浮水印（使用者帳號 + 時間），防止截圖外流 | ### 4.3 導覽階層 ``` 第一層（選單群）→ 第二層（功能頁）→ 明細抽屜（Drawer） ``` - 點選側欄第二層項目 → 內容區載入對應頁面。 - 點選資料表任一列 → 右側開啟明細抽屜（不離開頁面）。 - 麵包屑顯示「選單群 / 功能頁 / 明細」三層。 --- ## 5. 頁面清單與權限矩陣 ### 5.1 頁面清單（**14 群 59 頁**） > ⚠️ **2026-09-30 重盤修正（本節頁數）**：原載「**60 頁**」與實際表列**不符**—— > 逐列實測為 **59 頁**（差異 1 頁疑為 `v1.9` 補列時之計數誤差，來源已不可考）。 > **本節以實測 59 頁為權威**；`§5.1.2` 之各桶頁數**已同步重算**（見該節）。 | 群 | 頁面 | 路徑 | 主要服務 | 批次 | |---|---|---|---|:--:| | 儀表板 | 營運總覽 | `/dashboard` | 跨服務聚合 | R1 | | 徵審與進件 | 申請管道整合 | `/onboarding/channel` | card | R1 | | 徵審與進件 | 證件與影像辨識 | `/onboarding/ocr` | card | R2 | | 徵審與進件 | 徵信與聯徵查詢 | `/onboarding/jcic` | card | R2 | | 徵審與進件 | 評分卡與決策引擎 | `/onboarding/scoring` | card | R2 | | 徵審與進件 | 人工審查與照會 | `/onboarding/review` | card | R2 | | 徵審與進件 | 最終核決與製卡送件 | `/onboarding/approval` | card | R2 | | 卡片與帳戶 | 產品與費率設定 | `/card/product` | product | R1 | | 卡片與帳戶 | 卡片生命週期管理 | `/card/lifecycle` | card | R1 | | 卡片與帳戶 | 額度控管 | `/card/limit` | limit | R1 | | 卡片與帳戶 | 虛擬卡與 Token 管理 | `/card/token` | card | R2 | | 卡片與帳戶 | 拼圖與個人化管理 | `/card/personalization` | card | R3 | | 授權與清算 | 線上授權處理 | `/auth/engine` | authorization | R1 | | 授權與清算 | 授權策略檢核 | `/auth/policy` | authorization | R1 | | 授權與清算 | 離線授權與代授權 | `/auth/stip` | authorization | R1 | | 授權與清算 | 清算與請款 | `/auth/clearing` | clearing | R3 | | 授權與清算 | 爭議款處理 | `/auth/dispute` | dispute | R3 | | 風控與反洗錢 | 即時盜刷偵測 | `/risk/fraud` | authorization | R2 | | 風控與反洗錢 | 行動安全驗證 | `/risk/mobile-auth` | party | R2 | | 風控與反洗錢 | 洗錢防制與制裁掃描 | `/risk/aml` | party | R3 | | 風控與反洗錢 | 催收管理 | `/risk/collection` | statement | R2 | | 財務帳務稅務 | 帳務日終處理 | `/finance/batch` | posting | R1 | | 財務帳務稅務 | 帳單生成與發送 | `/finance/bill` | statement | R2 | | 財務帳務稅務 | 銷帳與入帳處理 | `/finance/payment` | payment | R1 | | 財務帳務稅務 | 分期付款管理 | `/finance/installment` | installment | R2 | | 財務帳務稅務 | 總帳會計介接 | `/finance/gl` | clearing | R3 | | 行銷與忠誠度 | 紅利點數管理 | `/marketing/bonus` | rewards | R2 | | 行銷與忠誠度 | 現金回饋與刷卡金 | `/marketing/cashback` | rewards | R2 | | 行銷與忠誠度 | 聯名卡哩程與外幣轉換 | `/marketing/miles` | rewards | R2 | | 行銷與忠誠度 | 活動行銷引擎 | `/marketing/campaign` | rewards | R2 | | **收單與商店** | **商店管理與請款** | **`/merchant/settlements`** | **merchant** | **R3** | | 客服與數位管道 | 客服視窗 | `/service/csr` | party | R1 | | 客服與數位管道 | 語音與文字客服 | `/service/ivr` | notification | R3 | | 客服與數位管道 | 行動銀行 App 介接 | `/service/api` | platform | R2 | | 客服與數位管道 | 申訴與工單管理 | `/service/ticket` | notification | R3 | | 系統管理 | 參數設定 | `/system/parameters` | product | R1 | | 系統管理 | 權限與角色 | `/system/rbac` | platform | R1 | | 系統管理 | 稽核軌跡查詢 | `/system/audit` | platform | R1 | | 系統管理 | 報表作業 | `/system/reports` | report | R2 | | 系統管理 | 批次作業監控 | `/system/batch` | platform | R2 | | 系統管理 | 端點與連線管理 | `/system/endpoints` | platform | R2 | | 系統管理 | 通知樣板管理 | `/system/notification-templates` | notification | R2 | | 系統管理 | 資料遷移作業 | `/system/migration` | migration | R2 | | 系統管理 | 分流比例管理 | `/system/split-ratio` | platform | R1 | | 系統管理 | 健康檢查與監控 | `/system/health` | platform | R1 | | **獨立授權平台** | 預授權與交易取消 | `/switch/auth/pre-auth` | authorization | R2 | | 獨立授權平台 | 沖正機制（Reversal） | `/switch/auth/reversal` | authorization | R2 | | 獨立授權平台 | 交易狀態機與冪等 | `/switch/auth/state` | authorization | R2 | | 獨立授權平台 | 收單端即時風控 | `/switch/auth/risk` | authorization | R2 | | 獨立授權平台 | 清算前置處理 | `/switch/auth/clearing-prep` | authorization | R3 | | **獨立紅利平台** | 商城兌換訂單 | `/loyalty/mall-orders` | rewards | R2 | | 獨立紅利平台 | 會員與等級 | `/loyalty/members` | rewards | R2 | | 獨立紅利平台 | 平台介接與防弊 | `/loyalty/integrations` | rewards | R3 | | **TMS 終端／POS 管理** | 終端生命週期 | `/tms/lifecycle` | —（見註） | R2 | | TMS 終端／POS 管理 | 遠端管理 | `/tms/remote` | —（見註） | R2 | | TMS 終端／POS 管理 | 監控與告警 | `/tms/monitoring` | —（見註） | R2 | | TMS 終端／POS 管理 | 維修管理 | `/tms/repair` | —（見註） | R3 | | **BASE24 SWITCHING 平台** | Switch 核心 | `/switch/core` | —（見註） | R2 | | BASE24 SWITCHING 平台 | 清算檔案處理 | `/switch/file-transfer` | —（見註） | R3 | > **前 4 群之頁面即客戶認可原型之選單結構；後 6 群為本專案依設計文件補充之營運必要頁面。** > **⚠️ 與「客戶認可原型」之對照（2026-09-23 實測，`GOV-006 §4 #13` 之處置）** > > 原記載「前 4 群即客戶認可原型之選單結構」**不精確**——實測客戶原型 > （`ECSplus信用卡核心系統Vue3版.html`）之選單為 **13 大模組**，而本節為 **10 群**，並非同一組結構。 > 逐模組對照如下（原型 L2 數為實測）： > > | 原型模組 | 原型 L2 數 | 本節對應群 | 判定 | > |---|---:|---|---| > | 1 徵審與進件管理 | 7 | 徵審與進件 | ✅ 對應 | > | 2 卡片與帳戶管理 | 6 | 卡片與帳戶 | ✅ 對應 | > | 3 授權與清算 | 6 | 授權與清算 | ✅ 對應 | > | 4 風控與反洗錢 | 5 | 風控與反洗錢 | ✅ 對應 | > | 5 財務、帳務與稅務 | 6 | 財務帳務稅務 | ✅ 對應 | > | 6 行銷與忠誠度回饋 | 5 | 行銷與忠誠度 | ✅ 對應 | > | 7 客服與數位管道 | 6 | 客服與數位管道 | ✅ 對應 | > | 8 系統管理 | 6 | 系統管理 | ✅ 對應 | > | **11 收單作業平台** | **9** | **收單與商店（v1.8 新增）** | ✅ **已補**（原**完全缺席**——`merchant-service` 於 `C-4` 實作完成卻無作業台頁面） | > | **9 獨立授權平台** | **7** | **獨立授權平台（v1.9 新增）** | ✅ **已補列 5 頁**（見 §5.1.1 之 L2 逐項對照） | > | **10 獨立紅利平台** | **5** | **獨立紅利平台（v1.9 新增）** | ✅ **已補列 3 頁**（見 §5.1.1） | > | **12 TMS 終端／POS 管理** | **5** | **TMS 終端／POS 管理（v1.9 新增）** | ✅ **已補列 4 頁**（見 §5.1.1；⚠️ **無對應本專案服務**） | > | **13 BASE24 SWITCHING 平台** | **5** | **BASE24 SWITCHING 平台（v1.9 新增）** | ✅ **已補列 2 頁**（見 §5.1.1；⚠️ 核心為 ACI 產品） | > > **⚠️ 補列之範圍界定（務必先讀）**——**補列 ≠ 全部都要本專案實作**： > > | 模組 | 主要服務 | 實作歸屬 | > |---|---|---| > | 9 獨立授權平台 | `authorization`（8081） | **本專案**——既有 `authorization-service` 即此平台；多數 L3 已有後端，缺者為頁面 | > | 10 獨立紅利平台 | `rewards`（8091） | **本專案**（同上） | > | 12 TMS 終端／POS 管理 | **—** | ⚠️ **無對應本專案服務**——終端／POS 管理屬**收單端設備管理**，本案 17 服務**不含** TMS。頁面補列以維持原型追溯完整，惟**實作需先確認 SoW 是否納入**（`GOV-006 §4 #15` 之待確認項） | > | 13 BASE24 SWITCHING 平台 | **—** | ⚠️ 核心（Switch／ISO 8583 電文／連線容錯）為 **ACI BASE24 產品**，非本專案開發範圍；「清算檔案處理」部分可由 `clearing` 承接。同上，**實作需先確認 SoW** | > > **故本節頁數之語意**：**59 頁＝原型可追溯之完整清單**；其中**前 10 群 45 頁**為**本案交付範圍**， > **新增 4 群 14 頁**中，**模組 9／10 之 8 頁**屬本專案（服務已存在）、 > **模組 12／13 之 6 頁實作歸屬待確認**。 > **不將「已補列」誤讀為「已承諾實作」**——此為誠實揭露之要求。 > > **併更正原記載**：原版載「前 4 群之頁面即客戶認可原型之選單結構」**不精確**（原型 13 模組 vs 本節群數）； > 且原版將模組 9／10／12／13 標為「**待裁定**」並註「勿誤讀為已覆蓋」—— > 經 BEAM PMO **2026-09-23 裁定「請補列」**，本版已補列並改為**逐 L2 對照**（見 §5.1.1），不再停留於「待裁定」。 > > #### 5.1.1 模組 9／10／12／13 之 L2 ↔ 頁面逐項對照（補列依據） > > | 模組 | L2 | 判定 | 對應頁面 | > |---|---|---|---| > | 9 | 授權交易處理（報文組拆／**預授權**／預授權完成／**增量預授權**／**查餘額**／**線上退貨**／**交易取消**） | 部分重疊（報文組拆已由「線上授權處理」涵蓋）；**預授權系列／查餘額／退貨／取消為新增** | `/switch/auth/pre-auth`（＋既有 `/auth/engine`） | > | 9 | 沖正 Reversal 機制（超時自動／POS 手動／失敗重試佇列／狀態追蹤） | **新增**——既有「入帳作業台」之沖正為**帳務**沖正，此為**授權**沖正 | `/switch/auth/reversal` | > | 9 | 交易狀態機管理（生命週期狀態機／**冪等性檢核 STAN+MID+TID**／交易副本快取） | **新增** | `/switch/auth/state` | > | 9 | 收單端即時風控（MID 狀態／單筆門檻／滾動累計／黑名單／卡網路規則／即時告警） | **新增**——既有「即時盜刷偵測」為**發卡端** | `/switch/auth/risk` | > | 9 | Stand-in 獨立授權（開關門檻／超時代行／待補送佇列／補送結果） | **重疊** → 已由「離線授權與代授權（STIP）」涵蓋 | （既有 `/auth/stip`） | > | 9 | 清算前置處理（交換分類標籤／手續費基礎／NCCC 交換紀錄／B2B 採購卡） | **新增** | `/switch/auth/clearing-prep` | > | 10 | 點數帳務核心（登錄／餘額／到期） | **重疊** → 已由「紅利點數管理」涵蓋 | （既有 `/marketing/bonus`） | > | 10 | 點數兌轉中心（哩程兌轉／現金回饋／**商品商城兌換訂單**） | 部分重疊（哩程／現金回饋已有）；**商城訂單為新增** | `/loyalty/mall-orders`（＋既有 `/marketing/miles`、`/marketing/cashback`） | > | 10 | 會員與等級（等級維護／升級保級規則／權益設定） | **新增** | `/loyalty/members` | > | 10 | 平台介接（核心點數介接／第三方平台交換／防弊風控規則） | **新增** | `/loyalty/integrations` | > | 12 | 終端生命週期（入庫註冊／派發裝機／回收報廢） | **新增**（⚠️ 無本專案服務） | `/tms/lifecycle` | > | 12 | 遠端管理（韌體升級／遠端安裝／遠端鎖定復原） | **新增**（⚠️ 同上） | `/tms/remote` | > | 12 | 監控與告警（線上狀態／離線告警／防拆告警） | **新增**（⚠️ 同上；既有「健康檢查與監控」為**系統**監控） | `/tms/monitoring` | > | 12 | 維修管理（工單／巡檢排程／備品） | **新增**（⚠️ 同上） | `/tms/repair` | > | 13 | Switch 核心（可用性／交易路由／TPS 與負載） | **新增**（⚠️ ACI 產品） | `/switch/core` | > | 13 | 網路連線管理（拓樸／主機連線／容錯切換） | **重疊** → 已由「端點與連線管理」涵蓋 | （既有 `/system/endpoints`） | > | 13 | 電文處理（ISO 8583 解析／電文重送沖正／STIP） | **重疊** → 已由「線上授權處理」「離線授權與代授權」涵蓋 | （既有 `/auth/engine`、`/auth/stip`） | > | 13 | 清算檔案處理（檔案產製／傳送 FTP·SFTP／檔案對帳） | **新增** | `/switch/file-transfer`（部分可由 `clearing` 承接） | ### 5.2 頁面權限矩陣 `✅` 可存取　`⚠️` 需覆核或欄位受限　`❌` 不可存取 | 群 | CSR | CSR_SUP | CREDIT | CREDIT_MGR | OPS | RISK | FIN | AUDIT | ADMIN | |---|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:| | 儀表板 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | 徵審與進件 | ⚠️ | ✅ | ✅ | ✅ | ❌ | ⚠️ | ❌ | ✅ | ❌ | | 卡片與帳戶 | ⚠️ | ✅ | ⚠️ | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ | | 授權與清算 | ⚠️ | ⚠️ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ⚠️ | | 風控與反洗錢 | ❌ | ⚠️ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | | 財務帳務稅務 | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ⚠️ | | 行銷與忠誠度 | ⚠️ | ✅ | ❌ | ❌ | ⚠️ | ❌ | ❌ | ✅ | ✅ | | 客服與數位管道 | ✅ | ✅ | ❌ | ❌ | ⚠️ | ❌ | ❌ | ✅ | ⚠️ | | 系統管理 | ❌ | ❌ | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ | ✅ | ✅ | ### 5.3 敏感欄位顯示 | 欄位 | CSR | CSR_SUP | 其他角色 | 說明 | |---|---|---|---|---| | 完整卡號 | ❌ | ⚠️（需理由） | ❌ | 一律遮罩 `411111****1234` | | 身分證字號 | ❌ | ❌ | ❌ | 一律遮罩 `A12345****` | | 手機號碼 | ⚠️ | ✅ | ⚠️ | 遮罩 `0912***567` | | 電子郵件 | ⚠️ | ✅ | ⚠️ | 遮罩 `abc***@mail.com` | | CVV2 | ❌ | ❌ | ❌ | **不顯示、不儲存** | > 顯示完整卡號須**填寫理由**並寫入稽核軌跡（`SAD-005 §6.3`）。 --- ## 5.4 頁面操作與按鈕定義（2026-09-19 補建） > **緣由**：BEAM PMO 指出「沒有定義按鈕的功能」——經查本文件原僅有元件規範， > 未逐鈕定義「做什麼、打哪支 API、權限是誰、成功／失敗如何回饋。本節已補足 **17 頁**（§5.4.1～§5.4.17）。 > ⚠️ **2026-10-01 更新（v1.27）**：本節經 `C-14` 批次一～八與桶 C 逐頁解鎖，**已擴充至 §5.4.31**（缺 §5.4.19，已撤銷） > ＝ **30 頁**，與 `App.tsx` 之頁數**一一對應** > （含**超出 `§5.1` 清單之 2 頁**：`/limit-adjustments`（§5.4.2）與 **`/accounts`（§5.4.31）**）。 > 其中 §5.4.1～§5.4.8 為**已實作**頁面之定義； > §5.4.9 進件作業台曾為「規格先行」（BEAM PMO 2026-09-20 要求）， > **已於 v1.4 依該節定義實作完成**； > §5.4.10～§5.4.12（清算與請款／爭議款處理／報表作業）於 **v1.8（`C-14` 批次一）** 補建， > 同樣**先立規格再實作**； > §5.4.14～§5.4.15（產品與費率設定／參數設定）於 **v1.11（`C-14` 批次三）** 補建， > 係依 **§5.1.2 就緒度盤點** 之**桶 A** 優先實作； > §5.4.16～§5.4.17（卡片生命週期管理／虛擬卡與 Token 管理）於 **v1.12（`C-14` 批次四）** 補建， > ⚠️ 該兩頁之動工前查證以**真機實測**攔下**四項缺陷** → **`CR-020`**（F1 三要素未接收／ > F2 標頭未綁定／F3 查無卡片回 409／F4 `status` 未同步）→ 按鈕定義**已據實調整** > （**不提供** `threeFactors` 輸入、**如實**顯示錯誤碼與兩維度）； > §5.4.13（商店管理與請款）於 **v1.9（`C-14` 批次二）** 補建——本頁係因 > **`GOV-006 §4 #13`** 之追溯缺口（`merchant-service` 已實作卻無頁面）而補列。 > 其餘頁面於開發時依此格式增補。格式：按鈕 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 ### 5.4.1　授權作業台（`/authorizations`） | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **送出授權** | 送出取授權請求 | `POST /api/v1/authorizations` | 卡號 12~19 碼數字；金額 ≥ 1；MCC 4 碼；幣別 3 碼大寫 | `CSR` | 顯示決策徽章（核准／拒絕）＋ 6 項檢核明細；清單自動更新 | 顯示錯誤封套之 `code + message` | | **重新整理清單** | 重新載入最近授權 | `GET /api/v1/authorizations?limit` | — | `CSR` | 表格更新 | 錯誤盒顯示 | | **點選任一列** | 開啟明細抽屜 | `GET /api/v1/authorizations/{authNo}` | — | `CSR` | 右側抽屜顯示完整檢核結果 | 抽屜內顯示錯誤 | | **關閉** | 關閉明細抽屜 | — | — | `CSR` | 抽屜關閉 | — | **欄位說明**：卡號下拉選單固定 3 張測試卡（4111…1111 正常／4222…2222 小額度／4333…3333 已鎖卡）。 ### 5.4.2　額度調整申請（`/limit-adjustments`） | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **送出申請** | 提出額度調整 | `POST /limit-api/v1/limit-adjustments` | 帳戶必填；目標金額 ≥ 0；原因必填；申請人必填；臨時額度時起訖日必填 | `CSR` | 顯示單號與狀態（直接生效／待覆核） | 錯誤 `code + message`（如 `CC-LIM-1001`） | | **覆核通過** | 核准待覆核申請 | `POST /limit-api/v1/limit-adjustments/{id}/approval`（`APPROVE`） | 單號必填；覆核人必填 | `CSR_SUP` | 狀態轉 `EFFECTIVE` | `CC-LIM-3001/3002`（非法／終態） | | **覆核駁回** | 駁回申請 | `POST .../{id}/approval`（`REJECT`） | 同上 | `CSR_SUP` | 狀態轉 `REJECTED` | 同上 | | **撤銷** | 撤銷已生效調整（回復額度） | `POST /limit-api/v1/limit-adjustments/{id}/revocation` | 單號必填；覆核人必填；原因必填 | `CSR_SUP` | 狀態 `REVOKED`，主檔回復至調整前金額 | | **查詢** | 查詢申請單 | `GET /limit-api/v1/limit-adjustments/{id}` | 單號必填 | `CSR` | 顯示單號／狀態／調整前後金額 | 錯誤盒 | | — | — | — | — | — | — | — | **前端代理**：開發期 `/limit-api` 由 Vite 代理至 `limit-service:8083`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 ### 5.4.3　持卡人／歸戶查詢（`/parties`） | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢持卡人** | 依識別碼查持卡人主檔 | `GET /party-api/v1/parties/{partyId}` | 識別碼須為 UUID | `CSR` | 顯示持卡人主檔（PII 遮罩）＋ flags | `CC-PTY-4040`（404 查無）／`CC-PTY-4001`（400 格式錯） | | **查詢歸戶** | 依識別碼查歸戶含 `parties[]` | `GET /party-api/v1/accounts/{accountId}` | 識別碼須為 UUID | `CSR` | 顯示歸戶主檔＋持卡人清單 | 同上 | | **設定貼標** | 寫入／更新單一貼標 | `POST /party-api/v1/parties/{partyId}/flags` | `flagCode` ≤32、`flagValue` ≤64、`reason` ≤200；`X-Channel`、`X-Idempotency-Key` 必帶 | `CSR` | **201** 首次／**200** 重播；flags 即時更新 | `CC-PTY-2001`（409 冪等衝突）／`CC-PTY-4001` | | **設定管制碼** | 設定／解除歸戶管制碼 | `POST /party-api/v1/accounts/{accountId}/block-codes` | `blockCode` 須屬列舉值；`reason` 必填；兩 header 必帶 | `CSR_SUP` | **201**；狀態更新並寫入稽核歷程 | `CC-PTY-1001`（422 管制中不得再設）／`CC-PTY-2001` | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單重置 | — | **說明**： - **PII 一律顯示遮罩值**（`idNoMasked`／`mobileMasked`／`emailMasked`）； 前端**不得**自行解密，遮罩由後端於回傳前完成（{@code SAD-005 §5}、{@code SCS-004 §5}）。 - 貼標採「整包覆寫」語意（更新單鍵、其餘保留），POC-10 市區停車之身分參數即以此管理。 - 管制碼設定為 `CSR_SUP` 權限（涉及交易限制），貼標與查詢為 `CSR`。 - **前端代理**：開發期 `/party-api` 由 Vite 代理至 `party-service:8084`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 ### 5.4.4　入帳作業台（`/postings`） | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **送出入帳** | 交易入帳並更新分戶餘額 | `POST /posting-api/v1/postings` | 歸戶必填（UUID）；`txCode` ≤16；`txType` 屬 11 種列舉；`amount` ≥1（最小單位）；`currency` 3 碼大寫；`postingDate` 為 `YYYY-MM-DD`；`businessIdempotencyKey` ≤120 且為防重依據；`X-Channel`、`X-Idempotency-Key` 必帶 | `CSR` | **201**：顯示交易編號（連號）、分錄（子帳／變動量／前後餘額）與入帳後餘額 | `CC-POST-4001`（409 重複入帳）／`CC-POST-4000`（400 格式錯） | | **查詢入帳明細** | 查詢單筆入帳與分錄 | `GET /posting-api/v1/postings/{postingId}` | 識別碼須為 UUID | `CSR` | 顯示交易與分錄明細 | `CC-POST-4040`（404 查無） | | **錯帳沖正** | 成對產生反向交易 | `POST /posting-api/v1/postings/{postingId}/reversals` | `reason` 必填 ≤200；兩 header 必帶；原交易須為 `POSTED` | `CSR_SUP` | **201**：顯示反向交易編號，原交易轉 `REVERSED`，餘額回沖 | `CC-POST-3001`（409 已 REVERSED 不得再沖正） | | **查詢餘額** | 查詢分戶餘額 | `GET /posting-api/v1/accounts/{accountId}/balances` | 識別碼須為 UUID | `CSR` | 顯示本金／利息／費用／稅／總額與不變式檢核結果 | `CC-POST-4040` | | **查詢交易明細** | 分頁查詢交易 | `GET /posting-api/v1/accounts/{accountId}/transactions?page&size` | 識別碼須為 UUID；`size` ≤200 | `CSR` | 表格列出交易編號／類型／金額／入帳日／狀態 | 錯誤盒 | | **重複偵測** | 整批重複請款偵測 | `POST /posting-api/v1/posting-duplicate-checks` | 同入帳之欄位檢核；`X-Channel` 必帶 | `CSR` | **200** 且 `data` 為 null（未發現重複） | `CC-POST-4002`（409 疑似重複，轉人工判定） | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單重置 | — | **說明**： - 金額一律以**最小單位（分）**輸入與顯示，前端僅做「分 → 元」之呈现換算， **不做**浮點運算（{@code CSP-001 DP-03}）。 - 餘額區須顯示**不變式檢核**（本金＋利息＋費用＋稅 ＝ 總額）， 讓操作人員可即時驗證帳務正確性（{@code SCS-007 §7}）。 - 沖正為 `CSR_SUP` 權限（涉及帳務異動）；其餘為 `CSR`。 - **前端代理**：開發期 `/posting-api` 由 Vite 代理至 `posting-service:8087`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 ### 5.4.5　帳單作業台（`/statements`） | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **執行帳單批次** | 依週期執行結帳，產生帳單 | `POST /statement-api/v1/statement-cycles/{cycleCode}/runs` | 週期代碼須為 `M01`～`M31`；`businessDate` 為 `YYYY-MM-DD`；`X-Channel` 必帶 | `CSR_SUP` | **201**：顯示 runId、狀態、已處理／已產生筆數與 Checkpoint | `CC-STM-1001`（422 週期不存在）／`CC-STM-5001`（503 已有執行中批次） | | **查詢批次狀態** | 查詢執行結果與 Checkpoint | `GET /statement-api/v1/statement-runs/{runId}` | runId 須為 UUID | `CSR` | 顯示狀態／筆數／Checkpoint／起訖時間／錯誤原因 | `CC-STM-4040`（404 查無） | | **查詢帳單** | 分頁查詢歸戶之帳單 | `GET /statement-api/v1/accounts/{accountId}/statements?page&size` | 歸戶識別碼須為 UUID；`size` ≤200 | `CSR` | 表格列出帳單號／帳單月份／結帳日／繳款截止／總額／最低應繳／狀態（**明細為空，由單筆查詢取得**） | 錯誤盒 | | **點選任一列** | 展開該期帳單明細抽屜 | `GET /statement-api/v1/statements/{statementId}` | 帳單識別碼須為 UUID | `CSR` | 右側抽屜顯示帳單摘要＋明細項目（#／入帳日／交易編號／說明／類型／金額） | 抽屜內顯示錯誤 | | **關閉** | 關閉明細抽屜 | — | — | `CSR` | 抽屜關閉 | — | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單重置 | — | **說明**： - 金額以最小單位（分）呈現，前端僅做「分 → 元」換算，**不做浮點運算**。 - 「執行帳單批次」為 `CSR_SUP` 權限（涉及帳務產製）；查詢為 `CSR`。 - 同月份重複執行為**冪等**：已產生者跳過（產生筆數為 0），不重複產製。 - **兩個狀態維度不得混用同一欄（`CR-003` 後）**： - **批次執行**（`statement-runs`，`SDD-005 §9.2`）：`GENERATING`／`GENERATED`／`FAILED` ——「查詢批次狀態」之結果欄。 - **帳單本體**（`statements`，`SDD-005 §9.1`）：`GENERATED`／`SENT`／`PAID`／ `PARTIALLY_PAID`／`OVERDUE`／`DISPUTED`／`CLOSED`——帳單列表之狀態欄。 - 兩者皆有 `GENERATED` 但**語意不同**（前者為「批次跑完」、後者為「帳單已產製」）， 徽章文案須區分，不得共用同一標籤對照表。 - **前端代理**：開發期 `/statement-api` 由 Vite 代理至 `statement-service:8092`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 ### 5.4.6　繳款作業台（`/payments`） | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **繳款受理** | 受理繳款並分配入帳 | `POST /payment-api/v1/payments` | 歸戶必填（UUID）；`amount` ≥1（最小單位）；`currency` 3 碼大寫；`paymentMethod` 屬 6 種列舉；`paymentDate` 為 `YYYY-MM-DD`；`X-Channel`、`X-Idempotency-Key` 必帶 | `CSR` | **201**：顯示繳款單號、狀態與分配明細（稅→費→息→本金） | `CC-PAY-4000`（400 格式錯／分配不平衡） | | **查詢繳款** | 查詢單筆繳款與分配 | `GET /payment-api/v1/payments/{paymentId}` | 識別碼須為 UUID | `CSR` | 顯示繳款與分配明細 | `CC-PAY-4040`（404 查無） | | **繳款沖正** | 沖正已入帳之繳款 | `POST /payment-api/v1/payments/{paymentId}/reversals` | 識別碼須為 UUID；兩 header 必帶；原繳款須為 `POSTED` | `CSR_SUP` | **201**：狀態轉 `REVERSED`，額度回復標記取消 | `CC-PAY-3001`（409 已 REVERSED 不得再沖正） | | **自扣設定** | 新增約定扣款 | `POST /payment-api/v1/auto-debit-enrollments` | 歸戶必填；`debitBank` ≤8；`debitAccount` ≤20；`effectiveFrom` 為 `YYYY-MM-DD`；`X-Channel` 必帶 | `CSR` | **201**：顯示約定編號、銀行與**遮蔽後帳號** | `CC-PAY-4000` | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單重置 | — | **說明**： - 分配順序固定為**稅 → 費用 → 利息 → 本金**；金額為 0 之子帳不出現在分配明細。 - 繳款後之可用額度（`availableLimitAfter`）本期顯示為「—」： 額度回復依 `SCS-008 §8` 採**事件非同步**，受理時不即時查詢。 - 自扣帳號一律顯示**遮蔽值**（僅留後 4 碼），前端與介面皆不得呈現明文。 - 沖正為 `CSR_SUP` 權限；其餘為 `CSR`。 - **繳款狀態值域（`CR-003` 後）**：`RECEIVED`／`ALLOCATED`／`POSTED`／`REVERSED`／`FAILED`／ `UNMATCHED`——對齊 `SDD-001 §3.7` DDL CHECK 與 `SDD-005 §5` 狀態機。 `UNMATCHED` 徽章文案為「未收銷帳檔」，**不得**與 `unmatchedFlag`（「未取得沖抵來源」） 混用同一文案——二者為**正交維度**，可同時成立。 - **前端代理**：開發期 `/payment-api` 由 Vite 代理至 `payment-service:8088`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 --- ### 5.4.7　紅利點數作業台（`/rewards`） | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢點數帳戶** | 查詢三層點數餘額 | `GET /rewards-api/v1/rewards/accounts/{accountId}` | 歸戶必填（UUID） | `CSR` | 顯示 **CUR／AV1／AV2** 三層餘額、各層最近到期日與總點數 | `CC-RWD-4040`（404 查無點數帳戶） | | **點數入點** | 依消費金額換算並累積點數 | `POST /rewards-api/v1/rewards/accruals` | 歸戶必填（UUID）；`amount` ≥1（最小單位）；`txTime` 為 ISO-8601 含時區；`isRefund` 選填；`X-Channel`、`X-Idempotency-Key` 必帶 | `CSR` | **201**：顯示分錄編號、**點數**與餘額 **before → after**、到期日 | `CC-RWD-4000`（400 格式錯／缺必填）／`CC-RWD-4040`（404 退款但查無帳戶）／`CC-RWD-3002`（409 帳戶已 `CLOSED`） | | **點數兌換** | 扣抵點數兌換標的（**標的類別 × 折抵方式**雙維度，`CR-012`） | `POST /rewards-api/v1/rewards/redemptions` | 歸戶必填（UUID）；`pointsUsed` ≥1；**`redemptionType`（兌換標的類別）屬 6 種列舉**；**`settlementMethod`（折抵方式）屬 5 種列舉或省略**（省略→後端補預設 `POINTS_ONLY`，與主檔 DEFAULT 同值）；`insufficientPolicy` 本期僅 `REJECT`；兩 header 必帶 | `CSR` | **201**：顯示兌換單號、**`標的類別／折抵方式`**、狀態、**現金價值**（`CR-013`）與**可兌換點數 before → after**，並**自動重查三層餘額**（供使用者看出點數自哪一層扣除） | `CC-RWD-1001`（422 點數不足）／`CC-RWD-1003`（422 帳戶凍結）／`CC-RWD-4040`（404）／`CC-RWD-4000`（400 **未知折抵方式**，不靜默降級） | | **設定回饋規則** | 新增回饋規則定義 | `POST /rewards-api/v1/reward-rules` | `ruleCode` ≤40 必填；`ruleType` 屬 5 種列舉；`status` 屬 3 種列舉；`condition`／`action` 須為 **JSON 物件**（非陣列或純量）；`effectiveFrom` 為 `YYYY-MM-DD`；`X-Channel` 必帶 | `CSR_SUP` | **201**：顯示規則代碼、類型、狀態與生效區間 | `CC-RWD-1005`（422 規則代碼重複）／`CC-RWD-4000`（400） | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單與結果區重置 | — | **說明**： - **三層點數語意**（`BRD-001 BR-07-03`、客戶 FR 13.1）——畫面**必須**以業務語意呈現， 不得直接顯示儲存欄位名（`balance`／`pending_balance`／`confirmed_balance`）： | 層 | 業務語意 | 可否兌換 | |---|---|---| | `CUR` | 可用點數 | ✅ | | `AV1` | 到期點數（寬限期內） | ✅ | | `AV2` | 凍結點數 | ❌ **不得呈現為可兌換** | - **兌換雙維度（`CR-012`，1.6）**：`redemptionType`＝**兌換標的類別**（換什麼：`CASH`／`CATEGORY`／`GOODS`／`MILEAGE`／`FEE_WAIVER`／`DONATION`）與 `settlementMethod`＝**折抵方式**（怎麼付：`POINTS_ONLY`／`POINTS_PLUS_CASH`／`ONLINE_REDEEM`／`MERGE`／`EXCHANGE_CENTER`）為**正交維度**—— 「用點數＋現金換哩程」＝ 標的 `MILEAGE` ＋ 折抵 `POINTS_PLUS_CASH`，單一欄位無法同時表達。 畫面以**兩個下拉分列**（標籤明示「換什麼」／「怎麼付」），**不得合併為單一欄位**； 未知折抵方式後端回 `CC-RWD-4000`，前端如實呈現錯誤、不靜默降級。 結果區顯示 `標的類別／折抵方式` 供單據自證（契約 `RedemptionView` 已回傳兩欄）。 - **兌換為「先到期先用」**（`BRD-004 POC 2-12`）：點數依到期日由早到晚扣抵，且**跨 CUR／AV1**。 因契約 `RedemptionView` **未回傳**實際扣抵之階段（見 `SCS-010 §10`）， 畫面於兌換成功後**自動重查三層餘額**，讓使用者由各層餘額變化看出點數自哪一層扣除—— **不**在畫面上臆測或推導扣抵階段（推導結果若與後端不符，即為兩套真相）。 - 入點分錄初始為 `PENDING`（待爭議期後確認）；畫面顯示狀態以符實。 - **凍結（`FROZEN`）帳戶仍可入點**（消費為客戶既有權益），僅**兌換**被擋； `CLOSED` 帳戶連入點都擋。此分工已於 `CR-003` **封存**為 `SDD-005 §10.3`「各狀態之操作權限」表（原為 `SCS-010 §10.6` 之規格空白）， 畫面不得自行加設「凍結即不可入點」之客戶端限制（會與後端不一致）。 - **三個維度不得混用同一欄（`CR-003` 後）**——`SDD-005 §10` 已依維度拆分： - **桶階段**（`§10.1`）：`CUR`／`AV1`／`AV2`——三層餘額之**分欄**。 - **桶狀態**（`§10.2`）：`ACTIVE`／`EXPIRED`／`REDEEMED`——單一到期桶之狀態。 - **帳戶狀態**（`§10.3`）：`ACTIVE`／`FROZEN`／`CLOSED`——帳戶層級徽章。 - 三者在畫面屬**不同層級**（帳戶徽章／階段分欄／桶列），不得繪為同一狀態流程。 - **兌換現金價值（`CR-013`，1.7）**：`cashValue`（分）＝ `pointsUsed × POINTS_TIERS.REDEEM_RATE` （每 1 點可折抵之現金（元），依帳戶層級），四捨五入至分——**由後端依權威參數計算**， 請求端不得宣稱（`RedeemRequest` 無此欄位）。畫面於兌換結果區顯示「現金價值」（以元呈現）。 折算率缺漏時後端記 0、兌換照常（fail-soft），畫面如實顯示 0。 - 規則設定僅**維護定義**、不執行；畫面不得暗示規則已生效於交易。 - 兌換與規則設定為 `CSR_SUP` 以上權限；查詢與入點為 `CSR`。 - **前端代理**：開發期 `/rewards-api` 由 Vite 代理至 `rewards-service:8091`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 --- ### 5.4.8　分期作業台（`/installments`） | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **建立分期** | 成立分期計畫並產生攤還表 | `POST /installment-api/v1/installments` | 歸戶與卡片必填（UUID）；**`channelType` 屬 7 種列舉**（必填）；**`businessType` 屬 3 種列舉或省略**（省略→寫入 NULL＝「未記錄」）；`originalAmount` ≥1（最小單位）；`periodCount` **僅 3／6／12／24**；`agreementSigned` 須為 `true`；`X-Channel`、`X-Idempotency-Key` 必帶 | `CSR` | **201**：顯示分期編號、狀態、**來源通路**、**業務型態**、每期金額、總手續費與**攤還表**（期別／本金／手續費／到期日／剩餘本金） | `CC-INS-1001`（422 期數不支援）／`CC-INS-1002`（422 總約未簽署）／`CC-INS-4000`（400 格式錯、**未定義之通路或業務型態**） | | **查詢分期** | 查詢單筆計畫與期數 | `GET /installment-api/v1/installments/{planId}` | 識別碼須為 UUID | `CSR` | 顯示計畫摘要（含**來源通路**與**業務型態**）與攤還表 | `CC-INS-4040`（404 查無分期計畫） | | **提前結清／違約** | 結清剩餘本金或轉催收 | `POST /installment-api/v1/installments/{planId}/settlements` | 識別碼須為 UUID；`settlementType` **僅 `EARLY`／`DEFAULT`**（未定義值一律拒絕）；`reason` ≤200；計畫狀態須為 `ACTIVE`；兩 header 必帶 | `CSR_SUP` | **201**：狀態轉 **`PRE_CLOSED`**（EARLY）或 **`DEFAULTED`**（DEFAULT）；剩餘期數與剩餘本金歸零 | `CC-INS-3001`（409 非 `ACTIVE` 不得結清）／`CC-INS-4000`（400 未定義之結清類型）／`CC-INS-4040`（404） | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單與結果區重置 | — | **說明**： - **攤還試算**：每期本金＝`originalAmount ÷ periodCount`（整數除），**尾差由末期吸收** （如 100,000 ÷ 3 → 33,333／33,333／**33,334**），確保各期本金加總恰等於原始金額； 手續費依費率計算後平均分攤，尾差同樣由末期吸收。 手續費率本期為**固定值**（`SCS-009 §10`：待 `pricing-service` 費率引擎就緒後參數化）。 - **期數僅 3／6／12／24**：以**契約列舉**為準，非 DDL 之 `BETWEEN 1 AND 60`。 兩者為**約束層級差異**（非值域衝突），已記於 `SCS-009 §10.3`。 - **雙軸分類（CR-008，2026-09-20 BEAM PMO 核定）**——原「分期類型」單欄已拆分為兩欄： - **`channelType` 來源通路**（誰提供）：下拉 **7 值** `MERCHANT`／`BANK`／`REVOLVING`／`BILL`／`ACQUIRER`／`NCCC`／`QRCODE`，**必填**。 原欄名 `installmentType` 字面為「分期類型」但實為通路軸，致呼叫端填入業務型態值 而 100% 被拒（`CR-002`），故改名以消除誤讀（`CR-008 §7.1`）。 - **`businessType` 業務型態**（怎麼發起）：下拉 **3 值** `SINGLE`（單筆消費分期）／`RECURRING`（約定分期）／`STATEMENT`（帳單分期）， **選填**；另有「**（不指定 → 記錄為「未記錄」）**」選項。 - ⚠️ **`businessType` 為 `null` 時畫面必須顯示「未記錄」**（灰色標記）， **不得**顯示成 `SINGLE` 或任何預設型態——「未記錄」與「單筆分期」是**不同事實** （既有資料於拆分前未曾記錄此維度，見 `CR-008 §7 ③`）。 - ⚠️ 本期**未**（亦不應）於畫面提供「以業務型態篩選」之功能——`business_type` 有空值， 未定義空值之篩選語意；若日後需要提供，須先與業務確認「未記錄」如何呈現。 - **`status` 顯示值**：`ACTIVE`／`COMPLETED`／`PRE_CLOSED`／`DEFAULTED`／`CANCELLED` ——**契約、`SDD-005 §6` 狀態機、`SDD-001 §3.9` ER/DDL 四者於 `CR-002` 後已一致**。 可附中文語意說明供辨識（見 `frontend/src/api/installments.ts` 之 `PLAN_STATUS_LABEL`）。 - **`settlementType` 為嚴格列舉**：契約僅 `EARLY`／`DEFAULT`。未定義值（含錯字）**必須拒絕**， **不得**以「非 `DEFAULT` 即 `EARLY`」推斷——那會把「違約處理」靜默執行成「提前結清」， 兩者之帳務與催收後果完全不同（該缺陷已於 2026-09-19 修復，見 `SCS-009 §10`）。 - 結清為 `CSR_SUP` 權限（財務不可逆操作）；建立與查詢為 `CSR`。 - **前端代理**：開發期 `/installment-api` 由 Vite 代理至 `installment-service:8089`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 ### 5.4.9　進件作業台（`/card-applications`） > ✅ **前端已實作完成**（2026-09-20，v1.4）：`pages/CardApplicationConsole.tsx` > ＋ `api/cardApplications.ts`；`vite.config.ts` 加 `/card-api` → 8082，`App.tsx` 四處接線。 > 本頁原依 BEAM PMO「WebUI 亦須規格先行」先立規格（v1.3），規格定稿後方動手寫頁面。 > 端到端實測 9 情境全數符合（見 `SCS-024 §11.2`）。 > ⚠️ 實測期間抓到後端兩個真缺陷（`ORA-17006`／`ORA-12899`），皆已修復並記錄於 `SCS-024 §11.2`。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **建立申請** | 受理進件（`RECEIVED`） | `POST /card-api/v1/card-applications` | `accountId` 必填（UUID）；`productCode` 必填非空白；`channel` 屬 **5 種**列舉（`WEB`／`MOBILE`／`API`／`BRANCH`／`MERCHANT`）；`X-Channel`、`X-Idempotency-Key`（≥8 字元）必帶 | `CSR` | **201**：顯示 `applyNo`（`APP`+yyyyMMdd+8 碼）、狀態 `RECEIVED`、版本 0 | `CC-CARD-4001`（400 欄位／列舉錯）／`CC-CARD-2001`（409 同鍵不同內容） | | **查詢案件** | 查詢單筆案件 | `GET /card-api/v1/card-applications/{id}` | 識別碼須為 UUID | `CSR` | 顯示案件明細：狀態、`applyNo`、核准序號（若已核准）、通路、商品、版本 | `CC-CARD-4040`（404 查無案件） | | **送徵信** | `RECEIVED → REVIEWING`，**隨後呼叫徵審並依結果自動轉態** | `POST /card-api/v1/card-applications/{id}/transitions`（`event=SUBMIT_REVIEW`） | 案件須為 `RECEIVED`；`reason` 選填 ≤200；兩 header 必帶 | `CSR` | 依徵審 `decision` 轉態：
`APPROVE`→**`APPROVED`**（並顯示核准序號）
`DECLINE`→**`REJECTED`**
`SUPPLEMENT`→**`SUPPLEMENT`**
`REFER`→**維持 `REVIEWING`**（提示「徵審結果：轉人工核決」） | `CC-CARD-3001`（409 非法轉換，如非 `RECEIVED`）／`CC-CARD-3002`（409 終態）／`CC-CARD-4040`／`CC-CARD-2001` | | **要求補件** | `REVIEWING → SUPPLEMENT` | `POST .../{id}/transitions`（`event=REQUEST_SUPPLEMENT`） | 案件須為 `REVIEWING`；`reason` **必填** ≤200 | `CREDIT` | 轉 `SUPPLEMENT`，顯示補件原因 | `CC-CARD-3001`／`CC-CARD-3002`／`CC-CARD-4001`（`reason` 空白） | | **補件完成** | `SUPPLEMENT → REVIEWING` | `POST .../{id}/transitions`（`event=COMPLETE_SUPPLEMENT`） | 案件須為 `SUPPLEMENT` | `CREDIT` | 回 `REVIEWING`（可再送徵信） | `CC-CARD-3001`／`CC-CARD-3002` | | **核准** | 人工核決核准 `→ APPROVED` | `POST .../{id}/transitions`（`event=APPROVE`） | 案件須為 `REVIEWING`；`operatorId`、`reason` 必填 | `CREDIT` | 顯示核准序號（`APR`+yyyyMMdd+8 碼＝19 碼） | `CC-CARD-3001`（⚠️ 未經徵信之 `RECEIVED` 直接核准**必被拒**）／`CC-CARD-3002` | | **婉拒** | 婉拒 `→ REJECTED` | `POST .../{id}/transitions`（`event=REJECT`） | 案件須為 `REVIEWING` 或 `RECEIVED`（資格明顯不符可逕予婉拒）；`reason` **必填** | `CREDIT` | 轉 `REJECTED`，顯示婉拒原因 | `CC-CARD-3001`／`CC-CARD-3002` | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單與結果區重置 | — | **說明**： - **狀態顯示值**（`SDD-005 §12`，五值）： `RECEIVED`（受理）／`REVIEWING`（徵審中）／`SUPPLEMENT`（補件）／ `APPROVED`（核准）／`REJECTED`（婉拒）。 終態為 `APPROVED`、`REJECTED`——終態後**所有**轉換皆回 `CC-CARD-3002`。 - ⚠️ **「送徵信」之結果未必是核准**：畫面**必須**依實際回傳狀態顯示。 若回 `REFER`（含徵審系統未接上、逾時、`5xx`、未知 `decision`）， 狀態**維持 `REVIEWING`**，並明確提示「**徵審結果：轉人工核決**」—— **不得**顯示為核准，亦**不得**靜默略過（fail-closed，見 `SCS-025 §6.4`）。 - ⚠️ **未經徵信不得核准**：`RECEIVED → APPROVED` 為**非法轉換**，後端回 `CC-CARD-3001`。 畫面應於 `RECEIVED` 狀態**隱藏或停用**「核准」鈕，避免使用者白撞。 - **核准序號**為快發「部分開卡」三要素之一（`BR-01-04`），核准後須**明顯顯示**供後續使用。 - **冪等鍵每次狀態推進皆須不同**：同一 `X-Idempotency-Key` 用於不同內容 → `CC-CARD-2001`； 同鍵同內容則**重放前次結果**（不重複轉態）。前端應於每次送出時產生新鍵。 - **補件逾期結案**（`SUPPLEMENT_EXPIRED`）為**批次作業**，非畫面按鈕—— 逾商品參數 `supplement.days` 未補件者由批次轉 `REJECTED`（`SCS-024 §12`）。 - **角色**：受理與查詢為 `CSR`；徵審相關（補件／核准／婉拒）為 `CREDIT` （大額覆核另由 `CREDIT_MGR`，見 `§5.2` 權限矩陣「徵審與進件」列）。 - **前端代理**：開發期 `/card-api` 由 Vite 代理至 `card-service:8082`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 --- ### 5.4.10　清算與請款（`/auth/clearing`）——2026-09-22 補建（`C-14` 批次一） > **緣由**：`clearing-service`（8094）於 `C-5`（#A-81）完成並真機實測通過，本頁依 > 「**WebUI 亦規格先行**」（`SDD-007` 開頭之要求）先立規格再實作。 > **⚠️ 動工前查證攔下一處契約缺陷**：`GET /clearing/reconciliations/{runId}` 之回應型別 > 契約誤宣告單一物件、實作回陣列——已立 `CR-016` **v1.2 §8** 修正並真機複驗。 > **本頁依修正後契約（陣列）實作**。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **執行清算** | 依業務日與組織執行清分與比對 | `POST /clearing-api/v1/clearing/runs` | `businessDate` 必填（`YYYY-MM-DD`）；`orgs` 選填（**7 種列舉**：`VISA`／`MASTERCARD`／`NCCC`／`AMEX`／`JCB`／`DINERS`／`DISCOVER`，未選＝全部）；`X-Channel`、`X-Idempotency-Key` 必帶 | `OPS`／`FIN` | **202**：顯示 `runId`、業務日、狀態（`MATCHED`／`DIFFERENCE`／`FAILED`）、筆數、總額、差異筆數與差異金額；**自動帶入下方查詢欄** | `CC-PLT-4003`（400 格式錯）／`CC-CLR-5001`（503 卡組織清算檔未到） | | **查詢對帳結果** | 依執行查詢差異明細（**陣列**） | `GET /clearing-api/v1/clearing/reconciliations/{runId}` | `runId` 須為 UUID | `OPS`／`FIN`／`AUDIT` | **200**：表格列出各組織之**差異類型**（`TIMING`／`FX_RATE`／`SUBSTANTIVE`）、差異筆數、差異金額與處理說明；**無差異時顯示空清單**（非錯誤） | `CC-PLT-4040`（404 查無該執行）／`CC-PLT-4003`（400 非 UUID） | | **結算** | 撥款與會計分錄之觸發 | `POST /clearing-api/v1/clearing/settlements` | `runId` 須為 UUID；`direction` 屬 **2 種列舉**（`ACQUIRER_PAYOUT`／`ISSUER_RECEIVABLE`）；兩 header 必帶 | `FIN` | **202**：顯示該執行之狀態與差異摘要 | `CC-PLT-4040`（404 查無該執行）／`CC-PLT-4003`（400） | | **清除** | 清空輸入與結果 | — | — | `OPS` | 表單與結果區重置 | — | **說明**： - **差異類型不得自行推導**：本期 `differenceType` **一律為 `SUBSTANTIVE`**（後端僅能判定實質差異； `TIMING`／`FX_RATE` 之自動判別需帳務交易面資訊，尚未實作——`SCS-013 §10`）。 畫面**如實顯示後端回傳之值**，**不得**依筆數或金額自行推論類型（推論結果與後端不符即為兩套真相）。 - **⚠️ 結算之回應不含結算單識別碼**（契約限制，`CR-016 §5` K）：本端點回 `ClearingRunView` 而非結算單視圖——畫面**只呈現執行層級資訊**，**不得**顯示或臆造結算單編號。 - **「結算」與「執行清算」為不同角色**：前者為 `FIN`（財務不可逆操作），後者為 `OPS`／`FIN`。 - 金額一律以**最小單位（分）**接收與呈現，前端僅做「分 → 元」換算，**不做浮點運算**。 - **前端代理**：開發期 `/clearing-api` 由 Vite 代理至 `clearing-service:8094`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 --- ### 5.4.11　爭議款處理（`/auth/dispute`）——2026-09-22 補建（`C-14` 批次一） > **緣由**：`dispute-service`（8093）於 `C-6`（#A-82）完成並真機實測通過，含 `CR-017` 之 > **雙軸拆分**（`DISPUTE_REASON` 原因軸／`WORKFLOW_STAGE` 作業階段軸）。本頁**必須**分欄呈現兩軸。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **開立爭議** | 受理爭議案件 | `POST /dispute-api/v1/disputes` | `accountId`／`transactionId` 必填（UUID）；**`disputeType` 屬 4 種列舉**（`UNAUTHORIZED`／`DUPLICATE`／`GOODS_SERVICES`／`OTHER`＝**爭議原因**）；`amount` ≥1（最小單位）；`reason` ≤400 **必填**；`X-Channel`、`X-Idempotency-Key` 必帶 | `CSR` | **201**：顯示爭議編號（`DSP`+yyyyMMdd+6 碼）、**作業階段**、**卡組織階段**、金額、卡組織時限與開案時間 | `CC-DSP-1001`（422 類型不支援）／`CC-DSP-1002`（422 已逾卡組織時限）／`CC-PLT-4003`（400 格式錯） | | **查詢爭議** | 查詢單筆案件 | `GET /dispute-api/v1/disputes/{disputeId}` | `disputeId` 須為 UUID | `CSR` | 顯示案件摘要（**兩軸分列**）與時限 | `CC-PLT-4040`（404 查無案件） | | **提交扣款** | 向卡組織提交扣款（`FIRST`→`SECOND`→`ARBITRATION`） | `POST /dispute-api/v1/disputes/{disputeId}/chargebacks` | `chargebackType` 屬 **3 種列舉**；`evidence` 為 **JSON 物件或省略**；`reason` ≤400；**順序守衛**：跳號即拒；兩 header 必帶 | `CSR_SUP` | **201**：顯示扣款類型、**兩軸之新階段**與提交次數；**重複提交同類型為冪等**（回傳現況、次數不變） | `CC-DSP-3001`（409 **跳號**，如未 `FIRST` 即送 `ARBITRATION`）／`CC-DSP-3002`（409 終態）／`CC-PLT-4040` | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單與結果區重置 | — | **說明**： - **⚠️ 兩個階段維度必須分欄，不得合併（`CR-017` 裁定 A／B）**： | 維度 | 欄位 | 值域 | 業務語意 | |---|---|---|---| | **本行作業階段** | `stage` | `OPENED`／`EVIDENCE_COLLECTING`／`UNDER_REVIEW`／`ARBITRATION`／`RESOLVED_ISSUER`／`RESOLVED_ACQUIRER`／`CLOSED`（**7 值**） | 本行怎麼處理這件爭議 | | **卡組織程序階段** | `orgStage` | `INQUIRY`／`FIRST_PRESENTMENT`／`SECOND_PRESENTMENT`／`PRE_ARB`／`ARBITRATION`／`CLOSED`（**6 值**） | 卡組織流程走到哪 | 兩者**交集僅 `ARBITRATION`／`CLOSED`**，且**語意不同**——畫面以**兩個獨立欄位／徽章**呈現 （標籤明示「本行作業階段」／「卡組織階段」），**不得**繪為同一條流程或共用同一標籤對照表。 - **「爭議原因」與「程序類型」亦為正交**：`disputeType`（契約）＝**爭議原因**（為何爭議）； DDL 之 `DISPUTE_TYPE` 為**程序類型**（開案時為 `INQUIRY`）。畫面僅呈現契約之 `disputeType`， **不得**將其標示為「程序類型」（欄位標籤須為「爭議原因」）。 - **扣款順序為硬約束**：`FIRST → SECOND → ARBITRATION`，跳號後端回 `CC-DSP-3001`（409）。 畫面應於送出不合法順序時**如實呈現錯誤碼**，不得於前端「自動補齊」中間步驟。 - **`evidence` 為物件**（契約 `type: object`）：畫面以 JSON 文字框輸入，前端**須先驗證可解析為物件** 再送出；非物件（陣列／純量）將被後端拒為 400。空白＝省略該欄。 - 提交扣款為 `CSR_SUP` 權限（涉及帳務調整）；開案與查詢為 `CSR`。 - **前端代理**：開發期 `/dispute-api` 由 Vite 代理至 `dispute-service:8093`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 --- ### 5.4.12　報表作業（`/system/reports`）——2026-09-22 補建（`C-14` 批次一） > **緣由**：`report-service`（8098）於 `C-7`（#A-83）完成並真機實測通過（Oracle 作業指標 > ＋ Postgres 讀模型＋非同步產生）。本頁為**作業受理與狀態查詢**，**不含**報表定義管理 > （契約無該端點）。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **提交報表作業** | 受理報表產生（非同步） | `POST /report-api/v1/report-jobs` | `reportCode` 必填 ≤40（本期內建 **`DAILY_AUTH_SUMMARY`**）；`parameters` 必填且為 **JSON 物件**；`format` 屬 **4 種列舉**（`CSV`／`XLSX`／`PDF`／`JSON`，預設 `CSV`）；`X-Channel`、`X-Idempotency-Key` 必帶 | `ADMIN` | **202**：顯示 `jobId`、狀態 `QUEUED`；**自動帶入下方查詢欄** | `CC-RPT-1001`（422 報表定義不存在）／`CC-PLT-4003`（400 參數非物件／格式錯） | | **查詢作業** | 查詢產生結果 | `GET /report-api/v1/report-jobs/{jobId}` | `jobId` 須為 UUID | `ADMIN`／`AUDIT` | **200**：顯示狀態（`QUEUED`／`RUNNING`／`COMPLETED`／`FAILED`）、資料列數、完成時間與**輸出位址** | `CC-PLT-4040`（404 查無作業） | | **重新查詢** | 重新取得最新狀態 | 同上 | 同上 | 同上 | 狀態即時更新 | 同上 | | **清除** | 清空輸入與結果 | — | — | `ADMIN` | 表單與結果區重置 | — | **說明**： - **`XLSX`／`PDF` 未支援**：本期產生器僅實作 **`CSV`／`JSON`**（`SCS-017 §10.4`）。 送出未支援格式時，作業會轉 **`FAILED` 並載明原因**（**不產空檔、不假裝成功**）—— 畫面**如實呈現 `failReason`**，**不得**將未支援格式從下拉中移除後假裝只有兩種格式 （客戶需知道規格與現況之差異）。 - **輸出為本地檔案**：本期物件儲存未部署，`downloadUrl` 為 `file://` 形式 （`SCS-017 §10.1`）。畫面顯示該位址**但標示「本地開發 stand-in」**， **不得**呈現為正式環境之檔案服務網址。 - **參數無預設區間**：未提供 `parameters` 時後端取讀模型**全部**資料（`SCS-017 §10.6`）—— 畫面應提示此行為，避免使用者誤以為有預設日期範圍。 - **報表定義無管理端點**：定義由遷移內建（契約未定義 CRUD）→ 本頁 `reportCode` 以**下拉** 提供已知代碼，**不提供**新增／修改（避免暗示有不存在之功能）。 - 報表作業為 `ADMIN` 權限（跨域資料匯出）；查詢為 `ADMIN`／`AUDIT`。 - **前端代理**：開發期 `/report-api` 由 Vite 代理至 `report-service:8098`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 --- ### 5.4.13　商店管理與請款（`/merchant/settlements`）——2026-09-23 補建（`C-14` 批次二） > **緣由**（`GOV-006 §4 #13`）：`merchant-service`（8095）於 `C-5`／`C-4`（#A-80）完成並真機實測通過， > 惟 `SDD-007 §5.1` **完全無對應頁面**——經查客戶認可原型之**第 11 模組「收單作業平台」** > （9 個 L2，含「特店 (MID) 管理」「對帳與結算撥款」）即其歸屬，屬**追溯缺口**而非刻意省略。 > 已於 §5.1 新增「**收單與商店**」群補列本頁（§5.1 之對照表有完整證據）。 > **⚠️ 動工前查證**：`tools/verify_contract_dto.py`（`CSP-001 §7.1` G-8）核對本服務 > **0 不符**——契約與實作完全對齊，故本頁依契約實作無虞。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **建立商戶** | 受理商戶建檔 | `POST /merchant-api/v1/merchants` | `merchantName` 必填；**`merchantType`（商店型態）屬 4 種列舉**；**`industryType`（業別）屬 7 種列舉**；`mcc` 必填；`merchantId` 選填（未填由後端產生）；`parentMerchantId` 選填（集團店上層）；`acceptedCardTypes` 為陣列（`VISA`／`MASTERCARD`）；`X-Channel`、`X-Idempotency-Key` 必帶 | `CSR_SUP` | **201**：顯示 `merchantId`、**商店型態**、**業別**、`mcc`、風險等級與狀態 | `CC-MRC-1001`（422 特店代碼重複）／`CC-PLT-4003`（400 格式錯／未知列舉） | | **查詢商戶** | 依特店代碼查詢主檔 | `GET /merchant-api/v1/merchants/{merchantId}` | `merchantId` 必填 | `CSR` | **200**：顯示商戶主檔（**兩軸分列**）與狀態徽章 | `CC-PLT-4040`（404 查無商戶） | | **商店請款** | 受理商店請款（產生結算單） | `POST /merchant-api/v1/merchant-settlements` | `merchantId`／`settlementDate`（`YYYY-MM-DD`）／`grossAmount`／`feeAmount`／`taxAmount` 必填；`batchNo`／`batchCount`／`currency` 選填；兩 header 必帶 | `FIN` | **201**：顯示結算單號、毛額／費用／稅／**淨額**、幣別、狀態（`SUBMITTED`）與例外原因（若有） | `CC-PLT-4040`（404 查無商戶）／`CC-PLT-4003`（400 格式錯） | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單與結果區重置 | — | **說明**： - **⚠️ 兩個維度必須分欄，不得合併（`CR-015` 裁定，2026-09-22）**： | 維度 | 契約欄位 | 值域 | 業務語意 | |---|---|---|---| | **商店型態** | `merchantType` | `SINGLE`／`FRANCHISE`／`CHAIN`／`GROUP`（**4 值**） | 這家店**長什麼樣**（單店／加盟／連鎖／集團） | | **業別** | `industryType` | `RETAIL`／`EC`／`MOTO`／`RESTAURANT`／`TRAVEL`／`SUPERMARKET`／`OTHER`（**7 值**） | 這家店**做什麼生意** | 兩者為**正交維度**（原以單一欄位承載，且值域與 DDL **無交集**——`CR-015 §2.1`）。 畫面以**兩個下拉分列**（標籤明示「商店型態」／「業別」），**不得合併為單一欄位**； 亦**不得**以其中一者推斷另一者（如「連鎖店必為零售」——無此規則）。 - **`riskLevel` 為後端評估之結果**（契約 `nullable`）：新建時可能為 `null`， 畫面**如實顯示「—」**，**不得**以預設值（如 `LOW`）填充——評估未完成與評估為低風險是**不同事實**。 - **淨額由後端計算**（`netAmount = gross − fee − tax`）：請求端**不得宣稱**淨額 （`MerchantSettlementRequest` 無此欄位）。畫面於結果區顯示淨額，並可由三者驗算。 - **`status` 顯示值**：`SUBMITTED`／`VERIFIED`／`EXCEPTION`／`PAID`（**契約、DDL CHECK 於 `CR-015` 後已一致**）； `EXCEPTION` 時**必載** `exceptionReason`，畫面須明顯呈現（例外不得靜默）。 - 商戶建檔為 `CSR_SUP` 權限（涉及費率與合約）；查詢為 `CSR`；請款為 `FIN`（財務不可逆操作）。 - 金額一律以**最小單位（分）**接收與呈現，前端僅做「分 → 元」換算，**不做浮點運算**。 - **前端代理**：開發期 `/merchant-api` 由 Vite 代理至 `merchant-service:8095`（rewrite 去掉前置）； 正式環境應統一走 API Gateway（8100）。 --- ### 5.1.2 ★ 剩餘頁面之**後端就緒度盤點**（2026-09-23；**2026-09-30 重盤**） > **緣由**：`C-14` 尚餘 **48 頁**（以 `v1.10` 當時之頁面清單計）。 > ⚠️ **2026-09-30 重盤 ＋ 2026-10-01 更新**：該數字**已過時**——經 `C-14` 批次一～八、桶 C 逐頁解鎖（`§5.4.10`～`§5.4.30`）， > **實際剩餘桶 C 為 28 頁**（見 `§5.1.2.3`）。**本節各桶頁數已依實測重算**。 > ⚠️ **2026-10-01 併更正**：`v1.25` 之版本列已載「桶 C 30 → 29」，惟本節／`§5.1.2.3`／重盤總表**漏同步** > （仍記 30）——**又一次「已做卻漏記」**；本版一併校正（含補計 `#A-114` 之 `/switch/auth/state`）。 > 惟**「服務有端點」≠「該頁有對應端點」**—— > 例：`/onboarding/ocr`（證件與影像辨識）掛 `card-service`（10 端點），但**其中無任何 OCR 端點**。 > 若照頁名造頁，即為**空殼**（違反客戶硬性要求）。 > 故逐頁做**語意匹配**（頁面所需功能 ↔ 該服務端點語意），結果如下。 > > ⚠️ **2026-09-23 修正（本節方法論之缺失，見 `CR-021`）**：初版盤點**只做語意匹配、 > 未驗證「該端點在實作中確實存在」** → 誤將 3 頁列入桶 A。實測發現 > **「契約有端點」≠「實作有端點」**（`authorization-service` 之 `reversals`／`advices`／ > `check-results` **三支完全未實作**）。已將該 3 頁移至桶 C， > 並將「**端點存在性**」納入 `tools/verify_contract_dto.py` 之檢查面（`CSP-001 §7.1` G-8）。 | 桶 | 頁數 | 定義 | 處置 | |---|---:|---|---| | **A 可立即實作** | **6**（**已全數完成 ✅**：產品與費率設定／參數設定／卡片生命週期管理／虛擬卡與 Token 管理／額度控管／資料遷移作業） | 有**語意對應**之端點、**實作確實存在**，且**不與既有頁面重複** | ✅ **已完成**（`§5.4.14`～`§5.4.18`／`§5.4.20`） | | **B 與既有頁面重複** | **11** | 原型分頁，但**功能已由本案既有頁面涵蓋** | **不另造**（於下表標明由哪一頁涵蓋）——造了即為**同一功能兩套 UI**。⚠️ **2026-10-01 新增 2 頁**：`/onboarding/review`／`/onboarding/approval`（BEAM PMO 裁定——核心流程已由 `§5.4.9` 涵蓋） | | **C 無對應端點** | **28** | 該服務**無**對應語意之端點（多為外部系統／未實作功能）。⚠️ **2026-09-30 重盤**：原記 34／35 頁，其中 **11 頁已解鎖並實作**（`§5.4.10`～`§5.4.13`、`§5.4.21`～`§5.4.27`）→ 實餘 33 頁；**2026-10-01 再移 2 頁入桶 B**（`/onboarding/review`／`/onboarding/approval`，BEAM PMO 裁定）**＋再解鎖 3 頁**（`/dashboard` BEAM PMO 裁定 (a)、`/switch/auth/state`（`#A-114`）、`/system/split-ratio`（`#A-120`））→ **實餘 28 頁** | **待後端就緒**；**不造空殼** | > **★ 重盤總表**（`§5.1` 之 59 頁**全數歸類，無遺漏**；**2026-10-01 更新**）： > > | 分類 | 頁數 | 說明 | > |---|---:|---| > | **已實作** | **20** | 桶 A 6 ＋ 桶 C 已解鎖 14 | > | **桶 B（不另造）** | **11** | 由既有頁面／按鈕涵蓋（見 `§5.1.2.2`） | > | **桶 C 待辦** | **28** | 見 `§5.1.2.3` | > | **合計** | **59** | ＝ `§5.1` 表列頁數 ✅ | > > **已實作 20 頁之構成**：桶 A 6（`/card/product`、`/card/lifecycle`、`/card/limit`、`/card/token`、 > `/system/parameters`、`/system/migration`）＋ 桶 C 解鎖 14（`/auth/clearing`、`/auth/dispute`、 > `/system/reports`、`/merchant/settlements`、`/auth/policy`、`/switch/auth/reversal`、`/auth/stip`、 > `/system/health`、`/system/audit`、`/system/batch`、`/system/endpoints`、`/dashboard`、 > **`/switch/auth/state`**、**`/system/split-ratio`**）。 > **另有 2 頁超出 `§5.1` 清單**（本案額外建置，**不計入 59 頁**）： > `/limit-adjustments`（額度調整申請，`§5.4.2`）；**`/accounts`（歸戶 360，`§5.4.31`，`CR-032`，2026-10-01 新增）**。 #### 5.1.2.1 桶 A：可立即實作（**6 頁**——`CR-021` 後由 11 修正為 8，再依實際就緒度修正為 6；**6 頁已全數完成 ✅**） | 群 | 頁面 | 路徑 | 可用端點（依據） | |---|---|---|---| | 卡片與帳戶 | ✅ 產品與費率設定（#A-90） | `/card/product` | `POST`／`GET`／`PUT /products`（`product-service`） | | 卡片與帳戶 | ✅ 卡片生命週期管理（#A-91） | `/card/lifecycle` | `POST /cards/{cardId}/lifecycle-transitions`＋`GET /cards/{cardId}` | | 卡片與帳戶 | ✅ 額度控管（批次五／§5.4.18） | `/card/limit` | `GET /accounts/{id}/limits`＋`special-limits`＋`POST /limit-holds`＋`…/releases` | | 卡片與帳戶 | ✅ 虛擬卡與 Token 管理（#A-91） | `/card/token` | `POST`／`GET /cards/{cardId}/tokens` | | 系統管理 | ✅ 參數設定（#A-90） | `/system/parameters` | `GET`／`PUT /parameters/{namespace}/{paramKey}` | | 系統管理 | ✅ 資料遷移作業（批次六／§5.4.20） | `/system/migration` | `POST /migration-jobs`＋`GET /legacy-accounts/{legacyId}` | #### 5.1.2.2 桶 B：與既有頁面重複（**11 頁**，**不另造**） | 原型頁面 | 路徑 | **已由本案既有頁面涵蓋** | |---|---|---| | 申請管道整合 | `/onboarding/channel` | `/card-applications`（進件作業台） | | **人工審查與照會** | `/onboarding/review` | **`/card-applications`（進件作業台，`§5.4.9`）**——其狀態機 `RECEIVED→REVIEWING→SUPPLEMENT→APPROVED／REJECTED` **已涵蓋人工審查、要求補件、補件完成**（`REQUEST_SUPPLEMENT`／`COMPLETE_SUPPLEMENT`）。⚠️ **差異項**：「**照會記錄**」**無端點**——若客戶要求，應**另立 CR 補端點**，**不另造重複頁**（BEAM PMO 2026-10-01 裁定移桶 B） | | **最終核決與製卡送件** | `/onboarding/approval` | **`/card-applications`（`§5.4.9`）**——「**核准**」／「**婉拒**」已涵蓋（`APPROVE`／`REJECT`，`CREDIT` 權限，產生核准序號 `APR`+yyyyMMdd+8 碼）。⚠️ **差異項**：「**製卡送件**」**無端點**（送製卡廠為外部流程）——同上，**另立 CR** 而非重造頁面（BEAM PMO 2026-10-01 裁定移桶 B） | | 線上授權處理 | `/auth/engine` | `/authorizations`（授權作業台） | | 帳務日終處理 | `/finance/batch` | `/postings`（入帳作業台） | | **總帳會計介接** | `/finance/gl` | **§5.4.10「清算與請款」之「結算」按鈕**（`POST /clearing/settlements`，`direction` 兩列舉、`FIN`、202）——**⚠️ `SDD-007` 1.14 曾誤立 §5.4.19**（稱「§5.4.10 只做對帳」），**未查該節按鈕定義即斷言**，查證後撤銷 | | 帳單生成與發送 | `/finance/bill` | `/statements`（帳單作業台） | | 銷帳與入帳處理 | `/finance/payment` | `/payments`（繳款作業台） | | 分期付款管理 | `/finance/installment` | `/installments`（分期作業台） | | 紅利點數管理 | `/marketing/bonus` | `/rewards`（紅利點數作業台） | | 客服視窗 | `/service/csr` | `/parties`（持卡人／歸戶查詢） | > ⚠️ **此桶之處置原則**：原型將同一功能域拆為多個選單項，本案則**以服務為單位**合併為一頁 > （如 `/finance/*` 四頁＝posting／statement／payment／installment 四個既有作業台）。 > **不為湊頁數而重造**——同一功能兩套 UI 必然漂移，且維護成本加倍。 > 若客戶**明確要求**原型選單結構，應以**路由別名（alias）**指向既有頁面，而非另寫一份。 #### 5.1.2.3 桶 C：無對應端點（**28 頁**，待後端） > **★ 2026-09-30 重盤 ＋ 2026-10-01 裁定與解鎖**：本節原記「**34 頁**」且清單**仍含已解鎖之頁面** > （稽核軌跡／批次監控／端點管理／健康檢查／離線授權與代授權／授權策略檢核／沖正機制 > 等 **11 頁**——**皆已解鎖並實作**，見 `§5.4.10`～`§5.4.13`、`§5.4.21`～`§5.4.27`）。 > 重盤後實餘 33 頁；**再經 BEAM PMO 2026-10-01 裁定**： > **(i)** `/onboarding/review`／`/onboarding/approval` **移入桶 B**（核心流程已由 `§5.4.9` 涵蓋）； > **(ii)** **`/dashboard`（營運總覽）解鎖並實作**（`§5.4.28`；`SCS-020 §9.11`，契約 **87 端點**）； > **(iii)** **`/switch/auth/state` 解鎖並實作**（`§5.4.29`；`SCS-001 §7.11`，`#A-114`）； > **(iv)** **`/system/split-ratio` 解鎖並實作**（`§5.4.30`；`SCS-020 §9.12`，`#A-120`） > → **實餘 28 頁**。 > ⚠️ **併更正**：`v1.25` 之版本列已載「桶 C 30 → 29」，惟本節標題與清單**漏同步**（仍記 30）； > 本版一併校正，並補計 `#A-114` 之 `/switch/auth/state`（原清單**遺漏該頁**）。 > 逐頁標註**主要缺口**與**服務就緒度實測** > （實測方式：掃 `contracts/openapi/*.yaml` 之端點清單，比對各頁所需語意）。 | 群 | 頁數 | 頁面（路徑） | 主要缺口／就緒度實測（2026-09-30） | |---|---:|---|---| | 徵審與進件 | **3** | 證件與影像辨識（`/onboarding/ocr`）／徵信與聯徵查詢（`/onboarding/jcic`）／評分卡與決策引擎（`/onboarding/scoring`） | **徵審為外部系統**（`SCS-025` 有契約、`card-service` 未接）→ 三頁**確無端點**。⚠️ **2026-10-01 移出 2 頁**：`/onboarding/review`／`/onboarding/approval` 之核心流程**已由 `§5.4.9` 涵蓋** → **BEAM PMO 裁定移入桶 B**（見 `§5.1.2.2`） | | 卡片與帳戶 | 1 | 拼圖與個人化管理（`/card/personalization`） | **無端點**——`card-service` 9 端點中無個人化／拼圖 | | 風控與反洗錢 | 4 | 即時盜刷偵測（`/risk/fraud`）／行動安全驗證（`/risk/mobile-auth`）／洗錢防制與制裁掃描（`/risk/aml`）／催收管理（`/risk/collection`） | **均無端點**——`authorization`／`party`／`statement` 皆無對應語意端點 | | 行銷與忠誠度 | 3 | 現金回饋與刷卡金（`/marketing/cashback`）／聯名卡哩程與外幣轉換（`/marketing/miles`）／活動行銷引擎（`/marketing/campaign`） | **均無專屬端點**——`rewards-service` 僅 4 端點（`accruals`／`redemptions`／`accounts/{id}`／`reward-rules`），無現金回饋專屬／哩程轉換／活動引擎 | | 客服與數位管道 | 3 | 語音與文字客服（`/service/ivr`）／行動銀行 App 介接（`/service/api`）／申訴與工單管理（`/service/ticket`） | **無端點**——`notification-service` 僅 2 端點（發送／查詢），**無 IVR／工單** | | 系統管理 | **2** | 權限與角色（`/system/rbac`）／通知樣板管理（`/system/notification-templates`） | `rbac`＝**Keycloak 管理**（非本案服務）；`notification-templates`＝**`C-9` 明確不做 CRUD**。⚠️ **2026-10-01 解鎖 1 頁**：**分流比例管理（`/system/split-ratio`）**（`§5.4.30`；`SCS-020 §9.12`，`#A-120`）——機制早已存在（`SAD-004 §2.4`，POC-13），原僅缺管理面 | | 獨立授權平台 | **3** | 預授權與交易取消（`/switch/auth/pre-auth`）／收單端即時風控（`/switch/auth/risk`）／清算前置處理（`/switch/auth/clearing-prep`） | **均無端點**——`authorization-service` 端點中無預授權／收單風控／清算前置。⚠️ **2026-10-01 解鎖 1 頁**：**交易狀態機與冪等（`/switch/auth/state`）**（`§5.4.29`；`SCS-001 §7.11`） | | 獨立紅利平台 | 3 | 商城兌換訂單（`/loyalty/mall-orders`）／會員與等級（`/loyalty/members`）／平台介接與防弊（`/loyalty/integrations`） | **均無端點**——`rewards-service` 無商城訂單／會員等級／平台介接 | | **TMS 終端／POS** | **4** | 終端生命週期（`/tms/lifecycle`）／遠端管理（`/tms/remote`）／監控與告警（`/tms/monitoring`）／維修管理（`/tms/repair`） | **無對應本專案服務**（RFP：終端維護由 CAKU 支援）——**實作歸屬待 SoW 確認**（`GOV-006 §4 #15`） | | **BASE24 SWITCHING** | **2** | Switch 核心（`/switch/core`）／清算檔案處理（`/switch/file-transfer`） | **ACI 產品**（Switch 核心）；`/switch/file-transfer` 部分可由 `clearing` 承接 | | **合計** | **28** | | | > **★ 對 `C-14` 剩餘工作量之修正（2026-09-30 重盤／2026-10-01 更新）**： > 原記「餘 48 頁」係以**頁面清單**計；經就緒度盤點與逐批解鎖後： > **桶 A 6 頁已完成 ✅**、**桶 B 11 頁不另造**、**桶 C 待辦 28 頁**。 > → **`C-14` 之可交付終點為 12（既有）＋6（桶 A）＋14（桶 C 已解鎖）＝32 頁**， > 餘 **28 頁待後端就緒**（其中 **TMS 4／BASE24 2 之實作歸屬待 SoW 確認**）。 > > **✅ 重盤所揭露之待裁定項（已裁定）**：`/onboarding/review`／`/onboarding/approval` 之**核心流程已由 `§5.4.9` 涵蓋** > （狀態機 `RECEIVED→REVIEWING→SUPPLEMENT→APPROVED/REJECTED` 完整）→ **BEAM PMO 2026-10-01 裁定「移桶 B」**： > 兩頁已移入 `§5.1.2.2`（**不另造**）；差異項（**照會記錄**／**製卡送件**）**另立 CR 補端點**，**不重造頁面**。 --- ### 5.4.14　產品與費率設定（`/card/product`）——2026-09-23 補建（`C-14` 批次三） > **緣由**：`§5.1.2` 就緒度盤點列為**桶 A（可立即實作）**——`product-service`（8085）之 > `POST`／`GET`／`PUT /products` 完整可用（`C-2`／#A-76 已實作並真機驗證）。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **建立產品** | 新增信用卡產品 | `POST /product-api/v1/products` | `productCode`／`cardName`／`cardGrade`／`effectiveFrom` 必填；**`org` 屬 7 種列舉**（`VISA`／`MASTERCARD`／`JCB`／`AMEX`／`UNIONPAY`／`DINERS`／`DISCOVER`）；`effectiveFrom` 為 `YYYY-MM-DD`；`effectiveTo` 選填；`copyFrom` 選填（複製既有產品之參數）；`X-Channel`、`X-Idempotency-Key` 必帶 | `ADMIN` | **201**：顯示 `productCode`、卡名、組織、卡等、狀態（`DRAFT`）與生效區間 | `CC-PRD-1001`（422 **產品代碼重複**）／`CC-PLT-4003`（400 格式錯） | | **查詢產品** | 依產品代碼查詢 | `GET /product-api/v1/products/{productCode}` | `productCode` 必填 | `ADMIN`／`CSR` | **200**：顯示產品主檔與狀態徽章 | `CC-PLT-4040`（404 查無產品） | | **更新產品** | 依產品代碼更新 | `PUT /product-api/v1/products/{productCode}` | 同建立之欄位檢核 | `ADMIN` | **200**：顯示更新後之產品 | `CC-PRD-1001`／`CC-PLT-4040` | | **清除** | 清空輸入與結果 | — | — | `ADMIN` | 表單與結果區重置 | — | **說明**： - **費率以「參數」承載**（`valueType=RATE`），非本頁欄位——**試算引擎為 `pricing-service`** （`SCS-006`）。本頁**不重複實作費率計算**，僅維護產品主檔與其參數入口（見 §5.4.15）。 - **`copyFrom` 為「複製既有產品之參數」**（`C-2` 之參數版本鏈）：指定後新產品之參數自該產品複製， 避免逐項重填。畫面以**下拉**提供已知產品代碼，留空＝不複製。 - **`status` 之值域為 `DRAFT`／`ACTIVE`／`SUSPENDED`／`RETIRED`**，惟**本期無狀態轉換端點** （契約未定義）→ 畫面**僅顯示**，**不提供**變更按鈕（避免暗示不存在之功能）。 - 產品為 `ADMIN` 權限（影響全體卡戶）；查詢放寬至 `CSR`。 - **前端代理**：開發期 `/product-api` 由 Vite 代理至 `product-service:8085`（rewrite 去掉前置）。 --- ### 5.4.15　參數設定（`/system/parameters`）——2026-09-23 補建（`C-14` 批次三） > **緣由**：同 `§5.1.2` 桶 A——`GET`／`PUT /parameters/{namespace}/{paramKey}` 可用。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢參數** | 依命名空間與鍵查詢 | `GET /product-api/v1/parameters/{namespace}/{paramKey}` | `namespace`／`paramKey` 必填 | `ADMIN`／`OPS` | **200**：顯示 `paramValue`、**`valueType`**、生效區間 | `CC-PLT-4040`（404 查無參數） | | **設定參數** | 新增或更新參數（**版本鏈**） | `PUT /product-api/v1/parameters/{namespace}/{paramKey}` | `paramValue`／**`valueType` 屬 6 種列舉**（`STRING`／`NUMBER`／`BOOLEAN`／`JSON`／`AMOUNT`／`RATE`）／`effectiveFrom` 必填；`effectiveTo` 選填；`X-Channel`、`X-Idempotency-Key` 必帶 | `ADMIN` | **200**：顯示更新後之參數與生效區間 | **`CC-PRD-1002`（422 參數生效日重疊）**／`CC-PLT-4003`（400） | | **清除** | 清空輸入與結果 | — | — | `ADMIN` | 表單與結果區重置 | — | **說明**： - **⚠️ 版本鏈語意（`C-2` 之核心）**：同 `namespace`／`paramKey` 可有多個生效版本。 - `effectiveFrom` **相同** → 視為**更新該版本**； - **真重疊**（新版本區間與既有版本重疊） → **`CC-PRD-1002`（422）**； - **切割尾端**（新版本自既有版本之中間生效） → **既有版本之 `effectiveTo` 自動延續／封閉**， **不報錯**。 畫面應**如實呈現後端回應之生效區間**，**不得**於前端自行推算版本鏈（推導結果若與後端不符即為兩套真相）。 - **`paramValue` 之型別由 `valueType` 決定**：畫面以**文字框**輸入並提示型別 （`NUMBER`／`AMOUNT`／`RATE` 輸入數字、`BOOLEAN` 輸入 true／false、`JSON` 輸入物件）。 **前端不做型別轉換**——交由後端依 `valueType` 解析；型別不符回 `CC-PLT-4003`。 - **費率參數**（`valueType=RATE`）即「產品與費率設定」頁所稱之費率（見 §5.4.14 說明）。 - 參數為 `ADMIN`／`OPS` 權限（影響全體交易行為）。 - **前端代理**：同 `/product-api`（與 §5.4.14 共用）。 --- ### 5.4.16　卡片生命週期管理（`/card/lifecycle`）——2026-09-23 補建（`C-14` 批次四） > **緣由**：`§5.1.2` 桶 A——`GET /cards/{cardId}`＋`POST /cards/{cardId}/lifecycle-transitions` 可用 > （`card-service`，`#C-10`／#A-37 已實作並真機驗證）。 > ⚠️ **動工前查證（真機實測）攔下四項缺陷** → **`CR-020`** > （F1 三要素未接收／F2 標頭未綁定／F3 查無卡片回 409／F4 `status` 未同步）。 > ✅ **四項已於 2026-09-23 全部修正**（真機實測＋DB 複核；BEAM PMO 裁定採「修根因」而非 workaround） > → **本節之按鈕定義已隨之更新**：三要素**改為提供**、冪等**可宣稱**、查無卡片回 **404**。 > 見下方「說明」各條。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢卡片** | 依卡片識別碼查詢狀態 | `GET /card-api/v1/cards/{cardId}` | `cardId` 必填，**須為含連字號之 UUID**（實測：不帶連字號回 `CC-PLT-4003`／400） | 已認證 | **200**：顯示 `blockCode`（生命週期）、`status`（啟用／帳務）、卡號遮罩、到期日、票證類型、`transactable`／`expired` | `CC-CARD-4040`（404 查無卡片）／`CC-PLT-4003`（400 格式錯） | | **狀態轉換** | 對該卡執行生命週期事件 | `POST /card-api/v1/cards/{cardId}/lifecycle-transitions` | `event` **屬 7 種列舉**（`ACTIVATE`／`LOCK`／`UNLOCK`／`REPORT_LOST`／`REISSUE`／`EXPIRE`／`CLOSE`）；`reason` 必填（≤200 字元）；`operatorId` 選填（≤32）；**★ `threeFactors` 於 `event=ACTIVATE` 時必填**（身分證字號／生日／核准序號；後端比對**本卡所屬申請案件**之核准序號）；`X-Channel`／`X-Idempotency-Key` **必帶** | 已認證 | **201**：顯示轉換後之 `blockCode`／`status`／`transactable` | `CC-CARD-3001`／`CC-CARD-3002`（409 非法或終態轉換）／**`CC-CARD-1002`（422 三要素不符或查無來源申請案件）**／`CC-CARD-2001`（409 冪等鍵已用於不同內容）／`CC-PLT-4001`（400 缺必要標頭）／`CC-PLT-4003`（400 格式錯） | | **清除** | 清空輸入與結果 | — | — | — | 表單與結果區重置 | — | **說明**： - ★ **兩個維度不得合併**：`blockCode`（生命週期，**7 值**：`INACTIVE`／`ACTIVE`／`LOCKED`／`LOST`／ `REISSUED`／`EXPIRED`／`CLOSED`）與 `status`（啟用／帳務，**4 值**：`UNACTIVATED`／`ACTIVE`／ `SUSPENDED`／`CLOSED`）為**正交維度**（`V1__baseline.sql` 兩欄各自 `CHECK`）。 畫面**分欄呈現**、**不得由 `blockCode` 推導 `status`**（推導即為**兩套真相**）。 - ✅ **三要素（`CR-020` F1，已修正）**：`event=ACTIVATE` 時**提供**輸入並由後端**確實驗證** ——比對「本卡所屬申請案件」之核准序號（`CC_CARD.CARD_APPLICATIONS.CARD_ID`，V7 遷移）； 不符或查無來源案件回 **`CC-CARD-1002`（422）**。 修正前為「契約宣告但實作未接收」（送錯仍回 201），故當時**不提供**輸入以避免**假功能**； **修正後即應提供**（否則反而變成「功能已存在而畫面不給用」）。 其餘 6 種事件**不需**三要素（`SDD-005 §2.1` 僅轉換 1／9 有此前置條件）。 - ✅ **冪等已生效（`CR-020` F2，已修正）**：`X-Channel`／`X-Idempotency-Key` **必帶** （缺則 `CC-PLT-4001`／400）；同鍵同指紋**重放**（回當前狀態）、同鍵異指紋回 **`CC-CARD-2001`**。畫面**可**向使用者宣稱「重送不重複」。 - ✅ **查無卡片回 `CC-CARD-4040`（404）（`CR-020` F3，已修正）**：與 `GET /cards/{cardId}` 及 Token 端點一致——修正前為 `CC-CARD-3001`（409），同服務兩套真相。 - ✅ **`status` 隨 `blockCode` 同步（`CR-020` F4，已修正）**：依 **`SDD-005 §2.4`** 之映射表 （`ACTIVE→ACTIVE`、`LOCKED`／`LOST`／`EXPIRED→SUSPENDED`、`INACTIVE`／`REISSUED→UNACTIVATED`、 `CLOSED→CLOSED`）。⚠️ **兩欄現為衍生關係、非獨立維度**；本頁仍**各自顯示** （後端為權威，前端**不推導**）。 - ⚠️ **無來源申請案件之卡無法開卡（fail-closed，刻意）**：卡片須由「**已核准**之申請案件」發出 ——發卡（`POST /cards`）時帶 `applicationId`，發卡後回填 `CARD_APPLICATIONS.CARD_ID`。 既有種子／測試卡多數無此關聯，`ACTIVATE` 將回 `CC-CARD-1002`——**此為預期行為**， 畫面須如實顯示該錯誤碼，**不得**放寬為「允許無案件開卡」。 - **角色**：本服務**本期僅驗證「已認證」，未實作端點級角色細分**（實測原始碼無 `@PreAuthorize`； `SDD-005 §2.1` 之「允許角色」為**設計目標**而非現況）→ 畫面**不顯示**角色限制，避免暗示已生效。 - **前端代理**：開發期 `/card-api` 由 Vite 代理至 `card-service:8082`（rewrite 去掉前置）。 --- ### 5.4.17　虛擬卡與 Token 管理（`/card/token`）——2026-09-23 補建（`C-14` 批次四） > **緣由**：`§5.1.2` 桶 A——`POST`／`GET /cards/{cardId}/tokens` 可用（同 `card-service`）。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢 Token** | 列出該卡之全部 Token | `GET /card-api/v1/cards/{cardId}/tokens` | `cardId` 必填（含連字號 UUID） | 已認證 | **200**：清單（`tokenId`／`tokenNo`／`platform`／`status`／`boundAt`）；**含 `DELETED`**（後端**刻意保留**以利稽核） | `CC-CARD-4040`（404 查無卡片） | | **綁定 Token** | 綁定支付平台之代碼化卡號 | `POST /card-api/v1/cards/{cardId}/tokens` | `platform` 必填、**屬 7 種列舉**（`APPLE_PAY`／`GOOGLE_PAY`／`SAMSUNG_PAY`／`GARMIN_PAY`／`FITBIT_PAY`／`TAIWAN_PAY`／`QR_CODE`）；`deviceRef` 選填（≤80）；**`X-Channel` 必帶** | 已認證 | **201**：顯示新 Token 之 `tokenId`／`tokenNo`／`platform`／`status`／`boundAt` | `CC-CARD-1004`（422 同平台已有有效 Token，不可重複綁定）／`CC-CARD-4001`（400 `platform` 不在列舉內）／`CC-CARD-4040`（404 查無卡片） | | **清除** | 清空輸入與結果 | — | — | — | 表單與結果區重置 | — | **說明**： - ⚠️ **`tokenNo` 不是卡號**：為**代碼化卡號**（格式 `tok_` ＋ 32 位十六進位，`SCS-003 §7.6`）。 畫面**不得**與卡號混用呈現，須明確標示其為**代碼化值**。 - ⚠️ **本期 `tokenNo` 由本服務自行產生，非 TSP 簽發**（`SCS-003 §10 #11`）→ 畫面附註「本期為本服務產生之 **stand-in**，非真實 TSP 簽發」，**不得**呈現為已介接 TSP。 - ⚠️ **查詢含 `DELETED`**：`JdbcTokenRepository.FIND_SQL` **無狀態過濾**、 `CardTokenService.list` javadoc 明載「**不篩除，以利稽核**」→ 畫面**不得**預設過濾， 並以徽章區分 `ACTIVE`／`SUSPENDED`／`DELETED`。 - ⚠️ **`X-Channel` 為實作確實要求之標頭**——**與生命週期端點不同** （該端點實測不帶亦通，見 §5.4.16 之 `CR-020 F2`）→ 本頁**必帶**；不帶時後端回 **400**。 - ⚠️ **本期無解綁／停用端點**（契約僅 `POST`／`GET`）→ 畫面**不提供**「解綁」按鈕 （避免暗示不存在之功能）。 - **角色**：同 §5.4.16——本期僅「已認證」，未實作角色細分。 - **前端代理**：同 `/card-api`（與 §5.4.16 共用）。 --- ### 5.4.18　額度控管（`/card/limit`）——2026-09-23 補建（`C-14` 批次五） > **緣由**：`§5.1.2` 桶 A——`GET /accounts/{accountId}/limits`＋`special-limits`、 > `POST /limit-holds`、`POST /limit-holds/{holdId}/releases` 皆**實作確實存在** > （`CR-021` 後之複核：本頁 4 支端點皆已於 `LimitController`／`LimitAdjustmentController` 實作）。 > > ⚠️ **與既有「額度調整申請」（§5.4.2）之分工**：本頁處理**佔用與釋放**（授權生命週期）， > 額度主檔**調整**（申請／覆核／撤銷）屬 §5.4.2，**不重複造**。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢額度** | 查詢歸戶額度主檔 | `GET /limit-api/v1/accounts/{accountId}/limits` | `accountId` 必填（UUID）；`currency` 選填（預設 `TWD`） | 已認證 | **200**：顯示永久／暫時／彈性／已用／**佔用中**／可用額度與幣別 | `CC-LIM-1001`（422 查無此帳戶之額度主檔） | | **查詢專用額度** | 列出該歸戶之專用額度 | `GET /limit-api/v1/accounts/{accountId}/special-limits` | `accountId` 必填 | 已認證 | **200**：顯示筆數與明細清單（無專用額度時顯示 0 筆） | `CC-LIM-1001`（422） | | **建立佔用** | 佔用可用額度 | `POST /limit-api/v1/limit-holds` | `accountId` 必填；`holdAmount` 必填且 ≥ 1（**單位：分**）；`holdType` 屬 3 種列舉（`GENERAL`／`SPECIAL`／`INSTALLMENT`）；`authorizationId` 選填；`currency` 選填（預設 `TWD`） | 已認證 | **201**：顯示 `holdId`／佔用金額／`status`／幣別 | `CC-LIM-1001`（422 查無額度主檔或**可用額度不足**）／`CC-PLT-4003`（400） | | **釋放佔用** | 釋放（可部分） | `POST /limit-api/v1/limit-holds/{holdId}/releases` | `holdId` 必填（UUID）；`amount` 必填且 ≥ 1（**單位：分**）；`currency` 選填 | 已認證 | **200**：顯示釋放後之 `status`／`releasedAmount` | `CC-LIM-1001`（422 查無此佔用或已全數釋放） | | **清除** | 清空輸入與結果 | — | — | — | 表單與結果區重置 | — | **說明**： - ⚠️ **金額單位一律為「分」**（`HoldRequest.holdAmount`／`ReleaseRequest.amount` 皆 `minimum: 1`、 單位分）。畫面須**明確標示單位**，並於可用額度旁同步顯示元值供對照 （**換算僅供閱讀，送出仍用分**）。 - ⚠️ **狀態機依 `SDD-005 §3`**：`HELD` →（`PARTIALLY_RELEASED`）→ `RELEASED`／`EXPIRED`； `RELEASED`／`EXPIRED` 為終態，重複釋放回 `CC-LIM-1001`。 畫面**顯示後端回傳之 `status`**，**不得**自行推導。 - ⚠️ **`holdAmount`（佔用中）為 `CR-019` C-7 新增之欄位**——`LimitView` 原無此欄， 畫面須呈現，否則無從得知「有多少額度被佔住」。 - ⚠️ **專用額度另有獨立端點**（`special-limits`），`LimitView` **不含**專用額度明細 （`CR-019` C-7 移除 `specialLimits` 欄——避免兩處來源漂移）。 - ⚠️ **不提供「額度調整」**（永久／暫時額度變更）——屬 §5.4.2 既有頁面， 避免同一功能兩套 UI。 - **前端代理**：開發期 `/limit-api` 由 Vite 代理至 `limit-service:8083`（§5.4.2 已建，沿用）。 --- ### 5.4.20　資料遷移作業（`/system/migration`）——2026-09-23 補建（`C-14` 批次六） > **緣由**：`§5.1.2` 桶 A——`POST /migration-jobs`＋`GET /legacy-accounts/{legacyId}` > 實作確實存在（`migration-service` 8096，`#A-84`）。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **建立遷移作業** | 建立 W0–W4 波次之遷移作業 | `POST /migration-api/v1/migration-jobs` | `migrationType` **屬 5 種列舉**（`ACCOUNT`／`CARD`／`BALANCE`／`POINTS`／`MERCHANT`）；`sourceRef` 必填（來源資料集識別）；`waveCode` **屬 5 種列舉**（`W0`–`W4`，**W0＝試遷移**）；`dryRun` 選填（預設 false，**true＝試跑不動任何列**） | `OPS` | **201**：顯示 `jobId`／`waveCode`／`status`（`RUNNING`／`COMPLETED`／`FAILED`）／`dryRun`／processed／success／**errorCount**／`errorDetail` | `CC-MIG-1001`（422 業務規則）／`CC-MIG-3001`／`CC-MIG-3002`（409）／`CC-PLT-4003`（400） | | **查詢舊帳** | 查詢舊系統帳戶之對映與遷移狀態 | `GET /migration-api/v1/legacy-accounts/{legacyId}` | `legacyId` 必填 | `OPS`／`CSR` | **200**：顯示 `legacyId`／`accountNo`／`migrated`／`migratedAt`／snapshot（如實呈現 JSON） | `CC-PLT-4040`（404 查無） | | **清除** | 清空輸入與結果 | — | — | — | 表單與結果區重置 | — | **說明**： - ★ **`dryRun` 為試跑**（`#A-84`）：**不寫入任何列**、僅回報將處理之筆數與錯誤； 畫面須**明顯標示**「試跑（不動資料）」，避免誤以為已遷移。 - ★ **`waveCode=W0` 為試遷移波次**；未知波次（如 `W9`）後端回 422（`#A-84` 實測）。 - ★ **`errorCount`／`errorDetail` 必須如實顯示**（`#A-84`：`errorDetail` 為後端組裝之 失敗原因，如「200 筆缺出生日期」）——**不得**只顯示 successCount 而隱藏失敗 （「靜默不做」型假綠）。 - ⚠️ **`migrated=false` 之舊帳須如實顯示**（含 `migratedAt=null`）——畫面**不得** 將「未遷移」美化為任何完成狀態。 - **前端代理**：開發期 `/migration-api` 由 Vite 代理至 `migration-service:8096`。 --- ### 5.4.21　授權策略檢核（`/auth/policy`）——2026-09-23 補建（`C-14` 批次八；桶 C 解鎖） > **緣由**：`CR-021` 補實作 `GET /authorizations/{authNo}/check-results` 並真機驗證後， > 本頁自桶 C 解鎖。**明細為授權當下落庫之結果，查詢不重算**（`SCS-001 §7.5`）。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢檢核明細** | 逐項檢視授權檢核結果 | `GET /api/v1/authorizations/{authNo}/check-results` | `authNo` 必填（**授權編號**，如 `AUTH000035`） | 已認證 | **200**：逐項 `checkCode`／`result`（`PASS`／`FAIL`）／`reasonCode` 清單 | `CC-AUTH-4040`（404 查無授權） | | **清除** | 清空輸入與結果 | — | — | — | 表單與結果區重置 | — | **說明**： - ★ **檢核項目之揭露原則**：`CheckCode` 共 15 項，本期**僅 6 項具資料來源** （`AMOUNT`／`CURRENCY`／`CARD_STATUS`／`CARD_EXPIRY`／`MCC`／`LIMIT`—— 風控名單、CVV/EMV、地域/頻率等**無資料模型，不做假檢核**，`CSP-001 §8 B2`）。 畫面**如實顯示落庫之項目**，**不得**補畫未檢核之項目。 - ⚠️ **任一 `FAIL` 即授權拒絕**——回應碼取第一個失敗項（`SCS-001 §7.1`）； 畫面以徽章區分 `PASS`／`FAIL`，失敗項醒目顯示。 - **前端代理**：沿用 `/api`（8081，§5.4.1 已建）。 --- ### 5.4.22　沖正機制（`/switch/auth/reversal`）——2026-09-23 補建（`C-14` 批次八；桶 C 解鎖） > **緣由**：`CR-021` 補實作 `POST /authorizations/{authNo}/reversals` 並真機驗證 > （FULL 沖正：`AUTH000035` hold 25000 → `RELEASED`；重複沖正 → `CC-AUTH-3002`）。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢授權現況** | 沖正前先確認授權與佔用 | `GET /api/v1/authorizations/{authNo}` | `authNo` 必填 | 已認證 | **200**：顯示決策／佔用金額／holdId | `CC-AUTH-4040`（404） | | **執行沖正** | 釋放佔用並產生反向紀錄 | `POST /api/v1/authorizations/{authNo}/reversals` | `reversalType` **屬 2 種列舉**（`FULL`／`PARTIAL`；**FULL＝釋放原佔用全額**）；`PARTIAL` 必帶 `amount` 且 ≤ 未釋放餘額；`reason` 必填（≤200）；兩 header 必帶 | `OPS`／`FIN` | **200**：顯示 `authNo`／`type`／沖正金額／`holdReleased`／`reversedAt` | `CC-AUTH-3002`（409 **已沖正**）／`CC-AUTH-3001`（409 無佔用可沖、`PARTIAL` 未帶或超額）／`CC-AUTH-4040`（404）／`CC-LIM-1001`（422 額度側拒絕） | | **清除** | 清空輸入與結果 | — | — | — | 表單與結果區重置 | — | **說明**： - ★ **沖正＝新增反向紀錄，不修改原授權決策欄**（`SDD-005 §4` 轉換 4 同一原則； `SCS-001 §7.6`）——畫面顯示沖正結果，**原授權之 decision/respCode 照舊**。 - ★ **`reversed_at` 為終態標記**——重複沖正回 `CC-AUTH-3002`（409），畫面如實顯示。 - ⚠️ **雙軌釋放（`SCS-001 §7.6`）**：佔用可能為**遠端**（limit-service）或 **Stand-in 本地** （額度服務不可用時之降級）——後端「怎麼佔的就怎麼放」（遠端優先、失敗降級本地＋WARN）； 畫面**不需也無從**區分，如實呈現結果即可。 - ⚠️ **無佔用之授權（拒絕件）不可沖正**——`holdId` 為空回 `CC-AUTH-3001`，畫面如實顯示。 - **前端代理**：沿用 `/api`（8081）。 ### 5.4.23　離線授權與代授權（`/auth/stip`）——2026-09-24 補建（`C-14`；桶 C 解鎖） > **緣由**：`CR-022` 於 2026-09-24 裁定 `advices` 採 **(A) 後送**並實作＋真機驗證（**#A-98**）， > `§5.1.2.3` 原記「**語意待裁定，裁定前不造頁**」之該頁**隨之解鎖**。 > **併補後端（規格先行之連帶）**：查證發現 `SCS-001 §7.7` 定義之三職責中， > 「**查詢待補送佇列**」與「**批次手動上送**」**無端點可達**（實作僅有單筆之 > `POST …/{authNo}/advices`）→ 依「規格先行」**先立 `SCS-001 §7.7`（`CR-023`）** > → 改 `tools/gen_openapi.py` **重生契約**（77 端點、驗證 0 錯誤）→ **後實作端點** → 本節逐鈕定義 → 實作頁面。 **頁面定位**：Stand-in（離線授權／代授權）之**後送作業台**——維運／客服發現 「**本地代佔**與**額度權威**落差」時，查詢待補送清單並手動補送。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢清單** | 依狀態查待後送／已後送 | `GET /api/v1/authorizations/standin` | `status` **屬 3 種列舉**（`PENDING` 預設／`UPLOADED`／`ALL`）；`limit` 預設 20 | `OPS`／`CSR` | **200**：清單（`authNo`／決策／金額／幣別／`txTime`／`standinUploadAt`）——`standinUploadAt` 非空顯示**上送時間**、空則顯示「**待後送**」徽章 | 後端錯誤碼如實顯示 | | **單筆後送** | 對選取列立即上送 | `POST /api/v1/authorizations/{authNo}/advices` | 該筆須為 Stand-in 件（`standin_flag=1`）；`X-Channel`／`X-Idempotency-Key` **必帶** | `OPS` | **201**：顯示後送後之授權視圖；已上送者**冪等略過**並回報原上送時間 | `CC-AUTH-3001`（409 **非 Stand-in 件**）／`CC-AUTH-4040`（404）／額度服務不可用（500，**保留待後送**） | | **批次後送** | 手動觸發**一次**待補送上送（等同排程之一輪） | `POST /api/v1/authorizations/standin/advices?batchSize=50` | `batchSize` 預設 50；兩 header 必帶 | `OPS` | **201**：顯示**本次上送筆數**／**仍待上送筆數** | 遇錯**中斷本批**（已成功者已標記、其餘保留待後送） | | **重新整理** | 重新查詢清單 | 同「查詢清單」 | — | — | 清單更新 | — | **說明**： - ★ **待後送件不限於 `STANDIN` 決策**（`SCS-001 §7.7.1`）——轉人工（`REFERRAL`）與核准（`APPROVED`） 於**本地代佔**時 `standin_flag` **亦為 1**。畫面之「決策」欄**如實顯示**， 但**不得**以決策碼過濾清單（後端亦不以 `decision='STANDIN'` 篩選——否則**轉人工件被漏掉**）。 - ★ **`standin_flag` 之語意＝「該筆佔用未經額度服務確認」**——依**佔用方式**（`HoldResult.standIn`）判定， **非**決策碼（`§7.7.1`；此為 `#A-98` 真機實測揭露並修正之缺陷）。 - ⚠️ **後送失敗＝保留待後送**（`SCS-001 §7.4`：上送**不降級**、失敗即拋）—— 畫面**如實顯示錯誤且不樂觀更新**，該筆**仍留在清單**，由排程續試。 - ⚠️ **端點不取代排程**：本頁為「**現在就送**」之手動補位；`StandInUploadScheduler` 續行定時上送， 兩者**共用同一冪等守門**（`markStandInUploaded` 之 `standin_upload_at IS NULL` 條件）→ 重複後送**不會產生第二筆佔用**。 - ⚠️ **金額單位為分**——畫面須換算並標幣別（如 `250.00 TWD`）；金額右對齊（§6.1）。 - ⚠️ **本頁不提供「取消待後送」**——後送係收斂額度落差之**必要動作**，取消將使落差永久化； 如誤送，應以**沖正**（`/switch/auth/reversal`）處理，而非自佇列移除。 - **前端代理**：沿用 `/api`（8081）。 ### 5.4.24　健康檢查與監控（`/system/health`）——2026-09-29 補建（`C-14`；桶 C 解鎖） > **緣由**：`§5.1.2.3` 原記「**須先於 bff-web 新增健康聚合端點**方可實作」—— > 該端點已依 **`SCS-020 §9.8`** 完成**規格先行**（立規格 → 改 `gen_openapi.py` → > **重生契約 78 端點、0 錯誤** → 實作 → 本節逐鈕定義 → 頁面）。 **頁面定位（★ 回應 `§5.1.2.3` 之「本頁定位須先釐清」）**： 本頁為 **作業台**——維運人員之**即時總覽**（哪些服務 UP／DOWN）。 **不取代** Prometheus／Grafana 之**長期指標與告警**——瀏覽器畫面無法呈現歷史趨勢與告警規則。 → **頁面須明載此定位**，避免使用者誤解為「監控看板」。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢健康狀態** | 聚合全部服務之健康 | `GET /api/v1/bff/health` | 無參數 | `OPS`／`ADMIN` | **200**：顯示 `overall` 徽章（**`UP` 綠／`DEGRADED` 黃／`DOWN` 紅**）＋ `checkedAt` ＋ **逐服務清單**（服務名／狀態／`latencyMs`／失敗原因） | 後端錯誤碼如實顯示 | | **重新整理** | 重新查詢（**不快取**） | 同上 | — | — | 清單更新 | — | **說明**： - ★ **`overall` 三態**：`UP`（全 UP）／`DEGRADED`（**部分 DOWN**）／`DOWN`（全 DOWN）。 **空清單亦為 `DOWN`**——「沒有任何可探測對象」**不等於**「一切正常」（不樂觀預設，`CSP-001 §8 B2`）。 - ⚠️ **單一服務失敗不拖垮整體**（與 `BffSection` 同一降級政策）——失敗者標 `DOWN` 並帶原因， 其餘照常顯示。**畫面不得**因一服務失敗而整頁報錯。 - ⚠️ **不快取**——每次查詢即時探測（後端逾時 2 秒）；快取會顯示過期狀態，**比不顯示更危險**。 - ⚠️ **失敗原因如實呈現**（逾時／連線失敗／非 200）——**不得**以「未知」或樂觀值掩蓋。 - **服務清單**以 `bff.health.targets` 組態為準；**未組態者不列入**（新增服務時補組態即可，**不硬編**）。 - **前端代理**：`/api` → **8101**（bff-web）。 ### 5.4.25　稽核軌跡查詢（`/system/audit`）——2026-09-29 補建（`C-14`；桶 C 解鎖） > **緣由**：`§5.1.2.3` 原記「**表存在但無查詢端點**」—— > 端點已依 **`SCS-001 §7.9`** **規格先行**（立規格 → 改 `gen_openapi.py` → > **重生契約 79 端點、0 錯誤** → 實作 → 本節逐鈕定義 → 頁面）。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢軌跡** | 依事件類型查稽核軌跡 | `GET /api/v1/authorizations/audits` | `eventType` **屬 3 種列舉**（`ALL` 預設／`OVERRIDE`／`REVERSAL`）；`limit` 預設 20、**上限 200** | `OPS`／`ADMIN` | **200**：**統一時間軸**清單（`eventType`／`authNo`／`actor`／`action`／`amountMinor`／`reason`／`occurredAt`） | 後端錯誤碼如實顯示 | | **重新整理** | 重新查詢 | 同上 | — | — | 清單更新 | — | **說明**： - ★ **統一時間軸**：合併 `auth_overrides`（人工／強制核決，`§7.8`）與 `auth_reversals`（沖正，`§7.6`） 兩張 **append-only** 稽核表——使用者關心「**這筆授權發生過什麼**」，而非「它屬於哪張表」。 - ⚠️ **`actor` 之誠實揭露**：`auth_reversals` **無操作者欄位** → 沖正事件之 `actor` 為 `null`， 畫面須顯示「**未記錄**」，**不得**顯示空白或臆造值（`CSP-001 §8 B2`）。 - ⚠️ **append-only 唯讀**：本頁**不提供**修改／刪除——稽核紀錄**一旦可竄改即失去證據力**。 - ⚠️ **服務範疇（畫面須明載）**：本頁涵蓋**授權服務**之稽核軌跡； 其餘服務之稽核（`party` 管制碼異動、`card` 生命週期等）**尚無查詢端點**， 待各自就緒後擴充（`C-46`）——**不得**讓使用者誤以為這是「全系統稽核」。 - **前端代理**：沿用 `/api`（8081）。 ### 5.4.26　批次作業監控（`/system/batch`）——2026-09-30 補建（`C-14`；桶 C 解鎖） > **緣由**：`§5.1.2.3` 之桶 C「批次作業監控」—— > 端點已依 **`SCS-020 §9.9`** **規格先行**（立規格 → 改 `gen_openapi.py` → > **重生契約 81 端點、0 錯誤** → 實作 → 本節逐鈕定義 → 頁面）。 > 🔄 **2026-09-30 補**（`HANDOVER #A-104`）：⚠️ **四個來源端點原不存在**——實測**只有 `POST`** > （`GET` 回 405／404／404／404）→ 已**先行新增四支 `GET` 列表端點** > （`SCS-011 §6.1`／`SCS-013 §6.1`／`SCS-015 §6.1`／`SCS-017 §6.1`；契約 **85 端點、0 錯誤**）。 > `limit` 參數亦補宣告（**每服務**上限，預設 10／上限 50）。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢批次** | 聚合四服務之批次執行紀錄 | `GET /api/v1/bff/batch-jobs?limit=N` | `limit` 可選：**每服務**筆數上限，**1..50**（預設 10）；越界回 **400 `CC-PLT-4003`** | `OPS`／`ADMIN` | **200**：清單（`jobType`／`service`／`jobId`／**`status`（原始）**／**`statusGroup`**／筆數／時間／摘要）；依 `startedAt` 遞減 | 後端錯誤碼如實顯示；**個別服務失敗**以 `unavailable[]` 呈現，**不使整頁報錯** | | **重新整理** | 重新查詢 | 同上 | — | — | 清單更新 | — | **說明**： - ★ **統一狀態分組（本頁核心）**——四服務之原始狀態值域**各不相同**： | 分組 | 原始狀態 | 語意 | |---|---|---| | `PENDING` | `QUEUED` | 已排入、尚未開始 | | `RUNNING` | `GENERATING`／`RUNNING` | 執行中 | | `SUCCEEDED` | `GENERATED`／`MATCHED`／`COMPLETED` | 成功完成 | | **`WARNING`** | **`DIFFERENCE`** | **完成但有差異**（對帳不平） | | `FAILED` | `FAILED` | 失敗 | | `UNKNOWN` | 未定義值 | **如實標示，不臆造歸類** | - ⚠️ **`DIFFERENCE` 不可歸為 `SUCCEEDED`**——對帳有差異之批次**帳務上不等於成功**， 歸為成功會使差異被忽略（**假綠**）。 - ⚠️ **原始狀態與分組並存**——畫面**兩者皆顯示**（分組供篩選／排序，原始狀態為準）。 - ⚠️ **`unavailable[]` 須明顯呈現**——某服務查詢失敗時，**不得**讓使用者誤以為「該服務沒有批次」。 - ⚠️ **服務未回傳之欄位留空**（如 `clearing` 無 `processedCount`）——**不以 0 填充**。 - ⚠️ **僅監控**——本頁**不提供**觸發或中止批次（那屬各服務之職責與權限）。 - **前端代理**：`/bff-api` → 8101（bff-web）。 ### 5.4.27　端點與連線管理（`/system/endpoints`）——2026-09-30 補建（`C-14`；桶 C 解鎖） > **緣由**：`§5.1.2.3` 之桶 C「端點與連線管理」—— > 端點已依 **`SCS-020 §9.10`** **規格先行**並實作。 > 併依 `§5.1.1`：原型之「網路連線管理（拓樸／主機連線／容錯切換）」**已由本頁涵蓋**（判定為重疊）。 > 🔄 **2026-09-30 補**（`HANDOVER #A-103`）：⚠️ **原設計之 `/actuator/gateway/routes` 於本技術棧版本 > 未被註冊**（實測 `/actuator` 索引僅 7 個）→ 已改由 `api-gateway` 自供唯讀端點 > **`GET /api/v1/gateway/routes`**；真機驗證 **`routesAvailable=true`**（修正前為 `false`）、17 筆路由。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢端點與連線** | 聚合 gateway 路由 ＋ 各服務連線 | `GET /api/v1/bff/endpoints` | 無參數 | `OPS`／`ADMIN` | **200**：**路由清單**（`routeId`／`service`／`uri`／`predicates`）＋ **連線清單**（`service`／`status`／`latencyMs`／`error`） | 後端錯誤碼如實顯示；**其一失敗不影響另一者** | | **重新整理** | 重新查詢 | 同上 | — | — | 清單更新 | — | **說明**： - ★ **兩個維度並列才完整**——**端點（路由）**＝服務之入口（gateway）；**連線（狀態）**＝目標服務是否連得上。 只看路由不知通不通；只看健康不知入口在哪。 - ⚠️ **其一取不到不影響另一者**——gateway 掛掉時連線狀態照常呈現（並以 `routesAvailable=false` ＋ `routesError` **如實標示**），反之亦然。 - ⚠️ **僅呈現狀態**——**不提供「容錯切換」操作**：切換屬維運程序（gateway `refresh`／部署流程）， **不由作業台直接觸發**（避免誤觸造成路由中斷）。 - ⚠️ **`predicates` 為原文透傳**（如 `Path=/auth-api/**`）——不解析為結構化欄位。 - ⚠️ **`service` 由 `routeId` 推導**；**無法對映者保留 `routeId` 原文**（**不臆造**）。 - ⚠️ **不涵蓋非 HTTP 連線**（DB／Kafka／Redis）——那屬各服務 `/actuator/health` 細部與 Prometheus 範疇。 - **前端代理**：`/bff-api` → 8101（bff-web）。 --- ### 5.4.28　營運總覽（`/dashboard`）——2026-10-01 補建（`C-14`；桶 C 解鎖） > **緣由**：`SDD-007 §5.1.2.3` 之桶 C「**營運總覽**」（`/dashboard`）——原記 > 「**跨服務聚合**——須先於 `bff-web` 立聚合端點」。 > **BEAM PMO 2026-10-01 裁定**採「**挑投報率最高者，先補後端、再規格先行、再實作**」——本頁為選定目標。 > **規格先行**：`SCS-020 §9.11`（端點規格）→ 改 `tools/gen_openapi.py` → 重生契約 > （**87 端點、0 錯誤**）→ 實作 → 本節逐鈕定義 → 頁面。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **載入／重新整理** | 取得營運總覽摘要 | `GET /bff-api/v1/bff/dashboard` | 無參數；**進入頁面即自動載入** | 全部角色（`§5.2`「儀表板」列：**9 角色皆 ✅**） | **200**：顯示**三區塊摘要**（服務健康／批次作業／端點連線）與 `checkedAt` | 各區塊**獨立降級**（見下） | **說明**： - ⚠️ **★ 本頁範圍：系統營運面**（`SCS-020 §9.11.1`）——呈現**服務健康／批次作業／端點連線**之**摘要**。 **業務 KPI**（發卡量／授權量／待辦件數）**不在本版**：經查 **17 個領域服務皆無統計端點**（僅 CRUD 與列表）， 須先由各服務提供（**第二階段**）。→ **畫面須明載此範圍**，避免被誤認為「業務儀表板已交付」。 - ⚠️ **★ 三區塊獨立降級，不以 0 充數**： - 區塊聚合失敗 → 後端回 **`null`** → 畫面須顯示「**不可用**」，**不得**顯示 `0`。 - 「**取不到**」與「**真的是 0**」是**不同事實**（`CSP-001 §8 B2`）。 - 例：`endpoints.routes` 為 `null`（gateway 路由查詢失敗）時，**不得**顯示「0 條路由」。 - ⚠️ **★ `batch.unknown` 必須顯示**——服務回傳**未定義狀態**時如實歸此； **略過會使計數總和對不上並掩蓋異常**（`SCS-020 §9.9.2`）。 - ⚠️ **本頁為「摘要層」，不取代三頁「明細層」**（`SCS-020 §9.11.4`）： `/system/health`（逐服務明細）／`/system/batch`（逐筆批次）／`/system/endpoints`（逐條路由）。 畫面應提供**連結**導向該三頁，**不重複**其實作。 - ⚠️ **定位為「作業台即時總覽」**——**不取代** Prometheus／Grafana 之長期指標與告警（同 `§5.4.24`）。 畫面須**明載**此定位。 - **不快取**——每次載入即時彙整（快取會使畫面顯示過期狀態，比不顯示更危險）。 - ⚠️ **不得**在畫面上提供「業務 KPI」之**假佔位**（如顯示「0 張新卡」）——**沒有就是沒有**。 - **前端代理**：`/bff-api` → 8101（bff-web）。 --- ### 5.4.29　交易狀態機檢視（`/switch/auth/state`）——2026-10-01 補建（`C-14`；桶 C 解鎖） > **緣由**：`SDD-007 §5.1.2.3` 之桶 C「**交易狀態機與冪等**」（`/switch/auth/state`）——原記「均無端點」。 > **規格先行**：`SCS-001 §7.11`（端點規格）→ 改 `tools/gen_openapi.py` → 重生契約 → 實作 → 本節逐鈕定義 → 頁面。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢** | 查某授權之狀態機視圖 | `GET /api/v1/authorizations/{authNo}/state` | `authNo` **必填**、非空 | 全部角色（`§5.2`「授權作業」列） | **200**：顯示當前狀態、佔用、狀態轉移歷程 | 查無 → **404**（顯示錯誤碼） | **說明**： - ⚠️ **★ 狀態機視角，非事件時間軸**：本頁聚焦「**這一筆**授權現在的狀態與其轉移歷程」； `/system/audit`（`§5.4.25`）為「**所有**授權之核決／沖正事件統一時間軸」——**兩者互補、不重複**。 - ⚠️ **★ 佔用為 `null` 時如實顯示「無佔用」**——**不得**顯示 `0`（「沒有佔用」與「佔用 0 元」是不同事實）。 - ⚠️ **★ 冪等如實揭露**：`X-Idempotency-Key` 之冪等由 **API 層**（Redis）保證、**未落 Oracle** → 本頁**不顯示**冪等明細；畫面須**明載**「冪等由 API 層保證，本頁不重現」（**不臆造欄位**）。 - ⚠️ **狀態值域**：`APPROVED`／`DECLINED`／`REFERRAL`／`STANDIN`（DDL CHECK 4 值）——**後端回什麼就顯示什麼**。 - **轉移歷程**：由 `created_at`（`AUTHORIZED`）／`override_at`（`OVERRIDDEN`）／`reversed_at`（`REVERSED`） **權威時間欄**推導；**不以 `decision` 反推**（避 `SCS-001 §7.7.1` 同型缺陷）。 - **不快取**——每次查詢即時。 - **前端代理**：`/api` → 8081（authorization-service）。 --- ### 5.4.30　分流比例管理（`/system/split-ratio`）——2026-10-01 補建（`C-14`；桶 C 解鎖） > **緣由**：`SDD-007 §5.1.2.3` 之桶 C「**分流比例管理**」（`/system/split-ratio`）——原記「**僅 actuator**」。 > **規格先行**：`SCS-020 §9.12`（端點規格）→ 實作 → 本節逐鈕定義 → 頁面。 > **機制早已存在**（`SAD-004 §2.4`；POC-13 已驗收），本頁補的是**管理面**。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **重新整理** | 讀取當前生效之分流組態 | `GET /api/v1/gateway/split-ratio` | — | 全部角色（唯讀） | **200**：顯示 `enabled`／`percentage`／`legacyUri`／`merchantHeader`／`pathPrefix`／`configFile`／`configFileWritable` | 失敗 → 顯示錯誤碼 | | **套用變更** | 調整啟用狀態與比例 | `PUT /api/v1/gateway/split-ratio` | `percentage` **必填**、**整數 0–100** | 維運（⚠️ **角色級授權未實作**，見下） | **200**：顯示**回讀後**之生效值；`effectiveMatchesRequest=true` | 範圍外 → **400** `CC-PLT-4003`；寫檔／refresh 失敗 → **500** `CC-PLT-5000` | | **快速回退（比例歸零）** | 一鍵回退至全舊系統（`SAD-004 §2.4` POC-13-6） | `PUT /api/v1/gateway/split-ratio`（`percentage=0`） | 同上 | 同上 | 同上 | 同上 | | **全量上線（比例 100）** | 一鍵切至全量新系統（波次 W4） | `PUT /api/v1/gateway/split-ratio`（`percentage=100`） | 同上 | 同上 | 同上 | 同上 | **說明**： - ★ **「快速回退」與「全量上線」為一鍵操作**——`SAD-004 §2.4` 明訂「**回退＝比例調回 0**」， 事故處置時**不應要求維運手動輸入數字**（少一次出錯機會）。 - ⚠️ **★ 顯示「回讀後之生效值」，非「請求值」**：後端於寫檔 ＋ refresh 後**重讀** `CycleSplitProperties`；`effectiveMatchesRequest=false` 時畫面須**明顯呈現 `warning`** ——**不以請求值冒充生效值**（`SCS-020 §9.12.3 #4`）。 - ⚠️ **★ `configFileWritable=false` 時**：畫面須**預先**停用「套用變更」並說明原因 （**不讓維運白試一次**）——見 `SCS-020 §9.12.2`。 - ⚠️ **★ 比例語意如實標示**：`percentage`＝**新系統承接比例**；`0`＝全舊、`100`＝全新； **未帶 `X-Merchant-Id` 之請求於比例 < 100 時一律走舊系統**（保守可回退，`SAD-004 §2.4`）—— 畫面須以說明文字呈現，**不得**簡化為「0% 等於關閉分流」。 - ⚠️ **★ 免責揭露（誠實）**：本頁**只改本實例**之 `cycle-split.yml`； **多實例部署時各實例須自行同步**（`SCS-020 §9.12.5`）——畫面須明載。 - **不快取**——每次查詢／套用皆為即時。 - **前端代理**：`/gateway-api` → `api-gateway:8100`（**開發期**；正式環境統一由閘道出口）。 --- ### 5.4.31　歸戶 360（`/accounts`）——2026-10-01 補建（`CR-032`） > **緣由**：`CR-031 §4.5`／`SAD-004 §2.2.1.1` 誠實揭露「`BffAccountOverview` **尚無前端消費者**」。 > 本頁即該缺口之**閉環**：`#A-143`（事件投影）→ `#A-144`（BFF 四區塊聚合）→ **本頁（呈現）**。 > **規格先行**：`CR-032`（計畫）→ 本節（逐鈕）→ 實作 → 頁面。 > ⚠️ **無契約變更、無後端變更**——聚合端點已於 `#A-144` 就緒。 | 按鈕／操作 | 功能 | 觸發端點 | 檢核規則 | 所需角色 | 成功回饋 | 失敗回饋 | |---|---|---|---|---|---|---| | **查詢** | 取得該歸戶之**四區塊**跨域總覽 | `GET /bff-api/v1/bff/accounts/{accountId}/overview` | `accountId` 須為 **UUID** | **`CSR`** | **200**：四個區塊**各自**依 `status` 呈現（見下表）；**部分失敗仍為 200** | 非 UUID → **400 `CC-PLT-4003`**；未登入 → **401** | | **清除** | 清空輸入與結果 | — | — | `CSR` | 表單重置、結果區塊移除 | — | **四區塊之呈現規則**（`BffAccountOverview`；`SAD-004 §2.2.1`） | 區塊 | 資料來源（BFF 下游） | `OK` 時顯示 | `UNAVAILABLE` 時顯示 | |---|---|---|---| | `party` | `party-service`（歸戶主檔＋`parties[]`） | 歸戶帳號／CIF／類型／管制碼／帳單週期／狀態＋**持卡人清單** | **不可用** ＋ 下游錯誤碼／訊息 | | `cards` | `party-service`（**卡片狀態投影**；`SCS-004 §7.5`） | 卡片清單（**卡號遮罩**／狀態／管制碼／有效期）；空陣列 →「**此歸戶尚無卡片**」 | **不可用** ＋ 下游錯誤碼／訊息 | | `limits` | `limit-service` | 永久／暫時／彈性／已用／佔用中／可用額度與幣別 | **不可用** ＋ 下游錯誤碼／訊息 | | `rewards` | `rewards-service` | 三層點數（CUR／AV1／AV2）餘額、最近到期日、總點數 | **不可用** ＋ 下游錯誤碼／訊息 | **說明**： - ★★ **降級呈現為本頁最重要之規則**：四區塊**各自獨立降級**（單一下游失敗**不拖垮**其餘）。 `UNAVAILABLE` **必須明顯呈現並帶下游錯誤碼**—— **嚴禁**以 `0`、`-`、空白表格代替。**「取不到」與「真的是 0／空」是兩種不同事實**： 額度取不到卻顯示 `0`，會讓客服誤判客戶無額度（此為 `SCS-020 §9.11` 同一原則之延伸）。 - ★ **空狀態 vs 不可用必須區分**： `cards` 為 `OK` 且 `[]` →「**此歸戶尚無卡片**」（**合法狀態**，`SCS-004 §7.5`）； `cards` 為 `UNAVAILABLE` →「**不可用**：`CC-PTY-4040` 查無歸戶」（**失敗**）。 - **PII／PCI**：卡號僅顯示**遮罩值**（`cardNoMasked`，**不含 PAN**）；歸戶／持卡人之 PII 一律顯示**後端回傳之遮罩值**，前端**不解密、不自行遮蔽**（`SAD-005 §5`）。 - **唯讀**：本頁**不做任何異動**；卡片狀態異動屬 `/card/lifecycle`、額度調整屬 `/limit-adjustments`、 點數屬 `/rewards`、貼標／管制碼屬 `/parties`——各區塊附「**異動請至〈頁名〉**」之文字指引。 - **與 `§5.4.3`（`/parties`）之分工**：`§5.4.3` 為 **party 域作業頁**（**有寫入**；直呼 `party-service`）； 本頁為**跨域唯讀總覽**（走 **BFF 聚合**）。兩頁**皆顯示**歸戶主檔與持卡人清單係**刻意**—— 總覽須自足，否則使用者仍要跳頁。 - ⚠️ **誠實揭露**：本頁**超出** `SDD-007 §5.1` 之 **59 頁**清單 （先例：`/limit-adjustments`）——為**第 2 頁**超出者。 - **不快取**——BFF 每次查詢皆為真實下游呼叫；本頁**不做自動輪詢**（僅「查詢」鈕觸發）。 - **前端代理**：`/bff-api` → `bff-web:8101`（**開發期**；正式環境統一由閘道出口）。 --- ## 6. 元件規範 ### 6.1 資料表（DataTable） | 特性 | 規範 | |---|---| | 欄位定義 | 由頁面設定（`columns`）驅動，不硬寫 | | 排序 | 點欄頭排序；預設依業務日期降冪 | | 分頁 | 伺服器端分頁（`page`／`size`） | | 載入中 | 骨架列（skeleton） | | 空資料 | 顯示「查無資料」與查詢建議 | | 錯誤 | 顯示錯誤碼與重試按鈕 | | 列點擊 | 開啟明細抽屜 | | 欄位對齊 | 金額**右對齊**、文字左對齊、狀態置中 | | 金額顯示 | 千分位 + 幣別（如 `1,234,567 TWD`） | | 狀態徽章 | 依語意色（見 §3.1） | ### 6.2 查詢列（Filter Bar） | 規範 | 說明 | |---|---| | 條件數 | 最多 6 個常用條件置於主列，其餘收於「進階查詢」 | | 預設值 | 日期區間預設為近 7 日 | | 查詢 | 按「查詢」才發出請求（不做即時查詢，避免壓力） | | 重置 | 一鍵清除條件 | | 匯出 | 依權限顯示，匯出須留稽核軌跡 | ### 6.3 明細抽屜（Detail Drawer） | 規範 | 說明 | |---|---| | 位置 | 右側滑出，寬 480px（大螢幕 560px） | | 欄位 | 由 `detailFields` + `detailLabels` 驅動 | | 分組 | 依業務分組（基本資料／金額／狀態／軌跡） | | 操作 | 依狀態與權限顯示可用動作（不顯示不可用動作） | | 軌跡 | 顯示該資源之異動軌跡（呼叫稽核 API） | ### 6.4 狀態徽章（Badge） | 語意 | 樣式 | |---|---| | 成功 | 綠底淺色 + 綠字 | | 警告 | 橙底淺色 + 橙字 | | 危險 | 紅底淺色 + 紅字 | | 中性 | 灰底淺色 + 灰字 | ### 6.5 KPI 卡與圖表（儀表板） | 元件 | 規範 | |---|---| | KPI 卡 | 標籤、數值、與前期比較（↑↓） | | 折線／長條圖 | 自繪 SVG，含座標軸與圖例 | | 圓餅／環圖 | 類別不超過 6 項 | | 資料來源 | **一律來自 API**，禁止前端計算或寫死 | | 更新 | 每 60 秒輪詢（可設定） | ### 6.6 表單驗證 | 規範 | 說明 | |---|---| | 即時驗證 | 失焦時驗證 | | 錯誤顯示 | 欄位下方紅字 + 紅框 | | 必填標示 | 標籤後加 `*` | | 送出 | 驗證通過才送出；送出中禁用按鈕避免重複 | | 冪等鍵 | 每次表單提交產生新 `X-Idempotency-Key` | --- ## 7. 多國語系 | 項目 | 規範 | |---|---| | 支援語系 | `zh-TW`（預設）、`en-US` | | 資源檔 | `src/i18n/zh-TW.json`、`src/i18n/en-US.json` | | Key 命名 | `.
.`（如 `card.limit.title`） | | 缺漏處理 | 開發環境顯示 key；生產環境回退至 `zh-TW` | | 日期格式 | 依語系（`zh-TW`：`2026/09/17`；`en-US`：`09/17/2026`） | | 數字格式 | 千分位依語系 | | 語系切換 | 頁首切換，持久化於 `localStorage` | | 覆蓋率 | 資源檔 key 覆蓋率 **100%**（建置時檢查） | --- ## 8. 響應式設計 | 斷點 | 寬度 | 版式 | |---|---|---| | 桌機 | ≥ 1280px | 側欄展開、明細抽屜並排 | | 筆電 | 1024–1279px | 側欄收合、明細抽屜覆蓋 | | 平板 | 768–1023px | 側欄為抽屜、表格橫向捲動 | | 手機 | < 768px | 側欄為全螢幕選單、表格改卡片式 | > 本系統為**營運後台**，主要使用情境為桌機；手機版僅需可查詢與核准。 --- ## 9. API 串接規範 ### 9.1 分層 ```mermaid flowchart LR P["頁面元件"] --> H["Hook
useCards / useLimits"] H --> Q["TanStack Query
快取 / 重試 / 失效"] Q --> C["API Client
攔截器 / 信封解析"] C --> GW["API 閘道"] ``` ### 9.2 規則 | 編號 | 規則 | |---|---| | FE-01 | **禁止**在前端產生或內建任何業務資料（mock／fixture／隨機產生） | | FE-02 | 所有資料來自 API；**禁止**在前端做業務計算（金額、點數、費率） | | FE-03 | 統一由 API Client 處理信封（`traceId`／`data`／`error`） | | FE-04 | 錯誤依 `error.code` 顯示對應訊息（i18n），並記錄 `traceId` | | FE-05 | 寫入操作自動產生 `X-Idempotency-Key`（UUID v7） | | FE-06 | 所有請求帶 `X-Channel`、`Accept-Language` | | FE-07 | 401 自動導向登入；403 顯示無權限頁 | | FE-08 | 429 依 `Retry-After` 退避重試 | | FE-09 | 金額一律以整數分傳輸與顯示換算，**禁止**浮點運算 | | FE-10 | 敏感欄位依後端回傳之遮罩值顯示，**前端不得自行還原** | ### 9.3 反模式禁令（對應 `GOV-003 §6.2`） **禁止**出現下列程式碼樣態： | 樣態 | 範例 | 掃描規則 | |---|---|---| | 內建資料產生器 | `const DATA = { gen: () => [...] }` | 掃描 `gen(`、`mockData`、`fixture` | | 隨機資料 | `Math.random()` 用於業務欄位 | 掃描 `Math.random` | | 假統計 | 儀表板數值字面量 | 掃描 KPI 元件內數值常數 | | 假延遲 | `setTimeout` 模擬 API | 掃描 `setTimeout` 於 api 層 | | 寫死選項 | 狀態選項硬寫於元件 | 掃描元件內狀態陣列（應來自參數 API） | **允許**：`src/i18n/*.json`（語系資源）、`src/theme/tokens.css`（設計 Token）、 `src/config/*.json`（**非業務**之前端設定，如輪詢間隔）。 --- ## 10. 前端測試規範 | 類型 | 範圍 | 覆蓋率要求 | |---|---|---| | 單元測試 | 工具函式、格式化、驗證 | ≥ 90% | | 元件測試 | 各元件之渲染與互動 | ≥ 80% | | Hook 測試 | 資料取得與錯誤處理 | ≥ 80% | | 整合測試 | 頁面層級（含 API 模擬） | 主要流程 100% | | 無障礙測試 | 鍵盤操作、對比度、標籤 | 主要頁面 100% | > 元件測試之 API 以 **MSW（Mock Service Worker）** 攔截， > 屬**測試替身**，僅存在於測試程式碼，**不得進入生產建置** > （`GOV-003 §6.2` 白名單）。 --- ## 11. 檢核 | 檢核項 | 標準 | |---|---| | 頁面清單與權限矩陣 | 45 頁 × 9 角色，100% 定義 | | 設計 Token 一致 | 100% 使用 CSS 變數 | | 多國語系覆蓋 | 100% | | 響應式斷點 | 4 個斷點皆通過 | | 無 mock／假資料 | 掃描 0 筆 | | API 契約一致 | 前端型別由 OpenAPI 產生 | | 無障礙 | 主要頁面 WCAG AA 通過 | --- ## 12. 修訂記錄 | 版本 | 日期 | 說明 | |---|---|---| | 1.27 | 2026-10-01 | **§5.4.31 歸戶 360（`/accounts`）補建**（`CR-032`；`#A-145`）——①**緣由**：`CR-031 §4.5`／`SAD-004 §2.2.1.1` **誠實揭露**「`BffAccountOverview` 尚無前端消費者」（**有能力、沒人用**）→ 本節即該缺口之**閉環**：`#A-143`（事件投影）→ `#A-144`（BFF 四區塊聚合）→ **本頁（呈現）**。②**無契約變更、無後端變更**——聚合端點已於 `#A-144` 就緒（`gen_openapi.py` 已納入 `cards`）。③★ **設計要點**：**降級呈現為本頁最重要規則**——四區塊**各自獨立降級**（單一下游失敗不拖垮其餘），`UNAVAILABLE` **必須明顯呈現並帶下游錯誤碼**，**嚴禁以 `0`／`-`／空白代替**（**「取不到」與「真的是 0」是兩種不同事實**——額度取不到卻顯示 `0` 會讓客服誤判；此為 `SCS-020 §9.11` 同一原則之延伸）；**空狀態 vs 不可用必須區分**（`cards` `OK` 且 `[]` ＝「尚無卡片」／`UNAVAILABLE` ＝「不可用」）；**唯讀**（卡片異動／額度／點數／貼標各指引至對應作業頁）；**PII／PCI**（卡號僅遮罩，**不含 PAN**）；**不快取**、**不自動輪詢**。④**選頁理由**：**新頁**而非併入 `§5.4.3`——職責（作業 vs 總覽）與**存取路徑**（`/party-api` 直呼 vs `/bff-api` 聚合）皆不同，一頁兩路徑會使快取／錯誤／權限語意混雜。⑤**角色** `CSR`（取四下游之最嚴者）。⑥⚠️ **誠實揭露**：本頁**超出 `§5.1` 之 59 頁清單**（**第 2 頁**超出者，先例 `/limit-adjustments`）。⑦**併修本表漏列之 1.26**（見下） | | 1.26 | 2026-10-01 | **§5.4.30 分流比例管理（`/system/split-ratio`）補建——桶 C 解鎖**（`#A-120`）——①**緣由**：`§5.1.2.3` 桶 C 該頁原記「**僅 actuator**」。②**選頁理由**：`SAD-004 §2.4` 之分流機制（POC-13 已驗收）**完整存在**，缺的**只是管理面**——不需新領域模型、不會造空殼；且「**灰度放量與回退**」為遷移期**最高頻**之維運操作。③**規格先行**：`SCS-020 §9.12` → 實作（gateway 自供 `GET`／`PUT /api/v1/gateway/split-ratio`）→ 本節逐鈕定義 → 頁面。④**規格要點**：定點行替換（**保留註解**）／`ContextRefresher` **熱更新**／**回讀驗證**（`effectiveMatchesRequest`——**不以請求值冒充生效值**）／失敗**不靜默**（`CC-PLT-5000`）／**一鍵回退**（比例歸零，事故處置不要求手輸數字）／**`configFileWritable=false` 時預先停用**。⑤**桶 C 29 → 28、已實作 19 → 20**（合計仍 **59 ✅**）。⚠️ **本列為 2026-10-01 補記**——版本列早已載 1.26，惟本表**漏列**（**「已做卻漏記」型缺陷**，與 1.2／1.3／1.21 同型） | | 1.25 | 2026-10-01 | **§5.4.29 交易狀態機檢視（`/switch/auth/state`）補建（桶 C 解鎖）**——①**緣由**：`§5.1.2.3` 桶 C「交易狀態機與冪等」原記「均無端點」。②**選頁理由**：`C-46` 建議延續 `authorization-service`；授權狀態機為本專案**建模最完整**之狀態機（`SCS-001 §3.2`／`SDD-005`）；來源資料全在 Oracle（`authorizations`＋`limit_holds`），免新領域模型。③**規格先行**：`SCS-001 §7.11`（`GET /api/v1/authorizations/{authNo}/state`）→ 改 `gen_openapi.py` → 契約 → 實作 → 本節逐鈕定義 → 頁面。④**規格要點**：**狀態機視角 vs `§5.4.25` 事件時間軸**（互補不重複）／**不以 `decision` 反推**核決／沖正（用 `override_at`／`reversed_at` 權威時間欄）／**佔用 `null` 如實顯示**／**冪等（Redis）如實揭露、不重現**（不臆造欄位）。⑤**桶 C 30 → 29** | | 1.24 | 2026-10-01 | **§5.4.28 營運總覽（`/dashboard`）補建（桶 C 解鎖）**——①**緣由**：`§5.1.2.3` 桶 C「營運總覽」原記「須先於 `bff-web` 立聚合端點」；**BEAM PMO 2026-10-01 裁定**採「挑投報率最高者，先補後端、再規格先行、再實作」→ 本頁為選定目標。②**規格先行**：`SCS-020 §9.11`（新端點 `GET /api/v1/bff/dashboard`）→ 改 `tools/gen_openapi.py` → **重生契約 87 端點、0 錯誤** → 實作（`BffDashboard`／`DashboardAggregationService`／`DashboardSourcesPort`＋`DashboardSourcesAdapter`／`BffDashboardController`）→ 本節逐鈕定義 → 頁面（`DashboardConsole.tsx`）。③**★ 範圍界定（回訪查證之結論）**：掃全數 **17 服務**契約，**皆無統計端點** → **業務 KPI 無法由既有端點推得** → **本版明訂為「系統營運面」**（服務健康／批次／端點連線之摘要）；**業務 KPI 屬第二階段**（需各服務統計端點，另立 CR）。④**規格要點**：**複用**既有三個聚合服務（**不重複探測**）、**並行**執行、**三區塊獨立降級**（失敗區塊為 `null`，**不以 0 充數**）、**不快取**、**fail-closed**；**`batch.unknown` 必須計入**（略過會使總和對不上）。⑤**真機驗證**：`services` **4/17 UP → `DEGRADED`**、`batch.unavailable=4`、**`endpoints.routes=null`**（gateway 查詢失敗 → **不以 0 充數**，如實呈現）；SSO 開啟時未帶 token → **401**（fail-closed）。⑥**測試**：`:platform:bff-web:test` **12 → 17 測 0 失敗**（新增 5 測）；側欄 **26 → 27 頁** | | 1.23 | 2026-10-01 | **桶 B 擴充：`/onboarding/review`／`/onboarding/approval` 移入（BEAM PMO 裁定）**——①**緣由**：重盤揭露該兩頁之核心流程**已由 `§5.4.9` 進件作業台涵蓋**（狀態機 `RECEIVED→REVIEWING→SUPPLEMENT→APPROVED/REJECTED` 完整；`REQUEST_SUPPLEMENT`／`COMPLETE_SUPPLEMENT`／`APPROVE`／`REJECT` 皆已實作並真機驗證）；②**裁定**：BEAM PMO 2026-10-01 裁定「**移桶 B**」→ **桶 B 9 → 11、桶 C 33 → 31**（合計仍 59 ✅）；③**差異項之處理**：「**照會記錄**」與「**製卡送件**」**無端點** → **另立 CR 補端點**，**不另造重複頁**（避免同一功能兩套 UI 漂移） | | 1.22 | 2026-09-30 | **桶 C 就緒度重盤（產出修正後清單）**——①**頁數修正**：`§5.1` 標題原載「14 群 **60 頁**」與表列**不符**，逐列實測為 **59 頁**（差異 1 頁疑為 `v1.9` 補列時之計數誤差）；②**桶 C 修正**：`§5.1.2.3` 原記 **34 頁**且清單**仍含已解鎖之 11 頁**（`§5.4.10`～`§5.4.13`、`§5.4.21`～`§5.4.27`——**皆已實作**）→ 重盤後**實餘 33 頁**；③**三桶重算**：桶 A **6**（已全數完成 ✅）／桶 B **9**／桶 C **33**，**合計 59 ✅**（附「重盤總表」確保 59 頁全數歸類、無遺漏）；④**逐頁就緒度實測**（掃 `contracts/openapi/*.yaml`）：33 頁**均確認無對應語意端點**；⑤**揭露待裁定項**：`/onboarding/review`、`/onboarding/approval` 之核心流程**已由 `§5.4.9` 進件作業台涵蓋**（狀態機 `RECEIVED→REVIEWING→SUPPLEMENT→APPROVED/REJECTED` 完整）→ **是否移桶 B 待 BEAM PMO 裁定**（本次**暫留桶 C**，不擅自改判）；⑥**併補 `v1.21` 之修訂記錄**（版本欄有 1.21 而本表漏列——**又一次「已做卻漏記」**） | | 1.21 | 2026-09-30 | **桶 C 兩頁之來源端點補齊 ＋ 前端實作**——`§5.4.26 批次作業監控`／`§5.4.27 端點與連線管理`。⚠️ **實測揭露**：`§5.4.26` 之四個來源端點**原不存在**（僅有 `POST`，`GET` 回 405／404／404／404）→ 已**先行新增四支 `GET` 列表端點**（`SCS-011／013／015／017 §6.1`）並補宣告 `limit`（**每服務**上限，預設 10／上限 50）；`§5.4.27` 之 `/actuator/gateway/routes` **於本技術棧版本未註冊** → 改由 gateway 自供唯讀端點（`#A-103`）。前端新增 `pages/BatchConsole.tsx`／`pages/EndpointConsole.tsx`，側欄 **24 → 26 頁** | | 1.20 | 2026-09-29 | **§5.4.25 稽核軌跡查詢（`/system/audit`）補建（桶 C 解鎖）**——①**緣由**：`§5.1.2.3` 原記「**表存在但無查詢端點**」；端點已依 **`SCS-001 §7.9`**（`CR-025`）完成**規格先行**（立規格 → 改 `gen_openapi.py` → **重生契約 79 端點、0 錯誤** → 實作）。②**規格要點**：**統一時間軸**（兩表 `UNION ALL`）／`action` 值域正規化／**`actor` 對沖正如實回 `null`**／**append-only 唯讀**／**服務範疇須明載**（僅授權服務）。③**實作**：`api/authorizations.ts`＋`pages/AuditConsole.tsx`；側欄 **23 → 24 頁**。**真機**：`ALL` **4 筆**正確排序、`OVERRIDE`／`REVERSAL` 各 2 筆、null 欄位如實 | | 1.19 | 2026-09-29 | **§5.4.24 健康檢查與監控（`/system/health`）補建（桶 C 解鎖）**——①**緣由**：`§5.1.2.3` 原記「**須先於 bff-web 新增健康聚合端點**方可實作」；該端點已依 **`SCS-020 §9.8`** 完成**規格先行**（立規格 → 改 `gen_openapi.py` → **重生契約 78 端點、0 錯誤** → 實作）。②**★ 釐清 `§5.1.2.3` 所載「本頁定位須先釐清」**：定位為**作業台即時總覽**，**不取代** Prometheus／Grafana 之長期指標與告警。③**規格要點**：`overall` 三態（**空清單亦為 `DOWN`**）；**單一服務失敗不拖垮整體**；**不快取**；**失敗原因如實呈現**。④**實作**：`api/bff.ts`＋`pages/HealthConsole.tsx`＋`/bff-api` 代理（8101）；側欄 **22 → 23 頁**。**真機**：`DEGRADED`、**3/17 UP 如實**。**併修兩個真缺陷**（`@Value` 讀 Map 靜默失敗、並行未傳遞 `SecurityContext`） | | 1.18 | 2026-09-24 | **§5.4.23 離線授權與代授權（`/auth/stip`）補建（桶 C 解鎖）**——①**緣由**：`CR-022` 裁定 `advices` 採 **(A) 後送**並實作＋真機驗證（#A-98）→ §5.1.2.3 原記「**語意待裁定，裁定前不造頁**」之該頁**解鎖**；②**★ 併補後端（規格先行之連帶）**：查證發現 `SCS-001 §7.7` 之三職責中，**實作僅有單筆之 `POST …/{authNo}/advices`** → 「**查詢待補送佇列**」與「**批次手動上送**」**無端點可達**，頁面**無法完整實作**；→ 依序：**先立 `SCS-001 §7.7`**（`CR-023`，明訂 3 端點）→ **改 `tools/gen_openapi.py`** 重生契約（**77 端點、0 錯誤**）→ 實作 `GET /api/v1/authorizations/standin`（`status=PENDING\|UPLOADED\|ALL`）＋`POST /api/v1/authorizations/standin/advices`（批次）→ 本節逐鈕定義 → 實作頁面；③**⚠️ 規格要點**：清單條件為 `standin_flag = 1`，**不得**以決策碼篩選（`§7.7.1`——`REFERRAL`／`APPROVED` 於本地代佔時亦為 1，否則**轉人工件被漏**）；後送失敗＝**保留待後送**（上送不降級），畫面**不樂觀更新**。側欄 21 → **22 頁** | | 1.17 | 2026-09-24 | **清單補正：§5.1.2.1 桶 A 之過期殘留**——①**修正自身矛盾**：§5.1.2 表列「桶 A **6**」而 §5.1.2.1 標題寫「**8 頁**」，且「額度控管」標 ⬜、「資料遷移作業」無標記，**與修訂記錄 1.14（批次五 §5.4.18）／1.15（批次六 §5.4.20）矛盾** → 標題修正為 **6 頁**、兩頁標記 ✅（**6 頁全數完成**）；②**註記桶 C 解鎖**：`/auth/stip`（`advices`）原記「**語意待裁定，裁定前不造頁**」，**`CR-022` 已於 09-24 裁定採 (A) 並實作＋真機驗證（#A-98）** → 該頁**解鎖**，待補 **§5.4.23** 逐鈕定義。**緣由**：BEAM PMO 指出「應按工作清單逐步執行」→ 查證發現清單（`GOV-006` 與本節）皆有「**已做完卻仍顯示未做**」之幽靈項 | | 1.16 | 2026-09-23 | **批次八：§5.4.21／§5.4.22 補建（桶 C 解鎖 2 頁）**——`CR-021` 補實作 `check-results`／`reversals` 並真機驗證後，「授權策略檢核」與「沖正機制」自桶 C 解鎖；**規格先行**補本兩節逐鈕定義後實作。桶 C 35 → 33、可交付終點 18 → 20 頁、側欄 19 → 21 頁。⚠️ **併更正版本欄漏同步**（批次五／六未升版欄，1.13 → 1.16） | | 1.15 | 2026-09-23 | **批次六：§5.4.20 資料遷移作業；⚠️ 撤銷誤立之 §5.4.19；健康檢查與監控移至桶 C**——①**⚠️ 誤立 §5.4.19（誠實撤銷）**：草擬時稱「§5.4.10 只做對帳、本頁做結算」，**未查該節按鈕定義即斷言**；逐鈕複查後發現 **§5.4.10 已有「結算」按鈕**（`POST /clearing/settlements`、`direction` 兩列舉、`FIN`、202、並載明回應不含結算單識別碼）→ **`/finance/gl` 屬桶 B（已涵蓋）**，§5.4.19 全節撤銷。★ **教訓：桶 A／桶 B 之判定須與既有頁「逐鈕比對」，語意層級的「分工」敘述須查證後才寫**——本節已兩度因盤點不實自我更正（§5.1.2 桶 A、§5.4.19）。②**健康檢查與監控移至桶 C**：各服務 `/actuator/health` 前端無法直呼（CORS；gateway 未代理；bff-web 無聚合端點），且瀏覽器無法取代 Prometheus／Grafana 之長期指標與告警——**須先釐清頁面定位（作業台 vs 監控看板）並由 bff 提供聚合端點**。③**§5.4.20 資料遷移作業**（2 按鈕：建立遷移作業／查詢舊帳；`dryRun` 明顯標示、`errorCount`／`errorDetail` 不得隱藏、`migrated=false` 如實顯示）。**桶 A 7 → 6、桶 B 8 → 9、可交付終點 19 → 18 頁**。④**§5.4.20 實作與真機實測**：`api/migrations.ts`＋`pages/MigrationConsole.tsx`；`vite.config.ts` 加 `/migration-api` → 8096；`App.tsx` `PAGES` 共 **19 頁**；`typecheck` 0 錯誤／`build` 357.49 kB。**真機實測 3 項**：**(i)** 建立遷移作業（`W0`＋`dryRun=true`）→ **「★ 本作業為試跑（未寫入任何資料）」明顯標示**＋`status=RUNNING`（非同步）＋處理／成功／失敗筆數如實；**(ii)** 查詢舊帳 `LEGACY_ACCT_0001` → **「已遷移」徽章＋`accountNo=OLD0001`＋`migratedAt`＋snapshot 原樣 JSON**；**(iii)** ⚠️ **初次點擊回 `CC-PLT-4001`（缺 `X-Channel`／`X-Idempotency-Key`）**——後端日誌 `MissingRequestHeaderException` 現形 → 查契約確有宣告兩 header、**係我方 API 用戶端漏帶**，補上後通過（**契約與實作一致，缺陷在我**）。截圖 2 張（`webui-migration-01`／`02`）。**★ 桶 A 六頁全數完成**（產品與費率／參數設定／卡片生命週期／虛擬卡與 Token／額度控管／資料遷移作業） | | 1.14 | 2026-09-23 | **⚠️ §5.1.2 桶 A 盤點錯誤之自我更正（`CR-021`）＋批次五 §5.4.18**——①**盤點方法之缺失**：原桶 A 盤點**只做語意匹配、未驗證端點存在**，誤將「授權策略檢核／離線授權與代授權／沖正機制」三頁列為可立即實作；實測其依賴之 `reversals`／`advices`／`check-results` **三支契約端點於 `authorization-service` 完全未實作**（全服務僅 1 支 Controller、3 端點）→ **三頁移至桶 C**，**桶 A 11 → 8、桶 C 31 → 34、可交付終點 23 → 20 頁**。★ **教訓：「契約有端點」≠「實作有端點」**——盤點須查實作，非僅查契約；已將「**端點存在性**」納入 `tools/verify_contract_dto.py` 檢查面（`CSP-001 §7.1` G-8，回測 **6/6**）。②**批次五：§5.4.18 額度控管**（4 按鈕；明載與 §5.4.2 之分工；分／元雙顯示、送出用分；`holdAmount` 為 `CR-019` C-7 新增欄位須呈現）。 | | 1.13 | 2026-09-23 | **`CR-020` 四項修正後同步更新 §5.4.16**——BEAM PMO 裁定「**不得以 workaround 心態處理**」→ 四項**全部修根因**並真機驗證：**F1** 三要素後端**確實驗證**（V7 加 `CARD_APPLICATIONS.CARD_ID`，發卡回填關聯）→ 本節**改為提供**三要素輸入（原「不提供」之記載**已過時**——過時記載比缺記載更毒）；**F2** `X-Channel`／`X-Idempotency-Key` **確實綁定且冪等生效** → **可宣稱**「重送不重複」；**F3** 查無卡片改回 **`CC-CARD-4040`（404）**；**F4** `status` 依 **`SDD-005 §2.4`** 映射表由 `blockCode` 推導並同步寫入（**兩欄為衍生關係、非獨立維度**）。真機實測 9 項＋DB 複核；單測新增 10 例（含**負樣本**：回退 F4 後 2 例精準轉紅）。 | | 1.12 | 2026-09-23 | **`C-14` 批次四（2 頁）：卡片生命週期管理／虛擬卡與 Token 管理**——依 **§5.1.2 桶 A** 實作（`card-service` 8082）。①**規格先行**：新增 **§5.4.16**（`/card/lifecycle`）與 **§5.4.17**（`/card/token`）逐鈕定義；②**動工前查證（真機實測，非靜態比對）攔下四項缺陷** → **`CR-020` 新建**：**F1** 契約宣告之 `threeFactors` **實作未接收**（送**明顯錯誤**之三要素仍回 **201**）→ `CC-CARD-1002` **不可達**、`SDD-005 §2.1` 轉換 1 之前置條件**未落地**；**F2** 契約宣告為**必要**之 `X-Channel`／`X-Idempotency-Key` **實作未綁定**（完全不帶亦回 201）→ 契約**過度宣告**、**冪等鍵無效**；**F3** 查無卡片回 **`CC-CARD-3001`（409）** 而非 404，且**同服務**之 `GET /cards/{cardId}` 與 Token 端點**皆回 `CC-CARD-4040`** → **同服務兩套真相**；**F4** 經本端點 `ACTIVATE` 後 `block_code=ACTIVE` 而 `status` 仍 `UNACTIVATED`（**快發快綁路徑則兩欄皆更新**）→ 同一業務事件**因路徑不同而結果不同**（DB 複核：該組合**測試前 0 列、測試後 2 列**）。★ **四項皆落在 G-8 工具之檢查面之外**（工具只比回應欄位集合）→ **再次證明工具不可取代端到端實測**。③**按鈕定義之據實調整**：**不提供** `threeFactors` 輸入（提供即暗示功能存在＝**假功能**）；**如實**顯示後端錯誤碼（不改寫為 404，避免**遮蔽缺陷**）；`blockCode`／`status` **分欄並列**且**不得互相推導**；明載「本期僅已認證、未實作角色細分」。④**實作**：`api/cards.ts`＋`pages/CardLifecycleConsole.tsx`＋`pages/CardTokenConsole.tsx`；**沿用既有 `/card-api` 代理**（§5.4.9 進件作業台已建，**本批未新增任何代理**）；`App.tsx` `PAGES` 加 2 筆（**共 17 頁**）。⑤**真機瀏覽器＋Keycloak 實測**（詳見 `HANDOVER #A-91`）。★ **桶 A 進度 4／11**（餘 7 頁） | | 1.11 | 2026-09-23 | **`C-14` 批次三（2 頁）：產品與費率設定／參數設定**——依 **§5.1.2 桶 A** 之「可用端點」欄位實作（`product-service` 8085）。①**規格先行**：新增 **§5.4.14**（`/card/product`）與 **§5.4.15**（`/system/parameters`）逐鈕定義；②**實作**：`api/products.ts`＋`pages/ProductConsole.tsx`＋`pages/ParameterConsole.tsx`，`vite.config.ts` 加 `/product-api` → 8085，`App.tsx` `PAGES` 加 2 筆（**共 15 頁**）；③**三項「不實作」之明示**——產品 `status` **僅顯示**（本期無狀態轉換端點）／**費率計算不在本頁**（試算引擎為 `pricing-service`，本頁僅維護參數入口）／**版本鏈一律如實呈現後端回應、前端不自行推算**；④**真機瀏覽器＋Keycloak 實測 4 情境**：建立產品 → `CR019PRD01`／`DRAFT`／`VISA`／`PLATINUM`／`2026-10-01 ～（未設失效日）`；參數設定（`RATE`／`0.015`）→ 成功；**真重疊** → **`CC-PRD-1002`（422）「參數生效日重疊：product.CASHBACK02/feeRate @ 2026-09-15」**（如實呈現）；查詢 → **`CC-PLT-4040`「查無生效中參數 @ 2026-09-23」**——★ **係正確行為**（該版本生效日為**未來**，後端僅回「當前生效」版本）。`typecheck` 0 錯誤、`build` 成功；截圖 2 張。★ **桶 A 進度 2／11**。⚠️ **併修正本文件自身之懸空引用**：§5.4 引言已引用「v1.11（`C-14` 批次三）」而**版本欄仍為 1.10、且 1.11 列不存在** → 本版一併補正 | | 1.10 | 2026-09-23 | **新增 §5.1.2 後端就緒度盤點**——緣由：**「服務有端點」≠「該頁有對應端點」**（例：`/onboarding/ocr` 掛 `card-service` 但其中**無任何 OCR 端點**）；若照頁名造頁即為**空殼**（違反客戶硬性要求）。逐頁語意匹配後分三桶：**A 可立即實作 11 頁**（有對應端點且不重複）／**B 與既有頁面重複 8 頁**（**不另造**，逐一標明由哪一頁涵蓋）／**C 無對應端點 31 頁**（含 TMS 4 頁無本專案服務、BASE24 2 頁屬 ACI 產品）。★ **修正 `C-14` 剩餘工作量之認知**：原記「餘 48 頁」係以**頁面清單**計；**實際可實作者為 11 頁**，**可交付終點為 23 頁**（既有 12＋桶 A 11）——**桶 C 須先有後端方可實作** | | 1.9 | 2026-09-23 | **`C-14` 批次二：商店管理與請款（1 頁）＋原型模組 9／10／12／13 補列（4 群 14 頁）**——①**§5.1 新增「收單與商店」群**（`/merchant/settlements`，主要服務 `merchant`），群數 9 → **10**、頁數 45 → **46**；②**新增 §5.4.13** 逐鈕定義（建立商戶／查詢商戶／商店請款，含 **`CR-015` 雙軸分列**、`riskLevel` 可能為 null 之如實呈現、淨額由後端計算）；③**併補 §5.1 之對照表**——原載「前 4 群即客戶認可原型之選單結構」**不精確**，實測客戶原型為 **13 大模組**，本節為 **10 群**；逐模組對照後確認 **原型模組 11「收單作業平台」（9 個 L2）原完全缺席**（＝本頁之歸屬，`merchant-service` 於 `C-4` 已實作卻無頁面）；**模組 9／10／12／13 亦無對應群，一律標「待裁定」不推定為已涵蓋**（已登錄 `GOV-006 §4 #13`）。④**動工前查證**：以新增之 `tools/verify_contract_dto.py`（`CSP-001 §7.1` G-8）核對本服務 **0 不符**，故依契約實作無虞。**真實瀏覽器＋Keycloak 實測 4 情境**：建檔 → `MERCH000002`（**兩軸分列** `SINGLE`／`RETAIL`、`riskLevel=LOW`、`APPLIED`）；查詢 200；請款 → `SET202609000003`／`SUBMITTED`／**淨額 9,790 元**（10,000−200−10，後端計算）。`typecheck` 0 錯誤、`build` 成功。⚠️ **實測中另發現 `merchantId` 同名字段語意不一致**（請求＝業務代碼、回應＝UUID）→ 記入 `CR-019 §3.5`。⑤**依 BEAM PMO 2026-09-23 裁定「請補列」**：將客戶認可原型**模組 9 獨立授權平台／10 獨立紅利平台／12 TMS 終端-POS 管理／13 BASE24 SWITCHING 平台**補列為 **4 個新群、14 頁**（群數 10 → **14**、頁數 46 → **60**），並新增 **§5.1.1 逐 L2 對照表**（18 個 L2 逐一判定「新增頁面」或「已由既有頁面涵蓋」）。⚠️ **併明確界定範圍**：模組 12／13 之 6 頁**無對應本專案服務**（TMS 屬收單端設備管理、Switch 核心屬 ACI 產品）→ **補列 ≠ 承諾實作**，實作歸屬待 SoW 確認（`GOV-006 §4 #15`） | | 1.8 | 2026-09-22 | **`C-14` WebUI 批次一（3 頁）：清算與請款／爭議款處理／報表作業**——**規格先行**補 **§5.4.10～§5.4.12** 逐鈕定義後實作（`ClearingConsole`／`DisputeConsole`／`ReportConsole`＋`api/clearing.ts`／`api/disputes.ts`／`api/reports.ts`）；`vite.config.ts` 加 3 條代理；**`App.tsx` 重構為 `PAGES` 單一來源**（側欄／路由／頁首標題同源，避免三處漂移）。⚠️ **動工前查證攔下 2 處契約缺陷**：①`GET /clearing/reconciliations/{runId}` 回應型別（實作回**陣列**、契約誤宣告單一物件）→ `CR-016` **1.2 §8**；②`ReportJobView.errorDetail` 實作有、契約無 → **`CR-018`**。兩者皆改產生器→重生→**嚴格驗證僅目標檔變動**→真機複驗。**真實瀏覽器 ＋ Keycloak 登入實測 8 情境**：清算執行 **202／`DIFFERENCE`**（6 筆／7,500 元／差異 1 筆 1,000 元）＋對帳**表格**（`VISA`／`SUBSTANTIVE`／1／1,000）；爭議開案 `DSP202609000002`（**雙軸分列** `OPENED`／`INQUIRY`）→ 扣款 `FIRST` → **`UNDER_REVIEW`／`FIRST_PRESENTMENT`**；**跳號 `ARBITRATION` → 畫面如實顯示 `CC-DSP-3001`**；報表 `CSV` → **`COMPLETED`**（4 列＋`file://` stand-in 提示）；`XLSX` → **`FAILED`＋原因**（不產空檔）。`typecheck` 0 錯誤、`build` 成功（107 模組）；截圖 3 張。**併修本節修訂記錄之版本排序**（原 1.0／1.1／1.5／1.2 次序錯亂） | | 1.7 | 2026-09-22 | 配合 **`CR-013`** 更新 **§5.4.7 紅利點數作業台**：①「點數兌換」成功回饋補**現金價值**顯示（`cashValue`（分）＝ `pointsUsed × REDEEM_RATE`，HALF_UP 至分，後端依權威參數計算）；②**清除過時記載**——原說明「`cashValue` 本期固定 0（契約無現金價值欄位），畫面不呈現」與 `CR-013` 後之實物矛盾，改為「結果區顯示現金價值（以元呈現）；折算率缺漏時後端記 0、兌換照常，畫面如實顯示 0」。前端 `RewardsConsole.tsx`／`api/rewards.ts` 已同步，`typecheck` 0 錯誤、`build` 成功，真機瀏覽器驗證通過 | | 1.6 | 2026-09-22 | 配合 **`CR-012`（雙欄位）** 更新 **§5.4.7 紅利點數作業台**：①「點數兌換」按鈕定義——檢核規則補 **`settlementMethod` 屬 5 種列舉或省略**（省略→後端補預設 `POINTS_ONLY`，與主檔 DEFAULT 同值）、`redemptionType` 正名為**兌換標的類別**；成功回饋補顯示 **`標的類別／折抵方式`**；②說明區新增「**兌換雙維度**」條目——`redemptionType`（換什麼）與 `settlementMethod`（怎麼付）**正交**，畫面以**兩個下拉分列**、不得合併為單一欄位（例：`MILEAGE`＋`POINTS_PLUS_CASH`＝用點數＋現金換哩程）；未知折抵方式後端回 `CC-RWD-4000`（不靜默降級）。前端 `RewardsConsole.tsx`／`api/rewards.ts` 已同步實作，`typecheck` 0 錯誤、`build` 成功，**真機瀏覽器 e2e 通過**（截圖 `docs/08-evidence/webui-rewards-dual-field-01.png`） | | 1.5 | 2026-09-20 | 配合 **`CR-008`** 更新 §5.4.8 分期作業台：原「分期類型」單欄拆分為**雙軸**——`channelType`（來源通路，**7 值**，必填）＋ `businessType`（業務型態，3 值，**選填**）；建立／查詢之按鈕定義同步；並明訂 **`businessType` 為 null 時畫面必須顯示「未記錄」**（不得顯示成 `SINGLE` 或任何預設型態），以及本期**不提供**「以業務型態篩選」及其理由（空值語意未定義）。前端 `installments.ts`／`InstallmentConsole.tsx` 已同步實作，`npm run typecheck` 0 錯誤 | | 1.2 | 2026-09-19 | 配合 **`CR-003`** 補述三處「維度不得混用」之前端規則：①§5.4.6 繳款作業台——補 `UNMATCHED` 值域與其徽章文案，並明訂**不得**與 `unmatchedFlag` 共用文案（二者正交）；②§5.4.5 帳單作業台——明訂**批次執行**（`§9.2`）與**帳單本體**（`§9.1`）為兩個維度，兩者皆有 `GENERATED` 但語意不同，徽章對照表須區分；③§5.4.7 紅利點數作業台——依 `§10.1`／`§10.2`／`§10.3` 之三維度拆分，明訂畫面屬**不同層級**（帳戶徽章／階段分欄／桶列），並將 `FROZEN` 入點行為之依據由「`SCS-010 §10.6` 規格空白」更新為「`SDD-005 §10.3` 已封存」 | | 1.1 | 2026-09-19 | ①**補建 §5.4 頁面操作與按鈕定義**（逐鈕定義：按鈕｜功能｜觸發端點｜檢核｜角色｜回饋），含 §5.4.1～§5.4.8 共 8 頁；②配合 **`CR-002`** 更新 §5.4.8 分期作業台之值域說明——契約與 DDL 於 `CR-002` 後已一致，移除「不得對照契約枚舉」之過時限制，並補註 `BRD-001 §5.6` 業務型態維度**尚無欄位承載**；③**新增本修訂記錄區**（原文件欠缺，無法追溯修訂） | | 1.0 | — | 初版：設計 Token、版式、頁面清單與權限矩陣、元件規範、多國語系、響應式、API 串接、前端測試規範 |