US-2：強制刪除／撤銷卡券

manage-customer-vouchers

As a 管理員, I want 刪除或撤銷特定顧客的卡券，並記錄異動原因, So that 我能處理退費或輸入錯誤的情況.

2026-08-22 決議（跨規格衝突已拍板）：管理員於管理頁面 UI 即可刪除／撤銷卡券。這取代了先前「只能透過程式介面操作」的定義；「只有管理員能做」這點不變，改變的是操作方式——現在管理員在後台頁面上點就能刪。

Acceptance Scenarios

WHEN 管理員在卡券清單或詳情面板裡點「刪除／撤銷此卡券」，THEN 跳出確認視窗，要求先選一個原因（顧客退費／輸入錯誤撤銷／店家補償重發／其他）
WHEN 未選擇異動原因，THEN 無法送出刪除
WHEN 異動原因選擇「其他」，THEN 顯示文字說明欄位供管理員補充具體原因
WHEN 管理員確認刪除，THEN 這張卡在顧客那邊和管理端同時消失，畫面出現完成提示
WHEN 卡券被刪除，THEN 系統留下紀錄（誰刪的、什麼時候、為什麼、從哪個網路位置操作），詳情面板的時間軸也會出現這筆事件

Independent Test

從清單和從詳情面板各刪一張測試卡券（各選不同原因），確認 ① 顧客那邊查不到 ② 紀錄裡有誰刪的／時間／原因／網路位置 ③ 沒選原因時送不出去。

設計稿

顧客卡券頁 — 列表與 Drawer 皆可觸發的刪除操作（含異動原因確認）

開啟互動原型 ↗

出自 proposal

Edge Cases

已失效／已用完的卡券：還是查得到，清單與詳情面板都會顯示，並標示狀態
重複刪除：已經作廢的卡券再點一次刪除，系統要擋下來並說明原因
空白搜尋：什麼都沒輸入時顯示全部（分頁呈現），不能報錯
同名顧客：有多位顧客同名時，清單要能用手機或頭像分辨出來
序號與手機的輸入格式：不管有沒有加 MP- 前綴、手機有沒有打分隔線，都要搜得到

出自 proposal

Functional Requirements

FR-001: 提供卡券搜尋，支援顧客姓名、手機（含/不含 -）、卡券序號（MP-…）三種查詢條件
FR-002: 提供「六大類別」與「狀態」兩組篩選標籤，可以同時選。狀態值為使用中／已用畢／已退費三種（2026-08-23 依設計稿確定）
FR-003: 卡券清單顯示顧客頭像／姓名／手機、卡券序號、名稱、類別、剩餘次數（含進度條）、剩餘金額、狀態；標題列顯示「共 N 張卡券 · 已篩選 M 筆」的文字計數（2026-08-24 依設計稿修訂，原為 KPI 卡）
FR-004: 點卡券任一列會開啟詳情面板，內容有剩餘次數／金額、購買金額、單次價值、開卡日期、開卡人員、使用進度、可用狀態、完整異動時間軸
FR-004a（2026-08-23 決議）: 「使用進度」對門市開的卡與匯入的卡一律顯示進度條，分母是「這張卡開出／匯入進來時共有幾次」；匯入前的使用歷程不算在內，畫面需說明這一點
FR-005: 清單上和詳情面板裡都要有刪除／撤銷的入口
FR-006: 刪除是「作廢」而不是真的清掉——顧客端與管理端都看不到，但資料留在系統裡可追查
FR-007: 刪除前要跳確認視窗，而且一定要選原因（顧客退費／輸入錯誤撤銷／店家補償重發／其他）
FR-007a: 原因選「其他」時要出現文字欄位讓管理員補充（是否必填、字數上限見 Open Questions）
FR-007b: 刪除／撤銷是管理員在後台頁面上就能完成的操作，不需要工程協助；權限僅限管理員
FR-008: 每次刪除都要留下可追查的紀錄（誰刪的、時間、原因、從哪個網路位置），並顯示在該卡券的詳情面板時間軸上
FR-009: 實際的退費金流不在這次範圍內
FR-010（2026-08-23 依設計稿補）: 提供「匯出名單」，匯出目前篩選結果的卡券清單

出自 proposal

Open Questions

2026-08-22 由 Jacky 逐題答覆（Ci 轉述）。決議彙整見 docs/grooming/2026-08-22-admin-console-open-questions-resolved.md。

~~跨規格衝突：本 US-2 定義為「管理後台 UI 操作」，specs/002-voucher-ui-enhancement 定義為「API only、僅 ADMIN」~~ — 2026-08-22 決議：以本 change 為準，管理員於管理頁面可刪除卡券。所有管理員皆可操作（manage-account-permissions 已確立無管理員內部分層）
- ⚠️ 待辦：舊版規格（002）還寫著「只能透過程式介面操作」，需同步改掉。細節見 implementation-notes.md
~~異動原因「其他」是否需要開放文字說明欄位~~ — 2026-08-22 決議：需要（見 FR-007a）
NEEDS CLARIFICATION（2026-08-22 細化）: 「其他」的文字說明欄位是否必填？字數上限？
~~詳情面板「使用進度」的計算基礎（次數型 vs 金額型呈現是否不同）~~ — 2026-08-23 決議：兩種卡券都顯示進度條，分母為「綁定／開卡當下的總次數」（即綁定後進度，非終身進度）
- 已查證現有系統做得到，不需要改資料庫
- 已知限制（需在畫面上說明）：舊系統在匯入之前已經用掉的次數查不到，所以進度的分母是「匯入進來時還剩幾次」。例：原本 10 次、匯入前已用 3 次、只匯入剩下的 7 次 → 畫面顯示「0/7」而非「3/10」
- 技術依據見 implementation-notes.md
~~贈品與產品的業務差異~~ — 已由卡券方案維護（Epic 4）文件釐清，與本變更無關
5 月產出的設計規格是照舊版畫面寫的，要對齊這次的詳情面板與時間軸重做