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

US-3：月度類別收支明細報表（財報版）

voucher-operational-reports

As a 管理員, I want 選定日期區間並取得按月拆解的各服務類別收入與消耗統計表, So that 我能進行財務對帳與營收確認.

Acceptance Scenarios

  • WHEN 管理員開啟月度財報頁, THEN 可自選開始月份與結束月份，並提供「近 3 個月／近 6 個月／全部」快捷
  • WHEN 區間選好, THEN 上方三格數字：這段期間賣出的卡券（收到的錢）、這段期間核銷的金額（附轉化率）、還沒用掉的餘額（欠顧客的）
  • WHEN 報表產生, THEN 每個月各有三列：該月賣出的卡券金額（收入）、該月核銷的金額（消耗）、兩者的差額；每列再按六大類別拆開，並附當月小計
  • WHEN 報表最後, THEN 列出這段期間的總計（收入合計＋核銷合計）
  • WHEN 管理員點「匯出月度財報」, THEN 下載 CSV 檔，用 Excel 打開中文不能變亂碼
  • WHEN 頁面載入, THEN 另外顯示每月開卡與核銷的折線趨勢圖（2026-08-23 依設計稿修正，原寫長條圖）

Independent Test

選「近 3 個月」，確認每月三列、六大類別小計、期末總計三組數字互相算得對；匯出 CSV，確認中文不亂碼。

設計稿

月度財報 — 月份區間、按月三列拆解、六大類別小計、CSV/Excel 匯出

月度財報 — 月份區間、按月三列拆解、六大類別小計、CSV/Excel 匯出 開啟互動原型 ↗
出自 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` 或人工映射