US-1：查詢顧客卡券狀態

manage-customer-vouchers

As a 管理員, I want 搜尋並查看所有顧客擁有的卡券清單，並能點開單張卡券的完整詳情, So that 我能協助顧客確認餘額或排除使用疑慮.

Acceptance Scenarios

WHEN 管理員於搜尋框輸入顧客姓名、手機（含或不含 -）、或卡券序號（MP-…），THEN 系統顯示符合條件的卡券清單
WHEN 管理員點選「六大類別」或「狀態」的篩選標籤（可以同時選多個），THEN 清單立刻只留下符合的卡券
WHEN 清單顯示，THEN 每列呈現顧客頭像+姓名+手機、卡券序號、卡券名稱、類別、剩餘次數（含進度條）、剩餘金額、狀態；標題列顯示「共 N 張卡券 · 已篩選 M 筆」（2026-08-24 依設計稿：不做 KPI 卡，改文字計數）
WHEN 管理員點擊任一列，THEN 右側滑出詳情面板，顯示完整資訊：剩餘次數/金額、購買金額、單次價值、開卡日期、開卡人員、使用進度、可用狀態、完整異動紀錄時間軸
WHEN 管理員點「匯出名單」，THEN 下載目前篩選結果的卡券清單（2026-08-23 依設計稿補）
WHEN 搜尋條件查無相符卡券，THEN 系統顯示「查無卡券」提示而非空白畫面

Independent Test

用已知的顧客手機號搜尋，確認清單欄位與標題列計數正確；同時選類別＋狀態，確認篩選正確；點開一列，確認詳情面板完整顯示、含時間軸。

設計稿

顧客卡券頁 — 搜尋、類別/狀態篩選 chip、KPI、清單欄位、點列開 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 月產出的設計規格是照舊版畫面寫的，要對齊這次的詳情面板與時間軸重做