Feature #1422
是由 陳國瑋 於 17 天 前更新
## 閱讀方式與需求定位 現行 Usage 資料來源（USG-DEC-010）
請並排開啟 [HTML Mock v0.3](https://redmine.sylksoft.com/attachments/1117)，依下方 **01 → 08** 的順序閱讀：由上到下，同一列由左到右。編號是本 Description 的對照索引，尚未加在 Mock 畫面上。 **狀態：已確認（2026-09-07，Ken）**
本功能把目前空白的 Branch Admin「Dashboard」做成**唯讀營運總覽**，讓使用者快速看懂設備、供電、充電用量與結算狀態；需要處理事情時，再前往既有管理頁。**不改變充電、輪充、Queue 或帳務作業邏輯。**
- 適用所有案場；A17 只是 Mock 展示與首站驗證案例，不能把其名稱、數量或設定寫死。 「30 日充電用量」與「今日已完成充電量」只以 completed transaction 的既有最終 `energy_consumed` 聚合，並依 building timezone 的交易開始日歸屬；跨日不拆分。
- Mock 中的數字都是假資料，僅用來對照畫面，不是正式驗收的固定數值。 Usage 不使用 raw MeterValue 重新估算、不呼叫 `MeterValueTariffCalculationService`，也不做費率時段或帳務邊界分段。
- 目前文件套件仍為 **v0.3 Draft**，尚非 v1.0 開發基準。2026-09-14 本次僅重整 Description 的敘述與排版，不發布新版本，也不變更已確認需求。
- 第 01～08 節說明畫面；第 09 節集中說明資料更新與異常狀態；第 10～12 節供開發、驗收與版本追蹤。各子票保留完整決策細節。 MeterValue 只由 #1462「案場即時負載」用於 current power 與 time-weighted series；兩個區塊的資料來源與公式分開。
## 畫面配置與對照圖 現行 KPI 更新通道（DEC-031／032 一致性清理）
下圖表示桌面版的區塊位置，不表示各區實際尺寸。左側 Sidebar 是案場識別與導覽；主內容的閱讀順序如下： **狀態：已確認（2026-09-06，Ken）**
```text - 六張 KPI 全部由共用 `GET /api/dashboard/overview` 在頁面首載、每 5 分鐘及手動刷新時更新；KPI 不訂閱 Dashboard WebSocket。
左側 Sidebar 主內容（由上往下）
┌─────────────────────────────────────────┐
│ 01 頁首：案場名稱 連線／更新／刷新 │
├─────────────────────────────────────────┤
│ 02 需留意事項 │
├─────────────────────────────────────────┤
│ 03 六張 KPI：03-1 → 03-2 → … → 03-6 │
├─────────────────────┬───────────────────┤
│ 04 案場即時負載 │ 05 群組容量 │
│ 目前功率＋趨勢 │ 與 Slots │
├─────────────────────┴───────────────────┤
│ 06 - Dashboard 不新增或訂閱 `NETWORK_HEALTH_UPDATED`、`CONNECTOR_OVERVIEW_UPDATED` 來更新 KPI。若其他既有功能使用同名事件，不在本需求刪除或改變。
- Dashboard WebSocket 的最小 message type 仍只有 `DASHBOARD_LIVE_SNAPSHOT`、`CONNECTOR_LIVE_BLOCK_UPDATED`、`LIVE_LOAD_UPDATED`；後兩者分別只負責 Connector 即時狀態 │
│ 五項摘要 → 預覽卡片 → 查看全部 │
├─────────────────────┬───────────────────┤
│ 07 30 日充電用量 │ 08 結算流程 │
└─────────────────────┴───────────────────┘ 即時狀態與案場即時負載。
``` - KPI 可以反映最近一次 Overview snapshot，最長約有 5 分鐘更新差異；Header 顯示一般資料更新時間，使用者需要時可手動刷新。
- 本清理不改變任何 KPI 公式、Connector 即時狀態、Live Load 即時更新或既有作業邏輯。
小螢幕依同一內容順序換行；各區的卡片數與欄數依下方規則調整，不以縮小文字或頁面水平捲動容納內容。
## 01｜頁首與左側案場識別 現行首站發布檢查（REL-DEC-001）
**要讓使用者知道：目前正在看哪個案場，以及資料是否仍在更新。** **狀態：已確認（2026-09-06，Ken）**
對照 Mock 頂部「案場營運總覽」與左側「目前案場」：
| 位置 | 顯示內容 | 行為與規則 | - Dashboard 適用所有案場；本規則只定義首個實際 rollout 案場的發布檢查，不形成 A17-specific 產品邏輯。
|---|---|---| - 部署完成後執行一次 smoke test：確認授權使用者可開啟 Dashboard、Overview 可回應、兩個 live blocks 可連線或在失敗時顯示既定提示，並抽查既有管理頁未受影響。
| 左側案場識別、主內容標題下方 | Backend 回傳的案場名稱；Mock 為「寶台 A17・地下停車場」 | 唯讀識別，不是案場切換選單。 | - 下一個工作日使用既有 application log、既有維運工具與資料庫負載資訊，檢查是否出現明顯 Overview／WebSocket error 或異常負載。
| 頁首右側第一行 | 即時連線正常／無法連線／連線中斷 | 只表示兩個即時區塊的 WebSocket 連線情況，不代表所有設備正常。 | - 不新增 Dashboard 專用監控平台、metrics、instrumentation、自動告警、排程或 24 小時值守；pre-release query latency 仍依 PERF-DEC-001／DEC-042 的可重現 baseline 驗證。
| 頁首右側第二行 | 一般資料最後更新時間 | 對應最近一次 Overview 資料；與即時連線狀態分開顯示。 |
| 右側刷新按鈕 | 重新整理一般資料 | 取得一次 Overview，不重建 WebSocket；整頁重新載入才重新嘗試連線。 | - 若發現明顯問題，依既有 release／rollback 流程處理；本需求不新增另一套發布 workflow。
**案場範圍：** 每個 EMS Branch 必須恰好有一個 enabled Building，由 Backend 決定本次資料範圍。若零筆或多筆，顯示「案場設定異常」並隱藏營運數字；不可任選第一筆、跨案場加總或填入 0。
Sidebar 中其他導覽是 Mock 的展示脈絡，不代表本需求要重新開發這些管理頁；正式版沿用既有選單、路由及權限。
**開發對照：** #1424 DEC-029～033。Backend 提供案場識別、時間與狀態；FE 顯示並處理設定錯誤。
## 02｜需留意事項 現行離線與 ACTIVE Session 顯示邊界（ATT-DEC-008／KPI-DEC-011）
**要讓使用者知道：哪些「已確認的狀況」值得進一步查看。** 這是摘要，不是新的告警、派工或自動修復系統。 **狀態：已確認（2026-09-06，Ken）**
Mock 目前顯示「3 類」：設備故障 1 個 Connector、Queue 阻塞 2 個項目、結算待確認 2 個步驟。**3 是類別數，不是 1＋2＋2，也不是不同設備總數。**
### 類別、數字與點擊目的地
只顯示數量大於 0 的類別，依以下固定順序排列；不依數量、時間或顏色重排。
| 順序 | 類別 | 數字代表什麼 | 點擊後 |
|---|---|---|---|
| 1 | - Charge Point 離線 | 既有 離線與 canonical ACTIVE Session 是兩個獨立的既有事實；Dashboard 不把兩者合成新的狀態、告警或原因判斷。
- 「需留意事項」可依既有 OCPP 連線狀態為 OFFLINE 的 connection state 顯示 CP 數；同一 離線，但不得增加「可能仍在離線充電」、「待 reconciliation」或同義推測性提示。
- 「充電進行中」仍依既有 canonical ACTIVE transaction 規則計數；parent CP 只計一次 | 既有 /cp/list | 暫時 OFFLINE／disabled 時，尚未結束的 Session 仍保留在數字中，但不代表 Dashboard 已確認設備當下仍在輸出電力。
| 2 | Connector 故障（Mock 文案「設備故障」） | 既有狀態為 FAULTED 的 Connector 數；同一 Connector 只計一次 | 既有 /connector/list |
| 3 | 即時負載資料不完整 | 「目前負載」為 STALE／PARTIAL／ERROR 時算 1 類、受影響數量固定 1 | 同頁 04 案場即時負載 |
| 4 | Queue 阻塞 | 既有 BLOCKED Queue 項目數；依 Queue entry ID 去重 | 同頁 06 Connector 即時狀態 |
| 5 | 結算未完成／異常（Mock 文案「結算待確認」） | - Backend 已確認未完成或異常的結算步驟數 | 同頁 08 結算流程 | 不新增 `offlineCharging`、`reconciliationRequired` 等衍生欄位或 cross-source 推論；Frontend 只呈現兩個區塊各自的資料，調查時使用既有 deep link。
## 現行 Overview 效能驗證（PERF-DEC-001／DEC-042）
**狀態：已確認（2026-09-06，Ken）**
- 同一類別內去除重複；不同類別不推論共同原因，也不跨類合併。 Dashboard 適用所有案場；A17 只是第一個 baseline 驗證站點。實作與首站驗證使用 A17 或具代表性的等量資料，不把 A17 的資料量或結果硬編碼成其他案場規則。
- 只看「目前負載」的資料品質；歷史圖表的缺口不另外增加此摘要，尚未結束但資料完整的時間區間也不是異常。 V1 不將 `P95 < 1.5 秒` 列為產品 SLA。必須對 Overview aggregate query 執行 EXPLAIN，並量測、記錄 endpoint P50／P95，作為後續比較的可重現 baseline。
- CP 離線與尚未結束的充電 Session 分別呈現，不推論「仍在離線充電」或「待 reconciliation」。 Test report 必須記錄測試環境、主要資料表 row count／資料分布、暖機方式、併發數、sample size 與量測起訖邊界；效能數字不得脫離測試條件單獨解讀。
- 所有非零類別全部顯示。桌面自動換行、平板兩欄、手機單欄；不做 Top N、展開、Drawer 或分頁。 Backend 必須避免 N+1、無界查詢及不必要的重複聚合。只有量測證明效能已影響正常使用時，才提出 query 或普通 index 優化。
- V1 不為達成固定秒數預先新增 Dashboard snapshot table、專用 cache、效能排程或其他架構。若未來要承諾跨案場 SLA，另案定義資料量級、負載模型與測試條件。
### 正常、部分失敗與全部失敗 ## 現行 Connector Full List 固定排序（UI-DEC-020／DEC-041）
| 情況 | 使用者看到什麼 | - Drawer 不提供使用者排序控制；Backend 對完整搜尋／篩選結果套用與 Top-8 相同的 priority hierarchy 及 deterministic tie-breaker，再依固定 20 筆分頁。
|---|---|
| 完整查詢成功，確定 0 類 | 保留精簡狀態列：「目前沒有需留意事項」，附「所有已檢查的狀態目前皆正常」與更新時間。 |
| 部分來源失敗 | 顯示已確認的項目，註明「部分狀態暫時無法確認，顯示數量可能不完整」；有項目時標題為「已確認 N 類項目需要留意」。 |
| 整體無法取得 | 顯示「需留意事項暫時無法取得」，數量為未知，不顯示 0 類正常。 | - 既有 `POST /api/connector/search` 以 stable `sortMode = DASHBOARD_PRIORITY` 區隔 Dashboard read mode；`/connector/list` 原有欄位排序不受影響。細節見 #1423 UI-DEC-020／#1424 DEC-041。
每張卡為單一連結，支援滑鼠、Tab 與 Enter。同頁導覽會把焦點移至目標區塊；不自動篩選列表、不新增詳情 API，也不執行任何作業。 ## 現行 Connector Full List 固定分頁（UI-DEC-019／DEC-040）
**開發對照：** #1463 ATT-DEC-001～008；更新方式為第 09 節的共用 REST。 - Drawer 使用／擴充既有 `POST /api/connector/search`，固定 `size = 20`；Footer 只提供上一頁／下一頁與頁次／總筆數，1～20 筆隱藏換頁控制。
- 搜尋／篩選改變時回第 1 頁，Server 對完整資料集套用條件後再分頁；V1 不提供 page-size selector、直接跳頁、virtualization 或完整 inventory WebSocket。狀態保存生命週期仍依 UI-DEC-018／DEC-039。細節見 #1423 UI-DEC-019／#1424 DEC-040。
## 03｜六張 KPI：由左到右 現行 Connector Full List Drawer 狀態（UI-DEC-018／DEC-039）
**要讓使用者快速掌握六項營運數字。六張全部使用一般 REST 更新，不訂閱 WebSocket。** 因此可能與下方即時區塊有約 5 分鐘更新差異，這是已接受的 - 搜尋、篩選與頁碼只保留於目前 Dashboard page memory；關閉重開 Drawer 時維持，reload 或離開後返回時重設為預設排序、空白條件與第一頁。
- V1 行為。 不寫入 URL／browser history、localStorage／sessionStorage、Backend preference API 或 WebSocket。細節見 #1423 UI-DEC-018／#1424 DEC-039。
### 03-A｜畫面、含意與操作對照 ## 現行 Connector Status Summary 互動（UI-DEC-017／DEC-038）
| 編號／Mock 名稱 | Mock 假資料 | 要回答的問題 | 整卡點擊後 | - 五個狀態摘要項目只呈現分類名稱與數量，不可點擊、不進入鍵盤 Tab 順序，也不開 Drawer、套 filter、導頁或送出 request。
|---|---|---|---|
| 03-1 Charge Point 連線 | 4 / 4 台啟用；0 台離線、0 台尚未確認 | 已啟用的 CP 中，有多少目前被系統記錄為在線？ | /cp/list |
| 03-2 - 單支 detail 仍由 Connector 可服務 | 11 / 12 個；1 個不可服務，其中 1 個故障 | 有多少 preview card 開啟；完整清單仍由「查看全部」開啟。Backend 不新增 bucket-to-filter mapping、click API、URL 欄位或 WebSocket event。細節見 #1423 UI-DEC-017／#1424 DEC-038。
## 現行 Connector 沒有已知故障、不可用或連線問題？**可服務不等於空閒。** | /connector/list |
| 03-3 充電進行中 | 3 Sessions | 系統目前有幾筆尚未結束的充電 Session？不保證每筆此刻都正在輸出電力。 | /connector/list |
| 03-4 等待供電 | 2 個；另有 1 個未插槍（不計入） | 有多少 Status Summary 零值呈現（UI-DEC-016／DEC-037）
- Backend 的 REST／WebSocket contract 固定回五個 bucket（允許 count = 0）。`total > 0` 時 Frontend 固定顯示五項，不因即時數字更新增減或重排；`total = 0` 時隱藏 summary 並顯示 Connector 的 Queue 狀態為 ELIGIBLE、正在等候供電？ | /connector/list | Empty State。
| 03-5 今日已完成充電量 | 84.6 kWh；已完成 6 次充電 | 歸屬今天、已完成且符合條件的充電，共有多少電量與次數？ | 同頁 07 用量區（#usage） |
| 03-6 上月電費 | —；8 月結算未完成，10 / 11 筆 | 上一完整日曆月的門牌帳單應收電費總額是多少？ | 同頁 08 結算區（#billing） | - 0 是有效數值，不得當成 Loading、Error、Unknown 或 null；本規則只控制唯讀呈現，不新增傳輸或作業邏輯。細節見 #1423 UI-DEC-016／#1424 DEC-037。
### 03-B｜Backend 計算與 FE 呈現規則 ## 現行 Connector Status Summary Mapping（UI-DEC-015／DEC-036）
1. **CP 連線：** 分母是本案場 enabled CP；分子使用既有 persisted OCPP ONLINE 狀態。ONLINE＋OFFLINE＋UNKNOWN＝啟用總數。disabled 另列，不算離線；Dashboard 不用 Heartbeat 時間另建連線判定。 - 固定五類與順序：`NEEDS_ATTENTION`「需留意」→ `CHARGING`「充電進行中」→ `WAITING`「準備／排隊」→ `AVAILABLE`「可用」→ `OTHER`「其他狀態」；Backend 由上而下命中第一類，Frontend 使用固定中文 label。
2. **Connector 可服務：** 分母只含 enabled CP 下的 Connector；分子還必須同時符合 parent CP ONLINE，以及既有狀態為 AVAILABLE、PREPARING、ENQUEUED、CHARGING、SUSPENDED_EV、SUSPENDED_EVSE、FINISHING 或 RESERVED。FAULTED、UNAVAILABLE、未知狀態、parent CP 非 ONLINE 都排除。不可服務＝總數－可服務；故障只作「其中」說明，不重複加總。
3. **充電進行中：** 每個 - Unknown／資料不足歸 NEEDS_ATTENTION，NOT_PLUGGED 歸 OTHER；`NEEDS_ATTENTION.count = abnormalTotal`。細部條件與唯讀邊界見 #1423 UI-DEC-015。
## 現行 Connector 沿用既有 current transaction 解析規則，最多取一筆 canonical ACTIVE transaction（系統認定的目前交易），忽略較舊的孤兒 ACTIVE。Queue 或尚未建立 StartTransaction 的操作不算。CP 暫時離線／停用時，尚未結束的 Session 仍計入，但不推論離線充電。小字固定「依未結束的充電 Session 計算」，不再顯示功率。 Status Summary 計數（UI-DEC-014／DEC-035）
- Backend 依同一份 authoritative snapshot，讓每個 Connector 恰好歸入一個唯讀 `displayBucket`；所有 bucket count 無重複、無遺漏且加總等於 `total`。Frontend 不從 Top-8 preview 重算。
4. **等待供電：** 只計 ELIGIBLE 的不同 Connector；多筆 - Card／Drawer 仍分層顯示 OCPP connection、Connector runtime 與 Queue 不重複計。NOT_PLUGGED 另列且排除已屬 ELIGIBLE 者，不加回主數字；BLOCKED 放在需留意事項，不新增等待逾時或 SLA。
5. **今日已完成充電量：** 直接重用第 07 節 Usage 的今日日期桶（rangeEndDate），不再建立另一套今日查詢；不估算進行中交易、不做昨日同時段比較。交易依**開始日**歸屬，跨日不拆分。
6. **上月電費：** Backend 依案場時區取上一完整日曆月，使用該案場 e_bill_settlement.cost_predict；paid／pending 都納入。全部計算 COMPLETE 才回金額，否則回 null，FE 顯示「—」、月份及完成筆數。**不顯示部分合計、不退回更早月份、不做本月預估。** 原始狀態；bucket codes／labels／mapping／precedence 已由 #1423 UI-DEC-015 確認。
FE 直接呈現 ## 現行 Connector Preview Payload（UI-DEC-013／DEC-034）
- Backend 的聚合結果，不從 對完整 Connector 預覽卡重算。第 03-3 的 Session 數與第 06 節的「充電進行中」分類，來源與含意不同，不要求數字相等。 集合完成排序與異常分類後，REST bootstrap 與 `CONNECTOR_LIVE_BLOCK_UPDATED` 固定回傳同一份最多 Top-8 `items`，以及 `total`、`abnormalTotal`；每筆帶 Backend authoritative `isAbnormal`、`severity`、`priorityReason`。
- Frontend 不傳 viewport、不重排或重判異常，只依 breakpoint 顯示前 8／6／4 筆，並用 Backend totals 與 visible slice 計算純顯示用隱藏總數／隱藏異常數。完整清單仍由 Drawer 呼叫 REST search API。
### 03-C｜排版與互動 ## 現行「充電進行中」KPI 顯示（KPI-DEC-010）
| 畫面寬度 | - 第三張 KPI 排列 | 只顯示 `{activeSessionCount} Sessions`，小字為「依未結束的充電 Session 計算」。
|---|---|
| ≥ 1240 px | 6 欄 × 1 列 |
| 768～1239 px | 3 欄 × 2 列 |
| 320～767 px | 2 欄 × 3 列 | - KPI 不重複顯示 `currentPowerKw`；即時功率只留在 WebSocket-owned「案場即時負載」區塊。
固定上述順序，六張完整保留，不用輪播或水平捲動。每張卡是一個原生連結、只有一個 Tab 焦點；Loading／Error 等狀態仍可導覽。長文案換行，數字更新不逐卡朗讀；狀態顯示遵循第 09 節。 ## 現行 V1 Freshness 設定（DEC-033）
**開發對照：** #1486 KPI-DEC-001～011；Usage 公式另見 #1461。 - Stale cutoff 由 Backend 依資料來源設定全系統預設值，所有案場共用；Frontend 不硬編碼秒數，A17 只作 default 驗證。
- V1 不提供 per-building override，也不新增設定資料表、管理 API／UI、設定權限或 audit trail；特殊案場需求未來另開 Feature。
## 04｜案場即時負載（中段左側） 現行 V1 REST 更新週期（DEC-032）
**要讓使用者知道：現在充電功率是多少，以及這段時間的負載如何變化。** **狀態：已確認（2026-09-04，Ken）**
由區塊上到下閱讀：
1. **右上時間切換：** 即時／今日／7 日；預設「即時」。 - 所有非即時區塊共用同一個更新週期：頁面首次載入、Dashboard 開啟期間每 5 分鐘一次，以及使用者手動刷新。
2. **大數字「目前功率」：** 全案場目前充電功率，單位 kW；Mock 為 21.84 kW。它是目前值，不是整段期間的平均。 - 每個更新週期只呼叫一次 `GET /api/dashboard/overview`，整包取得 KPI、需留意事項、群組容量／Slots、30 日用量、今日已完成充電量、結算流程、上月電費與 Live Load 歷史 series；不得為不同區塊建立 5／15／60 分鐘等多套 timer 或各自發 request。
3. **下方折線圖：** X 軸是案場當地時間；Y 軸是「區間平均總充電功率（kW）」。每個點代表下表的一段時間，不是累計用電量 kWh。
| 檢視 | X 軸涵蓋範圍 | 每個點代表的時間區間 | - Frontend 以同一份 response `generatedAt` 更新 REST-owned sections，並沿用各區塊既有的 COMPLETE／PARTIAL／ERROR、null／0、lastSuccessfulAt 與同 building cache 顯示規則。
|---|---|---| - 「Connector 即時狀態」與「案場即時負載」仍由 DEC-031 的單一 WebSocket 負責即時更新。Overview 首載可提供兩區初始畫面；WebSocket 接手後，後續 5 分鐘／手動 REST refresh 不得覆寫兩區的 live state，也不得在 socket 斷線時冒充備援更新。
| 即時 | 最近 60 分鐘 | 1 分鐘 | - Header 必須把「即時連線狀態」與「一般資料最後更新」分開呈現。手動刷新只更新一般 REST 資料，不重建 WebSocket；重新載入整頁才重新嘗試 WebSocket。
| 今日 | 案場當地今天 00:00 至現在 | - 本決策取代下方及相關子票中帳務 15 分鐘 |
| 7 日 | 含今天的最近 7 個案場日曆日 | 1 小時 | 分鐘、群組低頻刷新、區塊各自 timer 等較早描述；不改變任何資料公式、充電／Queue／帳務作業邏輯或 Dashboard 唯讀邊界。
**7 日不是往回推固定 168 小時。** 例如今天是 9/14，日曆範圍從 9/8 00:00 到現在。 ## 現行 V1 資料取得方式（DEC-031）
### 數值如何取得 > 本節取代本票下方較早關於 Dashboard 全區 WebSocket、REST polling fallback、capped exponential backoff、sequence／gap recovery、固定 5 秒 coalescing及 2 秒 propagation SLO 的傳輸描述；資料公式、權限、所有案場共用及唯讀規則不變。
- `GET /api/dashboard/overview` 負責整張 Dashboard 的首次 snapshot 與所有非即時資料。
- 另建立一條案場層級 Dashboard WebSocket，只更新「Connector 即時狀態」與「案場即時負載」。
- Connector 即時狀態採整個區塊 replacement，payload 為 Backend 使用有效、未過期的最新電表功率，先統一 W／kW 單位，再建立案場功率時間線。 排序／分類後的 Top-8 + `total`／`abnormalTotal`，FE 依 breakpoint 顯示 8／6／4；案場即時負載只更新目前功率與 open buckets，完整歷史 series 仍由 REST 取得。
- 圖表採**時間加權平均**：例如一分鐘內前 30 秒為 10 kW、後 30 秒為 20 kW，該點為 15 kW。不能直接把不同頻率、不同時間的 raw MeterValue 列相加或算術平均。 六張 KPI、需留意事項、群組容量／Slots、30 日用量、今日已完成充電量、結算流程與上月電費不訂閱 Dashboard WebSocket。
- 已確認且資料新鮮的非充電狀態可為 0；充電中的功率超過 cutoff 仍未知時，對應區間為 null＋PARTIAL。圖表留缺口，不補 0、不插值、不跨缺口連線，也不只加總已知部分冒充完整總量。 WebSocket 失敗或中斷時，Header 與兩個即時區塊顯示提示；保留最後成功資料及時間並標示已停止更新，沒有資料時顯示 `—`。
- 「時間區間尚在進行中」（OPEN）與「資料是否完整」（COMPLETE／PARTIAL／ERROR）分開表示；OPEN 不等於異常。
### 更新與範圍邊界
三組完整歷史資料隨同一次 V1 不做 REST polling fallback、custom backoff、jitter、背景自動重連、sequence／gap recovery或專用 Retry workflow；重新載入頁面才重新連線。
- WebSocket 斷線不影響其他 REST 區塊。
- Backend 需開發最小事件集合：`DASHBOARD_LIVE_SNAPSHOT`、`CONNECTOR_LIVE_BLOCK_UPDATED`、`LIVE_LOAD_UPDATED`。
- Frontend 需提供 connected、首次連線失敗與連線後中斷三種 fixture；驗證兩區提示、最後資料保留、最後更新時間，以及未啟動 REST fallback。
- 非即時 REST 區塊的更新方式已由 DEC-032 確認為頁面首載、共用 5 分鐘 Overview 回傳，切換頁籤只切換已取得資料，不再發 API 或重建 WebSocket。刷新保留所選頁籤，該頁籤無資料／失敗時不自動跳到別的範圍。 cycle 與手動刷新；詳細 supersession 與驗收條件見 #1424。
WebSocket 只更新目前功率、三種範圍的進行中區間，以及跨界時剛結束的區間；FE 依 buildingId＋rangeCode＋bucketStartAt 取代對應資料，不自行積分或平均。
**本區不顯示案場契約容量、容量利用率或剩餘容量。** 不得把各 Charge Group 的契約容量加總，當作案場契約容量。
**開發對照：** #1462 LOAD-DEC-001～007；斷線處理見第 09 節。
## 05｜群組容量與 Slots（中段右側） 背景
**要讓使用者知道：各充電群組目前的負載、群組自身容量，以及供電名額占用情形。** Branch Admin 的 `/dashboard` 目前是空白頁。既有 `DashboardStatsCard` 只有硬編碼假資料且未掛載；現有 `GET /api/connector/dashboard` 只能提供 Connector 總數、Available、Charging、Faulted、公用與私人數量，尚不足以支援案場營運判斷。
Mock 依序列出 B1、B2、B3 三個 Charge Group；這些名稱與數量只是範例，正式版依 本需求建立所有案場共用的 Backend 資料顯示，不固定三組。
| 由上到下的位置 | 內容與意義 |
|---|---|
| 區塊右上 | 既有時段資訊，例如 Mock 的「離峰時段」。 |
| 每個群組標題列 | 群組名稱、目前功率／該群組自身契約容量，單位 kW；例如 B1 Admin 營運 Dashboard；A17 僅為第一個驗證與導入案場。每個 EMS Branch 的 7.33 / 99 kW。 |
| 群組容量條與說明 | 該群組自身容量／餘裕，以及目前充電、等待或 BLOCKED 情況。 |
| 群組 Slots | 已占用名額／可配置名額；例如 1 / 14 Slots。Slots 是既有供電名額概念，不是電量。 |
| 區塊底部 | OCCUPIED（已占用）、WAITING（等待）、RESERVED（保留）摘要；Mock 為 3／3／0。 |
V1 自動顯示該 Branch 唯一一個 enabled Building；API、WebSocket、UI、freshness policy 與資料模型不得硬編碼 A17，且資料仍須以 Backend 沿用既有 SlotCalculator、群組容量與 Queue 狀態語意彙整 occupied／reserved／available slots；等待資訊可含 source、status、priority、statusReason、waitingSince／持續時間。只讀取和顯示，**不更改名額分配、輪充派送、優先序或等待門檻**。 解析的 `buildingId` 明確隔離。
本區使用一般 REST 更新，不跟著 WebSocket 每次變動；因此不要求與第 04 節的即時功率在每一刻完全同步。 > Mockup 內所有數字均為假資料。A17 production baseline 必須在實作前以 read-only query 驗證，不得將 mock 數字作為驗收基準。
**開發對照：** #1462（負載／群組）與 #1424（資料取得）。
## 06｜Connector 即時狀態（中下段、整列） 多案場適用原則
**要讓使用者知道：有哪些 Connector，哪些值得先查看，以及個別設備的連線、運作與排隊狀態。**
依畫面順序：**區塊標題與資料時間 → 五項摘要 → Connector 預覽卡 → 顯示筆數／查看全部**。
### 06-A｜五個狀態摘要：純資訊、不可點擊
| 固定順序 | 固定顯示名稱 | Backend code | - Dashboard 功能適用所有案場，A17 僅作為首個 rollout／baseline 驗證站點。
|---|---|---| - V1 的每個 EMS Branch 必須且只能有一個 enabled Building；Dashboard 自動使用該 Building，不提供案場 selector 或跨案場彙總。
| 1 | 需留意 | NEEDS_ATTENTION | - Frontend 呼叫 Overview／ticket 及建立 WebSocket 時不傳 `buildingId`；Backend 解析唯一 enabled Building。Overview response 與 WebSocket event 仍明確帶 `buildingId`，供 scope 驗證與資料隔離。
| 2 | 充電進行中 | CHARGING | - enabled Building 為零筆或多筆時，Dashboard 必須顯示設定錯誤；Backend 不可任選第一筆、跨 Building 加總或回傳全零資料。
| 3 | 準備／排隊 | WAITING | - Freshness／stale cutoff 由 Backend 依資料來源設定全系統預設值，不由 FE 或 A17-specific code 決定；V1 不提供 per-building override 或設定介面。
| 4 | 可用 | AVAILABLE |
| 5 | 其他狀態 | OTHER | - A17 Phase 0 的數據只用於驗證通用方案的公式、效能及預設值，不能成為其他案場的固定規則。
Backend 對完整集合分類，每個 Connector 由上到下命中第一類，**只屬於一類，五類相加必須等於總數**；需留意數＝abnormalTotal。Unknown／資料不足歸「需留意」，NOT_PLUGGED 歸「其他狀態」。完整條件沿用 #1423 UI-DEC-015。 ## 產品目標
讓 Site Admin、Operations、Finance 與 Engineer 在 10 秒內回答：
- 有 Connector 時固定顯示五項，包括 0，不隨更新隱藏或重排。 案場現在是否正常？
- 總數 0 時隱藏五項摘要，顯示 哪些 Charge Point 離線、哪些 Connector 空狀態。 故障？
- 五項均不可點擊、不進入 Tab 順序、不開 Drawer、不套篩選、不導頁，也不發 request。 目前有多少充電工作階段、全案場即時充電功率是多少？
- FE 使用 Backend 的完整統計，不從畫面上少數預覽卡計算。
### 06-B｜預覽卡：少量不撐滿，大量保留總覽
Backend 對完整集合依已確認的優先順序與穩定的同順位排序產生**最多前 8 筆**，一起回傳 total、abnormalTotal 及每筆異常原因。FE 不重排、不自行判斷異常，也不把螢幕寬度送給 Backend。
| 畫面寬度 | 最多顯示卡片數 | 若案場只有 1 或 2 個 | 輪充／離峰隊列是否已有明確 BLOCKED 狀態？
|---|---|---| - 今日使用量與最近一期結算流程是否有待處理項目？
| ≥ 1240 px | 8 | 只顯示實際 1／2 張，不補空卡、不把假資料補滿。 |
| 640～1239 px | 6 | 同左，按可用寬度排列。 |
| < 640 px | 4 | 同左，維持可讀的卡片排列。 | - Dashboard 資料是否仍然新鮮、可被信任？
例如 30 個 Connector 的桌面版顯示前 8 張，註明「顯示 8 / 30，另有 22 個未顯示」，由「查看全部」進入完整清單；手機顯示前 4 張。隱藏異常數使用 Backend 異常總數扣除可見異常數，不把未顯示者當成正常。 Dashboard V1 以唯讀總覽與 deep link 為主，不在首頁直接執行 Remote Start／Stop、Reset、Modbus 或 Engineer command。
每張卡保留 Connector／Charge Point 識別、位置／類型及已有的功率、Queue 等資訊；以下狀態必須分層，不合成一個「在線／離線」： ## 文件版號與 Redmine 附件管理（DOC-DEC-001）
```text
同一個 Connector
├─ 所屬 CP 的 OCPP 連線：ONLINE／OFFLINE／UNKNOWN
├─ Connector 運作狀態：AVAILABLE／CHARGING／FAULTED…
└─ Queue 狀態與原因：ELIGIBLE／BLOCKED／NOT_PLUGGED…
``` **狀態：已確認（2026-09-07，Ken）**
Heartbeat／BootNotification 不能把 FAULTED 或 CHARGING 覆寫成 AVAILABLE；Connector runtime 以既有 StatusNotification 為主要來源。未知功率顯示「—」，不是 0。 PDF、Markdown 與 HTML Mock 視為同一個 reviewer-facing 文件套件，必須使用相同版號。每次發布新套件時，三個檔案都新增為 #1422 的附件；不得覆蓋或刪除舊版，讓 Redmine 保留完整演進歷程。
點預覽卡開啟單支詳情，再依既有入口前往管理頁／Engineer Tools；目的頁仍需原有權限，Dashboard 不授予操作能力。
### 06-C｜「查看全部」：完整清單 Drawer 版號規則
Drawer 是從側邊開啟的完整清單，支援搜尋（Connector ID、Charge Point ID、車位）、狀態與 Charge Group 篩選。
```text - `v0.x Draft`：需求討論期間的 review snapshot。工作中的 Redmine 決策與本機 mock 可以持續演進；到達 review checkpoint 時，才一起產生下一個同步套件。
查看全部
↓ - `v1.0`：所有需求確認、整體一致性檢查及 Product review 完成後的開發 baseline。
搜尋／篩選完整資料集 → Backend 固定優先排序 → 每頁 20 筆
↓
上一頁／下一頁、頁次／總筆數 - `v1.x`：v1.0 後不改變主要 scope 的需求澄清或文件修正；若發生重大 scope／contract 變更，須在 Redmine 先建立新決策，再決定下一個 major version。
```
- 正式版使用／擴充既有 POST /api/connector/search，size 固定 20，sortMode 固定 DASHBOARD_PRIORITY；沿用 page 與 Spring Page 回應格式。 三個檔案的封面／頁首、檔名、文件日期及 Redmine 版本索引必須一致；不得出現 PDF、Markdown、HTML 各自使用不同版號。
- 先對**完整資料集**搜尋與篩選，再排序、分頁；不能只過濾已下載的 8 張卡或當頁資料。 每一版的 Redmine note 必須記錄 decision cutoff、主要變更摘要及三個 attachment IDs。
- 0～20 筆不顯示換頁控制；30 筆為 2 頁、100 筆為 5 頁。改搜尋／篩選時回第 1 頁。 在 v1.0 發布前，#1422 與各子票的現行 Description／已確認決策是需求依據；已發布的 v0.x 附件是特定時間點的 review snapshot。若兩者不同，以較新的 Redmine 決策為準。
### 檔名格式
- `backend-admin-dashboard-requirements-v{version}.pdf`
- 關閉再開保留搜尋、篩選及頁碼；重新載入或離開 Dashboard 後返回則重設。只存在本次頁面記憶體，不存 URL、瀏覽器儲存或 Backend 偏好。 `backend-admin-dashboard-requirements-v{version}.md`
- 不提供排序控制、每頁筆數選單、直接跳頁、Grid／Table 切換或 virtualization；不透過 WebSocket 推送完整清單。既有 /connector/list 的排序不變。 `backend-admin-dashboard-mock-v{version}.html`
**開發對照：** #1423 UI-DEC-006～020、#1424 DEC-034～041。預覽區塊由 WebSocket 整包取代；完整清單仍走 REST。 既有 v0.2 檔名不回溯更名；從下一版開始使用上述格式。
## 07｜30 日充電用量（底部左側）
**要讓使用者知道：最近 30 天完成了多少充電、每天分布如何，以及每次平均充多少電。**
區塊固定最近 **30 個案場日曆日（含今天）**，保留右上的 kWh／Sessions 切換；不提供 7／90 日或自訂範圍。
### 圖表與右側三項摘要 已發布版本索引
| 位置 版本 | 資訊 文件日期 | 定義 PDF |
|---|---|---|
Markdown | 圖表 X 軸 HTML Mock | 日期 狀態與說明 | 依案場時區，固定 30 個每日資料桶。 |
| kWh 模式 Y 軸 | 每日有效充電量（kWh） | 當日符合條件、已完成交易的最終電量合計。 | |---|---|---|---|---|---|
| Sessions 模式 Y 軸 v0.2 Draft | 每日有效充電次數（次） 2026-07-25 | 當日 COMPLETED 且 energy_consumed > 0 的交易筆數。 attachment #1108 |
attachment #1109 | 右側第 1 項 attachment #1110 | 有效充電量 初版 review snapshot；三份視為同一套件。其後已有多項 Redmine 決策取代部分內容，因此不得單獨作為現行開發規格。 | 30 日有效電量合計；Mock 2213.6 kWh。 |
| 右側第 2 項 v0.3 Draft | 充電 Sessions 2026-09-07 | 30 日有效次數；Mock 136。 attachment #1115 |
attachment #1116 | 右側第 3 項 attachment #1117 | 平均每次充電量 現行 review snapshot；整併截至本版發布前已確認的跨案場、資料取得、KPI、Connector、Live Load、Usage、帳務、UI state、驗收及開發分工。尚非 v1.0。 | 有效充電量 ÷ 有效次數，由 Backend 計算；Mock 16.28 kWh／次。 |
### 日期歸屬與資料來源 目前版本與下一版
```text
9/13 23:30 開始 ──── 跨午夜 ──── 9/14 01:00 結束
↓
完成後，整筆歸入 9/13
不拆成 9/13 - `v0.3 Draft` 是目前最新的 reviewer-facing 文件套件；PDF、Markdown 與 9/14 兩筆 HTML Mock 使用相同版號與日期。
``` - 若後續 review 有新決策，下一個 checkpoint 發布 `v0.4 Draft`；若所有需求已確認並通過整體一致性檢查，才發布 `v1.0` 開發 baseline。
- 在需求尚未全部確認前，不將任何 v0.x 標示為「最終」或「完整開發 baseline」。
- 舊附件永久保留供差異追溯；版本索引只新增列，不覆寫既有列。
## V1 Scope
- 只使用 completed transaction 已有的最終 energy_consumed，按既有單位換算 kWh，以 start_timestamp 判斷歸屬日。 「需留意事項」唯讀異常摘要與 deep link；只納入既有明確狀態（ATT-DEC-001，詳見 #1463）
- ACTIVE 不估算；0 Wh 不算有效 Session；異常 Completed 排除並標示 PARTIAL。 Charge Point OCPP connection 與 runtime 摘要
- 不讀 raw MeterValue 重算用量、不呼叫 MeterValueTariffCalculationService，也不按費率時段或帳務邊界切分。 Connector 完整狀態統計與即時狀態 grid
- 查詢成功但某日無使用，該日為 0；未知為 null。30 日全無使用時，顯示 0 kWh／0 次／—，並提示沒有紀錄，不建立告警。 Active sessions、案場即時總功率與負載趨勢（保留「即時／今日／7 日」三種檢視；軸線定義詳見 #1462）
- 平均每次充電量在 0 次時回 null，不除以零。 各 Charge Group 的目前功率、群組自身 contract capacity、occupied／reserved／available slots
- 初次失敗顯示 Error；刷新失敗可保留同案場最後成功資料與時間，標示失敗／過期，不冒充新資料。
**時間使用率已移除**，不再實作其分母、門檻或資料查詢。Usage 與第 04 節 Live Load 是不同資料來源與公式。
**開發對照：** #1461 USG-DEC-001～010；更新方式為共用 REST。
## 08｜結算流程（底部右側）
**要讓使用者知道：最近有結算資料的那一期，四個步驟分別完成到哪裡。** 沿用 Mock 的四列流程，不改成「本月帳務摘要」。
Mock 標題為「8 月結算流程」。正式版月份由 Backend 依**最近結算資料**回傳 periodYear／periodMonth／timezone，FE 只格式化，不自行用今天推算。
| 由上到下 | 使用者看到的內容 | Mock 假資料 | Queue waiting／blocked／最久等待時間摘要（唯讀資訊）
|---|---|---| - 今日用電與近 30 日 kWh／sessions 趨勢
| 1. Connector 結算 | 設備電量與費率計算的完成狀態 | 11 / 12 | - 結算流程區塊沿用 attachment #1110 四步驟面板；假數字改接正式 API，資料期間由 Backend 依最近結算資料回傳（BIL-DEC-001／002，詳見 #1460）
| 2. 門牌結算 | 私人與公用費用歸戶的完成狀態 | 10 / 11 | - Loading、Empty、Error、Stale、Partial、403 等 UI states
| 3. 帳務覆核 | 既有帳務 paid／pending 分布與覆核狀態 | 7 paid、4 pending；進行中 | - Desktop／Tablet／Mobile responsive
| 4. 發票結算 | 既有發票結算狀態 | draft；未完成 |
四列均為**純資訊、不可點擊**，不在 - SS3A 權限沿用既有 `dashboard` function 與 `administrator`、`power_user`、`association`、`dealer` 四個 role；不新增 Dashboard 執行計算、重跑、覆核、請款或開立發票。既有 Backend aggregation／DTO 只讀取狀態，不改月結排程。 role／function（#1424 DEC-030）
**與 Mock 的一項差異要明列：** #1460 BIL-DEC-003 已確認區塊 footer 應提供「查看帳單」→ /bill/list、「查看請款／發票」→ /invoice/list；但附件 #1117 的本區尚未畫出這兩個入口。這是既有需求與 Mock 的呈現差異，不是本次新增功能，也不能誤稱 v0.3 已經有畫。 ## V1 Scope Boundary
**別與 03-6「上月電費」混淆：**
| | 03-6 上月電費 | 08 結算流程 | - Dashboard 是唯讀營運資訊頁，只查詢、彙整及呈現既有系統狀態。
|---|---|---| - V1 的案場名稱是 Backend-resolved 唯讀識別；不新增 site switcher、多案場權限矩陣或跨案場 aggregate。
| 目的 | 看應收電費金額 | 看四步驟的完成狀態 | - 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 summary 使用固定五項互斥 `displayBucket` 且分項合計等於 total；`total > 0` 時包含零值的五項全部顯示，`total = 0` 時改顯示 Empty State。五個摘要項目為不可點擊的純資訊；detail 與完整清單分別由 preview card／「查看全部」負責。Connector preview 固定 Cards，使用單一 Top-8 payload，Desktop／Tablet／Mobile 顯示 8／6／4 張。完整清單 Drawer 採單一 responsive list與固定每頁 20 筆的 REST server pagination；只提供上一頁／下一頁，搜尋／篩選改變後回第 1 頁。搜尋／篩選／頁碼只保留於目前 page session，不提供 bucket click API、viewport-specific API、Grid／Table toggle、sorting control／state、page-size selector、直接跳頁、virtualization、URL／storage 或 Backend preference 保存。完整清單固定採 Backend priority ordering，搜尋／篩選不改變排序規則。
- Dashboard 開發不得改變 queue lifecycle、priority、slot allocation、rotation dispatch、OCPP command 或任何充電作業邏輯。
- 「需留意事項」只彙整既有明確狀態；V1 不新增 Queue mismatch、waiting timeout／SLA、scheduler-health、容量告警、派工或自動修復規則（詳見 #1463）。
- 若未來確有 SLA／scheduler monitoring 需求，須另案確認；本次不先建立實作 ticket。
**開發對照：** #1460 BIL-DEC-001～003；更新方式為共用 REST。
## 09｜共用規則：資料更新、異常與權限 開發工作拆分
### 09-A｜只保留兩條清楚的資料路徑 Backend / API
```text - [ ] 新增 typed `GET /api/dashboard/overview`；request 不含 `buildingId`，response 回傳 Backend-resolved `buildingId`、案場名稱與 timezone
首載／每 5 分鐘／手動刷新
│
▼ - [ ] 建立 `DashboardController`、`DashboardService`、「需留意事項」與各區塊 DTO
GET /api/dashboard/overview
├─ 六張 KPI、需留意事項
├─ 群組容量／Slots、30 日用量
├─ 結算流程、上月電費
└─ 負載三組完整歷史；首載另提供即時區初始畫面
一條 - [ ] 建立 current-building scope resolver，驗證 enabled Building 恰好一筆，並讓全部 Dashboard query 共用該 scope；零筆／多筆回明確 configuration error，不得沿用 `findDefault()` 的任選第一筆行為
- [ ] 聚合 CP connection/runtime、Connector 狀態、active transaction
- [ ] 依 #1423 UI-DEC-019～020／#1424 DEC-040～041 使用／擴充既有 `POST /api/connector/search` 作為完整清單：沿用 `page`／`size` 與 Spring Page metadata，固定 `size = 20`；`SearchConnectorDto` 增加 stable `sortMode = DASHBOARD_PRIORITY`，Server 對完整集合套用全部搜尋／篩選後，重用 preview ranking service 排序，再進行分頁。確認並補足 Charge Point ID／Charge Group 等缺少的 DTO／query 條件與 contract tests；既有管理頁未使用此 mode 時保留 `sidx`／`sord`，不新增完整 inventory WebSocket
├─ 或 Dashboard 專用分頁格式
- [ ] 依 #1423 UI-DEC-006／007／013～016 建立單一 Connector 即時狀態：整個預覽區塊取代
└─ 案場即時負載：目前值＋進行中／剛結束的區間 preview read model：對完整集合排序／分類後回最多 Top-8、`total`、`abnormalTotal` 與 item `displayBucket`／`isAbnormal`／`severity`／`priorityReason`；依 NEEDS_ATTENTION → CHARGING → WAITING → AVAILABLE → OTHER precedence，以同一 snapshot 產生互斥 bucket counts，保證每個 Connector 恰好一類、總和等於 total 且 NEEDS_ATTENTION count = abnormalTotal。REST bootstrap 與 `CONNECTOR_LIVE_BLOCK_UPDATED` 固定回五個 bucket（包含 count = 0）並共用 service／contract，不接受 viewport／device／requestedLimit，也不透過 WS 傳完整 inventory
```
每次一般更新只呼叫一次 Overview，共用一個 5 分鐘週期，不為各區另設 timer 或 API。六張 - [ ] 依 #1486 KPI-DEC-002 聚合 Backend-resolved current building 的 enabled CP：persisted OCPP ONLINE 為分子、enabled total 為分母，另回 OFFLINE／UNKNOWN／disabled；不得以 lastHeartbeat 另建 Dashboard cutoff，並只隨共用 Overview REST 更新
- [ ] 依 #1486 KPI-DEC-003 聚合 Connector 可服務數：分母為 enabled CP 下的 Connector，分子同時要求 parent CP ONLINE 與固定 runtime status allowlist；FAULTED／UNAVAILABLE／unknown／parent CP 非 ONLINE 排除，並只隨共用 Overview REST 更新
- [ ] 依 #1486 KPI-DEC-004／010／011 聚合「充電進行中」：每個 Connector 解析最多一筆 canonical ACTIVE transaction，忽略較舊孤兒 ACTIVE；只隨共用 Overview REST 更新，不回傳 KPI 不訂閱 NETWORK_HEALTH_UPDATED／CONNECTOR_OVERVIEW_UPDATED；不影響其他既有功能使用同名事件。
WebSocket 最小 message type 固定為 DASHBOARD_LIVE_SNAPSHOT、CONNECTOR_LIVE_BLOCK_UPDATED、LIVE_LOAD_UPDATED。WebSocket 接手後，後續 次要功率、不推論離線充電，也不新增交易 timeout 或修正
- [ ] 依 #1486 KPI-DEC-005 聚合「等待供電」：主數字只計 Queue ELIGIBLE 的 distinct Connector；NOT_PLUGGED 另列且排除已屬 ELIGIBLE 的 Connector，BLOCKED 留在需留意事項，其餘 Queue 狀態排除；只隨共用 Overview REST 刷新可更新一般資料與歷史，但**不能覆寫兩區的 live state，也不能在斷線時充當即時備援**。
### 09-B｜WebSocket 連不到，明確提示即可
| 連線情況 | FE 行為 | 更新，且不新增 Queue timeout、SLA 或狀態轉換
|---|---| - [ ] 建立案場 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 區塊照常更新。 |
**不做 REST polling 備援、自訂 backoff／jitter、背景自動重連、sequence／gap recovery、固定 5 秒 coalescing、2 秒傳播 SLO 或專用 Retry 流程。** 使用者重新載入整頁才再建立連線；手動刷新一般資料不重連。
以上 DEC-031／032 取代早期較複雜的傳輸提案；不改資料公式或作業流程。
### 09-C｜狀態字典：0、未知、失敗不可混用
| 狀態 | 中文含意與呈現 | 提供完整 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，不插值或回部分合計
| Loading | 還在取得資料，顯示載入樣式，不先填 0。 | - [ ] 依既有 SlotCalculator 語意逐組產生 Charge Group capacity summary；群組 contract capacity 不得加總成案場契約容量 KPI
| COMPLETE＋0 | 確認成功且數量為零；依各區規則顯示 0 或空狀態。 | - [ ] 統計既有 queue waiting／blocked／statusReason／waiting duration；不得新增 Queue SLA、timeout 或狀態轉換規則
| PARTIAL | 只有部分資料可確認；保留可信結果並標明不完整，不能宣稱整體正常。 | - [ ] 依 #1463 ATT-DEC-001 彙整 CP OFFLINE、Connector FAULTED、Queue BLOCKED、明確 source STALE／PARTIAL／ERROR 與 #1460 結算未完成／異常；不得新增 mismatch 或推測性判斷；Live Load 只依 current STALE／PARTIAL／ERROR 建立一個 category，歷史 bucket gap 不納入
| ERROR | 該來源無法取得；未知數值為 null／「—」，不轉成 0。 | - [ ] 依 #1463 ATT-DEC-003 回傳非零 categoryCount 與各類 distinct affectedCount；不加總成設備數，不做跨類 root-cause 去重
| 刷新失敗、有舊資料 | 只保留同 - [ ] 依 #1463 ATT-DEC-004 以固定 allowlist 順序回傳全部非零 categories；不依 severity／count／時間動態排序
- [ ] 依 #1461 USG-DEC-001～010 建立固定最近 30 個案場日曆日（含今天）的 kWh／Sessions usage trend；有效充電量只讀取符合條件的 COMPLETED energy_consumed，Sessions 只計算 COMPLETED 且正電量交易，兩者依 building 最後成功資料，顯示 lastSuccessfulAt 與失敗提示，不假裝更新成功。 | timezone 的交易開始日歸屬且跨日不拆分；不得讀取 raw MeterValue 重新估算或呼叫 MeterValueTariffCalculationService。Backend 回傳平均每次充電量與固定 30 daily buckets，成功無使用回 0、資料未知回 null／PARTIAL，整段全零回 COMPLETE + EMPTY，子查詢失敗回 source error metadata；不提供 7／90 日、自訂範圍或時間使用率
| STALE | 資料已過期，顯示過期與時間；不可當成正常即時數據，也不可納入需要即時性的完整總功率。 |
Backend - [ ] 依 #1486 KPI-DEC-006 讓「今日已完成充電量」直接重用 #1461 `date = rangeEndDate` 的 daily bucket；不新增 active-energy／MeterValue 暫估 query、第二套今日聚合欄位或 Usage／Energy WebSocket
- [ ] 依 #1460 BIL-DEC-001／002 建立四步驟結算流程的 read-only aggregation／DTO，並回傳 periodYear／periodMonth／timezone；不得執行帳務 mutation 或改變既有月結排程
- [ ] 依 #1486 KPI-DEC-001 建立「上月電費」read model：以 building timezone 取上一完整日曆月、加總該案場 `e_bill_settlement.cost_predict`；paid／pending 均納入，全部 calculation COMPLETE 才回 amount，否則回 null 與完成筆數；不顯示部分合計、不退回前期、不新增帳務 WebSocket
- [ ] 依 #1486 KPI-DEC-007／#1424 DEC-028，讓各 KPI source 回傳 generatedAt、來源 updatedAt、dataStatus、freshness value（可為 null）、COMPLETE／PARTIAL／ERROR、freshness、updatedAt 及必要的 lastSuccessfulAt。單一子查詢失敗只影響相依區塊，其餘繼續顯示，整體標示 PARTIAL。
資料過期 cutoff 由 Backend **依來源設定全系統共用預設值**，所有案場共用；FE 不硬編碼秒數。不做 per-building override、設定資料表、設定 API／UI、權限或 audit trail；A17 僅驗證預設值。
未知 code 不當成 AVAILABLE／正常。FE 以 code 判斷、中文 label 顯示；所有狀態須有文字或圖示，不只靠顏色。Production lastSuccessfulAt；子查詢失敗不得回 0，且只影響相依 Card，同一 Overview response 的欄位語意一致
- [ ] KPI-DEC-008 為純 Frontend 排版責任；Backend 不新增 viewport-specific API 失敗絕不能改用 Mock 假資料。
### 09-D｜權限與案場隔離
欄位、回傳順序或 WebSocket event 分支，同一份 snapshot 支援所有寬度
- [ ] KPI-DEC-009 不新增 deep-link URL、target、keyboard 或 ARIA API 欄位；Card 點擊不觸發 Backend mutation，固定目的地與 accessible copy 由 Frontend 維護
- [ ] 沿用既有 SS3A dashboard function：administrator、power_user、association、dealer 四個 `dashboard` function，新增 Overview／ticket API mapping；以冪等 migration 確認 `administrator`、`power_user`、`association`、`dealer` 的既有 role-function mapping，不新增 role／function、不在 Java hardcode role 的 Dashboard 內容與唯讀能力一致，不新增 role／function。 name，並在部署重啟後驗證授權快取已載入
- 僅有 adm_user、member、hq 或 engineer，且未取得 dashboard function 時，Overview／ticket API 回 403；多 role 使用者具允許權限時可存取。 [ ] 補 OpenAPI `@Schema`、method／DTO 欄位註解與測試
- FE 選單／路由與 [ ] 依 PERF-DEC-001／DEC-042 完成 Overview aggregate query EXPLAIN 與可重現的 endpoint P50／P95 baseline；記錄環境、資料量、暖機、併發數、sample size 與量測邊界，並避免 N+1、無界查詢及不必要的重複聚合
### Frontend
- [ ] 重新實作 `react/branch/app/(dashboard)/dashboard/page.tsx`
- [ ] Dashboard menu／route 依 Backend 回傳的既有 `dashboard` function 一致，未授權不得先載入或短暫顯示資料；隱藏選單不能取代 API／ticket 授權。 顯示；未授權狀態不得先載入或短暫顯示 Dashboard 資料，且不可只靠 Frontend 隱藏作為授權
- [ ] OpenAPI refresh 與 React Query overview hook
- [ ] Header、「需留意事項」、KPI、LiveLoad、ChargeGroup、ConnectorGrid；LiveLoad 只顯示案場即時總功率／趨勢／freshness，不顯示推算的案場契約容量、利用率或剩餘容量
- [ ] Header／Sidebar 顯示 Overview 回傳的唯讀案場名稱，不提供 selector；Overview request、ticket request、WebSocket request 與 WebSocket URL 不帶 FE 指定的 buildingId。Backend 解析唯一 不送 `buildingId`
- [ ] Backend 回報 enabled Building，response、ticket binding Building 零筆／多筆時顯示整頁「案場設定異常」，隱藏所有營運數字且不得 fallback 到 0 或 fixture
- [ ] Charge Point KPI 顯示「online / enabled 台啟用」，OFFLINE／UNKNOWN 與 event envelope 帶相同 buildingId；不符案場的事件不得套用，快取不得跨案場。 disabled 另列文字；整卡固定導向 `/cp/list`，connection 與 runtime 不混用
- Deep link 沿用目的頁權限，不因可看 Dashboard 就可執行 Start／Stop、Reset、Queue、帳務或 Engineer command。
**開發對照：** #1424 DEC-028～042。此區集中承接各畫面的共用規則，不另增作業功能。
## 10｜開發工作分工與子票索引
畫面改動由 FE 負責，但**正式資料聚合、API、WebSocket、權限與驗證也在本需求範圍內**，不能只完成靜態畫面。
| 工作 | 需要交付的內容 | [ ] Connector KPI 顯示「serviceable / total 個」及不可服務／其中故障數；不得將可服務誤標為 AVAILABLE，也不得由 bounded preview 重算；整卡固定導向 `/connector/list`
|---|---| - [ ] 第三張 KPI 名稱固定為「充電進行中」，顯示 Backend activeSessionCount；不得由 raw CHARGING／功率／preview 推導；小字顯示「依未結束的充電 Session 計算」，不顯示次要功率，整卡導向 `/connector/list`
| Backend／API | DashboardController、DashboardService、typed Overview 與各區 DTO；唯一 Building resolver；依 02～08 節建立唯讀聚合。 | - [ ] 第四張 KPI 名稱固定為「等待供電」，顯示 Backend waitingForPowerCount 與「另有 N 個未插槍（不計入）」；不得將 notPluggedCount 加回主數字或由 preview／等待時間重算，整卡導向 `/connector/list`
| Backend／Connector | 共用預覽排序與分類 service、Top-8／完整統計；補齊既有 - [ ] 「需留意事項」頁首顯示 N 類，各 card 顯示自己的 affectedCount 與單位；FE 不加總或跨類別去重
- [ ] 「需留意事項」顯示全部非零 cards，Desktop auto-fit、Tablet 雙欄、Mobile 單欄；不做 Top N／Drawer／展開／分頁
- [ ] LiveLoad 明確顯示 X 軸時間、Y 軸「充電功率（kW）」、各模式 bucket 與「區間平均功率」；bucketState 的進行中語意與 dataStatus 的 COMPLETE／PARTIAL／ERROR 分開呈現，0 與 null 不得混淆
- [ ] 依 #1462 LOAD-DEC-007，Overview 一次回傳即時／今日／7 日三組 series；預設即時，切換只讀取既有 cache、不發 request 或重建 WebSocket；五分鐘／手動刷新保留選擇，所選範圍 Empty／Error 時不自動跳頁籤
- [ ] LiveLoad 以 buildingId + rangeCode + bucketStartAt 套用 Backend-produced WebSocket replacement，不自行積分／平均；V1 不做 sequence／gap recovery或背景自動重連，socket 中斷時依 DEC-031 保留最後資料並顯示已停止更新
- [ ] Connector summary 依固定順序與中文 label 顯示 NEEDS_ATTENTION「需留意」、CHARGING「充電進行中」、WAITING「準備／排隊」、AVAILABLE「可用」、OTHER「其他狀態」，直接使用 Backend counts、不從 preview 重算；`total > 0` 時五項皆顯示（包含 count = 0），`total = 0` 時隱藏 summary 並顯示 Connector Empty State，且 0 不得當成缺值。五個 summary 項目使用非互動內容語意，不實作 link／button／tabindex／click／filter／navigation；單支 detail 與完整清單只由 preview card／「查看全部」開啟。Card／Drawer 仍分層顯示 OCPP／runtime／Queue。Connector preview 固定 Cards並保持 Backend 順序；Desktop／Tablet／Mobile 只顯示 Top-8 payload 的前 8／6／4 筆，以 `total`／`abnormalTotal` 與 visible `isAbnormal` 計算隱藏數量；不傳 viewport 或重判異常。完整清單 Drawer 使用 REST search DTO／query 的搜尋條件、DASHBOARD_PRIORITY 與固定分頁，不影響管理頁原排序。 | 的單一 responsive list（不實作 Grid／Table toggle），固定每頁 20 筆，只提供上一頁／下一頁與頁次／總筆數，1～20 筆隱藏換頁控制；search／filter 改變時回第 1 頁並由 Server 重查完整集合。search／filter／page 保存在目前 page memory，close／reopen 保留，reload／navigation 重設；固定要求 `DASHBOARD_PRIORITY`，不呈現或保存 sorting control／state，也不使用 page-size selector、直接跳頁、virtualization、URL、storage 或 Backend preference API
| Backend／WebSocket | 一條案場 Dashboard socket、ticket 授權、三種最小事件；Connector 區塊取代、負載目前值與區間更新。 | - [ ] Connector detail drawer 與既有管理頁／Engineer Tools deep link
| Backend／權限文件 | Overview／ticket 對應既有 dashboard function；冪等 migration 確認 role-function mapping，Java 不硬編碼 role 名稱；重啟後驗證授權快取。補 OpenAPI @Schema、method／DTO 欄位註解與 contract tests。 | - [ ] 依 #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 導覽
| FE | - [ ] 第五張 KPI 名稱固定為「今日已完成充電量」，顯示 Usage today bucket 的 validEnergyKWh 與「已完成 N 次充電」；不顯示昨日同時段比較、不估算 ACTIVE，整卡以 keyboard-accessible anchor 導向同頁 `#usage`
- [ ] 依 #1486 顯示「上月電費」KPI：完整時顯示應收總額；未全數完成時顯示 `—`、月份及完成筆數，整卡可用鍵盤導向同頁 `#billing`，不得自行推算月份、顯示部分合計或 forecast
- [ ] 依 KPI-DEC-007 實作 react/branch/app/(dashboard)/dashboard/page.tsx、OpenAPI types KPI Loading skeleton、有效 0、PARTIAL 有值／無值、Initial Error、Refresh Error with same-building cache、STALE 與 React Query overview hook；依畫面順序完成元件、圖表、Drawer、狀態、RWD、鍵盤操作與固定導覽。 | recovery；null 不轉 0、狀態不只靠顏色、失敗 source 不清空其他 KPI
| DB／效能 | 優先唯讀聚合，避免 N+1、無界查詢及重複聚合；先量測，必要時才提出 - [ ] Healthy／Critical／Partial／Stale／Empty／Large fixtures，並涵蓋 KPI loading、zero、initial error、refresh error with cache 與跨 building cache isolation
- [ ] 依 #1486 KPI-DEC-008 實作六張 KPI responsive grid：`>=1240px` 6×1、`768～1239px` 3×2、`320～767px` 2×3；固定 DOM／視覺順序，不隱藏、不使用 carousel 或水平捲動，長文案完整換行；驗證 390／768／1024／1440px 與臨界值
- [ ] 依 #1486 KPI-DEC-009 將六張 KPI 實作為單一原生 link：固定導向 `/cp/list`、`/connector/list`、`#usage`、`#billing`；整卡支援 pointer／touch／Tab／Enter、同頁 anchor 後移動 focus、狀態同步 accessible name、支援 reduced motion，且 Overview refresh 不逐卡 live announce 數字
- [ ] Production API error 不得 fallback 到 fixture
### Database / Performance
- [ ] 取得 A17 或具代表性等量資料的主要 table row count、狀態分布、MeterValue 24h volume 與 query plan
- [ ] 優先採 read-only aggregate；不為固定秒數預先建立 Dashboard snapshot table、專用 cache 或效能排程
- [ ] 只有 baseline 證明正常使用受到影響時，才提出 query 或普通 index 優化。 | 優化
| QA／發布 | Backend repository／service／security／contract tests，FE fixture／互動／RWD，首站 E2E、效能 baseline、發布 smoke 與下一工作日檢查。 |
DB - [ ] 不新增 Dashboard snapshot table、專用 cache、效能排程、UNIQUE／FOREIGN UNIQUE／FOREIGN KEY／CHECK／cascade constraint。不得為本 Dashboard 改動 Queue lifecycle、priority、Slot allocation、Rotation dispatch、OCPP command、月結／費率作業。 constraint
### 查閱細節時，直接找對應子票 QA / Release
| 子票 | 對應本文 | 已確認決策 | - [ ] Backend repository／service／security／contract tests
|---|---|---| - [ ] 權限測試覆蓋 `administrator`、`power_user`、`association`、`dealer` 可讀取 Overview／取得 ticket，以及只有 `adm_user`、`member`、`hq`、`engineer` 時為 403／WebSocket 拒絕；多 role member 只要具任一允許 role 即可存取
| #1423 - [ ] FE fixture、RWD、keyboard、unknown enum、null／0／large value tests；Connector 覆蓋 0／1／2／8／9／30／100 筆與 390／768／1024／1440px，驗證同一 Top-8 payload 的 8／6／4 截取及隱藏數量；驗證五類固定 precedence、每個 Connector UI／UX | 06 | UI-DEC-006～020（其餘既有 UI 決策沿用） | 恰好一個 displayBucket、bucket counts 總和等於 total、NEEDS_ATTENTION count = abnormalTotal、Unknown／NOT_PLUGGED mapping 正確；另驗證 total > 0 時五類包含零值皆可見、total = 0 時只顯示 Empty State、0／null／Loading／Error 不混淆、五個 summary 項目不可點擊，以及 Drawer search／filter／page 在同一 page session 的 close／reopen 保留、reload／navigation 重設且不持久化；30／100 筆分別為 2／5 頁、每頁最多 20 筆，0～20 筆隱藏換頁控制，搜尋／篩選後回第 1 頁且使用完整 Server 結果；Drawer 無 sorting control，完整結果依固定 priority hierarchy 與 deterministic tie-breaker 排序後才分頁，且 `/connector/list` 原排序功能不受影響
| #1424 REST／WebSocket 與共用規則 | 01、09、10 | DEC-028～042；較早未被取代的技術條件仍見子票 | - [ ] Backend／FE contract tests：唯一 enabled Building 正常載入；零筆與多筆均顯示 configuration error；request 不含 buildingId；WS event buildingId 不符時拒絕套用
| #1463 需留意事項 | 02 | ATT-DEC-001～008 | - [ ] A17 staging E2E：offline、faulted、active transaction、stale meter、blocked queue、billing、partial data、403
| #1486 KPI | 03 | KPI-DEC-001～011 | - [ ] 依 REL-DEC-001，在首個實際 rollout 案場部署後執行一次 Dashboard smoke test，並於下一個工作日使用既有 application log／維運工具／資料庫負載資訊做一次檢查；不新增 Dashboard 專用監控、告警、instrumentation 或 24 小時值守
## 核心狀態規則
1. `ChargePoint.ocppConnectionStatus`、Charge Point runtime、Connector runtime、rotation queue 必須分層顯示，不得合併成單一在線／離線。
| #1462 Live Load／群組 | 04、05 | LOAD-DEC-001～007 | 2. Heartbeat／BootNotification 只能證明連線存活，不能把 FAULTED／CHARGING 覆寫為 AVAILABLE。
| #1461 充電用量 | 07、03-5 | USG-DEC-001～010 | 3. Connector runtime primary owner 是 StatusNotification。
| #1460 結算流程 | 08 | BIL-DEC-001～003 | 4. Charge Point 離線與未結束 ACTIVE Session 分開呈現：離線告警不得推論「離線充電／待 reconciliation」；「充電進行中」仍依 canonical ACTIVE transaction 獨立計數。
5. 即時數值不存在時回 `null`，不可用 0 表示未知。
6. Status code 供 FE 邏輯使用；中文 label 僅供顯示，未知 code 不得 fallback 成 AVAILABLE。
本次把散落的已確認決策併回所屬區塊，不再把已確認內容列在「待決策」底下。子票仍保留完整欄位、排序、狀態與驗收細節；本次不改子票內容、指派或進度。
## 11｜驗收、效能與完成條件 Acceptance Criteria
### 11-A｜依畫面走一次的驗收重點
| 對照區塊 | 必須驗證 | - [ ] 使用者 10 秒內可從「需留意事項」指出離線、故障、既有 Queue BLOCKED 或結算流程異常
|---|---| - [ ] 所有「需留意事項」摘要與關鍵數字都有可用 deep link；摘要本身不執行 mutation
| 01 頁首 | 唯一／零筆／多筆 enabled Building；案場名稱與隔離；即時連線與一般更新時間分開。 | - [ ] 「需留意事項」頁首 categoryCount 等於非零 categories 數量；各類 affectedCount 於類別內 distinct，跨類別不推導共同根因
| 02 - [ ] 需留意 | N 類不是受影響數量總和；固定順序、全部非零項目、類內去重；正常／PARTIAL／ERROR；五類導覽正確，不推論離線充電。 | categories 依固定 allowlist 順序全部顯示；1～5 類在 390／768／1024／1440 px responsive 換行且無水平捲軸
| 03 KPI | 分子分母、canonical ACTIVE、ELIGIBLE／NOT_PLUGGED 互斥、開始日歸屬、上月全部 - [ ] Attention aggregate 為 COMPLETE 才顯示金額；六卡全 REST、單一連結與正確欄數。 | + categoryCount 0 + empty categories 時保留精簡正常狀態；PARTIAL／ERROR 不得顯示為沒有需留意事項
| 04 負載 | 即時／今日／7 日、X/Y 軸與時間加權；0 與 - [ ] Attention PARTIAL 顯示已確認 categories 與數量可能不完整；ERROR 回 null 缺口；OPEN／FINALIZED 與品質分開；切換不發 API，斷線不備援。 | count 並顯示不可取得，兩者皆不新增作業行為
| 05 群組 | 群組自身容量、Slots 與既有 Queue 語意；不把群組容量加總成案場契約容量。 | - [ ] 五類 Attention card 依 ATT-DEC-007 固定導向既有 route／section；支援 keyboard focus，且不新增任意 URL、篩選 API 或 mutation
| 06 - [ ] Overview 效能依 PERF-DEC-001／DEC-042 產出 A17 或具代表性等量資料的 EXPLAIN、P50／P95 baseline 與完整測試條件紀錄；V1 不以固定 1.5 秒作產品 SLA
- [ ] Header 顯示 Backend-resolved 案場名稱與 `generatedAt`；各資料源有 `updatedAt` 與 freshness；UI 不提供案場 selector
- [ ] Overview／ticket request 與 WebSocket URL 不含 Frontend-supplied `buildingId`；Overview response、ticket binding 與 event envelope 使用相同 Backend-resolved `buildingId`
- [ ] enabled Building 恰好一筆才載入 Dashboard；零筆或多筆顯示設定錯誤並隱藏營運數字，不得任選、跨案場加總或將未知顯示為 0
- [ ] Charge Point 連線 KPI 只統計 Backend-resolved current building 的 enabled CP，ONLINE／OFFLINE／UNKNOWN 合計等於分母；disabled 不算離線，Dashboard 不用 Heartbeat 時間重新判定連線
- [ ] Connector | 0／1／2／8／9／30／100 筆；五類互斥、加總等於 total、需留意＝abnormalTotal，五摘要不可點；Top-8 可服務 KPI 的 8／6／4 截取與隱藏數量；Drawer 搜尋完整集合、排序後每頁 20、開關保留／reload 重設。 | parent CP／status allowlist、unknown 排除與 enabled CP scope 符合 KPI-DEC-003；serviceable + nonServiceable 等於 total，Frontend 直接使用 Overview 的 Backend aggregate
| 07 用量 | 30 個日期桶、開始日跨日歸屬、只用已完成最終電量、正電量有效次數、平均值；全零／未知／部分失敗與舊資料保留。 | - [ ] 「充電進行中」每 Connector 最多計一筆 canonical ACTIVE transaction；舊孤兒 ACTIVE、Queue 與未建立 StartTransaction 的 operation 不計，offline／disabled CP 下尚未結束 Session 不隱藏；CP 離線與 Session 數分別呈現，UI 不顯示「離線充電／待 reconciliation」或其他推測性原因；此計數不得被解讀或標示為已確認的「離線充電／待 reconciliation」
| 08 結算 | 最近資料期間與四步驟狀態、純資訊列、兩個既有列表入口；不誤當上月金額或本月預估。 | - [ ] 「等待供電」只計 Queue ELIGIBLE 的 distinct Connector；多筆 Queue row 不重複，NOT_PLUGGED 另列且與主數字互斥，BLOCKED 只由需留意事項呈現，REST／WS aggregate 一致
| 共用 | 四個允許 role／未授權 403、多 role、無效 - [ ] 「今日已完成充電量」與完成次數等於 Usage rangeEndDate daily bucket；只含依開始日歸屬的有效 COMPLETED 交易，ACTIVE 不估算，且不使用 raw MeterValue／費率分段重算；狀態與 REST refresh 完全沿用 #1461
- [ ] 六張 KPI 在 Loading／COMPLETE 0／PARTIAL／Initial Error／Refresh Error／STALE 下符合 KPI-DEC-007；null 不冒充 0、快取不跨 building，且 source failure 只影響相依 Card
- [ ] 六張 KPI 依 KPI-DEC-008 在 1440px 為 6×1、768／1024px 為 3×2、390px 為 2×3；固定順序且完整顯示，長內容可換行，320px 以上不產生水平捲軸
- [ ] 六張 KPI 依 KPI-DEC-009 各為一個原生 link 與單一 Tab stop；目的地、Enter、focus indicator、同頁 focus transfer、accessible name、reduced motion 與 Overview refresh 不逐卡 live announce 均符合規格，所有資料狀態仍可導覽
- [ ] 任一子查詢失敗時，其餘區塊仍顯示並標記 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。Socket 中斷後保留最後資料並顯示已停止更新，不啟動 REST fallback／gap recovery；整頁 reload 才重新取得 snapshot與 socket
- [ ] Live Load 完整零負載為 0 + COMPLETE；任一超過 cutoff 的 unknown 充電功率為 null + PARTIAL，圖表顯示缺口且不插值／跨線
- [ ] current Live Load STALE／PARTIAL／ERROR 只在「需留意事項」產生一個 category；歷史 gap 與 OPEN + COMPLETE 不產生摘要
- [ ] 「上月電費」以 building timezone 的上一完整日曆月及 `e_bill_settlement.cost_predict` 計算；paid／pending 均納入，任一帳單未 COMPLETE 時 amount 為 null 並顯示完成筆數，不顯示部分合計或退回前期
- [ ] `administrator`、`power_user`、`association`、`dealer` 經既有 `dashboard` function 可進入頁面、讀取 Overview 並取得 ticket；四者資料內容與唯讀能力一致
- [ ] 僅有 `adm_user`、`member`、`hq` 或 `engineer` role 而未取得 `dashboard` function 時，直接呼叫 Overview／ticket API 得到 403，且沒有有效 ticket 拒絕 WS；null／0／unknown／large value；來源失敗隔離、同案場快取；production 無 fixture fallback。 |
不得建立 Dashboard WebSocket
- 檢查 390／768／1024／1440 px 及各 breakpoint 臨界值，320 px 以上不產生頁面級水平捲軸。 [ ] Frontend menu／route visibility 與 Backend function 一致，但不得以隱藏 menu 取代 API／ticket 授權；Dashboard 權限不附帶任何 Start／Stop、Reset、Queue、帳務修改或 Engineer command 能力
- 狀態、文字對比、focus 與鍵盤符合 [ ] 狀態不可只靠顏色；keyboard focus、status message 與文字對比符合 WCAG 2.2 AA 基本要求；同頁導覽轉移焦點、支援 reduced motion，更新不逐卡 live announce。 基本要求
- Fixture 包含 Healthy／Critical／Partial／Stale／Empty／Large；KPI 載入、有效零、初次失敗、刷新失敗；WebSocket 正常、首次失敗、連線後中斷。 [ ] Connector Full List 固定每頁 20 筆；30／100 筆分別為 2／5 頁，0～20 筆隱藏換頁控制，第一／最後一頁按鈕狀態正確；搜尋／篩選後回第 1 頁並由 Server 查完整集合，不提供 page-size selector、直接跳頁或 virtualization
- A17 staging E2E 覆蓋 offline、faulted、active transaction、stale meter、blocked queue、billing、partial data、403，並確認既有管理頁與 [ ] Connector 排序無回歸。 Full List 不顯示或保存 sorting control／state；Backend 對完整結果固定 filter → priority sort → paginate，同層級順序穩定，且既有 `/connector/list` sorting 無回歸
- [ ] 390／768／1024／1440 px 不出現頁面級水平捲軸
- [ ] Production build 不包含 API error → fixture fallback
### 11-B｜實作前資料檢查與效能 baseline
以 ## A17 或具代表性等量資料做唯讀檢查，不把 Mock 數字當結果： Phase 0 Gate
實作前必須用 read-only query 確認：
- CP ONLINE／OFFLINE／UNKNOWN、runtime；Connector ONLINE／OFFLINE／UNKNOWN 與 runtime 分布
- Connector status／area／type 分布。 分布
- Active transaction 數與最長持續時間；各群組 contract／allocated／reserved／queue。 數與最長持續時間
- 各 Charge Group contract／allocated／reserved／queue
- MeterValue 24 小時筆數、峰值與最新資料延遲；近 小時筆數、峰值與 latest lag
- 近 30 日 transaction／kWh／每日分布。 transaction／kWh／日分布
- 最近結算資料期間的 Billing／Invoice 狀態；主要資料表筆數／分布及各 狀態分布
- 各 aggregate query 的 EXPLAIN。 EXPLAIN
Overview endpoint 記錄 P50／P95 baseline，附環境、資料量／分布、暖機、併發數、sample size 與量測起訖邊界。**V1 不承諾固定 P95 < 1.5 秒 SLA**；只有實測影響正常使用時才提出查詢／普通 index 優化，不預先增加架構。（PERF-DEC-001／DEC-042） ## E2E Test Impact
### 11-C｜E2E 與發布 **Classification：Add**
功能實作的 此需求新增 user-visible Dashboard、typed API、SS3A permission 與多來源營運聚合，需在實作階段新增長期 E2E impact 為 **Add**；本次純 Description 整理為 **No catalog change**，不代表功能已完成或已通過測試。 Catalog cases：
| 優先級 | 長期案例範圍 | 執行 trigger |
|---|---|---|
| - P0 | Overview／ticket／WS / Standard、Major、A17 release：Dashboard Overview／ticket／WebSocket 未授權拒絕、PARTIAL、stale safety | Standard、Major、A17 release；適用時為發布阻擋條件 |
| - P1 | 四 / Standard、Major、A17 release：四個允許 role 正向、多 role、案場 scope、offline／faulted／active／Queue／billing／responsive | Standard、Major、A17 release | 的正向存取、多 role member、OCPP offline、Connector faulted、active transaction、queue blocked、billing block、responsive，以及唯一／零筆／多筆 enabled Building scope
| - P2 | 大量資料、未知 enum、效能 / Major、A17 release：large data、unknown enum、performance baseline | Major、A17 release |
實作階段依 maintain-ems-e2e-catalog 確認 實作 ticket 的階段 2 必須依 `maintain-ems-e2e-catalog` skill 確認正式 Case ID 與 release pack；run-specific 結果放 test_report，不放長期 Catalog，Skip 不視為 Pass。 pack。
首站部署後做一次 smoke test（頁面／Overview／兩區連線或失敗提示／既有頁面），下一個工作日使用既有 application log、維運工具及 DB 負載資訊檢查。發現問題沿用既有 release／rollback 流程；不新增專用監控平台、metrics、instrumentation、自動告警、排程或 24 小時值守。（REL-DEC-001）
### 11-D｜Definition ## Definition of Done
- [ ] Product 確認各區數字定義、範圍，完成整體一致性 review。 確認 KPI 字典、範圍與待決策事項
- [ ] A17 或具代表性等量資料的效能 baseline 已完成，測試條件與 P50／P95 已記錄；若實測影響正常使用，所需 query／普通 index 優化已完成
- [ ] Backend API、OpenAPI、SS3A mapping 與測試完成。 與測試完成
- [ ] FE 各區、狀態、RWD、accessibility、deep 各區塊、states、RWD、accessibility、deep link 完成。 完成
- [ ] 首站或代表性資料的 EXPLAIN／P50／P95 baseline 完成；必要優化完成。
- [ ] A17 staging E2E 完成，結果與限制已記錄。 與 PERF-DEC-001／DEC-042 效能 baseline 完成
- [ ] E2E Catalog 與 ai/02-backend-services.md、ai/03-database.md、ai/04-frontend.md 更新。 `ai/02-backend-services.md`、`ai/03-database.md`、`ai/04-frontend.md` 更新
- [ ] 首站 首站部署後 smoke test 與下一工作日既有 log／DB 負載檢查完成。 與下一工作日的既有 log／資料庫負載檢查完成
## 12｜文件版號與 Redmine 附件管理（DOC-DEC-001） 待決策
PDF、Markdown、HTML Mock 是同一套 review 文件，**三份版號必須一致，每一版都新增到 #1422，不覆蓋、不刪除舊附件。**
### 已發布版本索引
| 版本／日期 | PDF | Markdown | HTML Mock | 定位 | - V1 已確認採每個 EMS Branch 自動使用唯一 enabled Building；Frontend 不傳或切換 `buildingId`，Overview response／ticket binding／WS event 仍帶 Backend-resolved `buildingId`；零筆或多筆顯示設定錯誤（#1424 DEC-029）
|---|---|---|---|---| - V1 不顯示或回傳由 Charge Group contract capacity 加總推導的案場契約容量、利用率與剩餘容量；只保留案場即時總功率及各群組自身容量（LOAD-DEC-001，已確認；詳見 #1462）
| v0.2 Draft／2026-07-25 | [#1108](https://redmine.sylksoft.com/attachments/1108) | [#1109](https://redmine.sylksoft.com/attachments/1109) | [#1110](https://redmine.sylksoft.com/attachments/1110) | 初版快照；後續多項決策已取代部分內容，不可單獨當現行規格。 | - Live Load 保留「即時／今日／7 日」三種檢視；X 軸分別為最近 60 分鐘／今日／含今天 7 個案場日曆日，bucket 為 1 分鐘／15 分鐘／1 小時，Y 軸為 time-weighted averagePowerKw（LOAD-DEC-002／003，已確認；詳見 #1462）
| v0.3 Draft／2026-09-07 | [#1115](https://redmine.sylksoft.com/attachments/1115) | [#1116](https://redmine.sylksoft.com/attachments/1116) | [#1117](https://redmine.sylksoft.com/attachments/1117) | 目前 review 快照，整併發布前已確認需求；尚非 v1.0。 |
### 後續版本規則
- **v0.x Draft：** 討論階段快照。Redmine 決策與工作 Mock 可持續演進，到 review checkpoint 才一起發布下一套。 Live Load 完整 series 由 REST 提供；WebSocket 只更新 currentPowerKw、三種 open buckets 與跨界 finalized bucket，FE 採 replacement（LOAD-DEC-004，已確認；詳見 #1462）
- **v1.0：** 所有需求確認、整體一致性檢查與 Product review 完成後的開發基準；不可預先稱 v0.x 為最終文件。 Live Load 以 bucketState 區分 OPEN／FINALIZED、dataStatus 區分 COMPLETE／PARTIAL／ERROR；unknown 充電功率回 null + PARTIAL，不插值、部分合計或 coverage threshold（LOAD-DEC-005，已確認；詳見 #1462）
- **v1.x：** 不改主要範圍的澄清／文件修正；重大 scope／contract 改變須先在 Redmine 建立新決策，再決定 major version。 Live Load 預設「即時」，三組 series 隨同一 Overview 一次取得；切換不發 API／重建 WebSocket，刷新保留選擇，Empty／Error 留在所選頁籤（LOAD-DEC-007，已確認；詳見 #1462）
- 三份封面／頁首、檔名、日期、版號及本索引一致。每版 note 記錄 decision cutoff、變更摘要與三個 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，已確認）
- Usage 與 Live Load 資料來源已分開：Usage 只讀 completed transaction 的 energy_consumed／start_timestamp，不使用 raw MeterValue 或 MeterValueTariffCalculationService；MeterValue 僅供 #1462 Live Load（USG-DEC-010，已確認）
- 首頁帳務區塊沿用 attachment IDs。 #1110 四步驟「結算流程」；不改成 Billing Summary（BIL-DEC-001，已確認）
- 檔名固定為 backend-admin-dashboard-requirements-v{version}.pdf、同名 .md，以及 backend-admin-dashboard-mock-v{version}.html；舊 v0.2 不回溯更名。 結算流程期間由 Backend 依最近結算資料回傳；Frontend 不依日曆月份推算（BIL-DEC-002，已確認）
- 有新決策時下一 checkpoint 可發布 v0.4 Draft；全部確認後才發布 v1.0。版本索引只新增列，舊附件永久保留。 結算四列維持純資訊；footer 分別導向既有 /bill/list 與 /invoice/list，不新增頁面或 drill-down API（BIL-DEC-003，已確認）
- v1.0 前以本票及子票的**現行 Description／較新已確認決策**為需求依據；附件是當時的 review 快照，差異須明確標示。
**本次編輯紀錄（2026-09-14）：** 依附件 #1117 的實際畫面順序重整 Description，加入區塊配置、狀態分層、日期歸屬與資料流示意；把已確認決策移回對應區塊，保留開發、驗收及版本管理內容。未更動既有附件、議題進度或產品範圍。 「需留意事項」ATT-DEC-001～008 已確認：使用既有明確狀態、current Live Load 品質規則、category／affected count、固定順序與 responsive、Empty／Partial／Error State、五類固定 deep link，以及 CP 離線不與 ACTIVE Session 合成推測性提示；本區塊待全 Dashboard 鎖版時整併（詳見 #1463）
- 「即時關鍵指標」KPI-DEC-001～011 已完成需求確認：六張 KPI 的資料與狀態、6×1／3×2／2×3 responsive layout、單一原生 link／固定 deep link，以及「充電進行中」不重複顯示即時功率、也不推論離線充電原因均已定案（詳見 #1486）
- Dashboard 權限已確認沿用既有 `dashboard` function，授權 `administrator`、`power_user`、`association`、`dealer`；`adm_user`、`member`、`hq`、`engineer` 不自動取得（#1424 DEC-030）
- 非即時區塊已確認使用頁面首載、共用 5 分鐘 Overview cycle 與手動刷新；六張 KPI 不訂閱 `NETWORK_HEALTH_UPDATED`／`CONNECTOR_OVERVIEW_UPDATED`，也不再採 60 秒 fallback 或各區塊獨立週期（DEC-031／032，一致性清理已確認）
- Freshness 已確認只使用 Backend per-source global defaults；V1 撤回 per-building override 及其設定儲存／API／UI／權限／audit（DEC-033，已確認）
- Connector preview 已確認採 Backend 單一 Top-8 payload + `total`／`abnormalTotal`／item abnormal metadata；FE 只依 breakpoint 顯示 8／6／4 筆並計算純顯示隱藏數量，完整清單走 REST Drawer（UI-DEC-013／DEC-034，已確認）
- Connector Status summary 已確認使用互斥 `displayBucket`，每個 Connector 恰好一類且分項合計等於 total；固定 NEEDS_ATTENTION／CHARGING／WAITING／AVAILABLE／OTHER 五類及 precedence，Unknown 歸需留意、NOT_PLUGGED 歸其他。非空案場固定顯示包含零值的五類，空案場顯示 Empty State；五個摘要項目為不可點擊的純資訊，detail／完整清單由既有 preview card／「查看全部」負責；原始狀態仍分層顯示（UI-DEC-014～017、DEC-035～038，已確認）
- Connector Full List Drawer 的 search／filter／page state 已確認只保留於目前 page session：close／reopen 保留，reload／navigation 重設，不寫 URL、storage、Backend 或 WebSocket（UI-DEC-018／DEC-039，已確認）
- Connector Full List 已確認固定每頁 20 筆，只提供上一頁／下一頁與頁次／總筆數；1～20 筆隱藏換頁控制，搜尋／篩選改變後回第 1 頁並由 Server 對完整集合查詢，不提供 page-size selector、直接跳頁或 virtualization（UI-DEC-019／DEC-040，已確認）
- Connector Full List 已確認不提供使用者排序控制；Backend 對完整結果固定使用 preview priority hierarchy 與 deterministic tie-breaker，再執行分頁。Dashboard 使用 `DASHBOARD_PRIORITY` read mode，既有管理頁 sorting 不受影響（UI-DEC-020／DEC-041，已確認）
- Overview 效能已確認採可重現的 EXPLAIN、P50／P95 baseline，不以固定 1.5 秒作 V1 產品 SLA；只有實測影響正常使用時才優化，且不預先新增 snapshot table、專用 cache 或效能排程（PERF-DEC-001／DEC-042，已確認）
- 首站發布已確認採一次 smoke test＋下一工作日使用既有 log／維運工具／資料庫負載資訊檢查；不新增專用監控平台、metrics、告警、instrumentation 或 24 小時值守（REL-DEC-001，已確認）
返回