manage-customer-profiles

管理員端顧客管理：顧客資料清單、搜尋、編輯、匯出名單 設計稿依據：「M+ Admin.html」顧客管理頁

本卡的由來：側邊欄 7 個功能頁裡，只有這頁沒有規格（見 design-spec-gap-audit A-1）。 2026-08-24 Jacky 確認本期要做，故新開此卡。

Background

管理員需要查得到顧客的基本資料——確認身分、核對聯絡方式、了解這位顧客手上有幾張卡。目前管理端沒有這個入口，顧客資料只存在資料庫裡。

Jacky 的需求描述（2026-08-24）：「依照畫面開發，主要呈現資料庫裡目前會員資訊，可以透過搜尋用手機、姓名、會員卡號，找出顧客，並呈現顧客資訊。」

本卡的範圍是「呈現既有資料」，不是建立新的顧客資料模型。

User Stories

P1 US-1

查詢與維護顧客資料

查看完整規格 →

Edge Cases

• 同名顧客：清單需能以手機或會員編號分辨
• 沒有 Email 的顧客（LINE 註冊者常見）：欄位顯示「—」而非空白或錯誤
• 手機格式：輸入含或不含分隔線都要搜得到
• 顧客持有 0 張卡券：正常顯示 0，不是空白
• 刪除顧客：本期不提供刪除功能（設計稿只有編輯）。顧客資料涉及既有卡券與交易紀錄，刪除的連帶影響需另行評估

Functional Requirements

• FR-001: 提供顧客搜尋，支援姓名、手機（含／不含分隔線）、會員編號三種條件
• FR-002: 提供依註冊方式（全部／LINE 註冊／帳號註冊）的篩選
• FR-003: 頁面上方顯示三格統計：顧客總數、LINE 註冊人數、帳號註冊人數
• FR-004: 顧客清單欄位：姓名、註冊方式、手機、Email、性別、生日、地址、是否同意行銷、持有卡券數（含使用中張數）
• FR-005: 提供新增顧客與編輯顧客資料
• FR-006: 提供「匯出名單」，輸出格式化 CSV，內容為目前篩選結果
• FR-007: 清單支援分頁
• FR-008: 本期不提供刪除顧客

Success Criteria

• SC-001: 姓名、手機、會員編號三種搜尋方式都能正確找到顧客
• SC-002: 上方三格統計與清單內容一致（總數 = LINE 註冊 + 帳號註冊）
• SC-003: 匯出的 CSV 在 Excel 開啟時中文不亂碼，且內容與畫面篩選結果一致

Related Modules

• （owl 為產品層 spec hub，無程式模組）
• 後端：目前只有顧客自己用的查詢（搜尋、我的卡券），管理端要看的顧客清單、編輯、匯出都還沒有
• 前端：管理後台目前沒有這個頁面，需新做
• 資料面：顧客的基本資料、註冊方式、行銷同意等欄位是否都已存在於現有資料表，需於 plan 階段確認

Open Questions

• NEEDS CLARIFICATION（個資處理，重要）: 這頁集中呈現手機、Email、生日、地址等個人資料——
  • 哪些角色可以看到這頁？（推定僅管理員，待確認）
  • 是否需要記錄「誰在什麼時候查看／匯出了顧客名單」的存取紀錄？
  • 匯出的 CSV 含完整個資，是否需要額外的確認步驟或浮水印？
• NEEDS CLARIFICATION（行銷同意）: 「是否同意行銷」這個欄位——
  • 顧客在哪裡表示同意？（註冊時？另有同意書？）
  • 管理員可以在這頁修改它嗎，還是唯讀？
  • 顧客要撤回同意時走什麼流程？
• NEEDS CLARIFICATION: 「會員編號」與顧客卡券頁的「卡券序號（MP-…）」是不同的東西，會員編號的格式與產生規則需確認
• NEEDS CLARIFICATION: 新增顧客時，哪些欄位必填？手機是否需要驗證唯一性？

Constitution Check

• Reviewed against prospec/CONSTITUTION.md
• P1（owl 是產品層）：PASS — 只描述管理員看得到什麼、能做什麼，未指定實作
• P2（契約意圖在 owl、實體在 cockatiel）：PASS — 未指定 API 或資料表設計
• P3/P4（兩軌分離、協調點）：PASS — 無新增手動同步步驟

UI Scope

Scope: full

（設計稿已存在：M+ Admin 顧客管理頁。）