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

US-2：特定日期區間歷史統計

voucher-operational-reports

As a 管理員, I want 選擇特定日期（含以前）查看累積數據, So that 我能分析過去某段時間的營運成效.

Acceptance Scenarios

  • WHEN 管理員開啟歷史統計頁, THEN 可以選日期，旁邊有「7 天前／30 天前／90 天前／今日」快捷按鈕
  • WHEN 管理員選了截止日, THEN 顯示三張卡（一次只能選一張）：累積開卡金額（總共收了多少錢）、累積核銷金額（已核銷的服務金額，附核銷率）、累積未使用金額（還沒用掉的，也就是欠顧客的，附佔開卡的比例）
  • WHEN 管理員點任一張卡, THEN 左邊的「類別佔比」圓環圖跟著切換；圓環圖旁另有開卡／核銷／未使用三個按鈕可以單獨切換
  • WHEN 資料就緒, THEN 右側「六大類別累計明細」表格同時列出三組金額與每一類的核銷率

Independent Test

點「30 天前」，確認三張卡的數字、圓環圖切換、六大類別明細表都正確而且互相對得上（例如未使用 = 開卡 − 核銷）。

設計稿

歷史統計 — 截止日 Picker、三態互斥 KPI 卡、Donut 切換、六大類別明細表、30 日趨勢圖

歷史統計 — 截止日 Picker、三態互斥 KPI 卡、Donut 切換、六大類別明細表、30 日趨勢圖 開啟互動原型 ↗
出自 proposal

Edge Cases

  • 三份報表的「開卡金額」和「核銷金額」算法要一樣，同一天的數字不能三頁不同（例如今日營運的「今日核銷」要能對上歷史統計選「今日」的數字）
  • 已刪除（作廢）的卡券自報表直接扣除（2026-08-22 決議），不獨立列示為負項；扣除的時點（以原始開卡日回溯扣除 vs 以刪除當日扣除）尚未定義，跨月刪除會影響已結算月報（見 Open Questions）
  • 沒資料的月份或當天：圖表與表格顯示 0 或「無資料」，不能報錯或整頁空白
  • 時區：「今日 00:00」與月份邊界一律以台灣時間 UTC+8 計算（2026-08-22 決議）
  • 核銷率 = 核銷金額 ÷ 賣出金額，賣出是 0 的時候要顯示「—」，不能出錯
  • 分店（2026-08-23 修訂）：目前系統完全沒有「店」這個概念，員工也沒有隸屬哪一間店的資料，所以無法從現有資料判斷一筆交易發生在哪裡。本期只先把「未來要能分店看」這件事在介面層預留好，完整的多分店另開需求
出自 proposal

Functional Requirements

  • FR-001: 今日營運頁顯示到目前為止的當日開卡與核銷統計，包含兩排數字、六大類別圓環圖、時段長條圖、核銷與開卡明細（分頁切換）
  • FR-001a（2026-08-23 依設計稿補）: 今日營運頁提供「即時更新」與「匯出今日報表」，明細區提供搜尋與類別／專員篩選
  • FR-002: 歷史統計頁可以選截止日看累積數字，包含開卡／核銷／未使用三張卡與對應的圓環圖、六大類別累計明細表
  • FR-003: 月度財報頁可以選月份區間，每個月分收入／核銷／差額三列並按六大類別拆開，附這段期間的數字與總計
  • FR-004（2026-08-24 依 Jacky「格式化 CSV」修訂）: 月度財報匯出為 CSV（不做 Excel 格式），中文不能亂碼
  • FR-005: 三份報表的「開卡／核銷金額」算法要統一，三頁之間一致（同一份資料、同一個時區）
  • FR-006（2026-08-22 決議）: 「今天」從幾點開始、「這個月」到幾號結束，一律用台灣時間算
  • FR-007（2026-08-22 決議）: 被刪掉的卡券直接從報表金額扣掉，不另外列一行負數
  • FR-008（2026-08-23 決議修訂）: 報表在取數時須預留「哪一間店」這個條件，但本期畫面以單店運作、不提供店別切換。目的是未來開第二間店時不必整組重做
  • FR-008a: 完整的多分店功能（建店、每筆交易歸哪間店、跨店合併看）這期不做，另開需求
出自 proposal

Open Questions

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

  • 已刪除／撤銷的卡券在三份報表中如何計算 — 2026-08-22 決議：自報表直接扣除，不獨立列示為負項（見 FR-007）
  • 「續卡記事」是否為全新概念 — 2026-08-22 決議：拿掉，不實作。後續「需要關注」面板整塊亦於 2026-08-24 決議本期不做
  • 報表是否需要分店（多分店）維度 — 2026-08-22 決議：要，未來會有多家分店（見 FR-008）
  • 「今日」與月份邊界的時區基準 — 2026-08-22 決議：台灣時間 UTC+8（見 FR-006）
  • NEEDS CLARIFICATION（2026-08-22 細化）: 刪除卡券的扣除時點——以原始開卡日回溯扣除（會改動已結算的歷史月報），還是以刪除當日扣除（歷史月報不動，但當月數字會出現跨期扣減）？
  • 「需要關注」面板的「剩餘次數<2」與「即將用完」閾值 — 2026-08-24 該面板本期不做，此題失效
  • 分店維度的實作範圍 — 2026-08-23 決議：本期只預留 API 參數，不做完整多分店（見 FR-008／FR-008a）。原「阻塞級」標記解除
  • NEEDS CLARIFICATION（未來做完整多分店時必須先解）: 屆時需建 stores 表、employee 的所屬分店關聯，並在 Voucher／Redemption 上存**不可變的 store_id snapshot**（否則員工調店後歷史報表會被錯誤重分類）；既有資料的 backfill 要定為 UNKNOWN` 或人工映射