EMS

閱讀基準： 主需求 #1422 與 HTML Mock v0.4／附件 #1121。以下沿用主票區塊編號，依畫面由上到下、由左到右說明。Mock 數字皆為假資料；功能適用所有案場，A17 不是固定規則。

03｜六張 KPI：本票要完成什麼¶

讓使用者快速讀懂設備連線、可服務數、未結束充電、等待供電、今日完成用量與上月應收電費。 位置在「需留意事項」下方、即時負載／群組上方。

雖然舊票名包含「即時」，六張 KPI 實際都是一般營運摘要：共用 Overview 首載／每 5 分鐘／手動刷新，不訂閱 Dashboard WebSocket。下方兩個即時區塊是另一份 live state，不要求同秒同步。

1. 先對照六張卡的畫面順序¶

正式名稱已定案，不再使用「Charge Point 在線」、「進行中充電」、「今日累積電量」或「本月預估電費」。表中數字只是對照版面，不是固定驗收值。

以下 2～7 節依卡片由左至右說明；第 8～10 節是六張卡共用規則。

2. 03-1 Charge Point 連線¶

要回答：啟用的 CP 中，有多少已被系統記錄為 OCPP 在線？ 連線正常不等於設備可充電，ONLINE＋FAULTED 可以同時成立。（KPI-DEC-002）

必須滿足 onlineCount＋offlineCount＋unknownCount＝enabledChargePointCount。不能沿用未套 building 的全 Branch count；disabled 不當 OFFLINE，也不因 disabled 建立離線需留意項目。

例：6 台 CP、5 台啟用（4 ONLINE、1 OFFLINE），顯示 4 / 5 台啟用，不是 4 / 6；另列 1 台停用。

既有 ems_branch OCPP 建連／斷線、BootNotification、Heartbeat、offline watchdog 已維護 persisted 連線狀態。Dashboard 不再比較 lastHeartbeat、不另設 cutoff、不改 watchdog、不逐 Heartbeat 發 browser event 或建立每 CP socket。Runtime 仍由原 StatusNotification 等來源維護。

回傳欄位：上述五個 count、dataStatus、updatedAt。FE 直接使用，不從 CP list／Connector 卡重算。

3. 03-2 Connector 可服務¶

要回答：啟用設備底下，有多少 Connector 沒有已知故障、不可用或連線問題？可服務不等於立即空閒。 忙碌、準備或暫停輸出，不必然不可服務。（KPI-DEC-003）

分母：本案場 enabled CP 下全部 Connector
                   ↓
分子必須同時符合：
  parent CP ONLINE ＋ Connector status 位於可服務 allowlist

允許 status：AVAILABLE、PREPARING、ENQUEUED、CHARGING、SUSPENDED_EV、SUSPENDED_EVSE、FINISHING、RESERVED。

排除：FAULTED、UNAVAILABLE、null／未知／不可解析，或 parent CP OFFLINE／UNKNOWN。即使保留舊 CHARGING，也不能忽略 parent 離線。Connector entity 沒有獨立 enabled 欄位，不虛構新條件；disabled CP 下的 Connector 不入分子分母。

故障直接讀 persisted FAULTED，不按 error text、lastStatusChange 或自訂 timeout 推論；故障與 parent 離線可重疊，不再相加當總數。Backend 查詢須 join CP 並限制 building，不能直接套未隔離案場的 queryStatisticsOfConnector()；FE 不由 Top-8 或其他 KPI 相減重算。

4. 03-3 充電進行中¶

要回答：系統目前仍認定多少筆充電 Session 尚未結束？不是計算 raw CHARGING 的 Connector 數，也不保證此刻每筆都在輸出功率。（KPI-DEC-004／010／011）

4.1 每個 Connector 最多一筆 canonical ACTIVE¶

canonical current transaction 是「沿用既有 Admin snapshot 規則認定的目前交易」，不是直接 COUNT 所有 ACTIVE rows：

