討論 #1486
是由 陳國瑋 於 27 天 前更新
## 目的
定義 Backend Admin Dashboard「即時關鍵指標」區塊的顯示內容、資料來源、計算邊界、更新方式與異常狀態。V1 僅呈現既有資料，不新增預測、告警、派工或任何作業邏輯。
## Mock 現況（全部為展示假資料）
目前工作版有六張 KPI card：
1. Charge Point 連線。
2. Connector 可服務。
3. 充電進行中。 正在充電。
4. 等待供電。
5. 今日累積電量。
6. 上月電費。
上述數值仍為展示假資料；「上月電費」、「Charge Point 連線」、「Connector 可服務」與「充電進行中」已由 KPI-DEC-001～004 連線」與「Connector 可服務」已分別由 KPI-DEC-001～003 確認，其餘 KPI 的名稱與公式仍須逐項確認。
## 已知約束
- Dashboard 必須適用所有案場；A17 只作第一個資料與效能驗證基準。
- CP connection、Connector runtime、Queue state 必須分層，不能互相覆寫。
- null 代表未知，不得以 0 冒充。
- 案場日期與「今日」以 building timezone 計算。
- V1 read-only，不調整 OCPP、Queue、rotation、結算或排程行為。
- V1 已明確移除「本月預估電費」及 forecast；第六張改用 KPI-DEC-001 定義的「上月電費」。
- KPI 的即時更新應沿用 #1424 已確認的 REST bootstrap／WebSocket replacement 架構，不為每張卡建立獨立連線。
## KPI-DEC-001：第六張 KPI 顯示「上月電費」
**狀態：已確認（2026-09-04，Ken）**
### 這張卡要讓使用者知道什麼
- 顯示指定案場「上一個完整日曆月」的門牌帳單應收總額。
- 「上月」以該案場的 building timezone 判定；例如案場當地時間已進入 9 月，目標期間就是 8 月。
- 金額代表所有門牌月結算資料 `e_bill_settlement.cost_predict` 的合計，不是已收款金額，也不是 Connector 請款金額。
- `paid`、`pending` 等 bill status 不改變當月應收金額，因此均納入合計。
- 只有該月每一筆門牌帳單的 `calculation_status` 都是 `COMPLETE` 時才顯示金額。
- 只要仍有 `PENDING_DATA` 或 `ERROR`，金額顯示 `—`，並清楚顯示完成筆數，例如「8 月結算未完成・10 / 11 筆」。
- 不顯示已完成資料的部分合計，也不自動退回更早月份，避免讓不完整或過期金額看起來像完整結果。
- 整張卡可導向 Dashboard 同頁 `#billing` 結算流程區塊，方便查看是哪個步驟尚未完成；卡片本身不執行任何帳務操作。
### 為何選 `e_bill_settlement.cost_predict`
目前程式碼與 schema 有三種不同金額：
1. `e_bill_settlement.cost_predict`：每門牌月結算應收金額，包含用量費與 private／public basic charge。
2. `e_connector_settlement.fee`：每個 Connector／idTag 的服務費，不等同住戶門牌帳單總額。
3. `InvoiceReportDataDto.totalFee`：Connector settlement fee 的請款報表合計，也不是門牌帳單總額。
「上月電費」採第 1 種語意。此 KPI 不把 `bill_status` 當成收款報表，也不混用第 2、3 種金額。
### Backend 要開發的內容
- 以 Overview API 的 `generatedAt` 轉換為指定 building timezone，求得上一個完整日曆月的 `periodYear`／`periodMonth`。
- 僅查詢指定 `buildingId` 與該期間的 `e_bill_settlement`，不可跨案場彙總。
- 回傳 `periodYear`、`periodMonth`、`amount`、`currencyCode`、`completedBillCount`、`totalBillCount`、`dataStatus` 與 `updatedAt`。V1 的 `currencyCode` 為 `TWD`，但 FE 不自行寫死幣別格式。
- 至少有一筆帳單且全部 `calculation_status = COMPLETE` 時，`dataStatus = COMPLETE`，`amount` 為所有 `cost_predict` 合計。
- 任一筆為 `PENDING_DATA` 時回 `dataStatus = PARTIAL`、`amount = null`；任一筆為 `ERROR` 時同樣不得回傳部分金額，並透過 source status 保留錯誤語意。
- 不依 `bill_status` 過濾 paid／pending，不改用 `e_connector_settlement.fee` 或 Invoice totalFee。
- 不回退查詢更早月份，不觸發重算、覆核、付款、Invoice 更新或其他 mutation。
- 本 KPI 隨 Dashboard REST snapshot／既有 refresh 更新；沿用 #1460 的 V1 邊界，不增加帳務 WebSocket。
> 完全沒有上月帳單資料時的共用 Empty 文案，將與其餘 KPI 的 Empty／Partial／Error 規格一起確認；在確認前不得把 0 筆解讀為 0 元。
### Frontend 要開發的內容
- 標題固定為「上月電費」，月份與金額只格式化 Backend 回傳值，不以瀏覽器時區自行推算。
- `COMPLETE` 時依 `currencyCode` 顯示完整金額；真正合計為 0 才能顯示 0。
- `PARTIAL`／計算錯誤時顯示 `—` 與「{月份} 月結算未完成・{completedBillCount} / {totalBillCount} 筆」，不可顯示部分合計。
- 卡片使用可鍵盤操作的同頁連結導向 `#billing`，具可見 focus 樣式及清楚的 accessible name。
- 不新增 forecast 說明、收款比例、帳務按鈕、Drawer 或 KPI 專用明細 API。
### A17 驗收基準（2026-09-04 唯讀查詢）
- 前一日曆月為 2026/08，`e_bill_settlement` 共 11 筆：10 筆 COMPLETE、1 筆 ERROR。
- 因資料未全部完成，卡片必須顯示 `—` 與「8 月結算未完成・10 / 11 筆」。
- 不得顯示 COMPLETE 部分合計 8,983.75 元，也不得把含 ERROR 資料的 9,533.63 元顯示成完整結果。
- 待 11 筆全部完成後，才依當時正式資料重新加總並顯示金額；驗收不把 mock 金額寫死為固定值。
### Acceptance Criteria
- [ ] 上月由 building timezone 與 generatedAt 決定，跨年時可正確得到前一年 12 月。
- [ ] 金額只使用指定 building／period 的 `e_bill_settlement.cost_predict`，paid／pending 均納入。
- [ ] 全部帳單計算完成前 `amount = null`，FE 顯示 `—`、期間與完成筆數，不顯示部分合計。
- [ ] 不因本月資料存在而改顯示本月，也不因上月未完成而退回更早月份。
- [ ] Card 可使用滑鼠及鍵盤跳到同頁結算流程，且不送出帳務 mutation。
- [ ] A17 2026/08 的 10 / 11 未完成情境符合上述顯示。
## KPI-DEC-002：第一張 KPI 顯示「Charge Point 連線」
**狀態：已確認（2026-09-04，Ken）**
### 這張卡要讓使用者知道什麼
這張卡只回答：「本案場目前應該連線的 Charge Point 中，有幾台已與 Branch 建立有效的 OCPP 連線？」它不回答設備是否可充電，也不把 runtime `FAULTED`／`CHARGING` 等狀態混入連線數。
- 使用者可見名稱由「Charge Point 在線」改為「Charge Point 連線」，避免把「有連線」誤解成「設備運作完全正常」。
- 主數字格式為 `{onlineCount} / {enabledChargePointCount} 台啟用`。
- 分母 `enabledChargePointCount`：指定 `buildingId` 下 `enabled = true` 的 Charge Point 數量。
- 分子 `onlineCount`：上述已啟用設備中，persisted `ocppConnectionStatus = ONLINE` 的數量。
- `OFFLINE` 與 `UNKNOWN` 不算在線，分別回傳並顯示，例如「1 台離線・1 台尚未確認」。
- `enabled = false` 的設備不放入分子或分母，避免計畫停用／除役設備拉低連線比例；若 `disabledCount > 0`，補充顯示「另有 N 台停用」。
- 整張卡導向既有 `/cp/list`；卡片本身只提供導覽，不執行啟用、停用、Reset 或其他設備操作。
### 為何不由 Dashboard 再看 Heartbeat 時間
現有 Backend 已將連線存活與設備運作狀態拆成兩個欄位：
- `ocppConnectionStatus`：`ONLINE`／`OFFLINE`／`UNKNOWN`，由 WebSocket 建連／斷線、BootNotification、Heartbeat 與既有 offline watchdog 維護。
- Charge Point runtime `status`：由 StatusNotification 等既有訊號維護，可為 AVAILABLE、CHARGING、FAULTED 等。
現有 repository／test 也明確要求在線統計讀取 persisted `ocppConnectionStatus`，不得再建立另一個 Heartbeat 時窗。因此 Dashboard 只統計已存在的 authoritative connection state；不比較 `lastHeartbeat`、不設定第二套 cutoff，也不修改 watchdog 行為。
### Backend 要開發的內容
- Overview API 依已授權的 `buildingId` 聚合並回傳：`onlineCount`、`offlineCount`、`unknownCount`、`enabledChargePointCount`、`disabledCount`、`dataStatus`、`updatedAt`。
- 必須符合 `onlineCount + offlineCount + unknownCount = enabledChargePointCount`；unknown enum／null 一律歸入 UNKNOWN，不可當成 ONLINE。
- 聚合查詢必須同時套用 building 與 enabled 條件；不能沿用目前未分 building 的全 Branch count 當成 Dashboard 數字。
- `disabledCount` 只供說明，不加入連線比例，也不因此建立「離線」需留意項目。
- REST overview 提供初始完整數字。既有 `ocppConnectionStatus` 發生 ONLINE／OFFLINE／UNKNOWN transition 且 transaction commit 後，案場級 Dashboard WebSocket 以 `NETWORK_HEALTH_UPDATED` replacement 更新整組計數。
- 每次 Heartbeat 若沒有造成 connection class 改變，不推送事件；不為每台 CP 建立獨立 Dashboard socket。
- Backend 不因 Dashboard 查詢或推送而改寫 connection／runtime status。
### Frontend 要開發的內容
- 顯示 Backend 回傳的分子、分母與 OFFLINE／UNKNOWN 數量，不從 CP list 或 Connector 卡片自行重算。
- `disabledCount = 0` 時可省略停用文案；大於 0 時顯示「另有 N 台停用」。
- 有 OFFLINE／UNKNOWN 時用文字清楚說明，不只靠顏色；runtime 故障另由 Connector／需留意區塊呈現。
- REST bootstrap 後，只接受同一 `buildingId` 且 sequence 較新的 `NETWORK_HEALTH_UPDATED` replacement。重連或 sequence gap 時重新取得 authoritative snapshot。
- 整張卡使用可鍵盤操作的固定 route link `/cp/list`，具可見 focus 狀態；Backend payload 不回傳任意 URL。
### 顯示例子
案場有 6 台 Charge Point，其中 5 台啟用：4 台 ONLINE、1 台 OFFLINE，另有 1 台停用。
- 主數字：`4 / 5 台啟用`
- 說明：`1 台離線・0 台尚未確認・另有 1 台停用`
停用設備不會被顯示成離線，也不會讓主數字變成 `4 / 6`。
### Acceptance Criteria
- [ ] 分子、分母只涵蓋指定 building；分母只計 enabled = true。
- [ ] ONLINE／OFFLINE／UNKNOWN 三者總和等於 enabledChargePointCount。
- [ ] Disabled CP 不計入分母、不算 OFFLINE；存在時可另外顯示 disabledCount。
- [ ] Dashboard 不依 lastHeartbeat 自行重判 ONLINE／OFFLINE，也不修改既有 watchdog cutoff。
- [ ] OCPP connection 與 runtime status 分開；ONLINE + FAULTED 是合法且可被正確呈現的組合。
- [ ] 初始 REST 與 NETWORK_HEALTH_UPDATED WebSocket replacement 使用相同聚合規則。
- [ ] Heartbeat 未造成狀態 transition 時不逐筆推送 Dashboard event。
- [ ] Card 可使用滑鼠及鍵盤前往 `/cp/list`，且不執行任何設備 mutation。
## KPI-DEC-003：第二張 KPI 顯示「Connector 可服務」
**狀態：已確認（2026-09-04，Ken）**
### 這張卡要讓使用者知道什麼
這張卡回答：「本案場已啟用設備底下的 Connector，有多少目前沒有已知故障、不可用或連線問題？」它衡量的是設備能否持續提供既有或後續充電服務，不是「現在是否空閒」。
因此：
- `AVAILABLE` 是空閒、可立即開始充電；但「可服務」的範圍更廣。
- 正在充電、準備中、排隊、暫停輸出、結束中或已預約，仍屬已知的正常服務生命週期，不因忙碌就判成不可服務。
- 整張卡導向既有 `/connector/list`；Dashboard 只呈現與導覽，不執行 Remote Start／Stop、Reset、狀態修正或其他設備操作。
### 分母與分子
**分母 `totalConnectorCount`**
- 指定 `buildingId` 下，所屬 Charge Point 為 `enabled = true` 的所有 Connector。
- 目前 Connector entity 沒有獨立 enabled 欄位，因此 V1 不虛構 Connector enabled 條件。
- 掛在 disabled Charge Point 下的 Connector 不進入分子或分母。
**分子 `serviceableCount` 必須同時符合兩項條件**
1. 所屬 Charge Point 的 persisted `ocppConnectionStatus = ONLINE`。
2. Connector persisted status 屬於以下 allowlist：
- `AVAILABLE`
- `PREPARING`
- `ENQUEUED`
- `CHARGING`
- `SUSPENDED_EV`
- `SUSPENDED_EVSE`
- `FINISHING`
- `RESERVED`
**下列情況不算可服務**
- Connector status 為 `FAULTED` 或 `UNAVAILABLE`。
- Connector status 為 null、未知 code 或無法解析。
- 所屬 Charge Point 的 OCPP connection 為 `OFFLINE` 或 `UNKNOWN`；即使 Connector 留有舊的 CHARGING 狀態，也不能讓它看起來仍是可正常通訊的設備。
`nonServiceableCount = totalConnectorCount - serviceableCount`。`faultedCount` 是不可服務項目的資訊子集合，可能與 parent CP 離線同時成立，因此 UI 使用「其中 N 個故障」，不把各原因數量再次相加當成總數。
### Backend 要開發的內容
- Overview API 依已授權 `buildingId` 聚合並回傳 `serviceableCount`、`totalConnectorCount`、`nonServiceableCount`、`faultedCount`、`dataStatus` 與 `updatedAt`。
- 聚合必須 join 所屬 Charge Point，套用 building、CP enabled、CP OCPP connection 與 Connector status allowlist；不得使用目前沒有 building filter 的全 Branch `queryStatisticsOfConnector()` 結果。
- 必須符合 `serviceableCount + nonServiceableCount = totalConnectorCount`；未知／null status 安全歸入不可服務，不得 fallback 成 AVAILABLE。
- `faultedCount` 直接來自既有 persisted Connector status，不依 error text、lastStatusChange 或 Dashboard 自訂 timeout 推測。
- REST overview 提供初始完整數字。Connector status 或 parent CP connection transition commit 後，案場級 Dashboard WebSocket 以 `CONNECTOR_OVERVIEW_UPDATED` replacement 更新整組 Connector summary。
- REST 與 WebSocket 必須共用同一 aggregation／presentation rule；FE 不自行掃描 preview cards 重算。
- 不新增 Connector health scheduler、timeout、狀態修正或任何 charging／OCPP mutation。
### Frontend 要開發的內容
- 主數字顯示 `{serviceableCount} / {totalConnectorCount} 個`。
- 說明列顯示「{nonServiceableCount} 個目前不可服務」；`faultedCount > 0` 時補充「其中 {faultedCount} 個故障」。
- 文字必須明確說明「可服務不等於立即空閒」；不得把 serviceableCount 改標成 AVAILABLE 數量。
- 卡片使用 Backend 回傳的聚合值，不從畫面上有限筆 preview、Connector Drawer 或其他 KPI 相減重算。
- 整張卡使用固定 route `/connector/list`，支援滑鼠、鍵盤及可見 focus；Backend payload 不回傳任意 URL。
- 套用同 building、較新 sequence 的 `CONNECTOR_OVERVIEW_UPDATED` replacement；sequence gap／重連時重新取得 REST snapshot。
### Mock 顯示例子
工作版假資料為 12 個 Connector：11 個符合可服務條件、1 個 `FAULTED`。
- 主數字：`11 / 12 個`
- 說明：`1 個目前不可服務・其中 1 個故障`
這只是用來驗證版面與文案，不代表 A17 即時營運結果，也不作為正式驗收固定數字。
### Acceptance Criteria
- [ ] 分母只包含指定 building 下 enabled CP 的 Connector；disabled CP 的 Connector 完全排除。
- [ ] 分子同時要求 parent CP ONLINE 與 Connector status 位於固定 serviceable allowlist。
- [ ] FAULTED、UNAVAILABLE、未知 status，以及 parent CP OFFLINE／UNKNOWN 均不算可服務。
- [ ] serviceableCount + nonServiceableCount 等於 totalConnectorCount；faultedCount 只作「其中」說明，不被再次加總。
- [ ] CHARGING／PREPARING／ENQUEUED／SUSPENDED／FINISHING／RESERVED 不因不是 AVAILABLE 就被誤判為不可服務。
- [ ] REST snapshot 與 CONNECTOR_OVERVIEW_UPDATED 使用完全相同的 Backend 計算規則。
- [ ] Card 可使用滑鼠及鍵盤前往 `/connector/list`，且不執行任何設備 mutation。
- [ ] Dashboard 不新增 health timeout、排程或狀態修正行為。
## KPI-DEC-004：第三張 KPI 顯示「充電進行中」
**狀態：已確認（2026-09-04，Ken；中文名稱依 Ken 意見調整）**
### 正式名稱與使用者語意
- 使用者可見名稱採「充電進行中」，不使用語序較不自然的「進行中充電」。
- 這張卡回答：「系統目前仍認定有多少筆尚未結束的充電 Session？」
- 它計算 ACTIVE transaction，不等同於 Connector raw status 恰好為 `CHARGING`，也不保證每一筆此刻都正在輸出電力。
### Active Session 計數規則
Backend 對指定 `buildingId` 的每個 Connector，沿用既有 Admin Connector snapshot 的 current transaction 解析方式；每個 Connector 最多計一筆：
1. 若 `connector.currentTransactionId` 指向一筆 `status = ACTIVE` 的 transaction，該 Connector 計一筆。
2. 若 current pointer 缺漏、失效或尚未同步，只有該 Connector「最新一筆 transaction」的 status 為 ACTIVE 時才計一筆。
3. 若最新一筆已是 COMPLETED／CANCELLED／ERROR，較舊且殘留的孤兒 ACTIVE row 不得計入。
補充邊界：
- 不要求 Connector status 必須等於 CHARGING。ACTIVE Session 在 `SUSPENDED_EV`、`SUSPENDED_EVSE`、`FINISHING`，或 parent CP 暫時 OFFLINE 時仍計入，直到 transaction 正式結束。
- 即使 Charge Point 後來被 disabled，已存在且尚未結束的 ACTIVE Session 仍須顯示，避免隱藏待結束／待 reconciliation 的交易。
- Queue waiting、off-peak waiting、Remote Start 已送出／接受但尚未建立 StartTransaction，都不算 ACTIVE Session；它們由「等待供電」或 Connector 狀態呈現。
- Connector raw status = CHARGING，但依上述 current transaction 規則找不到 ACTIVE transaction 時，不計入 Session 數；V1 不因此新增 mismatch 告警或狀態修正。
### Backend 要開發的內容
- Overview API 回傳 `activeSessionCount`、`dataStatus` 與 `updatedAt`，scope 必須經授權並限制於指定 building。
- 聚合查詢須以每個 Connector 的 canonical current transaction 為準，避免直接 `COUNT(status = ACTIVE)` 把舊孤兒資料重複算入。
- 必須保證同一 Connector 最多一筆，且 `activeSessionCount` 不受 Connector preview 顯示上限影響。
- Transaction start／stop commit 後，以案場級 `CONNECTOR_OVERVIEW_UPDATED` replacement 更新 activeSessionCount；REST overview 與 WebSocket 共用同一規則。
- 卡片次要文字的 `currentPowerKw` 直接重用已確認的 Live Load current snapshot；不為此 KPI 重新加總 MeterValue。
- Active Session source 與 Live Load source 的 dataStatus 分開：交易計數可正常顯示時，不因即時功率暫時未知就把 Session 數清為 0。
- 不新增 transaction timeout、自動結束、補寫、狀態修正或其他 charging lifecycle。
### Frontend 要開發的內容
- 標題固定顯示「充電進行中」，主數字顯示 `{activeSessionCount} Sessions`。
- 數字直接使用 Backend aggregate；不得以 Connector status = CHARGING 的 card 數、preview 數量或 current power 是否大於 0 重新推導。
- 說明列可顯示已確認 Live Load 的 `currentPowerKw`，例如「即時功率 21.84 kW」；功率未知時顯示 `—` 與對應資料狀態，不影響已知的 Session 數。
- `CONNECTOR_OVERVIEW_UPDATED` 更新主數字；`LIVE_LOAD_UPDATED` 更新次要功率，兩者可獨立刷新。
- 整張卡使用固定 route `/connector/list`，支援滑鼠、鍵盤及可見 focus；Backend payload 不回傳任意 URL。
### Mock 顯示例子
工作版使用 3 筆假 ACTIVE Session：
- 標題：`充電進行中`
- 主數字：`3 Sessions`
- 說明：`即時功率 21.84 kW`
數字僅供版面 review，不代表 A17 即時營運結果。
### Acceptance Criteria
- [ ] 使用者可見名稱必須是「充電進行中」。
- [ ] 每個 Connector 依 canonical current transaction 最多計一筆 ACTIVE Session。
- [ ] 最新 transaction 已結束時，不得因較舊孤兒 ACTIVE row 而增加計數。
- [ ] ACTIVE Session 在 suspended、finishing、CP offline 或 CP disabled 情境仍保留，直到 transaction 正式結束。
- [ ] Queue／off-peak waiting／尚未建立 StartTransaction 的 remote operation 不計入。
- [ ] Session 主數字不依 Connector CHARGING card 數或 currentPowerKw 推導。
- [ ] REST 與 CONNECTOR_OVERVIEW_UPDATED 使用相同 aggregate；Live Load 功率獨立由 LIVE_LOAD_UPDATED 更新。
- [ ] Card 可使用滑鼠及鍵盤前往 `/connector/list`，且不執行 Stop 或其他 mutation。
- [ ] Dashboard 不新增 transaction timeout、自動結束或資料修正行為。
## 待確認事項
- [x] 第六張移除「本月預估電費」，改為「上月電費」；採前一完整日曆月的門牌帳單應收總額，且全部計算完成才顯示金額（KPI-DEC-001）。
- [x] Charge Point 連線使用指定 building 的 enabled CP 為分母、persisted OCPP ONLINE 為分子；OFFLINE／UNKNOWN／disabled 分開，採 REST bootstrap + NETWORK_HEALTH_UPDATED replacement（KPI-DEC-002）。
- [x] Connector 可服務要求 parent CP ONLINE 且 status 位於固定 allowlist；FAULTED、UNAVAILABLE、unknown 或 parent CP 非 ONLINE 均排除，分母只含 enabled CP 的 Connector（KPI-DEC-003）。
- [x] 「充電進行中」依每個 Connector 的 canonical ACTIVE transaction 計算；不以 raw CHARGING 或功率推導，且保留 offline／disabled CP 下尚未結束的 Session（KPI-DEC-004）。
- [ ] 「等待供電」的精確來源、狀態範圍與 distinct 正在充電與等待供電的精確來源／distinct 規則。
- [ ] 今日累積電量的日期、有效資料與 Partial 規則。
- [ ] 其餘即時 KPI 的 WebSocket replacement／REST refresh 分工。
- [ ] KPI 共用 Empty／Partial／Error、responsive、accessibility 與 deep link 規則。
## 需求管理狀態
- Parent：#1422
- Related：#1424（REST／WebSocket）、#1460（結算流程）、#1461（30 日充電用量）、#1463（需留意事項）
- Requirement status：討論中；KPI-DEC-001～004（上月電費、Charge status：討論中；KPI-DEC-001～003（上月電費、Charge Point 連線、Connector 可服務、充電進行中）已確認，其餘兩張 可服務）已確認，其餘三張 KPI 與共用狀態待逐項確認
- Final specification：所有 Dashboard 區塊確認後整併至 #1422
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回