討論 #1461
是由 陳國瑋 於 28 天 前更新
## 討論目的
確認 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 與缺少日期資料的呈現方式另行確認。
## USG-DEC-002：有效充電量只採已完成交易的最終電量
**狀態：已確認（2026-09-03，Ken）**
### 指標定義
有效充電量使用下列唯讀聚合語意：
validEnergyKWh = SUM(energy_consumed) / 1000
納入條件：
- Transaction status 必須是 COMPLETED。
- energy_consumed 必須非 null 且大於或等於 0。
- energy_consumed 單位為 Wh，API 聚合後轉成 kWh。
- 0 Wh 的 COMPLETED 交易可納入資料集合，但對有效充電量的加總貢獻為 0；不得只因為 0 Wh 就自行改成 ERROR。
不納入有效充電量：
- ACTIVE：尚未形成最終 energy_consumed，完成後才納入。
- CANCELLED、ERROR。
- energy_consumed 為 null 或負值的 COMPLETED 交易。
### Partial 語意
- 如果查詢範圍內存在 energy_consumed 為 null 或負值的 COMPLETED 交易，Backend 將其排除於加總，並回傳 excludedEnergyTransactionCount。
- 上述資料品質缺漏會使 Usage 區塊標示 PARTIAL；不得靜默忽略，也不得把缺值當成 0。
- ACTIVE、CANCELLED、ERROR 因本來就不符合本指標定義，不計入 excludedEnergyTransactionCount。
### Backend 要開發的內容
- 使用 e_transactions 已保存的 status 與 energy_consumed 進行 read-only aggregation。
- Overview DTO 回傳 validEnergyKWh、excludedEnergyTransactionCount 及 section／source status。
- 不從 raw MeterValue 為 ACTIVE 或缺值交易另外估算電量。
- 不呼叫帳務重算、不修改 Transaction，也不建立第二套 energyConsumed 寫入公式。
- 每日 kWh series 使用相同的 Completed／energy_consumed eligibility；跨日交易歸屬哪一個日期另案確認。
### Frontend 要開發的內容
- 「有效充電量」顯示 Backend 回傳的 validEnergyKWh，不自行從每日 bucket 重算。
- 提供簡短說明：「僅包含已完成交易；進行中交易完成後納入」。
- section status 為 PARTIAL 時顯示部分完成交易電量缺漏，不能仍標示為完整資料。
- Frontend 不把 null、缺漏或排除筆數轉為 0。
### A17 驗證結果
以 2026-08-05 至 2026-09-03 的 A17 唯讀資料套用此 eligibility：
- 78 筆 COMPLETED 中，77 筆正電量、1 筆 0 Wh。
- null 與負值均為 0 筆，因此 excludedEnergyTransactionCount = 0。
- validEnergyKWh = 2,171.915 kWh。
- 另有 1 筆 ACTIVE，不在本指標內，待交易完成後才納入。
此數字只是當下 baseline，不是所有案場的固定驗收值。
## 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 連線。
- [ ] 有效充電量只加總符合 USG-DEC-002 的 COMPLETED energy_consumed，並正確由 Wh 轉成 kWh。
- [ ] 異常 Completed 的排除筆數可見且區塊標示 PARTIAL；ACTIVE 不進行 MeterValue 估算。
- [ ] 所有資料皆為唯讀彙整，不產生任何業務狀態變更。
## 已驗證的程式碼與 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 實際日切分。
以上數字只用於驗證方案與資料品質，不是所有案場的固定規則，也不是正式驗收期待值。
## 待確認事項
- [x] 「有效充電量」只加總 COMPLETED 且 energy_consumed 非 null、非負的交易；異常 Completed 排除並標示 Partial（USG-DEC-002）。 [ ] 「有效充電量」應採用哪一個既有資料欄位與有效交易條件？
- [ ] 「充電 Sessions」應計算哪些 transaction 狀態？
- [ ] 「時間使用率」的分子、分母與無資料語意。
- [ ] 缺少單日資料時應顯示 0、null 或 Partial。
- [ ] Empty／Partial／Error 的具體文案與圖表呈現。
## 需求管理狀態
- Parent：#1422
- Requirement status：**待確認（時間範圍與有效充電量已確認；每日歸屬、Sessions、時間使用率及資料狀態待確認）** status：**待確認（時間範圍已確認；指標定義與資料狀態待確認）**
- Confirmed decision：USG-DEC-001、USG-DEC-002 decision：USG-DEC-001
- Final specification：所有 Dashboard 區塊確認後再整併至 #1422 v1.0 文件
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回