🦉 owl SDD 看板 需求跑到哪了 · prospec × owl/cockatiel/raven
← 回看板
draft

客戶端卡券異動紀錄：顧客可查看卡券何時增加、何時使用、何時被刪除

HAIR-50
customer-voucher-activity-log · 建立於 2026-08-23

prospec 流程進度

探索›需求›規劃›設計›任務›實作›驗證›歸檔

跨 repo 進度

owl（產品層）
定意圖
2026-08-23 建立，取代已廢止的 exclude-binding-from-customer-issuances。依 Jacky 需求：顧客要知道卡券增加／使用／刪除的時間
→
cockatiel（後端）
待開始
底層資料多數已存在（redemption.redeemed_at、voucher_binding.operation_type），缺的是顧客端彙總 endpoint
→
raven（前端）
待開始
顧客 Vouchers 頁已有 activations/redemptions tab 但被註解掉，且呼叫的 endpoint 不存在，需重整

customer-voucher-activity-log

客戶端卡券異動紀錄：顧客可查看卡券何時增加、何時使用、何時被刪除 取代已廢止的 exclude-binding-from-customer-issuances（方向相反，見該 change 的 metadata）

Background

2026-08-22 Jacky 提出：顧客需要知道「什麼時候增加卡券、什麼時候使用、什麼時候卡券被刪除」。

2026-08-23 Jacky 進一步確認：這是獨立的一頁，與既有的「開卡記錄」頁並存。

  • 「開卡記錄」頁（exclude-binding-from-customer-issuances）：維持語意純淨，只顯示真實開卡
  • 「卡券異動紀錄」頁（本 change）：完整呈現增加／使用／刪除三類事件

兩頁目的不同，不是取代關係。

User Stories

P1 US-1

顧客查看卡券異動紀錄

查看完整規格 →

Edge Cases

  • 匯入前的使用紀錄查不到：匯入進來的卡券只帶了「還剩幾次」，舊系統在那之前的使用時間無法重建。畫面需說明「以下只包含匯入之後的紀錄」
  • 已刪除卡券的異動紀錄：卡券本身從有效清單消失，但其歷史事件仍應保留於紀錄中（否則顧客無從得知它曾存在又被刪除）
  • 同一天多筆事件：需顯示到時分，不能只到日期
  • 卡券被解綁（Unbind）而非刪除：依 2026-08-23 決議不對顧客顯示。但解綁會讓該卡券脫離這位顧客名下，若顧客的卡券清單因此少一張卻無對應事件，前端需另外處理此情境

Functional Requirements

  • FR-001: 提供顧客身分可存取的卡券異動紀錄查詢，涵蓋增加、使用、刪除三類事件
  • FR-002: 「增加」事件須涵蓋門市開卡與匯入卡券綁定兩種來源，但對顧客不區分來源，一律顯示為「卡券增加」
  • FR-003: 事件依時間倒序排列，時間精度至少到分
  • FR-004: 顧客僅能查詢自己的紀錄，不得取得他人資料
  • FR-005: UI 須明示「匯入前的使用紀錄不在範圍內」，避免顧客誤以為紀錄不完整是系統錯誤
  • FR-006（2026-08-23 決議）: 刪除的異動原因僅存於管理端稽核紀錄，顧客端 API 不得回傳
  • FR-007（2026-08-23 決議）: 解綁（Unbind）不列入顧客可見的異動紀錄
  • FR-008（2026-08-23 決議）: 本功能為獨立頁面，與「開卡記錄」頁並存，不合併

Success Criteria

  • SC-001: 三類事件（增加／使用／刪除）皆能正確呈現，時間序無誤
  • SC-002: 顧客 100% 無法透過本功能取得他人卡券資料
  • SC-003: 匯入卡券綁定後的每一次使用皆出現在紀錄中，完整率 100%

Related Modules

  • （owl 為產品層 spec hub，無程式模組）
  • 後端：記錄使用、綁定、刪除的資料多數都已經有了，缺的是一個給顧客看的彙總查詢
  • 前端：顧客卡券頁其實已經有一個做到一半的「異動紀錄」分頁，但被關掉了，而且它呼叫的後端功能不存在，需先決定沿用或重寫
  • 技術細節（資料表、既有半成品的位置）見同目錄 implementation-notes.md

Open Questions

2026-08-23 由 Jacky 逐題答覆。

  • 「刪除」事件是否對顧客顯示原因 — 不顯示，僅留在管理端內部（見 FR-006）
  • 「增加」事件是否需要對顧客區分兩種來源 — 不區分（見 FR-002）
  • 解綁（Unbind）是否對顧客顯示 — 不顯示。Jacky：「解綁顧客的卡券不會消失，只有刪除才會消失」（見 FR-007）
  • 本功能是獨立頁面還是併入「開卡記錄」頁 — 獨立頁面，與「開卡記錄」並存（見 FR-008）
  • NEEDS CLARIFICATION（答覆與現況不符，需再確認）: 「使用」的粒度。Jacky 回覆「這目前已經做好的功能不用調整」，但查證後顧客端的使用紀錄功能並不存在——
    • raven 顧客卡券頁確實寫了呼叫邏輯，但呼叫的 /customers/my/redemptions、/customers/my/activations 在後端找不到（cockatiel 只有 /customers/search、/my/vouchers、/my/voucher-groups）
    • 該分頁的 UI 在前端是被註解掉的
    • 建議回問：「使用紀錄那個分頁目前是關掉的，後端也還沒有對應 API，你說的『已經做好』是在哪裡看到的？」
    • 暫定預設：逐次核銷各一筆（底層 redemption 本來就是逐次記錄），待確認

Constitution Check

  • Reviewed against prospec/CONSTITUTION.md
  • P1（owl 是產品層）：PASS — 描述顧客可見的行為與資料範圍，未指定 API 實作
  • P2（契約意圖在 owl、實體在 cockatiel）：PASS — endpoint 設計留給 cockatiel plan 階段
  • P3/P4（兩軌分離、協調點）：PASS — 已標明 raven 既有未完成 UI 需重整，屬協調點

UI Scope

Scope: full

（設計稿尚未存在，需於 /prospec-design 階段補。）