CR #233 » CR-032_歸戶360頁面之設計與實作計畫.md
CR-032 「歸戶 360」頁面之設計與實作計畫
| 項目 | 內容 |
|---|---|
| 文件編號 | CR-032 |
| 版本 | 1.1（已執行完畢） |
| 提出日 | 2026-10-01 |
| 最後修訂 | 2026-10-02（1.1：實作完成並通過真實 Chrome 端到端驗證，見 §7） |
| 提出者 | WorkBuddy AI（開發團隊） |
| 緣起 | BEAM PMO 2026-10-01：「好期待『歸戶 360』頁做出來，先來這個（鐵律：擬定計劃、規格先行、任務追蹤清單）」——即 CR-031 §4.5 與 SAD-004 §2.2.1.1 所誠實揭露之「BffAccountOverview 尚無前端消費者」之閉環
|
| 依據 |
SAD-004 §2.2.1／§2.2.1.1（四區塊聚合）、SDD-007 §5.4.3（持卡人／歸戶查詢）、SCS-004 §7.5（卡片狀態投影）、GOV-003 條件 9（無規格不寫程式） |
| 範圍 | 新增 WebUI 頁面 /accounts「歸戶 360」（唯讀跨域總覽） |
| 不在範圍 |
無契約變更、無後端變更——後端聚合已於 #A-144 完成（CR-031 §4.5） |
1. 為什麼要做（閉環理由）
#A-144 完成後，BffAccountOverview 已能回四區塊，惟無前端消費者——
「有能力、沒人用」（SAD-004 §2.2.1.1 已揭露）。
本 CR 補上消費者，使三批工作形成完整可驗證之鏈路：
#A-143 card.card.status-changed.v1 ──事件──▶ CC_PARTY.card_status_caches （投影）
#A-144 BffAccountOverview ──聚合──▶ 四區塊（party／cards／limits／rewards）
#A-145 /accounts 「歸戶 360」 ──呈現──▶ 客服一眼看見客戶全貌 （本 CR）
⚠️ 若不做本頁，
#A-144即為「有能力、沒人用」之死碼——這正是CR-027 §7
「不為『打通』而建無語意來源之物」所警示者。
2. 設計裁定
2.1 新頁 /accounts，不併入 §5.4.3（/parties）
| 理由 | 說明 |
|---|---|
| 職責不同 |
§5.4.3 為 party 域作業頁（貼標、管制碼——有寫入）；本頁為跨域唯讀總覽
|
| 存取路徑不同 |
§5.4.3 直呼 party-service（/party-api）；本頁走 BFF 聚合（/bff-api）。一頁兩條存取路徑會使快取、錯誤、權限語意混雜 |
| 重疊之處理（刻意） | 兩頁都會顯示「歸戶主檔 ＋ 持卡人清單」——總覽頁必須自足，否則使用者仍要跳頁。惟本頁唯讀，並於畫面明示「異動請至「持卡人／歸戶查詢」」 |
⚠️ 誠實揭露：本頁超出
SDD-007 §5.1之 59 頁清單
（先例：/limit-adjustments，同為「本案額外建置，不計入 59 頁」）——故本頁為第 2 頁超出者。
2.2 路由與角色
| 項 | 值 |
|---|---|
| 路由 | /accounts |
| 側欄標籤／頁首標題 | 歸戶 360 |
| 服務標示 | bff-web:8101 |
| 所需角色 |
CSR（客服）——四區塊之下游讀取權限分別為 party（CSR）／limits（已認證）／rewards（CSR）→ 取最嚴者
|
2.3 版面（單頁、由上而下）
① 查詢列：歸戶識別碼（UUID）＋ [查詢] ＋ [清除]
② 歸戶主檔（含持卡人清單） ← 區塊 party
③ 卡片狀態清單 ← 區塊 cards
④ 額度 ← 區塊 limits
⑤ 紅利點數 ← 區塊 rewards
2.4 ★★ 降級呈現（本頁最重要之規則）
四區塊各自 OK／UNAVAILABLE。UNAVAILABLE 必須明顯呈現（顯示下游錯誤碼與訊息）。
⚠️ 嚴禁以
0、-、空白表格代替UNAVAILABLE。
「取不到」與「真的是 0／空」是兩種不同事實——混為一談會讓客服做出錯誤判斷
（例：額度取不到卻顯示0→ 客服誤以為客戶無額度）。
此為SCS-020 §9.11（營運總覽）同一原則之延伸。
2.5 空狀態 vs 不可用（必須區分）
| 情境 | 呈現 |
|---|---|
cards 為 OK 且 data: []
|
「此歸戶尚無卡片」——合法狀態（SCS-004 §7.5） |
cards 為 UNAVAILABLE
|
「不可用：CC-PTY-4040 查無歸戶」——失敗
|
limits 為 UNAVAILABLE（CC-LIM-1001） |
「不可用：該歸戶尚無額度主檔」——非 0 |
2.6 PII／PCI
- 卡號僅顯示遮罩值（
cardNoMasked，如411111******9682）——不含 PAN。 - 歸戶／持卡人之 PII（身分證／手機／電郵）一律顯示後端回傳之遮罩值，前端不解密、不自行遮蔽（
SAD-005 §5）。
2.7 快取
BFF 不快取（即時聚合）→ 每次查詢皆為真實下游呼叫。
前端以 react-query 依 accountId 快取；重查需明確觸發（本頁僅「查詢」鈕觸發，不做自動輪詢）。
3. 資料來源（無契約變更、無後端變更）
| 項 | 值 |
|---|---|
| 端點 | GET /bff-api/v1/bff/accounts/{accountId}/overview |
| 契約 |
bff-web.yaml 之 BffAccountOverview（四區塊；#A-144 已納入 gen_openapi.py） |
| 前端代理 | Vite /bff-api → localhost:8101（既有設定，無需改動） |
4. 執行步驟（依鐵律）
① 規格先行 SDD-007 §5.4.31（逐鈕／逐區塊定義）
② 前端 API frontend/src/api/bff.ts（型別 ＋ fetchAccountOverview）
③ 頁面 frontend/src/pages/AccountOverviewConsole.tsx
④ 註冊 frontend/src/App.tsx（PAGES：側欄／路由／頁首**同源**）
⑤ 關卡 typecheck ＋ build
⑥ 真機驗證 §5
⑦ 追蹤清單 HANDOVER ＋ GOV-006
5. 驗證計畫（真機）
| # | 樣本 | 預期 |
|---|---|---|
| 1 | 歸戶 …0001（有卡、有額度） |
歸戶 OK／卡片 2 張／額度 OK／點數 UNAVAILABLE（CC-RWD-4040）——★ UNAVAILABLE 必須看得出來，且不得顯示為 0
|
| 2 | 歸戶 …0010（有持卡人、有點數） |
歸戶 OK／持卡人 2 位／卡片 OK 但空 →「尚無卡片」／點數 OK |
| 3 | 卡片清單逐欄比對 | 與 CC_PARTY.card_status_caches 完全一致
|
| 4 | 非 UUID 之輸入 |
400 CC-PLT-4003 如實呈現 |
| 5 | ★ 負樣本：BFF 之 party 下游指向死埠 | 歸戶與卡片兩區塊顯示不可用＋錯誤碼；額度／點數仍正常顯示（降級為逐區塊） |
| 6 | 未登入 |
401 → 前端導向登入（SCS-022） |
6. 明確不做（避免同一功能兩套 UI）
| 不做 | 應至 |
|---|---|
| 卡片狀態異動（開卡／鎖卡／補發） |
/card/lifecycle（§5.4.16） |
| 額度調整／佔用 |
/limit-adjustments（§5.4.2）／/card/limit（§5.4.18） |
| 點數入點／兌換 |
/rewards（§5.4.7） |
| 帳單／入帳明細 |
/statements（§5.4.5）／/postings（§5.4.4） |
| 貼標／管制碼 |
/parties（§5.4.3） |
→ 本頁為唯讀總覽；各區塊附「異動請至〈頁名〉」之文字指引。
7. 執行結果（2026-10-02 完成）
| 步驟 | 產出 |
|---|---|
| ① 規格先行 |
SDD-007 1.27 新增 §5.4.31（逐鈕／逐區塊定義） |
| ② 前端 API |
frontend/src/api/bff.ts——BffSection／BffProjectedCard／BffAccountOverview ＋ fetchAccountOverview（沿用既有 AccountView／LimitView／PointsAccountView） |
| ③ 頁面 | frontend/src/pages/AccountOverviewConsole.tsx |
| ④ 註冊 |
frontend/src/App.tsx（側欄 29 → 30 頁） |
| ⑤ 關卡 |
typecheck 0 錯誤；build 成功（131 模組） |
| ⑥ 真機驗證 | 見下 |
真機驗證（真實 Chrome 154 ＋ CDP ＋ Keycloak 登入）
| # | 樣本 | 實測 |
|---|---|---|
| 1 | 未登入 | 導向 Keycloak 登入頁（fail-closed 生效） |
| 2 |
demo.csr 登入後 |
側欄 30 頁、含「歸戶 360」；頁首 歸戶 360 / bff-web:8101
|
| 3 | 歸戶 …0001
|
歸戶 可用／卡片 可用（2 列）／額度 可用／點數 不可用 ＋ CC-RWD-4040（★ 錯誤盒呈現，未以 0 代替） |
| 4 | 歸戶 …0010
|
歸戶 可用（2 位持卡人）／卡片 可用但空 →「此歸戶尚無卡片。（此為合法狀態，非查詢失敗。）」／額度 不可用 ＋ CC-LIM-1001／點數 可用（CUR 100,003／AV1 0／AV2 0——真實 0）
|
| 5 | 非 UUID |
CC-PLT-4003 如實呈現 |
★ 第 3／4 項同時證明兩件事：(a) 逐區塊降級（一區塊不可用不拖垮其餘）；
(b) 「不可用」與「真實 0／空」在同一畫面上明確區分（…0010之點數 AV1／AV2 為真實 0 並正常顯示為0，
而同畫面之額度為不可用並顯示錯誤碼——兩者外觀不同）。證據：
docs/08-evidence/A-145_歸戶360頁_四區塊正常與獨立降級_20261001.png／
A-145_歸戶360頁_空狀態與不可用區分_20261001.png。
三批閉環：#A-143（事件投影）→ #A-144（BFF 四區塊聚合）→ #A-145（本頁呈現）。
8. 修訂記錄
| 版本 | 日期 | 說明 |
|---|---|---|
| 1.1 | 2026-10-02 |
實作完成並通過真實 Chrome 端到端驗證（新增 §7）。SDD-007 升 1.27；側欄 29 → 30 頁；證據 45 → 47 張；GOV-006 WBS 1.3.2 完成
|
| 1.0 | 2026-10-01 | 初版：依 BEAM PMO 指示擬定計畫。裁定新頁 /accounts「歸戶 360」（不併入 §5.4.3——職責與存取路徑皆不同）；★ 降級呈現為本頁最重要規則（UNAVAILABLE 不得以 0／空白代替——「取不到」≠「真的是 0」）；區分空狀態與不可用；無契約／後端變更；★ 誠實揭露本頁超出 §5.1 之 59 頁清單（第 2 頁超出者，先例 /limit-adjustments） |