currentTransactionId 指向有效 ACTIVE？
    ├─ 是 → 計 1 筆
    └─ pointer 缺漏／失效／尚未同步
             ↓
       該 Connector 最新一筆 transaction 為 ACTIVE？
             ├─ 是 → 計 1 筆
             └─ 否 → 不計較舊孤兒 ACTIVE

• 最新 transaction 已 COMPLETED／CANCELLED／ERROR，不能因較舊孤兒 ACTIVE 增加數字。
• ACTIVE 在 SUSPENDED_EV／SUSPENDED_EVSE／FINISHING、CP OFFLINE 或後來 disabled 時仍保留，直到交易正式結束。
• Queue／off-peak waiting、Remote Start 已送出／接受但尚未建立 StartTransaction，不計入。
• Raw CHARGING 但沒有符合上述規则的 ACTIVE，不計數，也不新增 mismatch 告警／修正。

4.2 卡片只顯示 Session，不顯示功率或推論原因¶

回傳 activeSessionCount、dataStatus、updatedAt。顯示「{N} Sessions」，小字固定「依未結束的充電 Session 計算」。

不讀 Live Load state、不顯示 optional currentPowerKw；目前功率只在 #1462 即時負載顯示。交易來源正常時，即使 Live Load 失敗也不把 Session 清 0。

CP 離線與此數字分別呈現。不顯示「離線充電／待 reconciliation」，不新增 offlineCharging／reconciliationRequired 欄位；不因本卡新增 timeout、自動結束、補寫或 charging lifecycle 修正。第 06 區 Connector 的「充電進行中」分類有另一套 runtime mapping，不要求兩個數字相等。

5. 03-4 等待供電¶

要回答：有多少 Connector 的既有 Queue 已判為 ELIGIBLE，正在等候供電？ 主數字是 Connector 數，不是 Queue row 數。（KPI-DEC-005）

直接使用 e_connector_priority.charge_status，不從 runtime、等待秒數、可用 slot 或排程時間推導。

同 Connector 即使 MANUAL／OFF_PEAK 有多筆 Queue，也只計一次。Scope 是 Backend-resolved Building，資料 commit 後由下次成功 Overview 反映。

回傳 waitingForPowerCount、notPluggedCount、dataStatus、updatedAt；FE 顯示「N 個」，notPluggedCount>0 時補「另有 N 個未插槍（不計入）」，不能加回主數字。不新增 Queue timeout／SLA／scheduler／狀態轉換。

6. 03-5 今日已完成充電量¶

要回答：依案場開始日歸屬規則，今天目前已有多少最終確認的充電量與有效次數？不是今天實際流過的全部電量。（KPI-DEC-006）

唯一來源：#1461 Usage 的 date＝rangeEndDate 那個 today daily bucket。

日期以 building timezone 與 start_timestamp 判斷，跨日整筆歸開始日。ACTIVE／CANCELLED／ERROR 不算；異常 Completed 排除並 PARTIAL；今天開始的 ACTIVE 要完成後下一次成功 REST 才納入。

不新增第二套今日聚合、active-energy query、MeterValue 暫估、跨日拆分或 Usage／Energy WS。FE 不重算；不顯示昨日同時段 ±N% 比較。Tooltip 表達「依交易開始日歸屬，僅包含已完成交易」，0／null／各異常狀態沿用 #1461。

7. 03-6 上月電費¶

要回答：上一完整日曆月的門牌帳單應收電費共多少？不是已收款金額，也不是 Connector 請款總額。（KPI-DEC-001）

7.1 期間與金額來源¶

• Backend 以 generatedAt 轉 building timezone，決定 periodYear／periodMonth；9 月看 8 月，1 月看前一年 12 月。
• 查該案場／該月份 e_bill_settlement.cost_predict，包含用量費與 private／public basic charge；paid／pending 均納入，不依 bill_status 過濾。
• 不改用 e_connector_settlement.fee 或 InvoiceReportDataDto.totalFee，兩者是不同金額。
• V1 currencyCode＝TWD，由 API 回傳，FE 依回傳幣別格式化，不自己寫死幣別或月份。

