專案

一般

配置概況

下載 (36.2 KB)

Feature #1422 » backend-admin-dashboard-requirements-v0.4.md

v0.4 Draft｜需求說明書 Markdown - 陳國瑋, 2026-09-16 11:47

 

Backend Admin 營運 Dashboard 需求說明書

文件版本：v0.4 Draft
文件日期：2026-09-16
追蹤議題：Redmine #1422
適用範圍：所有 EMS Branch 案場；A17 僅為第一個資料基準與展示案例
文件狀態：需求討論快照，尚未進入 v1.0 需求鎖定與開發
配套 Mock：backend-admin-dashboard-mock-v0.4.html

本文件是目前已確認需求的完整快照，供 Product、FE、Backend、QA 與維運共同 review。Mock 內所有數字均為 UI 假資料，不代表 A17 或其他案場的即時營運結果。

1. 文件管理

1.1 版號規則

版號 用途 是否可直接進入開發
v0.x Draft 需求討論與 review 快照；每次保留 PDF、Markdown、HTML Mock 三份同版附件 否
v1.0 所有必要需求確認後的開發基準 是，仍須依 Redmine SOP 通過規劃關卡
v1.x v1.0 後的需求釐清或核准變更 依該版變更內容判定

每一個 review checkpoint 都必須產出相同版號、相同日期的 PDF、Markdown 與 HTML Mock。新版本一律新增至 Redmine #1422，不覆寫、不刪除舊附件。

1.2 版本紀錄

版號 日期 狀態 內容
v0.2 Draft 2026-07-25 已封存於 #1422 舊版 PDF #1108、Markdown #1109、HTML #1110
v0.3 Draft 2026-09-07 已封存於 #1422 納入當時已確認的跨案場、資料來源、WebSocket、KPI、Connector、負載、用量與帳務決策
v0.4 Draft 2026-09-16 本次 review 快照 修正 v0.3 一致性稽核 PKG-01～10；確認 Drawer 定義、「摘要分類」displayBucket、Full List search 最小契約與 canonical fixture

1.3 本版定位

  • 本版是「顯示資訊」的 Dashboard，不新增控制充電、重送命令、補帳、修改排程或調整案場設定的操作。
  • 本版保留必要的即時資訊，但不追求監控中心等級的秒級正確性、斷線容錯或專用告警系統。
  • 所有案場共用同一套產品規則。A17 的 Connector 數量、群組數量與歷史資料只能作為驗證尺度，不可寫死成跨案場規則。

1.4 v0.4 主要修訂

  • 需留意事項使用現行固定名稱；結算區顯示資料年份與帳單／請款發票入口。
  • 30 日用量 Mock 使用完整 30 個日期桶，圖表、合計、平均值與今日 KPI 由同一組假資料推導，並明列 X、Y 軸。
  • Connector 預覽卡分層顯示 CP OCPP connection、Connector runtime 與 Queue，另顯示 CP ID、功率、資料時間與 freshness。
  • 點預覽卡先開啟單支詳情 Drawer；「查看全部」開啟 Full List Drawer。兩者都不是新頁面，也不執行作業邏輯。
  • Full List 篩選名稱改為「摘要分類」，直接使用 displayBucket；首頁五項摘要維持純資訊、不可點擊。
  • 首頁 summary、Top-8、abnormalTotal 與完整清單由同一份 canonical fixture 推導；Tablet Full List Drawer 於 1239 px 以下使用全螢幕。

2. 背景、目標與成功條件

2.1 背景

Backend Admin 現有 Dashboard 為空白頁。EMS 已有 Charge Point、Connector、Transaction、MeterValue、Queue、Settlement 與 Invoice 等資料，但缺少一個讓案場管理人員快速掌握營運狀況的首頁。

2.2 目標

使用者進入 Dashboard 後，應能在不執行任何控制動作的前提下快速回答：

  1. 案場目前是否有明顯異常或資料不可靠？
  2. Charge Point 與 Connector 目前大致處於什麼狀態？
  3. 現在充電負載多少，各群組容量與可用 slots 如何？
  4. 最近 30 日的充電量與使用次數如何？
  5. 最近一個帳期的結算流程進行到哪裡？
  6. 上一個完整曆月的電費是否已完整結算、金額多少？

2.3 V1 成功條件

  • 有 dashboard function 權限的使用者可正常開啟頁面。
  • 每個 Branch 在 V1 僅有一個 enabled Building 時，可由 Backend 自動解析案場，不要求 FE 傳 buildingId。
  • 一般資料可於初次載入、每 5 分鐘及手動重新整理時更新。
  • Connector 即時狀態與案場即時負載可由同一條 Dashboard WebSocket 更新。
  • WebSocket 無法連線時，使用者看得到明確提示、最後更新時間與最後一份資料；其他 REST 區塊仍可使用。
  • 1、2、12、30 個 Connector 都能在同一 UI 結構內合理顯示，頁面不因數量改變而破版。
  • 390、768、1024、1440 px 寬度不產生整頁水平捲動。
  • 缺資料、部分資料、錯誤與真正的零值不會被混為一談。

