討論 #1486
是由 陳國瑋 於 27 天 前更新
## 目的
定義 Backend Admin Dashboard「即時關鍵指標」區塊的顯示內容、資料來源、計算邊界、更新方式與異常狀態。V1 僅呈現既有資料，不新增預測、告警、派工或任何作業邏輯。
## Mock 現況（全部為展示假資料）
目前工作版有六張 KPI card：
1. Charge Point 在線。
2. Connector 可服務。
3. 正在充電。
4. 等待供電。
5. 今日累積電量。
6. 本月預估電費。
上述名稱、公式與數值尚未全部確認，不能直接視為最終需求或 A17 現況。
## 已知約束
- Dashboard 必須適用所有案場；A17 只作第一個資料與效能驗證基準。
- CP connection、Connector runtime、Queue state 必須分層，不能互相覆寫。
- null 代表未知，不得以 0 冒充。
- 案場日期與「今日」以 building timezone 計算。
- V1 read-only，不調整 OCPP、Queue、rotation、結算或排程行為。
- 「本月預估電費」目前沒有已確認的 forecast 公式、資料完整度與誤差語意；在確認前不得進入 final specification。
- KPI 的即時更新應沿用 #1424 已確認的 REST bootstrap／WebSocket replacement 架構，不為每張卡建立獨立連線。
## KPI-DEC-001：第六張 KPI 改為「上月電費」，金額語意待確認 第一個建議決策
**狀態：項目已確認、計算定義待確認（2026-09-04，Ken）** 移除未定義的「本月預估電費」，改為「今日已完成充電 Sessions」：
### 已確認
- 移除 mock 原有「本月預估電費」。 使用 #1461 已確認的 valid session 規則：COMPLETED 且 energy_consumed > 0。
- 第六張 KPI 不改成「今日已完成充電 Sessions」，改為「上月電費」。 依 building timezone 的交易開始日歸屬今天。
- V1 不新增當月費用 forecast 或其他預測邏輯。 ACTIVE session 不計入此卡；目前進行中的數量由「正在充電」另行呈現。
- Mock 先顯示「上月電費／—／金額來源定義中」，避免在公式確認前沿用 8,920 元假裝已有定義。 顯示既有事實統計，不做費用預測。
### 程式碼與 schema 事實 此項尚待 Ken 確認。
目前存在三種不同金額語意：
1. e_bill_settlement.cost_predict：每門牌月結算金額，包含用量費與 private／public basic charge，另有 bill_status 與 calculation_status。
2. e_connector_settlement.fee：每個 Connector／idTag 的月應收費用，不等同門牌帳單合計。
3. InvoiceReportDataDto.totalFee：由 Connector settlement fee 加總的請款報表金額，另有 invoice status 與 calculation_status。
因此「上月電費」不能只憑欄位名稱選任一 SUM，必須先確認要顯示應收、已收，或 Connector 請款金額。
### A17 唯讀彙總基準（2026-09-04 查詢）
前一日曆月為 2026/08：
- e_bill_settlement：11 筆，cost_predict 合計 9,533.63 元。
- 其中 COMPLETE 10 筆／8,983.75 元，ERROR 1 筆／549.88 元。
- e_connector_settlement：12 筆，fee 合計 2,262.15 元；其中 1 筆 calculation_status = ERROR。
- e_bill_invoice_status：status = draft，calculation_status = ERROR。
以上只包含案場彙總，未記錄門牌、住戶或交易明細。它證明 2026/08 尚不能直接當成完整、最終電費顯示。
### 尚待確認的核心語意
- 上月「應收電費」：所有門牌帳單應收合計，不因 paid／pending 改變。
- 上月「已收電費」：只加總 paid，會隨付款狀態變動。
- 上月「Connector 請款金額」：加總 connector fee，不包含相同的門牌基本費結構。
必須先選定其中一種，才能定義 COMPLETE／PARTIAL／ERROR、0／null、期間欄位與 deep link。
## 待確認事項
- [x] 第六張移除「本月預估電費」，改為「上月電費」；精確金額語意另行確認（KPI-DEC-001）。 六張 KPI 的最終保留／替換項目與固定順序。
- 「上月電費」採應收、已收或 Connector 請款金額。
- Charge Point 在線的 connection／freshness 定義。
- Connector 可服務的 status allowlist 與 unknown 處理。
- 正在充電與等待供電的精確來源／distinct 規則。
- 今日累積電量及今日 Sessions 的日期、有效資料與 Partial 規則。
- 哪些 KPI 使用 WebSocket replacement、哪些只隨 REST refresh。
- Empty／Partial／Error、responsive、accessibility 與 deep link。
## 需求管理狀態
- Parent：#1422
- Related：#1424（REST／WebSocket）、#1460（結算流程）、#1461（30 Related：#1424（REST／WebSocket）、#1461（30 日充電用量）、#1463（需留意事項）
- Requirement status：討論中；第六張選用「上月電費」已確認，金額語意待確認 status：討論中；尚無已確認 KPI 決策
- Final specification：所有 Dashboard 區塊確認後整併至 #1422
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回