7.2 全部完成才顯示金額¶

未完成文案：「{月份} 月結算未完成・{completedBillCount} / {totalBillCount} 筆」。無上月帳單的專用 Empty 文案在原票沒有明列最終文字，本次不自行創造金額或新的資料狀態。

回傳 periodYear、periodMonth、amount、currencyCode、completedBillCount、totalBillCount、dataStatus、updatedAt。不退回更早月份、不顯示部分合計、不重算、覆核、付款或修改 Invoice。

7.3 與下方結算流程的差別¶

本卡固定上一日曆月；#1460 的流程區顯示最近已存在結算資料的期間，兩者可以不同月。整卡定位 #billing 方便查看流程，不新增 Drawer、明細 API、forecast、收款比例或帳務操作按鈕。

8. 六張卡共用資料狀態¶

保留六張卡的標題與位置，狀態改變不讓卡消失；0 是有效值，null／缺欄位／尚未載入不是 0。（KPI-DEC-007）

各來源回 dataStatus（COMPLETE／PARTIAL／ERROR）、freshness、updatedAt、必要 lastSuccessfulAt，value 允許 null。子查詢失敗不可 catch 後回 0；一個 source 只影響相依卡，共用該 source 的卡可一同受影響，其他卡繼續顯示。

Cache key 含 Backend-resolved buildingId，不能跨案場沿用。六卡所有刷新使用同一語意；Socket 斷線不清空／停止 KPI。#1424 的 global per-source freshness 適用，不另建 cutoff。

9. 排版與卡片導覽¶

9.1 固定六卡，只換欄數（KPI-DEC-008）¶

桌面 ≥1240px       [03-1][03-2][03-3][03-4][03-5][03-6]
768～1239px        [03-1][03-2][03-3]
                   [03-4][03-5][03-6]
320～767px         [03-1][03-2]
                   [03-3][03-4]
                   [03-5][03-6]

同一份 DOM、CSS Grid 改欄數，不用 JS device 判斷或複製兩套內容；同列等高，長標題／單位／狀態可換行，列高自然增加。不能截斷、省略、過度縮小、隱藏、重排、輪播、分頁或水平捲動；320px 以上可讀。

9.2 每張是一個原生 link（KPI-DEC-009）¶

• 目的地依第 1 節 FE 固定 mapping；同分頁導覽，不開 popup／新窗、不附未確認 filter、不新增明細頁；Backend 不回 URL／target／keyboard／ARIA 欄位。
• 整卡 pointer／touch hit area，每卡一個 Tab stop；Tab／Shift+Tab 依固定順序，Enter 啟用，不攔截 Space 模擬 button。
• 不用只有 onClick 的 div，不巢狀第二個互動控制。Loading／0／PARTIAL／ERROR／STALE 仍保留連結，不因數字未知 disabled。
• 清楚 focus-visible，不能被 overflow／sticky header 遮住；hover 不取代 keyboard focus。
• #usage／#billing 使用原生 anchor，保留 hash／捲動，再把 focus 移至 tabindex=-1 且有標題／aria-labelledby 的目標 section，提供定位提示。
• reduced motion 停用非必要平滑捲動／hover transition，但保留焦點與導覽。
• accessible name 含名稱、數值或明確狀態、目的地，與 visible text 同步更新。Loading 可 aria-busy，skeleton 裝飾性、不重複朗讀。
• KPI Grid 不設自動播報 live region，5 分鐘／手動刷新不逐卡打斷朗讀，聚焦時讀最新內容。

10. 更新方式與工程分工¶

一次 Overview（首載／每 300 秒／手動）
             ↓
       六張 KPI 的 value／status／時間
             ↓
       FE 同步畫面與 accessible name

下方兩個 WS live blocks：獨立 state，KPI 不讀取、不覆寫