3. 使用者、權限與案場範圍

3.1 權限

Dashboard 沿用既有 SS3A function/API mapping，功能代碼為 dashboard。

  • 預期可被授予 Dashboard 的既有角色：administrator、power_user、association、dealer。
  • adm_user、member、hq、engineer 不因角色名稱而自動取得 Dashboard 權限。
  • Backend API 仍須做授權檢查；FE 隱藏選單不是安全邊界。
  • 未授權時回傳或呈現 403，不顯示其他案場資料。

角色與 function 的關係應透過既有權限資料維護，不在 Dashboard 程式碼中以角色名稱硬編碼授權判斷。

3.2 Building 解析

V1 規則：一個 Branch 必須恰好有一個 enabled Building。

狀況 行為
恰好 1 個 enabled Building Backend 自動解析並回傳 Dashboard 資料
0 個 enabled Building 回傳案場設定錯誤，Dashboard 不載入資料
超過 1 個 enabled Building 回傳案場設定錯誤，Dashboard 不自行猜測

FE 不傳 buildingId，也不在 V1 提供 Building 下拉選單。未來若 Branch 支援多 Building，應另開需求擴充契約。

4. 範圍

4.1 In Scope

  • 案場頁首、資料更新狀態與手動重新整理。
  • 需留意事項。
  • 六個營運 KPI。
  • 案場即時負載與三個時間範圍圖表。
  • 群組容量與 slots。
  • Connector 即時狀態摘要、重點卡片與完整清單 drawer。
  • 最近 30 日充電用量。
  • 最近一個既有結算帳期的四步驟帳務流程。
  • REST API、Dashboard WebSocket、授權、資料品質、錯誤狀態與基本驗收。

4.2 Out of Scope

  • 從 Dashboard 控制充電、重啟設備、改變 Connector 狀態或手動重送 OCPP command。
  • 從 Dashboard 修改 Queue、priority、slot、排程或離峰設定。
  • 從 Dashboard 執行補帳、重算、付款、開立發票或修正帳務。
  • 新增 Operational Event SLA、處理時限、逾時升級或 on-call 規則。
  • 為 Dashboard 新增專用 snapshot table、cache、排程器、監控平台、告警與 fallback polling。
  • 自 Dashboard 推導「離線充電」、「待對帳」或其他會改變既有業務狀態的結論。
  • 以 A17 的數量、時間或設備特性作為所有案場固定設定。

5. 頁面資訊架構

頁面由上到下固定為：

  1. 案場名稱、即時連線狀態、一般資料更新時間與手動重新整理。
  2. 需留意事項。
  3. 六個 KPI。
  4. 案場即時負載。
  5. 群組容量與 slots。
  6. Connector 即時狀態。
  7. 30 日充電用量。
  8. 帳務結算流程。

區塊可以因 Empty、Partial、Error 或權限狀態改變內容，但不可任意改變順序。Dashboard 是資訊總覽；只有明確定義的卡片或文字連結可導向既有頁面，不在首頁加入操作按鈕。

6. 資料取得架構

6.1 簡化原則

Dashboard 只使用兩條資料通道：一支 Overview REST API 與一條 Dashboard WebSocket。

區塊 初始資料 後續更新 WebSocket 斷線時
需留意事項 Overview REST 每 5 分鐘或手動 refresh 不受影響
六個 KPI Overview REST 每 5 分鐘或手動 refresh 不受影響
案場即時負載 REST 提供三段完整歷史序列；WebSocket 提供目前值與 bucket 增量 WebSocket 顯示斷線提示，保留最後資料，不做 fallback
群組容量與 slots Overview REST 每 5 分鐘或手動 refresh 不受影響
Connector 即時狀態 Overview REST 初始摘要與重點資料；WebSocket 更新 WebSocket 顯示斷線提示，保留最後資料，不做 fallback
30 日充電用量 Overview REST 每 5 分鐘或手動 refresh 不受影響
帳務結算流程 Overview REST 每 5 分鐘或手動 refresh 不受影響

6.2 REST 生命週期

  • 初次進頁呼叫一次 GET /api/dashboard/overview。
  • 頁面存活期間每 5 分鐘呼叫一次。
  • 使用者按下重新整理按鈕時立即呼叫一次。
  • 同一時間只允許一個 Overview request；重複點擊不得製造平行請求。
  • 手動重新整理只重新取得 REST 資料，不另建第二條 WebSocket。
  • REST 某一來源失敗時，Backend 優先以該 section 的 dataStatus 隔離，不應讓整份 response 全部失效；授權或 Building 設定錯誤除外。

