voucher-operational-reports

Epic 2：營運數據統計 (Operational Analytics) — 對應頁面：今日營運、歷史統計、月度財報 設計稿依據：「M+ Admin.html」(2026-08-06)。owl 只定「要看什麼數字、怎麼算、怎麼呈現」； 計算實作與資料表設計由 cockatiel 自跑 prospec 決定。

Background

管理員後台要有三份報表：今日營運、歷史統計、月度財報。目前只有設計稿，沒有規格。三份報表算的都是同一件事——「開了多少卡、用掉多少」——只是時間範圍不同（今天／到某一天為止的累積／按月拆開）。放在同一份需求裡定義，才不會三頁各算各的、數字對不起來。

User Stories

P1 US-1

今日即時營運概況

查看完整規格 →

P1 US-2

特定日期區間歷史統計

查看完整規格 →

P1 US-3

月度類別收支明細報表（財報版）

查看完整規格 →

Edge Cases

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

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: 完整的多分店功能（建店、每筆交易歸哪間店、跨店合併看）這期不做，另開需求

Success Criteria

• SC-001: 今日營運頁的數字跟歷史統計頁選「今日」的數字一致（同一份資料的兩種看法）
• SC-002: 月度財報的月度小計加總 = 期間累計總額，100% 可驗算
• SC-003: 匯出的 CSV 在 Excel 開啟時中文欄位不亂碼

2026-08-24 範圍調整：「需要關注」面板（原 US-1）與 30 日趨勢圖（原 US-2） 因設計稿未畫且經拍板本期不做，已自本規格移除。匯出一律為 CSV（見 FR-004）。

Related Modules

• （owl 為產品層 spec hub，無程式模組）
• 後端：目前只能一筆一筆查明細，沒有任何「加總、算比例、看趨勢」的功能，報表需要的統計全都要新做
• 後端：目前系統沒有「分店」這個概念，交易也無從得知發生在哪一間店（本期決議只先預留參數，見 FR-008）
• 前端：管理後台目前沒有這三個頁面，需新做（含圖表）

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` 或人工映射

Constitution Check

• Reviewed against prospec/CONSTITUTION.md
• P1（owl 是產品層）：PASS — 描述統計口徑與行為，未涉及實作技術
• P2（契約意圖在 owl、實體在 cockatiel）：PASS — 未指定聚合 API 的 endpoint/schema，僅描述需要的統計能力
• P3/P4（兩軌分離、協調點）：PASS — 無新增手動同步步驟

UI Scope

Scope: full

（設計稿已存在：M+ Admin 今日營運／歷史統計／月度財報三頁。）