Project

General

Profile

Download (161 KB)

CR #201 » SDD-007_WebUI設計規範.md

內容更新：內部稱謂去識別化（2026-10-18） - Redmine Admin, 10/18/2026 05:32 AM

 

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 登入頁

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 主版式

flowchart LR
  subgraph Layout["App Layout"]
    SB["側欄 260px<br/>可收合 64px"]
    subgraph Main["主區"]
      HD["頁首 56px<br/>麵包屑＋使用者＋語系"]
      CT["內容區<br/>查詢列＋資料表＋明細"]
    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 命名 <page>.<section>.<element>（如 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 分層

flowchart LR
  P["頁面元件"] --> H["Hook<br/>useCards / useLimits"]
  H --> Q["TanStack Query<br/>快取 / 重試 / 失效"]
  Q --> C["API Client<br/>攔截器 / 信封解析"]
  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 串接、前端測試規範
(10-10/67)