6.3 WebSocket 生命週期

  • 頁面載入時建立一條 Dashboard WebSocket。
  • 僅處理三種 message：
    • DASHBOARD_LIVE_SNAPSHOT
    • CONNECTOR_LIVE_BLOCK_UPDATED
    • LIVE_LOAD_UPDATED
  • WebSocket 連線失敗或中斷時：
    • Connector 與即時負載區塊顯示「即時連線已中斷」類提示。
    • 保留最後一次成功資料與其時間，不清成 0。
    • 不改用 REST 輪詢、不做自訂 exponential backoff、不做 sequence gap recovery。
    • 不在背景自動重連；使用者重新載入整頁時才重新嘗試連線。
  • WebSocket 斷線不影響其他 REST 區塊的顯示與五分鐘更新。

7. 共用資料契約

7.1 Overview REST

建議 endpoint：GET /api/dashboard/overview

回應至少包含：

site                 案場識別、名稱、時區
generatedAt          Backend 產生 response 的時間
attention            需留意事項
kpis                  六個 KPI
liveLoad              三段完整圖表資料與目前值
chargeGroups          群組容量與 slots
connectorLive         Connector 五狀態摘要與固定 Top 8
usage30Days           30 日用量與摘要
billingPipeline       最近既有帳期的四步驟狀態

每一個主要 section 應具有：

dataStatus            COMPLETE | PARTIAL | ERROR
updatedAt             此來源最後成功更新時間
message               Partial 或 Error 的可顯示原因；Complete 可為 null

0 表示已確認數值為零；null 表示無法確認、無資料或不可計算。FE 不得把 null 格式化成 0。

7.2 時間與時區

  • 所有「今日」、「上月」、「最近 30 日」、「最近 7 日」以該 Building 的時區為準。
  • API 時間點使用含 offset 的 ISO 8601。
  • Backend 回傳 Building 時區；FE 負責依該時區顯示，不以瀏覽器所在時區重新歸日。
  • 日期區間採明確的半開區間 [start, end)，避免月末與午夜重複計算。

7.3 資料新鮮度

  • Backend 依資料來源套用全系統預設 freshness cutoff。
  • V1 不提供每案場、每 Building 的 cutoff override，也不新增 Dashboard 設定畫面。
  • 每個 section 回傳自己的 updatedAt 與 dataStatus；FE 不自行用一個全頁時間推定所有來源都新鮮。

8. 詳細功能需求

8.1 頁首與更新狀態

  • 顯示案場名稱，不把 A17 寫死在產品文案。
  • 顯示一般資料最後更新時間與「每 5 分鐘更新」。
  • 顯示 WebSocket 連線狀態：正常或中斷。
  • 手動重新整理按鈕要有 loading、disabled 與可讀的 accessible name。
  • refresh 成功時更新成功區塊；部分失敗時保留仍有效資料並顯示 section 訊息。

8.2 需留意事項

區塊名稱固定為「需留意事項」，不用 Needs Attention 作為使用者可見標題。

只允許以下五類，順序固定：

順序 code 中文名稱 affectedCount 意義 導向
1 CHARGE_POINT_OFFLINE Charge Point 離線 符合離線條件的 Charge Point 數 /cp/list
2 CONNECTOR_FAULTED Connector 故障 符合故障條件的 Connector 數 /connector/list
3 LIVE_LOAD_DATA_UNRELIABLE 即時負載資料不可靠 目前受影響的資料來源或設備數；依 Backend 契約定義 #load
4 QUEUE_BLOCKED 排隊受阻 目前 BLOCKED 的 distinct Connector 數 #connectors
5 SETTLEMENT_INCOMPLETE_OR_ERROR 帳務結算未完成或異常 目前帳期未完成或錯誤的結算單元數 #billing

顯示規則：

  • 只顯示 affectedCount > 0 的類別，全部顯示，不做 Top N、drawer 或獨立頁。
  • categoryCount 是非零類別數，不是受影響設備總數。
  • 不跨類別做 root-cause 去重；同一設備可同時影響不同類別。
  • COMPLETE 且 categoryCount=0 顯示中性的「目前沒有需留意事項」。
  • PARTIAL 顯示已確認卡片，並提示內容可能不完整。
  • ERROR 時 categoryCount=null，顯示暫時無法取得，不顯示 0。
  • 這些卡片只提供導向，不提供修復、acknowledge 或變更狀態的功能。

8.3 六個 KPI

固定順序如下：

順序 KPI 定義 顯示 導向
1 Charge Point 連線 persisted OCPP connection state；分母為 enabled Charge Point online / enabled total，並分列 offline、unknown、disabled /cp/list
2 Connector 可服務 enabled CP 之 Connector，且 parent CP 為 ONLINE、runtime status 在可服務 allowlist serviceable / enabled connector total /connector/list
3 充電進行中 canonical ACTIVE transaction；每個 Connector 最多計 1 個 {N} Sessions，輔助文案「依未結束的充電 Session 計算」 /connector/list
4 等待供電 Queue 狀態為 ELIGIBLE 的 distinct Connector {N} Connectors；NOT_PLUGGED 分開顯示且互斥，BLOCKED 歸需留意事項 /connector/list
5 今日已完成充電量 與 30 日用量的今日 bucket 使用完全相同規則 kWh #usage
6 上月電費 Building 時區上一個完整曆月的 settlement cost_predict 總和 完整時顯示金額；不完整顯示 — 與完成數 #billing

