討論 #1461: [Dashboard] 30 日充電用量區塊顯示與資料規則 - EMS - SYLKSOFT - Bug Tracking System

討論 #1461

## 討論目的 

 確認 Dashboard mockup 既有「30 日充電用量」區塊的期間、指標與資料語意。本票只定義唯讀圖表與摘要資訊，不改變交易、電量或充電作業邏輯。 

 ## Source of Truth 

 Redmine attachment #1110 a17-operations-dashboard.html 的既有設計包含： 

 - 標題「30 日充電用量」。 
 - 圖表指標切換：kWh／Sessions。 
 - 三項摘要：有效充電量、充電 Sessions、時間使用率。 
 - Mockup 中的數字均為展示假資料，正式功能必須由 Dashboard API 回傳。 

 原 mockup 沒有 7 日、90 日或自訂日期範圍選擇。 

 ## USG-DEC-001：V1 固定最近 30 個案場日曆日 

 **狀態：已確認（2026-09-03，Ken）** 

 ### 使用者會看到什麼 

 - V1 固定顯示最近 30 個案場日曆日，包含使用者開啟 Dashboard 的今天。 
 - 日期邊界依該 building 的 timezone 判定，不使用瀏覽器時區，也不硬編碼 A17。 
 - 今天尚未結束，因此今天的圖表數值屬於進行中資料；畫面不得暗示今天已完成結算。 
 - 保留 mockup 的 kWh／Sessions 指標切換；切換指標不改變 30 日日期範圍。 
 - V1 不提供 7 日、90 日或自訂日期範圍 selector。 

 ### 日期例子 

 若案場時區日期為 2026-09-03，30 個日期 bucket 為 2026-08-05 至 2026-09-03，共 30 個日曆日；其中 2026-09-03 是進行中的今天。 

 ### Backend 要開發的內容 

 - 依指定 buildingId 及該案場 timezone 產生固定 30 日查詢範圍。 
 - Dashboard read model 回傳 rangeStartDate、rangeEndDate、timezone，以及圖表使用的每日 kWh／Sessions series。 
 - 30 日範圍的日期計算由 Backend 統一負責，Frontend 不自行以 browser timezone 重算。 
 - 本區塊透過 REST 取得；不新增 Usage WebSocket event。 
 - 查詢只讀取、彙整既有資料，不回寫 Transaction、MeterValue、Billing 或其他業務資料。 

 ### Frontend 要開發的內容 

 - 標題維持「30 日充電用量」，不新增日期範圍 selector。 
 - 依 Backend 回傳的 rangeStartDate／rangeEndDate／timezone 顯示同一段 30 日資料。 
 - kWh／Sessions 切換只切換圖表指標，不觸發 7／90 日或自訂範圍查詢。 
 - 今天的 bucket 必須能被辨識為進行中資料。 
 - Loading、Empty、Partial、Error 與缺少日期資料的呈現方式另行確認。 

 ## V1 不開發 

 - 7 日、90 日或自訂日期範圍。 
 - Usage history export。 
 - Dashboard 內的交易或 MeterValue 明細表。 
 - Usage WebSocket publisher。 
 - 任何電量、Session 或時間使用率的寫入、修正或重算操作。 

 ## Acceptance Criteria 

 - [ ] 每次 response 的 rangeStartDate 至 rangeEndDate 依案場 timezone 恰好涵蓋 30 個日曆日。 
 - [ ] rangeEndDate 是案場當天，且該日可明確辨識為進行中。 
 - [ ] kWh 與 Sessions 使用相同 30 日範圍。 
 - [ ] UI 不出現 7 日、90 日或自訂日期範圍控制。 
 - [ ] 切換 kWh／Sessions 不影響 Dashboard WebSocket 連線。 
 - [ ] 所有資料皆為唯讀彙整，不產生任何業務狀態變更。 

 ## 已驗證的程式碼與 A17 基線（非需求決策） 

 ### 現有程式碼 

 - e_transactions 已有 status、start_timestamp、stop_timestamp、meter_start、meter_stop、energy_consumed 與 duration_seconds。 
 - TransactionService 在交易完成時以 meterStop - meterStart 寫入 energyConsumed，單位為 Wh，並將狀態改為 COMPLETED。 
 - 現有 Transaction status 包含 ACTIVE、COMPLETED、CANCELLED、ERROR。 
 - MeterValueTariffCalculationService 另有較完整的 MeterValue 分段與帳務邊界處理；是否需要把該複雜度帶入 Dashboard Usage，尚未決定。 

 ### A17 Read-only Baseline 

 查詢時間：2026-09-03；案場日曆範圍：2026-08-05 至 2026-09-03。 

 - Building：BLD000000014；4 個 Charge Points、12 個 Connectors。 
 - 最近 30 日共有 78 筆 COMPLETED、1 筆 ACTIVE。 
 - 78 筆 COMPLETED 均有 meterStart、meterStop 與 energyConsumed。 
 - 77 筆 energyConsumed > 0、1 筆等於 0、0 筆 null、0 筆負值。 
 - 78 筆的 energyConsumed 均與 meterStop - meterStart 一致。 
 - COMPLETED 正電量合計為 2,171.915 kWh。 
 - 其中 10 筆 COMPLETED 跨越案場日曆日，表示後續仍須明確決定每日 bucket 依交易開始日、完成日或 MeterValue 實際日切分。 

 以上數字只用於驗證方案與資料品質，不是所有案場的固定規則，也不是正式驗收期待值。 

 ## 待確認事項 

 - [ ] 「有效充電量」應採用哪一個既有資料欄位與有效交易條件？ 
 - [ ] 「充電 Sessions」應計算哪些 transaction 狀態？ 
 - [ ] 「時間使用率」的分子、分母與無資料語意。 
 - [ ] 缺少單日資料時應顯示 0、null 或 Partial。 
 - [ ] Empty／Partial／Error 的具體文案與圖表呈現。 

 ## 需求管理狀態 

 - Parent：#1422 
 - Requirement status：**待確認（時間範圍已確認；指標定義與資料狀態待確認）** 
 - Confirmed decision：USG-DEC-001 
 - Final specification：所有 Dashboard 區塊確認後再整併至 #1422 v1.0 文件 
 - Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues

專案

一般

配置概況

EMS

討論 #1461