Feature #1422
是由 陳國瑋 於 28 天 前更新
## 背景
Branch Admin 的 `/dashboard` 目前是空白頁。既有 `DashboardStatsCard` 只有硬編碼假資料且未掛載；現有 `GET /api/connector/dashboard` 只能提供 Connector 總數、Available、Charging、Faulted、公用與私人數量，尚不足以支援案場營運判斷。
本需求建立所有案場共用的 Backend Admin 營運 Dashboard；A17 僅為第一個驗證與導入案場。API、WebSocket、UI、freshness policy 與資料模型不得硬編碼 A17，並須以 `buildingId` 明確隔離案場資料。
> Mockup 內所有數字均為假資料。A17 production baseline 必須在實作前以 read-only query 驗證，不得將 mock 數字作為驗收基準。
## 多案場適用原則
- Dashboard 功能適用所有案場，A17 僅作為首個 rollout／baseline 驗證站點。
- REST、WebSocket ticket、URL 與 event envelope 明確使用 `buildingId`。
- Backend 必須驗證使用者對 building 的存取權；切換 building 不得混用舊案場 snapshot。
- Freshness／stale cutoff 由 Backend 依資料來源統一管理，不由 FE 或 A17-specific code 決定。
- A17 Phase 0 的數據只用於驗證通用方案的公式、效能及預設值，不能成為其他案場的固定規則。
## 產品目標
讓 Site Admin、Operations、Finance 與 Engineer 在 10 秒內回答：
- 案場現在是否正常？
- 哪些 Charge Point 離線、哪些 Connector 故障？
- 目前有多少充電工作階段、全案場即時充電功率是多少？
- 輪充／離峰隊列是否阻塞或等待過久？
- 今日使用量與最近一期結算流程是否有待處理項目？
- Dashboard 資料是否仍然新鮮、可被信任？
Dashboard V1 以唯讀總覽與 deep link 為主，不在首頁直接執行 Remote Start／Stop、Reset、Modbus 或 Engineer command。
## 完整需求文件
建立 Issue 後將附上：
- `a17-ems-dashboard-requirements.pdf`：17 頁完整需求說明書
- Repository source：`documents/dashboard-mockup/a17-dashboard-requirements.md`
- UI mockup：`documents/dashboard-mockup/a17-operations-dashboard.html`
## V1 Scope
- Needs Attention severity-first 告警列與 deep link
- Charge Point OCPP connection 與 runtime 摘要
- Connector 完整狀態統計與即時狀態 grid
- Active sessions、案場即時總功率與負載趨勢（保留「即時／今日／7 日」三種檢視；軸線定義詳見 #1462）
- 各 Charge Group 的目前功率、群組自身 contract capacity、occupied／reserved／available slots
- Queue waiting／blocked／最久等待時間摘要（唯讀資訊）
- 今日用電與近 30 日 kWh／sessions 趨勢
- 結算流程區塊沿用 attachment #1110 四步驟面板；假數字改接正式 API，資料期間由 Backend 依最近結算資料回傳（BIL-DEC-001／002，詳見 #1460）
- Loading、Empty、Error、Stale、Partial、403 等 UI states
- Desktop／Tablet／Mobile responsive
- SS3A Dashboard function/API 權限
## V1 Scope Boundary
- Dashboard 是唯讀營運資訊頁，只查詢、彙整及呈現既有系統狀態。
- V1 不以 SUM(group.contractCapacity) 推算案場契約容量、利用率或剩餘容量；案場即時總功率與各群組自身容量分開呈現（LOAD-DEC-001，詳見 #1462）。
- Queue 顯示既有 source、status、priority、statusReason、waitingSince／waiting duration；`BLOCKED` 沿用既有狀態呈現。
- V1 不新增 Queue SLA、等待逾時判定、門檻 override、Queue 設定頁或 Rotation scheduler-health 規則。
- Connector preview 固定 Cards，完整清單 Drawer 採單一 responsive list；不提供 Grid／Table toggle 或顯示偏好保存。
- Dashboard 開發不得改變 queue lifecycle、priority、slot allocation、rotation dispatch、OCPP command 或任何充電作業邏輯。
- 若未來確有 SLA／scheduler monitoring 需求，須另案確認；本次不先建立實作 ticket。
## 開發工作拆分
### Backend / API
- [ ] 新增 typed `GET /api/dashboard/overview`
- [ ] 建立 `DashboardController`、`DashboardService`、alerts 與各區塊 DTO
- [ ] 聚合 CP connection/runtime、Connector 狀態、active transaction
- [ ] 建立案場 currentPowerKw 的 latest power query、W/kW normalization 與 stale cutoff；不得從群組容量推算案場契約容量／利用率／餘裕
- [ ] 依 #1462 LOAD-DEC-003 建立 Live Load 歷史 read model：即時 60 分鐘／1 分鐘 bucket、今日 00:00 至現在／15 分鐘 bucket、含今天 7 個案場日曆日／1 小時 bucket；以案場 timezone 計算 time-weighted averagePowerKw，不可直接加總或平均 raw MeterValue rows
- [ ] 依 #1462 LOAD-DEC-004 由 REST 提供完整 Live Load series；LIVE_LOAD_UPDATED 只推 currentPowerKw、三種 open buckets 與跨界 finalized bucket，不重送完整歷史
- [ ] 依 #1462 LOAD-DEC-005 分離 bucketState（OPEN／FINALIZED）與 dataStatus（COMPLETE／PARTIAL／ERROR）；fresh 非充電為 0，正在充電但 Power 超過 cutoff 仍未知時整個 bucket 回 null + PARTIAL，不插值或回部分合計
- [ ] 依既有 SlotCalculator 語意逐組產生 Charge Group capacity summary；群組 contract capacity 不得加總成案場契約容量 KPI
- [ ] 統計既有 queue waiting／blocked／statusReason／waiting duration；不得新增 Queue SLA、timeout 或狀態轉換規則
- [ ] 依 #1461 USG-DEC-001～009 建立固定最近 30 個案場日曆日（含今天）的 kWh／Sessions usage trend；有效充電量只讀取符合條件的 COMPLETED energy_consumed，Sessions 只計算 COMPLETED 且正電量交易，兩者依 building timezone 的交易開始日歸屬且跨日不拆分；Backend 回傳平均每次充電量與固定 30 daily buckets，成功無使用回 0、資料未知回 null／PARTIAL，整段全零回 COMPLETE + EMPTY，子查詢失敗回 source error metadata；不提供 7／90 日、自訂範圍或時間使用率
- [ ] 依 #1460 BIL-DEC-001／002 建立四步驟結算流程的 read-only aggregation／DTO，並回傳 periodYear／periodMonth／timezone；不得執行帳務 mutation 或改變既有月結排程
- [ ] 支援 COMPLETE／PARTIAL／STALE 與 sourceStatuses
- [ ] 新增 SS3A function/API mapping
- [ ] 補 OpenAPI `@Schema`、method／DTO 欄位註解與測試
- [ ] 在 A17 資料量下完成 EXPLAIN 與 P95 驗證
### Frontend
- [ ] 重新實作 `react/branch/app/(dashboard)/dashboard/page.tsx`
- [ ] OpenAPI refresh 與 React Query overview hook
- [ ] Header、AttentionStrip、KPI、LiveLoad、ChargeGroup、ConnectorGrid；LiveLoad 只顯示案場即時總功率／趨勢／freshness，不顯示推算的案場契約容量、利用率或剩餘容量
- [ ] LiveLoad 明確顯示 X 軸時間、Y 軸「充電功率（kW）」、各模式 bucket 與「區間平均功率」；bucketState 的進行中語意與 dataStatus 的 COMPLETE／PARTIAL／ERROR 分開呈現，0 與 null 與「區間平均功率」；進行中 bucket、0、null／PARTIAL 不得混淆
- [ ] LiveLoad 以 buildingId + rangeCode + bucketStartAt 套用 WebSocket replacement；不自行積分／平均，sequence gap 或重連時以 REST snapshot 恢復
- [ ] Connector preview 固定 Cards；完整清單 Drawer 單一 responsive list（不實作 Grid／Table toggle）
- [ ] Connector detail drawer 與既有管理頁／Engineer Tools deep link
- [ ] 依 #1461 實作固定 30 日 UsageTrend（kWh／Sessions、平均每次充電量、0／null、Empty、Partial、Initial Error、Refresh Error with cached data、Stale，依案場 timezone且不提供 range selector），以及 attachment #1110 四步驟結算流程面板；月份只格式化 Backend 回傳期間，四列維持純資訊，footer 提供「查看帳單」與「查看請款／發票」既有 route 導覽
- [ ] Loading／Empty／Error／Stale／Partial／Unauthorized states
- [ ] Healthy／Critical／Partial／Stale／Empty／Large 六組 fixture
- [ ] 四組 responsive breakpoint 與 keyboard／accessibility 驗證
- [ ] Production API error 不得 fallback 到 fixture
### Database / Performance
- [ ] 取得 A17 table row count、狀態分布、MeterValue 24h volume 與 query plan
- [ ] 優先採 read-only aggregate，不先建立 Dashboard snapshot table
- [ ] 只有在 A17 EXPLAIN 證明必要時，才提出普通 index
- [ ] 不新增 UNIQUE／FOREIGN KEY／CHECK／cascade constraint
### QA / Release
- [ ] Backend repository／service／security／contract tests
- [ ] FE fixture、RWD、keyboard、unknown enum、null／0／large value tests
- [ ] A17 staging E2E：offline、faulted、active transaction、stale meter、blocked queue、billing、partial data、403
- [ ] 上線採 controlled release，觀察 24 小時 error rate、partial rate、query latency
## 核心狀態規則
1. `ChargePoint.ocppConnectionStatus`、Charge Point runtime、Connector runtime、rotation queue 必須分層顯示，不得合併成單一在線／離線。
2. Heartbeat／BootNotification 只能證明連線存活，不能把 FAULTED／CHARGING 覆寫為 AVAILABLE。
3. Connector runtime primary owner 是 StatusNotification。
4. `currentTransactionId` 或 ACTIVE transaction 存在時，離線告警需標記可能仍在離線充電／待 reconciliation。
5. 即時數值不存在時回 `null`，不可用 0 表示未知。
6. Status code 供 FE 邏輯使用；中文 label 僅供顯示，未知 code 不得 fallback 成 AVAILABLE。
## Acceptance Criteria
- [ ] 使用者 10 秒內可指出離線、故障、隊列阻塞或帳務異常
- [ ] 所有告警與關鍵數字都有可用 deep link
- [ ] Overview API 在 A17 資料量下 P95 < 1.5 秒
- [ ] Header 顯示 `generatedAt`；各資料源有 `updatedAt` 與 freshness
- [ ] 任一子查詢失敗時，其餘區塊仍顯示並標記 PARTIAL
- [ ] Stale 資料不可被顯示為正常，也不可納入需要即時性的總功率
- [ ] API 與 UI 不得以 Charge Group contract capacity 加總值作為案場契約容量、利用率或剩餘容量
- [ ] Live Load 三種檢視的 range／bucket 符合 LOAD-DEC-003，7 日為含今天的 7 個案場日曆日而非 rolling 168 hours
- [ ] Y 軸數值為重建案場功率時間線後的 time-weighted averagePowerKw；不得直接對不同步且頻率不同的 raw MeterValue rows 加總或算術平均
- [ ] WebSocket 一般更新不重送完整 series；bucket 跨界可正確 finalized／建立新 open bucket，重連或 gap 後由 REST authoritative snapshot 恢復
- [ ] Live Load 完整零負載為 0 + COMPLETE；任一超過 cutoff 的 unknown 充電功率為 null + PARTIAL，圖表顯示缺口且不插值／跨線
- [ ] 未授權使用者直接呼叫 API 得到 403
- [ ] 狀態不可只靠顏色；keyboard focus、status message 與文字對比符合 WCAG 2.2 AA 基本要求
- [ ] 390／768／1024／1440 px 不出現頁面級水平捲軸
- [ ] Production build 不包含 API error → fixture fallback
## A17 Phase 0 Gate
實作前必須用 read-only query 確認：
- CP ONLINE／OFFLINE／UNKNOWN 與 runtime 分布
- Connector status／area／type 分布
- Active transaction 數與最長持續時間
- 各 Charge Group contract／allocated／reserved／queue
- MeterValue 24 小時筆數、峰值與 latest lag
- 近 30 日 transaction／kWh／日分布
- 最近結算資料期間的 Billing／Invoice 狀態分布
- 各 aggregate query 的 EXPLAIN
## E2E Test Impact
**Classification：Add**
此需求新增 user-visible Dashboard、typed API、SS3A permission 與多來源營運聚合，需在實作階段新增長期 E2E Catalog cases：
- P0 / Standard、Major、A17 release：Dashboard overview 權限、PARTIAL、stale safety
- P1 / Standard、Major、A17 release：OCPP offline、Connector faulted、active transaction、queue blocked、billing block、responsive
- P2 / Major、A17 release：large data、unknown enum、performance baseline
實作 ticket 的階段 2 必須依 `maintain-ems-e2e-catalog` skill 確認正式 Case ID 與 release pack。
## Definition of Done
- [ ] Product 確認 KPI 字典、範圍與待決策事項
- [ ] A17 baseline 完成且未推翻公式／效能方案
- [ ] Backend API、OpenAPI、SS3A mapping 與測試完成
- [ ] FE 各區塊、states、RWD、accessibility、deep link 完成
- [ ] A17 staging E2E 與 P95 通過
- [ ] E2E Catalog 與 `ai/02-backend-services.md`、`ai/03-database.md`、`ai/04-frontend.md` 更新
- [ ] 發布後完成 24 小時監看
## 待決策
- Dashboard V1 是否固定單站，或 API 先支援 `buildingId`
- V1 不顯示或回傳由 Charge Group contract capacity 加總推導的案場契約容量、利用率與剩餘容量；只保留案場即時總功率及各群組自身容量（LOAD-DEC-001，已確認；詳見 #1462）
- Live Load 保留「即時／今日／7 日」三種檢視；X 軸分別為最近 60 分鐘／今日／含今天 7 個案場日曆日，bucket 為 1 分鐘／15 分鐘／1 小時，Y 軸為 time-weighted averagePowerKw（LOAD-DEC-002／003，已確認；詳見 #1462）
- Live Load 完整 series 由 REST 提供；WebSocket 只更新 currentPowerKw、三種 open buckets 與跨界 finalized bucket，FE 採 replacement（LOAD-DEC-004，已確認；詳見 #1462）
- Live Load 以 bucketState 區分 OPEN／FINALIZED、dataStatus 區分 COMPLETE／PARTIAL／ERROR；unknown 充電功率回 null + PARTIAL，不插值、部分合計或 coverage threshold（LOAD-DEC-005，已確認；詳見 #1462）
- Queue waiting 僅顯示持續時間，V1 不設定 warning／timeout 門檻（已確認）
- 30 日充電用量固定最近 30 個案場日曆日（含今天），保留 kWh／Sessions 切換，不提供 7／90 日或自訂範圍（USG-DEC-001，已確認；詳見 #1461）
- 有效充電量只加總 COMPLETED 的既有最終 energy_consumed；ACTIVE 不估算，異常 Completed 排除並標示 PARTIAL（USG-DEC-002，已確認）
- Usage 每日 kWh／Sessions 依 building timezone 的交易開始日歸屬，跨日不拆 MeterValue（USG-DEC-003，已確認）
- 充電 Sessions 只計算 COMPLETED 且 energy_consumed > 0 的交易；0 Wh 與 ACTIVE 不計入（USG-DEC-004，已確認）
- V1 移除時間使用率及其 Backend denominator／threshold（USG-DEC-005，已確認）
- 第三項摘要改為平均每次充電量，由 Backend 以 validEnergyKWh ÷ validSessionCount 計算；0 Sessions 回 null（USG-DEC-006，已確認）
- Usage 固定回傳 30 個日期 bucket；成功無使用為 0，資料未知為 null，部分未知時區塊為 PARTIAL（USG-DEC-007，已確認）
- 30 日全為零時 sourceStatus = COMPLETE、dataState = EMPTY，顯示 0／0／— 與中性無紀錄文案，不建立告警（USG-DEC-008，已確認）
- Usage 初次失敗顯示 Error；後續 refresh 失敗保留同 building 最後成功資料並顯示 lastSuccessfulAt，依 Backend freshness 轉為 STALE（USG-DEC-009，已確認）
- 首頁帳務區塊沿用 attachment #1110 四步驟「結算流程」；不改成 Billing Summary（BIL-DEC-001，已確認）
- 結算流程期間由 Backend 依最近結算資料回傳；Frontend 不依日曆月份推算（BIL-DEC-002，已確認）
- 結算四列維持純資訊；footer 分別導向既有 /bill/list 與 /invoice/list，不新增頁面或 drill-down API（BIL-DEC-003，已確認）
- Dashboard function 授權哪些既有 role
- V1 refresh 60 秒是否足夠
返回