補充規則：

  • 充電進行中 是「未結束 Session 數」，不是實際有功功率；即使 CP offline 或 disabled，只要 canonical transaction 仍為 ACTIVE 仍計入。
  • KPI 不推論 offline charging、不新增 reconciliation flag，也不重複顯示 currentPowerKw。
  • 上月電費包含該月已付款與待付款的 settlement，但只有所有應計單元都完整時才顯示總額。
  • 六張卡皆為 REST 資料，不使用 WebSocket 更新。
  • 六張卡皆為原生可聚焦連結；整張卡的可點擊範圍與 focus ring 必須清楚。
  • 版面：寬度大於等於 1240 px 為 6×1；768–1239 px 為 3×2；320–767 px 為 2×3。不隱藏、不輪播。

8.4 案場即時負載

此區塊只顯示案場「充電功率」，不顯示或推導案場契約容量、案場使用率、剩餘容量。群組契約容量只在群組區塊顯示。

固定提供三個 tab：

tab X 軸 bucket Y 軸
即時 最近 60 分鐘，由舊到新 1 分鐘 該分鐘的時間加權平均充電功率，單位 kW
今日 Building 當地日 00:00 至現在 15 分鐘 該 15 分鐘的時間加權平均充電功率，單位 kW
7 日 含今日在內的 7 個 Building 曆日 1 小時 該小時的時間加權平均充電功率，單位 kW

圖表規則：

  • X 軸名稱為「時間」，Y 軸名稱為「充電功率（kW）」。
  • REST 一次回傳三個 tab 的完整 series；切換 tab 只讀取頁面 cache，不重打 API，也不改變 WebSocket 訂閱。
  • tab 選擇在五分鐘 refresh 後保留，整頁重載後回到「即時」。
  • WebSocket 更新 currentPowerKw、OPEN bucket 與跨界後的 FINALIZED bucket。
  • bucketState 為 OPEN | FINALIZED，和 dataStatus 分開。
  • 新鮮且已確認沒有充電時可回 0。
  • 若有充電但必要功率資料超過 freshness cutoff，該 bucket 回 null 且 section 為 PARTIAL。
  • 不做內插、不顯示猜測值、不以 coverage threshold 補值，也不提供「部分總功率」。
  • 只有「目前」資料品質問題進入需留意事項；歷史缺口留在圖表中以 gap 呈現。

8.5 群組容量與 Slots

每個 Charge Group 顯示：

  • 群組名稱。
  • 群組目前充電功率 kW。
  • 群組自己的 contractCapacity kW。
  • 群組可使用與已使用 slots。
  • 必要時顯示該群組資料的 Partial/Error 狀態。

不同群組的 contractCapacity 不可直接加總成案場契約容量。Dashboard 不新增群組設定或調整 slots 的操作。

8.6 Connector 即時狀態

8.6.1 五個互斥狀態桶

所有 Connector 必須恰好歸入一個狀態桶，順序固定：

code 中文名稱 核心規則
NEEDS_ATTENTION 需留意 isAbnormal=true、faulted、unknown 或 Backend 無法安全歸類的狀態
CHARGING 充電進行中 依既有 runtime 狀態與交易事實判定
WAITING 準備／排隊 已插槍準備或 Queue waiting 類狀態
AVAILABLE 可用 parent CP 與 Connector 均符合可服務條件
OTHER 其他狀態 已知但不屬前四類；NOT_PLUGGED 歸此類

五個 count 加總必須等於 total，NEEDS_ATTENTION count 必須等於 abnormalTotal。當 total > 0 時五個摘要都顯示，包括 count 0；當 total = 0 時改顯示空狀態。

五個狀態摘要是純資訊，不可點擊、不可聚焦、不可當篩選器。使用者可點 Connector 卡片開啟單支詳情 Drawer，或按「查看全部」開啟 Full List Drawer。首頁摘要不會開啟 Drawer，也不會預先帶入篩選。

8.6.2 不同 Connector 數量的彈性設計

Backend 固定回傳最多 8 筆 priority items，加上 total 與 abnormalTotal。FE 依 viewport 顯示同一份 payload 的前幾筆：