Backend 針對狀態 commit 後的下次 Overview 回最新聚合，不新增 KPI event publisher、逐卡 timer／socket、NETWORK_HEALTH_UPDATED／CONNECTOR_OVERVIEW_UPDATED 訂閱或重連機制。

Dashboard 不修改 OCPP connection/runtime、watchdog、充電、Queue priority／lifecycle、Rotation、Transaction、Billing、Invoice 或排程。沒有 forecast、告警、派工、確認 dialog、通知中心或語音播報設定。

11. 驗收清單¶

• 六卡名稱／順序／目的地符合第 1 節，所有值來自 Backend，同一套支援所有案場。
• CP enabled 範圍、三種連線 count 加總正確；disabled 不當離線、不改 Heartbeat cutoff，ONLINE＋FAULTED 合法。
• Connector 分母與 allowlist／parent ONLINE 正確；faulted 是子集合，不重複加總或按 preview 重算。
• ACTIVE pointer／最新 transaction／孤兒 ACTIVE 各情境正確，每 Connector 最多一筆；offline／disabled 保留但不推論離線充電。
• 不重複顯示功率，Queue／未建立 StartTransaction 不計 Session，Live Load 失敗不清空正常 Session。
• ELIGIBLE distinct、NOT_PLUGGED 互斥、BLOCKED／其餘排除正確。
• 今日兩數等於 Usage today bucket，開始日跨日／有效交易／0／null 正確，無估算／昨日比較。
• 上月按時區／generatedAt 且跨年正確；至少一筆且全 COMPLETE 才顯示 cost_predict 合計，paid／pending 均納入，無部分金額／舊月 fallback。
• 六卡 Loading／0／PARTIAL 有值／無值／Initial Error／Refresh Error／STALE／恢復正確，source 隔離、cache 不跨 building。
• 首載／5 分鐘／手動共用 Overview，無 KPI WS；不覆寫兩個 live blocks、不充當 socket fallback。
• 1440 為6×1、768／1024 為3×2、390 為2×3；臨界1240／1239、768／767及320最小寬度無溢出／重複卡。
• mouse／touch／Tab／Shift+Tab／Enter 與至少一種 screen reader 可驗收；所有資料狀態維持單一 link、同頁焦點正確、無逐卡 live announce。
• production 無 fixture fallback，無業務 mutation。

Mock ?kpi=loading／partial／error／refresh-error／stale／zero 以第 03-5 卡展示共用狀態，非正式 query contract。

12. 決策索引與既有查核紀錄¶

001～010 於 2026-09-04、011 於 2026-09-06 已確認；傳輸依 #1424 DEC-031／032，Usage 來源並依 #1461 USG-DEC-010。早期 optional 功率與「今日累積電量」已被較新決策取代；不恢復為待確認項目。

2026-09-04 A17 舊票唯讀基線，本次未重查： 2026/08 共11筆門牌帳單，10 COMPLETE、1 ERROR；應顯示—與10/11。已完成部分8983.75元、包含ERROR的9533.63元，都不能冒充完整金額；全數完成後依當時資料重算顯示，不固定驗收金額。

相關票：#1424 共用資料／權限、#1461 Usage、#1460 結算流程、#1463 需留意事項。

需求管理與本次編輯¶

• 本票仍是已確認需求的追蹤票，不代表已完成開發或通過測試；指派、狀態、進度、附件與父子關係均維持原狀。
• v0.4 Draft 文件套件已依 #1422 DOC-DEC-001 發布並保留 v0.2／v0.3；目前閱讀基準為 PDF #1119、Markdown #1120、HTML #1121。此版仍是 review Draft，尚非 v1.0。
• 2026-09-14：僅重整 Description、說明與排版，將已確認決策併入對應畫面／工程工作；決策編號保留供追溯。E2E impact：No catalog change（沒有修改產品行為、公式或 API 契約）；功能實作時仍須遵循主票與本票驗收。