manage-voucher-products

Epic 4：卡券方案與贈品維護 (Catalog Management) — 對應頁面：卡券方案 設計稿依據：「M+ Admin.html」(2026-08-06) 卡券方案頁（產品／贈品雙分頁）。 2026-08-10 依團隊提供的完整 User Story 文件改版，取代 08-09 的推測版本（原 3 個 US 的 拆法改為對齊來源文件的「產品維護」「贈品維護」兩個 Story）。owl 只定「要有什麼能力」， 實際怎麼做由後端自行決定（Constitution P2/P3）。

Background

設計師開卡時要從「卡券方案清單」選產品，但這份清單現在是寫死的，門店想調價、加產品、加贈品都要找工程改。管理後台設計稿已畫出完整的卡券方案（含贈品）管理頁，本變更把它的規格補齊，讓門店可以自己維護。

User Stories

P1 US-1

維護卡券產品（服務項目）

查看完整規格 →

P2 US-2

維護贈品項目

查看完整規格 →

Edge Cases

• 同一個分類裡名稱重複：新增時要擋下來或明確警告
• 改了價格之後，已經開出去、還沒用完的卡，餘額和次數不能跟著變（以開卡當時的價格為準）
• 兩個管理員同時改同一個方案：後存的那個要被告知「資料已經被別人改過了」
• 分類固定六大類（洗剪燙染護頭皮），這期不開放自己加分類
• 贈品「不追蹤庫存」跟「庫存剛好是 0」是兩回事，畫面要分得出來（不能都顯示「—」）

Functional Requirements

• FR-001: 卡券方案頁提供「卡券產品」／「贈品項目」兩個分頁，預設停在卡券產品
• FR-002: 卡券產品分頁上方有 7 格數字（總項目數＋六大類別各幾項與平均價格），可以點類別卡篩選、用名稱搜尋、用類別標籤篩選
• FR-003: 卡券產品的欄位：分類、項目名稱、項目編號、單次價格；可以直接在列上新增／編輯／刪除，刪除等於下架（已開的卡不受影響）
• FR-004: 贈品項目的欄位：分類、項目、備註（贈送條件）、庫存（可以是「不追蹤」或數字，10 以下顯示補貨提醒）、建議售價（可以是 NT$0）；可以直接在列上新增／編輯／刪除
• FR-005: 不管刪產品還是刪贈品，都不能影響已經開出去的卡和過去的報表數字
• FR-006（2026-08-22 決議）: 「匯入清單(.csv)」本期要真的做，匯入標的為當前分頁的資料（產品／贈品各一份）
• FR-006a（2026-08-23 依設計稿補）: 提供「匯出清單」，匯出格式與匯入格式相同，匯出檔即為匯入範本
• FR-007（2026-08-22 決議）: 產品和贈品的新增、編輯、刪除所有管理員都能做，管理員之間不分級

Success Criteria

• SC-001: 管理員不需工程師協助即可完成「新增產品 → 設計師開卡選到該產品」全流程
• SC-002: 刪除／下架產品或贈品後，既有卡券可正常核銷、歷史報表數字前後一致
• SC-003: 9/5 staging 兩間店可用此功能自行維護產品與贈品清單

Related Modules

• （owl 為產品層 spec hub，無程式模組）
• 後端：目前只能「讀」卡券類別與開卡選項，不能新增、修改、刪除，這些要新做
• 後端：贈品的基礎資料結構其實已經存在，缺的是庫存、備註、建議售價這幾個欄位，以及維護介面
• 前端：管理後台目前沒有這個頁面，需新做（產品／贈品兩個分頁）

Open Questions

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

• 「贈品」與「產品」的業務差異？ — 已由本次改版釐清：贈品獨立分頁，欄位含庫存/備註/建議售價，價格可為 0
• 方案欄位有哪些？ — 已釐清：產品＝分類/名稱/單次價格；贈品＝分類/項目/備註/庫存/建議售價
• 本期是否排除「匯入清單 (.csv)」功能 — 2026-08-22 決議：不排除，會有匯入清單按鈕。設計稿上的按鈕不再是假動作，需真實作（見 FR-006）
• 產品／贈品的 CRUD 是否需要權限分層 — 2026-08-22 決議：所有管理員皆可操作，與 manage-account-permissions 的三層權限結論一致（見 FR-007）
• 匯入標的是產品、贈品，還是兩者各一份 — 依設計稿：匯入按鈕在分頁切換之上，匯入當前分頁的資料（產品／贈品各一份）
• 檔案的欄位格式與範本 — 設計稿同時有「匯出清單」，匯出格式即匯入範本，不需另行定義
• NEEDS CLARIFICATION: 匯入遇到重複項目（同分類同名，見 Edge Cases）如何處理：跳過、覆蓋更新、還是整批中止？
  • 暫定預設：同分類同名視為更新，其餘新增；匯入前顯示預覽讓管理員確認
• NEEDS CLARIFICATION（2026-08-23，答覆與現況不符）: Jacky 回覆「這個頁面功能已經做好了，請維持」，但查證後端 products 模組只有 2 個唯讀 API，沒有任何新增／編輯／刪除／匯入能力。
  • 兩種可能：① 指的是設計稿已完成；② 與「卡券匯入」（001-voucher-account-binding，匯入的是顧客既有卡券）混淆
  • 風險：若照答覆標為「維持現狀」，整個產品／贈品維護頁都不會進開發範圍
  • 建議回問：「卡券方案那頁我查了後端，目前只能讀不能改，新增／編輯／刪除／匯入都還沒做。你說的『已經做好』是指設計稿嗎？」

Constitution Check

• Reviewed against prospec/CONSTITUTION.md
• P1（owl 是產品層）：PASS — 本文件僅描述意圖與行為，無實作細節
• P2（契約意圖在 owl、實體在 cockatiel）：PASS — 未指定 endpoint／schema，僅描述「需要方案與贈品 CRUD 能力」
• P3（兩軌分離）：PASS — cockatiel／raven 各自以 prospec 接續，契約經 CI 流動
• P4（協調點只有兩個）：PASS — 本 change 即「owl 定意圖」協調點，未新增手動同步步驟

UI Scope

Scope: full

（設計稿已存在：M+ Admin 卡券方案頁，含產品／贈品雙分頁。/prospec-design 可走 Extract Mode 從既有 HTML 原型萃取規格。）