viewport 首頁最多顯示
Desktop 8
Tablet 6
Mobile 4
  • 案場只有 1 或 2 個 Connector：只顯示實際卡片，不補空白 placeholder、不把卡片無限制拉寬。
  • 案場有 30 個以上 Connector：首頁仍只顯示上述重點數量，標題與按鈕顯示總數，完整清單在 drawer 內分頁。
  • 重點項目由 Backend 固定 priority sort；先看 isAbnormal／severity，再以穩定欄位做 deterministic tie-breaker。V1 不提供使用者排序。
  • 每個 item 回傳 displayBucket、isAbnormal、severity、priorityReason；FE 不自行重算分類、異常或優先順序。
  • 卡片至少分層顯示所屬 Charge Point 的 OCPP connection、Connector runtime 與 Queue status／reason，另顯示 Connector ID、Charge Point ID、位置／群組、nullable currentPowerKw、updatedAt 與 freshness。未知功率顯示「—」，不是 0。

8.6.3 完整清單 Drawer

Drawer 是覆蓋在目前 Dashboard 上、由右側滑出的暫時面板，不是另一個頁面。桌面保留部分 Dashboard 作為背景脈絡；平板／手機可使用全螢幕 Sheet。關閉後回到原入口與原 Dashboard 位置。

入口 開啟內容 資料方式
點 Connector 預覽卡 單支 Connector 詳情 Drawer 按需取得既有單支 detail；開啟才使用既有單支 socket，關閉釋放
點「查看全部」 Full List Drawer REST search、篩選、固定 priority sorting 與 server pagination
  • 固定 server-side pagination，每頁 20 筆。
  • 只有上一頁、下一頁；總數小於等於 20 時隱藏 pager。
  • 搜尋或篩選條件改變時回到第 1 頁。
  • drawer 的搜尋、篩選與當前頁只保留在本次 Dashboard page session；關閉再開保留，整頁重載或離開頁面即清除。
  • 不寫入 URL、local storage 或 Backend preference。
  • 不提供 user-controlled sorting；現有 /connector/list 頁的排序不受影響。

Full List 的篩選固定為「摘要分類」與 Charge Group。「摘要分類」直接使用首頁同一套 displayBucket，不是 Connector runtime status 或 Queue status 的混合 selector：

UI 選項 Request displayBucket
全部 不傳或 null
需留意 NEEDS_ATTENTION
充電進行中 CHARGING
準備／排隊 WAITING
可用 AVAILABLE
其他狀態 OTHER

Full List search request 最少包含：

欄位 規則
page 沿用既有 API page convention；UI 頁次從 1 開始
size 固定 20
keyword 搜尋 Connector ID、Charge Point ID、車位；未填不過濾
displayBucket 可省略；值限上述五個 code
chargeGroupId 可省略；只限制目前案場可見群組
sortMode 固定 DASHBOARD_PRIORITY，不是使用者控制欄位
buildingId FE 不傳；Backend 使用與 Overview 相同的目前案場 resolver

每筆 response item 至少包含 connectorId、chargePointId、location、floor、parkingSpaceNo、chargeGroupId、chargeGroupName、displayBucket、isAbnormal、severity、priorityReason、ocppConnectionStatus、runtimeStatus、nullable queueStatus／queueReason、nullable currentPowerKw、updatedAt 與 freshness。Page 外層沿用既有 Spring Page metadata。

8.7 30 日充電用量

  • 範圍固定為含今日在內的 30 個 Building 曆日，不提供日期選擇器。
  • 只計算 completed transaction。
  • energy_consumed 單位由 Wh 轉為 kWh；null 或負值排除並將 section 標為 PARTIAL。
  • Sessions 只計 completed 且 energy_consumed > 0 的 transaction。
  • 整筆 transaction 依 start_timestamp 所屬 Building 日期歸日，不做跨日拆分。
  • 平均每次充電量 = 有效 kWh / 有效 Sessions；Sessions 為 0 時回 null。
  • API 固定回 30 個 buckets。已確認無資料的日期為 0；未知或無法計算為 null。
  • X 軸為 30 個 Building 日期，由最舊到今天；Y 軸依切換顯示「有效充電量（kWh）」或「有效充電 Sessions（次）」。畫面必須直接標示軸意義與單位，不可只靠 tooltip 推測。
  • 30 日皆為已確認 0 時，回 COMPLETE 並顯示 empty 說明，不判為錯誤。
  • 首次載入錯誤且無 cache 時顯示 Error；refresh 失敗但已有成功資料時保留 cache、標示 stale 與失敗時間。
  • 已移除「時間使用率」，以「平均每次充電量」取代。
  • 本區與「今日已完成充電量」只能使用 transaction 的 status、energy_consumed、start_timestamp。不讀 raw MeterValue、不呼叫帳務計費服務、不依 Tariff boundary 拆分。

8.8 帳務結算流程

此區塊保留 Mock 既有的四步驟流程，不新增「本月帳務摘要」或「本月預估電費」。

顯示 Backend 可取得的最新一個既有 settlement period；即使該帳期仍 pending 或 error，也顯示該帳期。完全沒有 settlement period 時顯示 empty。

固定四列：

  1. Connector 結算。
  2. 門牌結算。
  3. 帳務覆核。
  4. 發票結算。

四列都是純資訊，不可點擊。區塊底部提供兩個既有頁面連結：

  • 帳單：/bill/list
  • 發票：/invoice/list

帳務流程是 REST-only、read-only。上一個完整曆月的電費金額只出現在第六個 KPI，並依該 KPI 的完整性規則顯示。

9. FE 開發需求

9.1 頁面與元件

FE 至少需完成：

  • Dashboard route 與 navigation entry，套用既有 dashboard function 可見性。
  • Overview REST query、五分鐘 timer、manual refresh 與 request 去重。
  • 單一 Dashboard WebSocket connection 與三種 message reducer。
  • Header、Attention、KPI grid、Live Load chart、Group cards、Connector summary/cards/drawer、Usage chart、Billing pipeline。
  • Loading、Empty、Partial、Error、Stale、403 與 Building config error 畫面。
  • 所有既定 deep links、native links、hash focus 與 drawer keyboard interaction。

9.2 FE 不得自行推導的內容

以下必須由 Backend 回傳，FE 只負責呈現：

  • Charge Point online/offline/unknown 統計。
  • Connector 的五桶歸類、isAbnormal、severity、priorityReason 與固定 priority sort。
  • ACTIVE Session、Queue ELIGIBLE/NOT_PLUGGED/BLOCKED 計數。
  • 需留意事項類別與 affectedCount。
  • Usage bucket、平均每次充電量、上月電費完整性。
  • Live Load 的時間加權 bucket、bucket state 與 data quality。

9.3 FE 狀態管理

  • REST cache 與 WebSocket live state 分開管理。
  • WebSocket message 只能更新 Connector live 與 Live Load，不得改寫 REST-only KPI。
  • WebSocket 斷線保留最後資料；畫面明確標示資料時間與斷線，不把舊資料偽裝成即時。
  • section refresh error 不應清除其他 section。
  • tab、drawer 與 pagination 的 page-session 行為依第 8 節執行。

9.4 圖表與格式

  • 圖表必須顯示 X、Y 軸名稱、單位、tooltip 時間與數值。
  • null bucket 以 gap 表示；不得連線或補 0。
  • 金額、kW、kWh、小數位與千分位由共用 formatter 統一。
  • 顏色不能是唯一狀態線索；同時提供文字、icon 或 pattern。

10. Backend 開發需求

10.1 API 與授權

Backend 至少需完成：

  • GET /api/dashboard/overview controller、application service 與 response DTO。
  • Dashboard WebSocket endpoint 或既有 endpoint 內的 Dashboard subscription contract。
  • dashboard function/API mapping 與授權測試。
  • 單一 enabled Building 解析及 0/多筆的明確 domain error。
  • OpenAPI schema 與每個 DTO 欄位的中文說明。

10.2 Query 與聚合

Backend 負責：

  • 依既有 Charge Point connection state 統計 online/offline/unknown/disabled。
  • 依 parent CP 與 Connector runtime allowlist 統計可服務數。
  • 以 canonical transaction 計算 ACTIVE Sessions。
  • 以現有 Queue 資料計算 ELIGIBLE、NOT_PLUGGED、BLOCKED distinct Connectors。
  • 產生 Attention allowlist、count 與 deep-link code。
  • 產生三段 Live Load time-weighted series 與資料品質。
  • 查詢 Charge Group 自身 capacity、current power 與 slots。
  • 依 transaction 建立 30 日 Usage buckets。
  • 查詢最近既有 settlement period 的四步驟摘要。
  • 計算上一完整曆月 settlement 完整度與 cost_predict 總額。
  • 回傳 Connector 五桶摘要、Top 8 與 drawer 分頁查詢。
  • 擴充既有 Connector search：keyword 涵蓋 Connector ID、Charge Point ID、車位；新增可選 displayBucket、chargeGroupId 與固定 DASHBOARD_PRIORITY mode。先對完整案場集合 filter／sort，再固定每頁 20 筆 paginate。
  • Dashboard Full List 不重用既有原始 status 建立 runtime／Queue 混合選項；既有管理頁的原始 status 與 sorting 維持相容。
  • Connector search response 補足第 8.6.3 節的識別、群組、displayBucket、priority、原始狀態、功率與資料時間欄位，並完成 OpenAPI／contract tests。

10.3 WebSocket Publisher

只需發布：

  • 初次訂閱的 DASHBOARD_LIVE_SNAPSHOT。
  • Connector 相關事實變動後的 CONNECTOR_LIVE_BLOCK_UPDATED。
  • current power 或 bucket 變動後的 LIVE_LOAD_UPDATED。

不為 Dashboard 建立 NETWORK_HEALTH_UPDATED、CONNECTOR_OVERVIEW_UPDATED 或 KPI 專用訊息。Publisher 不負責自動修復設備狀態。

10.4 資料庫原則

  • V1 先使用既有 operational tables 與既有索引可支援的 read query。
  • 不預先建立 Dashboard snapshot table、materialized cache 或專用 scheduler。
  • 不為 A17 寫死 Building ID、Connector 數量、Group 數量或時間門檻。
  • 查詢必須限制 Building 與日期範圍，避免跨案場讀取與 unbounded scan。
  • 若實測顯示瓶頸，再以 EXPLAIN 與 endpoint baseline 決定是否補索引或調整 query。

11. UI 狀態與錯誤處理

狀態 定義 畫面行為
Loading 尚無首次資料，request 進行中 skeleton 或 loading，不顯示假數字
Empty request 成功且已確認沒有資料 中性說明；必要計數顯示 0
Partial 只有部分來源可確認 顯示可確認資料與「可能不完整」訊息
Error 該 section 無可用資料 顯示無法取得與 retry/refresh 提示，不顯示 0
Stale 曾成功，但後續 refresh 或 WebSocket 失敗 保留最後資料、標示最後成功時間與 stale
403 使用者無 dashboard 權限 不載入營運資料，顯示無權限
Building config error enabled Building 為 0 或多筆 不猜測、不載入，提示管理員修正設定

任一 section 的資料錯誤，不應自動讓其他來源正確的 section 變成 Error。只有 auth、Branch/Building scope 無法解析等全頁前置條件才阻止整頁載入。

12. Responsive 與 Accessibility

  • 測試寬度至少包含 390、768、1024、1440 px。
  • 不得產生整頁水平捲動；表格或 drawer 若需要可在元件內處理。
  • Full List Drawer 在 1240 px 以上由右側滑出並保留部分 Dashboard；1239 px 以下使用全螢幕 Sheet。RWD 只改版面，不改搜尋、摘要分類、群組、欄位或分頁語意。
  • 鍵盤可到達所有實際可互動元素，focus ring 清楚。
  • 五個 Connector 狀態摘要與帳務四列不可被放入 tab order。
  • Dialog/drawer 需有正確 role、可讀標題、focus trap、Esc 關閉與關閉後 focus restoration。
  • loading、斷線、error、partial 更新需有適當 live region，避免只靠視覺變色。
  • 文字與背景對比、非文字元件與 focus indicator 以 WCAG 2.2 AA 基本要求為準。
  • 動畫尊重 prefers-reduced-motion。

13. Performance、可靠性與安全性

13.1 Performance

本功能不設定硬性的 P95 < 1.5 秒產品 SLA。開發完成後必須做可重現 baseline：

  • 對 A17 與一個代表較大量資料的尺度執行 query EXPLAIN。
  • 測量 Overview endpoint 的 P50、P95。
  • 記錄環境、資料列數與分布、warm-up、concurrency、sample size、計時範圍。
  • 檢查 N+1、unbounded query、重複聚合與不必要 payload。
  • 只有量測證明一般使用受影響時才做額外 cache、索引或聚合設計。

13.2 Reliability

  • REST 五分鐘更新失敗時，保留已成功資料並標示 stale。
  • WebSocket 失敗只影響兩個 live 區塊；沒有 REST fallback、自訂重連或複雜 backoff。
  • 不以 Mock fixture 作為 production fallback。
  • response 與 message 必須能辨識 null、0、Partial、Error 與時間。

13.3 Security與Privacy

  • API 與 WebSocket 都必須做既有 session/JWT 授權與 Branch scope 驗證。
  • 不接受 client 傳入任意 Building ID 來跨案場查詢。
  • error message 不暴露 SQL、內部 host、token 或個資。
  • Dashboard 只回營運摘要所需欄位，不擴大暴露住戶或付款個資。

14. 驗收條件

14.1 共用驗收

  • 有權限且 Building 設定正確時，初次載入可見所有八個主要區段。
  • 無權限回 403；0 或多 enabled Building 顯示設定錯誤。
  • 五分鐘 refresh 與手動 refresh 不建立重複 request 或重複 socket。
  • 一個 section Error 不清除其他成功 section。
  • 0、null、Partial、Error、Stale 的畫面與文案可分辨。
  • 所有日期依 Building 時區計算。

14.2 WebSocket 驗收

  • 一條 socket 可更新 Connector live 與 Live Load。
  • 只接受三種既定 Dashboard message。
  • socket 中斷後兩區塊顯示提示、最後更新時間與最後資料。
  • socket 中斷不啟動 REST fallback、不自動重連、不影響 REST-only 區塊。
  • 重新載入整頁會重新嘗試建立 socket。

14.3 Connector 驗收

  • 五個 count 相加等於 total，需留意 count 等於 abnormalTotal。
  • total 大於 0 時五個摘要都在，且純資訊、不可點擊。
  • 1、2 個 Connector 不補假卡片；30 個 Connector 不一次塞滿首頁。
  • Desktop/Tablet/Mobile 最多顯示 8/6/4 筆。
  • 預覽卡分層顯示 CP OCPP connection、Connector runtime、Queue、CP ID、nullable 功率與資料時間；點卡片開啟可由 Esc 關閉且回復焦點的單支詳情 Drawer。
  • Full List Drawer 在 Desktop 為右側面板、Tablet/Mobile 為全螢幕；每頁 20，filter/search 回第 1 頁，page-session state 規則正確。
  • 「摘要分類」固定六個 UI 選項並直接對應 displayBucket；首頁五摘要不可點、不帶入條件，既有管理頁 status 無回歸。
  • 首頁 summary、abnormalTotal、Top-8 與 Full List 由同一完整集合推導；30／100 筆 fixture 不互相矛盾。
  • Backend priority sort 穩定，同一資料重查順序一致。

14.4 圖表與數值驗收

  • Live Load 三個 tab 的範圍、bucket、X/Y 軸與單位符合規格。
  • null bucket 顯示 gap，不補 0 或內插。
  • Usage 固定 30 buckets，依 start date 歸日，跨日不拆分。
  • 今日已完成充電量與 Usage 今日 bucket 完全一致。
  • 上月電費只有 settlement 全部完整才顯示總額；不完整時為 —。
  • 帳務區只有既有四步驟，沒有本月預估電費或虛構摘要。

14.5 Responsive與A11y驗收

  • 390、768、1024、1440 px 無整頁水平捲動。
  • Keyboard-only 可操作 refresh、KPI links、Connector cards、drawer 與 footer links。
  • 純資訊元素不誤設為 button/link，不進 tab order。
  • 狀態不只依顏色傳達，screen reader 可得知 loading/error/disconnected 更新。

15. 測試與發布要求

15.1 測試範圍

進入實作後，Backend 至少涵蓋：授權、Building 解析、各 KPI/section 聚合、時區邊界、0/null/Partial/Error、Connector 分桶守恆、Usage 歸日、上月電費完整性、WebSocket message contract。

FE 至少涵蓋：初載、refresh、socket update/disconnect、responsive 數量、drawer state、deep link、chart gap、keyboard 與錯誤狀態。

E2E Catalog 分類為 Add，但目前仍在需求階段，尚不建立測試結果或宣告 Pass。正式實作時需新增 P0–P3 優先級與 execution trigger，並依專案 catalog SOP 驗證。

15.2 First Rollout

  • A17 作為第一個 rollout 與資料合理性驗證案場，不代表程式限定 A17。
  • 上線後執行基本 smoke test：頁面權限、REST 初載、socket 更新、主要 deep links 與錯誤狀態。
  • 下一個工作日使用既有 logs、工具與 DB load 做一次檢查。
  • 不要求連續 24 小時監看，也不為本功能新增專用 dashboard metrics、alerts 或 on-call 流程。

16. A17 驗證基準

以下是規格整理時的 A17 觀察基準，只用於檢查 query 與 UI 是否能處理真實尺度；不得作為固定 fixture 或跨案場 acceptance value。

項目 A17 基準
Building BLD000000014
Charge Points 4
Connectors 12
Charge Groups B1、B2、B3，共 3 組
各 Group contract capacity 各 99 kW；不得加總推導成案場容量
觀察區間 2026-08-05 至 2026-09-03
Transactions completed 78、active 1
completed 正用電 77 筆；另 1 筆為 0 Wh，無 null/negative
有效總電量 2,171.915 kWh
有效 Sessions 77
平均每次充電量 28.21 kWh/session
跨日 Transactions 10 筆，Dashboard Usage 全部依開始日歸屬

17. 工作拆分與 Redmine 追蹤

Issue 範圍
#1422 Parent：全案場 Dashboard 需求、文件版本、整體驗收與發佈
#1423 Connector UI/UX、不同數量、狀態摘要、卡片與 drawer
#1424 Overview REST、Dashboard WebSocket、資料生命週期與效能原則
#1460 帳務結算流程與上月電費資料
#1461 30 日 Usage、今日用量與平均每次充電量
#1462 Live Load、圖表 buckets、群組 capacity/slots
#1463 需留意事項 allowlist、狀態與 deep links
#1486 六個 KPI 的計算、顯示與導向

所有 issue 在需求確認期間維持 New / 0%。只有需求 review 完成並由 Ken 明確同意進入開發後，才建立 v1.0、進入 planning gate 與實作。

18. Definition of Ready（進入開發前）

  • Product 確認 v0.4 內容或後續 v0.x 修訂。
  • FE 確認 layout、responsive、interaction、states 與 accessibility 可實作。
  • Backend 確認現有資料可支援定義，OpenAPI/WS contract 無重大未解問題。
  • QA 確認 acceptance criteria 可測。
  • 所有未決項目已在 #1422 或 subtask 明確定案。
  • 產出並附加同版 PDF、Markdown、HTML Mock。
  • Ken 明確同意需求鎖定後，才建立 v1.0。

本文件到 v0.4 為止仍是 review Draft。任何在本文件中沒有明確定義的業務狀態、控制流程、告警 SLA、fallback 或自動修復行為，都不屬於本 Dashboard V1，不能由實作者自行補想。

(8-8/9)