討論 #1424
是由 陳國瑋 於 27 天 前更新
## 現行 V1 傳輸規則：DEC-031
**狀態：已確認（2026-09-04，Ken）**
> 本節是目前有效的傳輸需求。下方較早提出的 Dashboard 全區 WebSocket、REST polling fallback、capped exponential backoff、jitter、sequence／gap recovery、固定 5 秒 coalescing 與 P95 2 秒 propagation SLO，均保留作為討論歷程，但不再是 V1 開發依據。
- V1 保留一條案場層級 Dashboard WebSocket，但只更新「Connector 即時狀態」與「案場即時負載」。
- `GET /api/dashboard/overview` 仍提供整張 Dashboard 首次載入所需的 snapshot；WebSocket 建立後，只 replacement 上述兩個即時區塊。
- Connector message 回傳整個即時狀態 summary 與 bounded preview；完整清單、搜尋及分頁仍走 REST。
- Live Load message 更新 `currentPowerKw` 與目前進行中的 open buckets；完整「即時／今日／7 日」歷史 series 仍走 REST。
- 六張 KPI、需留意事項、群組容量／Slots、30 日用量、今日已完成充電量、結算流程及上月電費不訂閱 Dashboard WebSocket。
- WebSocket 首次連線失敗或已連線後中斷時，Header 與兩個即時區塊顯示「即時連線中斷」。
- 若已有最後成功資料，畫面保留資料與最後更新時間，但明確標示「已停止更新」；若尚無資料，顯示 `—` 與「即時資料暫時無法取得」。不得清成 0。
- V1 不做 REST polling fallback、不顯示「定時更新模式」，也不開發 custom backoff、jitter、背景自動重連、sequence／gap recovery或專用 Retry workflow。
- 使用者重新載入整個頁面時，才重新取得 ticket 並嘗試建立新 WebSocket。
- WebSocket 斷線只影響兩個即時區塊；其他已成功載入的 REST 區塊仍可查看。
- Backend 的 source freshness／stale cutoff、null／0、building scope、SS3A 權限及 Dashboard 唯讀邊界繼續有效；socket 是否連線與資料來源本身是否 stale 必須分開呈現。
- V1 message type 收斂為 `DASHBOARD_LIVE_SNAPSHOT`、`CONNECTOR_LIVE_BLOCK_UPDATED`、`LIVE_LOAD_UPDATED`。同一 WebSocket 內採整區 replacement，不新增 client-side delta merge。
- 本決策完整取代 DEC-003 與 DEC-005；並取代 DEC-002 的 fallback／重連部分、DEC-004 的固定 5 秒產品契約、DEC-008 的 sequence／gap recovery、DEC-014 的重連／gap recovery，以及 DEC-021／023～028 中要求非上述兩個區塊使用 WebSocket 的傳輸部分。這些決策的資料公式、Backend authoritative aggregation、security 與 presentation 規則仍有效。
- 非即時 REST 區塊是否自動刷新及刷新間隔，另列為下一項待確認需求。
## 背景
所有案場共用的 Branch Admin Dashboard 主需求為 #1422；A17 僅是第一個驗證基準。
本票用於定義 Dashboard 各區塊的資料更新通道：哪些資料使用 REST API、哪些適合透過 WebSocket 即時推送，以及兩者如何在 initial load、重連、stale、partial data 與權限控制下協作。
**目前是 Proposed Design／需求待確認，不代表已進入開發。**
## 現有程式碼觀察
### 已有能力
- `react/branch` 已有 `useAdminConnectorSocket()`。
- `java/ems_branch` 已有 `/ws/admin/connectors/{connectorId}`。
- 既有流程先以 SS3A REST API 取得 30 秒、一次性、connector-bound ticket，再建立 WebSocket。
- 新連線會收到 `CONNECTOR_SNAPSHOT`，後續可收到 `OPERATION_RESULT`。
- `ConnectorEventPublisher` 已涵蓋 Connector status、MeterValue、Transaction、queue、off-peak、offline 等多條異動路徑，並在 commit 後重查 authoritative snapshot。
- Server 已使用 `ConcurrentWebSocketSessionDecorator` 保護並行推送。
### 現有限制
- 現有 Admin WebSocket 是「一個 Connector 一條連線」，不適合 Dashboard 同時顯示 20／30／100 個 Connector。
- 若 Dashboard 為每個 Connector 建立 socket，會造成 N 張 ticket、N 條連線、N 組重連與 browser／server 資源放大。
- 現有 WebSocket contract 是 FE 手寫型別，不在 OpenAPI 內；Dashboard event contract 必須另外版本化與測試。
- Charge Point ONLINE／heartbeat、billing、usage trend 並非全部都有現成 Dashboard event publisher。
- WebSocket 只是一種 transport，不可取代資料庫 authoritative state，也不可讓斷線後的舊資料看起來仍是即時資料。
## Proposed Architecture
採用：
> 一次 REST bootstrap + 一條案場層級 Dashboard WebSocket + REST drill-down
### Initial load
1. `GET /api/dashboard/overview` 載入完整初始畫面、歷史資料與非即時資料；Frontend 不傳 `buildingId`。
2. Backend 解析目前 EMS Branch 中唯一一個 enabled Building，並以其 `buildingId`、名稱與 timezone 作為整份 Dashboard scope。
3. 以具 Dashboard function 的 REST endpoint 取得一次性、短效 ticket；ticket 綁定使用者與 Backend 已解析的 `buildingId`。
4. 建立一條 `/ws/admin/dashboard?ticket=...`，WebSocket URL 不接受 Frontend 任意指定案場。
5. WebSocket 先回 `DASHBOARD_LIVE_SNAPSHOT`，作為即時區塊的 authoritative initial state。
6. 後續只推送有變化的「區塊 replacement event」，不傳 raw database rows，也不要求 FE 自行重算全站統計。
V1 的「所有案場共用」是同一套功能部署至各 EMS Branch；不是在單一 Branch 內提供案場切換或跨案場彙總。所有 response／event 仍必須帶 Backend 解析後的 `buildingId`，供 scope 驗證與避免資料混用。
## 區塊與資料通道矩陣
| Dashboard 區塊 | 資訊 | Primary channel | 更新策略 |
|---|---|---|---|
| Header | Backend 解析的目前案場名稱、buildingId、timezone、選擇的圖表 range | REST | 首次載入；案場名稱為唯讀識別，不提供切換 |
| Header | REST `generatedAt`、WS connection state、最後 event 時間、各 source freshness | Hybrid | REST 提供 source snapshot；FE 顯示 socket 狀態；WS 推 freshness transition |
| 需留意事項（#1463 ATT-DEC-001／002） | Connector FAULTED、CP OFFLINE、current Live Load STALE／PARTIAL／ERROR、既有 Queue BLOCKED | WebSocket + REST bootstrap | authoritative state commit／freshness transition 後重算 category summary；歷史 Live Load gap 與 WAITING duration 不產生告警 |
| 需留意事項（#1463／#1460） | 四步驟結算流程的既有未完成／異常狀態 | REST | 15 分鐘 refetch 或手動刷新；V1 不新增 billing WS 或 overdue 判斷 |
| KPI Row | CP ONLINE／OFFLINE／UNKNOWN、enabled／disabled counts（#1486 KPI-DEC-002） | WebSocket + REST bootstrap | persisted connection state transition 後以 NETWORK_HEALTH_UPDATED replacement；Heartbeat 未改變狀態時不推送 |
| KPI Row | Connector 可服務摘要、Connector status、「充電進行中」active sessions、「等待供電」distinct ELIGIBLE、Queue blocked、目前總功率 | WebSocket + REST bootstrap | Connector／transaction／parent CP／Queue transition 後更新 CONNECTOR_OVERVIEW_UPDATED；次要功率沿用 LIVE_LOAD_UPDATED |
| KPI Row | 「今日已完成充電量」與已完成 Sessions（重用 #1461 today daily bucket） | REST | 首載、每 5 分鐘 refetch、手動刷新；V1 不新增 Usage／Energy WebSocket |
| Live Load（#1462 LOAD-DEC-001／004） | currentPowerKw、LIVE／TODAY／SEVEN_DAYS open buckets、跨界 finalized bucket、latestMeterAt、freshness／source status；不含推算的案場契約容量、利用率或剩餘容量 | WebSocket + REST bootstrap | MeterValue 事件聚合，最多每 5 秒推一次；不重送完整 series |
| Live Load 歷史 series（#1462 LOAD-DEC-003／004） | LIVE：最近 60 分鐘／1 分鐘 bucket；TODAY：案場當日 00:00 至現在／15 分鐘 bucket；SEVEN_DAYS：含今天 7 個案場日曆日／1 小時 bucket；Y 值為 time-weighted averagePowerKw | REST + WebSocket bucket replacement | REST 提供完整 snapshot；WS 只更新 open／finalized buckets，不重送整段 series |
| Group Capacity | contract capacity、allocated power、reserved slots 等設定 | REST | 首載／手動刷新／低頻刷新 |
| Group Capacity | occupied、available、waiting、blocked、longest wait | WebSocket + REST bootstrap | Transaction／queue／status commit 後更新 |
| Connector Grid | summary、bounded preview、remaining abnormal count | WebSocket + REST bootstrap | Server 統一排序並推送整個 bounded preview replacement |
| Connector Full List | 搜尋、filter、pagination／virtualization | REST | 使用／擴充既有 search API |
| Connector Detail Drawer | 單支 Connector 完整狀態 | 既有單 Connector WebSocket | Drawer 開啟時才建立；關閉即釋放 |
| Usage Trend（#1461 USG-DEC-001～009） | 最近 30 個案場日曆日（含今天）的有效 kWh、valid Sessions、平均每次充電量；固定 30 daily buckets；成功無使用為 0、未知為 null；全段零為 COMPLETE + EMPTY；initial／refresh error、lastSuccessfulAt、STALE；依 building timezone 的交易開始日歸屬；異常 Completed 排除筆數與 PARTIAL status；不含時間使用率 | REST | 首載、5 分鐘 refresh；有 cache 時保留最後成功 snapshot；平均值由 Backend 計算；Sessions 僅 COMPLETED + positive energy；ACTIVE 不估算；跨日不拆分 |
| 結算流程（#1460 BIL-DEC-001／002／003） | periodYear／periodMonth／timezone、Connector 結算、門牌結算、Billing status、Invoice status | REST | 首載、15 分鐘 refresh、手動刷新；唯讀；導覽 route 由 FE 固定 |
## 不適合透過 WebSocket 的資料
- 歷史趨勢整段 series。
- 結算流程沿用 attachment #1110 四步驟面板；透過 REST 提供正式資料與 Backend 決定的最近結算期間，詳見 #1460 BIL-DEC-001／002。
- 完整 Connector inventory、搜尋結果與分頁。
- 案場名稱、時區、Charge Group contract capacity 等低頻設定。
- Export／報表。
- 任何可由 REST 查詢且容許 1–15 分鐘延遲的資料。
理由：這些資料更新頻率低、payload 可能較大，或需要 query parameter／pagination；WebSocket 不會因此提供足夠效益，反而增加事件契約與一致性成本。
## Dashboard WebSocket Event Contract
建議 envelope：
```json
{
"schemaVersion": "1",
"type": "CONNECTOR_OVERVIEW_UPDATED",
"buildingId": 123,
"sequence": 42,
"occurredAt": "2026-08-10T16:00:00+08:00",
"data": {}
}
```
V1 event types：
- `DASHBOARD_LIVE_SNAPSHOT`
- `NETWORK_HEALTH_UPDATED`
- `ALERTS_UPDATED`
- `LIVE_LOAD_UPDATED`
- `CHARGE_GROUP_OVERVIEW_UPDATED`
- `CONNECTOR_OVERVIEW_UPDATED`
- `SOURCE_FRESHNESS_UPDATED`
規則：
- Event 以「區塊 replacement」為主，不讓 FE 由細碎 delta 自行推導 summary／排序。
- 每條連線的 `sequence` 單調遞增；initial live snapshot 必須先於後續 update。
- FE 忽略較舊 sequence；發現 gap、重連或 schemaVersion 不支援時，重新取得 snapshot。
- 所有 event 帶 server `occurredAt`；各資料區塊另帶 source `updatedAt`／freshness。
- Dashboard preview 不回 currentIdTag 等不必要的敏感欄位；詳細資料留在既有權限控制的 detail flow。
- Unknown／null 不可轉成 Available／0。
## Event Trigger 與節流
| Source | Trigger | 建議推送 |
|---|---|---|
| Connector StatusNotification | status commit 後 | 2 秒內更新 Connector／KPI／Alerts |
| Transaction start／stop | transaction commit 後 | 2 秒內更新 Connector／KPI／Group |
| Queue／off-peak／rotation | priority lifecycle commit 後 | 2 秒內更新 Group／Connector／Alerts |
| CP offline watchdog／connection transition | ONLINE／OFFLINE／UNKNOWN transition | 2 秒內更新 Network／Connector／Alerts |
| MeterValue | 有新 power value | coalesce；最多每 5 秒更新 Live Load／受影響 preview |
| Heartbeat | 每次 heartbeat | 不逐次推送；只在 connection／freshness class 改變時推 |
| Usage aggregate | 時間累積 | REST 每 5 分鐘 |
| 結算流程 | 帳務異動／月結後由下一次 REST refresh 反映 | REST 每 15 分鐘或手動刷新；不新增 WS |
實際秒數須以通用協定與服務排程為基礎，並由 A17 起逐步用不同 Connector 規模與 MeterValue 頻率的代表性案場驗證；不得只用單一案場樣本硬編碼。Browser WebSocket 沒有 backpressure，因此不得把每筆 raw MeterValue 原樣 fan-out。
## 斷線、Stale 與降級
- Dashboard 是唯讀頁，可採 capped exponential reconnect；不能只顯示一次錯誤後永久停止更新。
- WS 斷線時保留最後資料，但立即顯示「即時連線中斷」；不可清成 0。
- 超過各 source cutoff 後，該資料標示 STALE，且 stale power 不納入 current total。
- WebSocket 無法恢復時，允許以 REST 30／60 秒 polling 降級，但 UI 必須明示「定時更新模式」，不可冒充即時。
- 手動 Refresh 同時重新取得 REST overview 與新的 WebSocket ticket。
- Browser 回到 visible state 時檢查 connection 與 freshness；必要時重新 bootstrap。
- Server 重啟、sequence gap 或 event parse failure 均以重新 snapshot 恢復，不嘗試從 client cache 猜測遺失事件。
## Backend 開發影響
- 新增 Dashboard-level ticket、handler、session registry、broadcaster、live snapshot service 與 typed WS DTO。
- 新增 current-building scope resolver：必須確認 Branch 內 enabled Building 恰好一筆；所有 Dashboard query 共用同一 scope，Overview 回傳 `buildingId`、名稱與 timezone。零筆或多筆時回明確 configuration error，禁止任選第一筆、跨案場加總或回傳零值 Dashboard。
- 沿用現有一次性 ticket、post-commit authoritative re-query 與 concurrent send 保護模式。
- 新增 CP lifecycle／freshness transition 的 Dashboard event hook；不可假設 Connector publisher 能涵蓋所有 CP online/heartbeat 異動。
- Connector／queue／transaction／MeterValue event 需做 section invalidation 與 debounce/coalesce。
- Billing／usage 不新增 WebSocket publisher。
- 沿用既有 SS3A `dashboard` function：將 Overview 與 ticket API mapping 至此 function，不新增 `dashboard_view` 或其他 role／function；Dashboard WebSocket 只接受由已授權 ticket endpoint 核發的有效 ticket。部署 migration 必須冪等確認 `administrator`、`power_user`、`association`、`dealer` 四個 role 的既有 mapping，並在 Branch 重啟後使授權快取生效。
- 若未來採多 instance，in-memory session registry 與 sequence 需另行評估跨 instance fan-out；V1 不應默認單 instance 永遠成立。
## Frontend 開發影響
- 新增一個 Dashboard socket hook，不可對 preview 每張卡呼叫 `useAdminConnectorSocket()`。
- Frontend 不送 `buildingId`、不顯示案場 selector；Header／Sidebar 只顯示 Overview 回傳的目前案場名稱。若 Backend 無法解析唯一 enabled Building，顯示整頁設定錯誤並隱藏營運數字，不得顯示 0 或 fixture。
- Dashboard menu／route 依 Backend 回傳的既有 `dashboard` function 顯示；Frontend 隱藏不是安全邊界，Overview 與 ticket API 仍須由 Backend 回 403。四個允許 role 看到同一份唯讀 Dashboard，不因角色分出不同資料版本。
- 將 REST overview 與 WS live section 分層保存；以 server event replacement 更新對應 section。
- Header 明確區分：REST 最後成功更新、WS 連線狀態、source freshness。
- kWh／Sessions 切換使用同一個固定 30 日 REST range，不重建不相關的 live socket；V1 不送出 7／90 日或自訂 range 查詢。
- Usage daily buckets 必須直接使用 Backend 回傳的完整 30 日序列；Frontend 不自行補缺日為 0。明確的 0 顯示零值，null 顯示資料缺口並標示 PARTIAL。
- 時間使用率已依 #1461 USG-DEC-005 移除；第三個摘要依 USG-DEC-006 改為 Backend REST 回傳的 averageEnergyPerSessionKWh，不新增 WebSocket event。
- Connector detail drawer 開啟後才沿用既有單 Connector socket。
- 結算面板的 /bill/list 與 /invoice/list 導覽由 FE 使用既有 route；Backend REST／WS contract 不回傳 URL。
- Usage initial error 不得顯示 0；refresh error 時可保留同 building 最後成功 snapshot，但必須顯示 lastSuccessfulAt／refresh error，並依 Backend freshness deadline 轉為 STALE。
- Production API／WS error 不得 fallback 到 fixture。
- WebSocket contract 為手寫型別時，需有 fixture／parser／unknown event／schema version tests。
## Acceptance Criteria
- [ ] Dashboard 不論有 1、2、30 或 100 個 Connector，本體只建立 1 條案場級 WebSocket。
- [ ] `GET /api/dashboard/overview` 與 Dashboard ticket request 不需要 Frontend 傳 `buildingId`；Backend 自動解析唯一 enabled Building，且 Overview 回傳其 `buildingId`、名稱與 timezone。
- [ ] Dashboard 不提供案場 selector 或跨案場彙總；同一份程式可部署至所有 EMS Branch，A17 不得被硬編碼。
- [ ] Branch 內 enabled Building 為零筆或多筆時顯示明確設定錯誤，所有營運區塊不載入，且未知資料不得顯示為 0。
- [ ] 每個 Dashboard WS event 的 `buildingId` 必須等於 ticket 綁定的 Backend-resolved Building；不符時 FE 拒絕套用並重新 bootstrap。
- [ ] 只有開啟 Connector detail drawer 時，才可額外建立 1 條既有 connector-bound WebSocket。
- [ ] 初始 REST 與 initial WS snapshot 不會發生舊事件覆蓋新資料。
- [ ] Connector status／transaction／queue／CP connection transition 在 commit 後於目標延遲內反映。
- [ ] Connector 可服務摘要由 Backend 以 enabled CP scope、parent CP ONLINE 與固定 Connector status allowlist 計算；REST 與 CONNECTOR_OVERVIEW_UPDATED 結果一致，FE 不由 preview 重算。
- [ ] 「充電進行中」依每個 Connector 的 canonical current ACTIVE transaction 計算，舊孤兒 ACTIVE 不得重複計數；Session count 與 Live Load power 可獨立更新／顯示狀態。
- [ ] 「等待供電」只計 Queue ELIGIBLE 的 distinct Connector；NOT_PLUGGED 另列且與主數字互斥，BLOCKED 不納入並沿用需留意事項。
- [ ] MeterValue 不逐筆無限制推送；Live Load 有明確 coalesce 上限。
- [ ] REST Live Load series 明確回傳 range、building timezone、bucket 起訖、averagePowerKw、bucketState 與 dataStatus；OPEN／FINALIZED、COMPLETE／PARTIAL／ERROR、0／null 不得混用。
- [ ] LIVE／TODAY／SEVEN_DAYS 分別符合 60 分鐘／1 分鐘、當日／15 分鐘、7 個案場日曆日／1 小時定義。
- [ ] LIVE_LOAD_UPDATED 不重送完整 series；一般 event 更新三種 open buckets，跨界 event 正確提供 finalized／new open bucket。
- [ ] FE 只以 buildingId + rangeCode + bucketStartAt replacement 合併；gap／重連後以 REST snapshot 恢復。
- [ ] Usage trend、四步驟結算流程、完整 Connector list 不走 WS；結算流程依 #1460 使用 REST。
- [ ] 「今日已完成充電量」與已完成次數直接等於 #1461 today daily bucket；不使用 ACTIVE MeterValue 暫估、不另建 WebSocket 或第二套聚合。
- [ ] WS 斷線時立即顯示非即時狀態，資料不清 0；超過 cutoff 正確標示 STALE。
- [ ] KPI source 的 COMPLETE／PARTIAL／ERROR、value／null、freshness 與 updatedAt 在 REST／WS 語意一致；source failure 只影響相依 Card，refresh error 可保留同 building 成功快取但不得假裝最新。
- [ ] WS 無法恢復時可進入明示的 REST polling fallback。
- [ ] sequence gap／server restart／schemaVersion 不支援會重新 snapshot。
- [ ] `administrator`、`power_user`、`association`、`dealer` 透過既有 `dashboard` function 可取得 Overview 與 ticket；不新增另一個 Dashboard role／function。
- [ ] 僅有 `adm_user`、`member`、`hq` 或 `engineer` role、但未取得 `dashboard` function 的使用者，直接呼叫 Overview／ticket API 必須得到 403；沒有有效 ticket 的 WebSocket handshake 不得建立 Dashboard session。
- [ ] Ticket 一次性、短效且綁定使用者與 Backend-resolved building scope；Frontend menu 隱藏不能取代 Backend 授權。
- [ ] Dashboard event 不洩漏 currentIdTag、JWT、ticket 或不必要個資。
- [ ] 「需留意事項」每個 category 都能追溯到既有 authoritative state；不以自由文字、等待時間或前端比較推導新異常。
- [ ] categoryCount 等於 affectedCount > 0 的 categories 數量；每類 affectedCount 依穩定 entity／entry／step identifier distinct，FE 不重新加總或跨類去重。
- [ ] categories array 只含全部非零 allowlisted categories 並保持固定順序；viewport 只影響換行，不影響資料或 DOM 順序。
- [ ] 摘要只有導覽作用，不觸發 Reset、Start／Stop、Queue／Rotation、帳務或工單 mutation。
- [ ] 390／768／1024／1440 px 的 loading、connected、reconnecting、fallback、stale state 均可辨識。
- [ ] A17 壓測驗證同時在線管理者、MeterValue 頻率、payload size、server buffer 與 browser CPU／memory。
## 待確認事項
- [x] V1 由 Backend 自動解析 Branch 唯一 enabled Building：Frontend 的 REST／ticket request 與 WebSocket URL 不傳 `buildingId`；Overview response、ticket binding 與 event envelope 明確帶 Backend-resolved `buildingId`（DEC-029，取代 DEC-001）。
- [x] V1 沿用既有 `dashboard` function 與既有四個 role mapping：`administrator`、`power_user`、`association`、`dealer`；不新增 role／function（DEC-030）。
- [x] Dashboard WebSocket 採 capped exponential backoff：1、2、4、8、16、30 秒，30 秒封頂並加入 ±20% jitter。
- [x] WebSocket 中斷期間啟用每 60 秒完整 Overview REST polling fallback。
- [x] Live Load 採 Backend server-side 5 秒 coalescing，最多每 5 秒推送一次完整負載摘要。
- [x] V1 Live Load 不以 Charge Group contract capacity 加總推算案場契約容量、利用率或剩餘容量（DEC-012／#1462）。
- [x] Live Load 三種 X 軸與 bucket、Y 軸 time-weighted averagePowerKw 依 DEC-013／#1462 LOAD-DEC-003。
- [x] REST 提供完整 series，WebSocket 只更新 currentPowerKw、三種 open buckets 與跨界 finalized bucket（DEC-014／#1462 LOAD-DEC-004）。
- [x] bucketState 與 dataStatus 分離；unknown 充電功率採 strict null + PARTIAL，不插值或部分合計（DEC-015／#1462 LOAD-DEC-005）。
- [x] 使用者可見名稱為「需留意事項」，只彙整既有明確狀態，不新增 Queue mismatch／SLA、scheduler-health、容量告警或作業 workflow（DEC-016／#1463 ATT-DEC-001）。
- [x] 只有 current Live Load STALE／PARTIAL／ERROR 建立一個需留意 category；歷史 bucket gap 只在圖表顯示（DEC-017／#1463 ATT-DEC-002）。
- [x] 需留意頁首使用非零 categoryCount；各類使用 distinct affectedCount，不跨 category 推導 root cause（DEC-018／#1463 ATT-DEC-003）。
- [x] 全部非零 categories 依固定 allowlist 順序輸出並 responsive 換行，不做 Top N／Drawer／分頁（DEC-019／#1463 ATT-DEC-004）。
- [x] Operational Event propagation SLO：正常運作條件下，從 Backend DB commit 成功至 FE 收到並套用更新的 P95 ≤ 2 秒。
- [x] REST overview 保留完整 live data，作為 bootstrap、手動刷新與 WebSocket fallback。
- [x] V1 不支援同一 Branch deployment scope 多個 `ems_branch` replicas；Dashboard WebSocket fan-out 以單一 active instance 為部署前提。
- [x] V1 延用現有 raw WebSocket，以版本化 envelope 定義 contract，不引入 STOMP／message broker sub-protocol。
- [x] 所有案場的 source stale cutoff 由 Backend 依資料來源集中定義與判定，並把 freshness／updatedAt／cutoff metadata 回傳給 FE；不得硬編碼 A17 或由 FE 自行設定。
- [x] Charge Point 連線 KPI 直接使用指定 building 的 persisted OCPP connection state；REST bootstrap 後只在狀態 transition 時以 NETWORK_HEALTH_UPDATED replacement，不逐筆推送 Heartbeat（DEC-023／#1486 KPI-DEC-002）。
- [x] Connector 可服務 KPI 要求 parent CP ONLINE 且 Connector status 位於固定 allowlist；REST bootstrap 後由 CONNECTOR_OVERVIEW_UPDATED replacement 更新，unknown 不得視為可服務（DEC-024／#1486 KPI-DEC-003）。
- [x] 「充電進行中」以 canonical ACTIVE transaction 計數；CONNECTOR_OVERVIEW_UPDATED 更新 Session count，LIVE_LOAD_UPDATED 獨立更新卡片次要功率（DEC-025／#1486 KPI-DEC-004）。
- [x] 「等待供電」只計 Queue ELIGIBLE 的 distinct Connector；NOT_PLUGGED 為互斥的次要數量、BLOCKED 留在需留意事項，並以 CONNECTOR_OVERVIEW_UPDATED replacement 更新（DEC-026／#1486 KPI-DEC-005）。
- [x] 「今日已完成充電量」重用 #1461 today daily bucket，只走 REST 5 分鐘 refresh；ACTIVE 不估算且不新增 Usage／Energy WebSocket（DEC-027／#1486 KPI-DEC-006）。
- [x] 六張 KPI 共用 Loading／0／null／PARTIAL／Initial Error／Refresh Error／STALE 契約；source failure 隔離、同 building cache 保留與 REST／WS status 一致（DEC-028／#1486 KPI-DEC-007）。
- [x] 允許受控的 per-building stale cutoff override；生效順序為 building override > 全系統各資料來源預設值，並由 Backend 管理權限與稽核。
## 建議預設決策
- V1 延續現有 raw WebSocket，不為單一 Dashboard 引入 STOMP。
- REST overview 保留所有區塊，作為 bootstrap 與降級來源。
- 一條 Dashboard socket 推送 bounded section replacement。
- Live Load 5 秒 coalesce；其他 operational event propagation P95 ≤ 2 秒。
- read-only Dashboard 可持續 capped exponential reconnect，並在失敗時切 60 秒 REST polling。
- stale cutoff 由 Backend 統一定義並在 response/event 回傳，不由 FE 各自硬編碼。
## 已確認決策
### DEC-001：V1 明確使用 buildingId 作為 Dashboard scope（已由 DEC-029 取代）
**狀態：已取代（2026-09-04，Ken）**
> 歷史決議曾要求 Frontend 在 Overview、ticket 與 WebSocket URL 指定 `buildingId`，並提供切換 building 的 lifecycle。Ken 後續確認 EMS Branch 的部署模型為「每個 Branch 自動顯示其唯一 enabled Building」，因此上述 client-selected scope 不再適用；目前規範以 DEC-029 為準。
- 保留不變的原則：Dashboard 資料必須以 `buildingId` 隔離，response／event 必須可驗證 scope，且不得跨案場混用。
- 已取消的要求：Frontend 傳入或切換 `buildingId`、URL 帶 buildingId，以及為 V1 實作案場 selector。
### DEC-002：Overview API 保留完整即時摘要
**狀態：已確認（2026-09-01，Ken）**
- `GET /api/dashboard/overview` 必須回傳 Dashboard 所需的完整初始資料，包含即時摘要與非即時區塊。
- 即時摘要至少包含 Network Health、operational alerts、Connector summary／bounded preview、active sessions、queue／group runtime 與 current live load。
- WebSocket 的用途是接續 REST snapshot 提供後續增量更新，不是 Dashboard 唯一資料來源。
- 首次畫面可先以 REST 完成顯示；取得 WebSocket initial snapshot 後，再依 server sequence／occurredAt 套用較新的資料，避免舊資料覆蓋新資料。
- 手動 Refresh 必須重新取得完整 overview，並重新建立對應 building 的 WebSocket session。
- WebSocket 無法建立或持續中斷時，Overview API 可作為 polling fallback；UI 必須明示目前為定時更新模式。
- REST 與 WebSocket 必須共用相同的 Dashboard aggregation／presentation service 或明確共用規則，避免同一 KPI 在兩種通道出現不同公式。
- Partial／stale／null 語意在 REST 與 WebSocket 必須一致；未知值不得轉為 0 或 AVAILABLE。
### DEC-003：WebSocket 指數退避重連與 60 秒 REST 降級
**狀態：已確認（2026-09-01，Ken）**
- WebSocket 非預期中斷後採 capped exponential backoff，重連等待序列為 1、2、4、8、16、30 秒，後續每次最多等待 30 秒。
- 每次等待加入 ±20% jitter，避免多個 Dashboard client 在服務恢復時同時重連。
- WebSocket 一中斷，FE 必須立即顯示「即時連線中斷／定時更新模式」，不可繼續把最後 snapshot 標示為即時。
- 中斷期間保留最後成功資料，不清為 0；各資料仍依 Backend 提供的 cutoff 判斷 freshness／stale。
- WebSocket 中斷期間每 60 秒重新呼叫完整 `GET /api/dashboard/overview`。
- REST polling 與 WebSocket 背景重連可以同時進行，但目前 Branch 同時間只允許一個 reconnect loop 與一個 polling timer。
- Browser network 由 offline 轉 online，或頁面由 hidden 回到 visible 時，可立即嘗試一次重連，不必等待目前 backoff timer。
- WebSocket 恢復後，必須先收到／取得新的 `DASHBOARD_LIVE_SNAPSHOT`，確認 buildingId 與版本正確，再停止 REST polling；僅 socket open 不視為資料已恢復即時。
- 使用者離開 Dashboard 時，必須取消目前 Branch 的 socket、backoff timer 與 polling timer。
- 預期的授權錯誤（401／403）、不支援的 schemaVersion，或 Backend 無法解析唯一 enabled Building 時不做無限重試，應停止並顯示可診斷錯誤。
### DEC-004：Live Load 採 5 秒 Server-side Coalescing
**狀態：已確認（2026-09-02，Ken）**
- MeterValue 更新由 Backend 在 server side 合併；Dashboard browser 不接收每筆 raw MeterValue。
- 同一 building 的 Live Load 最多每 5 秒推送一次，5 秒窗內的多筆讀值合併為一份重新計算後的完整 `LIVE_LOAD_UPDATED` section replacement。
- Payload 至少帶 `buildingId`、`occurredAt`、`sequence`、`currentPowerKw`、`latestMeterAt` 與 freshness／source status。依 DEC-012／#1462，不回傳由 Charge Group contract capacity 加總推算的案場 `contractCapacityKw`、`utilizationPercent` 或 `remainingCapacityKw`。
- 聚合只納入 Backend 判定為未 stale 的 enabled Connector 最新有效 Power value；未知值保留 `null`，不得以 0 代替。
- 沒有新 MeterValue 或沒有實際 Live Load／freshness 變化時，不需固定每 5 秒推送。
- Connector FAULTED、Charge Point connection transition、Transaction start／stop、Queue／off-peak／rotation 等 operational event 使用獨立更新路徑，不得為等待 Live Load 5 秒窗口而延遲。
- Coalescing key 必須包含 `buildingId`，不可把不同案場的讀值合併。
- V1 預設窗口為 5 秒，實作時由 Backend configuration 管理；若 A17 壓測證明需調整，必須保留同樣的事件語意並更新需求決策。
- 驗收需量測 A17 的 MeterValue 頻率、單一窗口合併數、WebSocket payload size、server buffer 與 browser CPU／memory。
### DEC-005：Operational Event 更新延遲 SLO 採 P95 ≤ 2 秒
**狀態：已確認（2026-09-02，Ken）**
- 正式名稱使用 **Operational Event propagation SLO**，不使用帶有對外合約／賠償語意的 SLA。
- 正常運作條件下，Operational Event 更新延遲目標為 **P95 ≤ 2 秒**。
- 計時起點：產生 Dashboard 狀態變化的 Backend database transaction 成功 commit。
- 計時終點：Frontend 收到、通過 `schemaVersion`／`buildingId`／`sequence` 驗證，並將 replacement event 套用至 Dashboard state。
- 適用事件：
- Connector runtime status transition。
- Charge Point OCPP connection transition。
- Transaction start／stop lifecycle。
- Queue／off-peak／rotation lifecycle 與 blocked transition。
- 由上述事件衍生的 operational alerts、KPI、Group／Connector overview 更新。
- 不包含設備實際狀態發生至 Branch 收到 OCPP／Modbus 訊息前的延遲；該區段屬設備與通訊層。
- 不適用於 Live Load；Live Load 依 DEC-004 採 5 秒 server-side coalescing。
- 不適用於 Usage Trend、四步驟結算流程與完整搜尋；這些區塊依 REST refresh 規則。
- WebSocket 中斷時不套用 2 秒 SLO，改依 DEC-003 的 60 秒 REST polling fallback，並明示非即時模式。
- 驗收需記錄至少 event type、buildingId、commit timestamp、event occurredAt、client received／applied timestamp、latency 與成功／失敗結果。
- 報告至少提供 sample size、P50、P95、P99、max 與未達標比例；P95 達標不代表可忽略遺失、亂序或無法解析的事件。
- 測試時的 client/server clock 必須同步；若 client timestamp 不可靠，需以可重現的 server-side correlation 或測試 harness 量測。
### DEC-006：Stale Cutoff 由 Backend 集中管理，適用所有案場
**狀態：已確認（2026-09-02，Ken）**
- Dashboard 是所有案場共用功能；A17 只是第一個驗證／導入案場，不是功能範圍、資料模型或 freshness 規則的唯一依據。
- Backend 依資料來源分別定義 stale cutoff，例如 OCPP Heartbeat、Connector Status、MeterValue 與其他 operational source；不同來源不得共用一個沒有語意的固定秒數。
- REST overview 與 WebSocket event 必須使用同一個 Backend freshness policy，回傳 `updatedAt`、`freshness` 與可解釋的 cutoff metadata。
- FE 只依 Backend 回傳的 stable code 呈現 FRESH／STALE／ERROR／NOT_CONFIGURED 等狀態，不自行硬編碼秒數或以 browser clock 另建一套規則。
- Cutoff 的預設值應由協定行為、服務排程、裝置正常回報週期及營運容忍度共同決定，不能從單一 A17 當下樣本直接推廣到所有案場。
- A17 Phase 0 的用途是驗證通用預設值、查詢效能與 UI 行為，若結果不合理應修正通用 policy 或提出有治理的 override 機制，不得在程式碼加入 `if buildingId == A17` 類型特例。
- 每次 bootstrap 都必須套用 Backend-resolved Building 的 freshness policy，並以 response／event `buildingId` 驗證 scope；V1 不提供案場切換。
- 是否允許 per-building override、由哪個設定來源管理及 fallback precedence，另列待確認事項，不在本決策中預先假定。
### DEC-007：允許受控的 Per-building Stale Cutoff Override
**狀態：已確認（2026-09-02，Ken）**
- 每一種資料來源都有全系統預設 stale cutoff；沒有 building override 時必須使用該 source default。
- 允許個別 building 因設備正常回報週期、網路特性或營運需求設定 override。
- 生效 precedence 固定為：`building + source override` > `global source default`。
- Override 必須以 source 為粒度，例如 Heartbeat 與 MeterValue 分開設定；不得用單一 building 秒數覆蓋所有資料來源。
- 設定、驗證與 effective policy 解析均由 Backend 負責；FE 不保存、不推導也不硬編碼案場特例。
- REST overview 與 WebSocket event 必須回傳相同的 effective cutoff／freshness 結果，並可識別目前使用 global default 或 building override。
- 只有具對應管理權限的角色可以修改 override；Dashboard 的一般唯讀權限不可修改設定。
- 每次新增、修改或移除 override 都必須保存 buildingId、source、before／after、operator、changedAt 與變更理由，以供稽核。
- Backend 必須拒絕 null 語意不明、負數、零或超出合理上下限的設定；移除 override 應使用明確操作並恢復 global default。
- 不允許以程式碼條件、環境變數命名或 FE 判斷建立 A17／特定案場的隱性例外。
- Global default、允許範圍、儲存位置及管理 API／UI 的實作細節，在進入開發前由 Backend plan 明確列出並經確認。
### DEC-008：V1 延用 Raw WebSocket，不引入 STOMP
**狀態：已確認（2026-09-02，Ken）**
- V1 延續現有 Spring `WebSocketHandler`／JSON message 模式，不啟用 STOMP sub-protocol、topic subscription 或 STOMP broker relay。
- Dashboard browser 對一個 `buildingId` 建立一條 socket；授權仍使用短效、一次性、admin identity + building-bound ticket。
- 所有訊息使用統一、版本化 envelope，至少包含 `schemaVersion`、`type`、`buildingId`、`sequence`、`occurredAt` 與 `data`。
- Event type 採明確 allowlist；FE 對未知 type 應安全忽略並記錄可診斷資訊，不可把未知 payload 套入既有區塊。
- FE 不支援 `schemaVersion` 時應停止套用資料、顯示版本不相容並重新 bootstrap／要求更新，不得陷入無限重連。
- 每次新 socket session 先送 `DASHBOARD_LIVE_SNAPSHOT`，再送後續 replacement events；sequence 的作用域與重置規則必須在 contract tests 固定。
- Server 端沿用 synchronized／decorated session send、send time limit 與 buffer size limit，並對慢速 client 執行可觀測的關閉與恢復。
- Raw WebSocket contract 雖不由 OpenAPI 自動產生，Backend DTO、FE TypeScript type、fixture、parser 與 contract test 必須同步維護。
- 若未來出現多種動態 topic、client-side subscribe／unsubscribe、跨服務 broker routing 或大規模 fan-out，再另立決策評估 STOMP；不得在 V1 預先增加未使用的協定層。
### DEC-009：V1 限定單一 Ems Branch Instance
**狀態：已確認（2026-09-03，Ken）**
- Dashboard 功能仍適用所有案場；本決策只限制同一個 Branch deployment scope 的執行拓撲，不代表只支援單一案場。
- V1 假設同一 deployment scope 只有一個 active `ems_branch` application instance 負責 REST、Dashboard WebSocket session 與 event fan-out。
- V1 可沿用 in-memory ticket store、session registry、coalescing timer 與 per-session sequence；不實作跨 instance session discovery 或 distributed sequence。
- 部署文件與 release checklist 必須明確標示 `ems_branch replicas = 1`；在未完成 multi-instance 設計前，不得把同一 scope 水平擴充至兩個以上 replicas。
- Sticky session 不能單獨解決問題：業務事件可能在沒有該 browser session 的另一 instance commit；因此不得把 load-balancer affinity 宣稱為完整跨 instance fan-out。
- 若誤以多 instance 部署，REST overview 仍可能可用，但 WebSocket 可能漏推、重複或亂序；系統不得將這種拓撲標示為受支援。
- 未來若需要 HA／水平擴充，必須另案設計 shared event fan-out、跨 instance authorization／ticket、session routing、sequence／deduplication、coalescing ownership 與 failure recovery；可評估既有 RabbitMQ，但不能直接假設現有 Connector exchange 已滿足 Dashboard contract。
- Multi-instance 支援完成前，部署變更的驗收需確認實際 replica count，並測試 restart 後依 DEC-003 重新 bootstrap／恢復 socket。
### DEC-010：Dashboard Queue 資料通道維持唯讀
**狀態：已確認（2026-09-03，Ken）**
- REST／WebSocket 可傳送既有 queue source、status、priority、statusReason、waitingSince／waiting duration，供 Dashboard 顯示。
- `BLOCKED` 沿用既有 Backend 狀態進入 Needs Attention；WAITING／ELIGIBLE 不新增 timeout 或 severity 判定。
- 本 Dashboard 不新增 Queue SLA、threshold／override、Admin 設定、Rotation scheduler-health 或對應 persistence。
- Dashboard publisher／aggregation 不得寫回 queue、改變 priority／slot、觸發 rotation dispatch 或送出 OCPP command。
- 此決策只收斂 Dashboard V1 scope，不影響既有 queue／off-peak／rotation lifecycle event 繼續觸發畫面更新。
### DEC-011：結算流程期間由 Backend 回傳
**狀態：已確認（2026-09-03，Ken）**
- 四步驟結算流程維持 REST-only；WebSocket 不推送月份或帳務狀態。
- Overview response 依 buildingId 回傳最近結算資料期間的 periodYear、periodMonth 與 timezone。
- Frontend 只格式化 Backend 回傳的期間，不用 browser 日曆或「目前月份減一」自行推算。
- 最新期間即使為 pending／partial／error，仍回傳並照實呈現，不得自動退回前一期掩蓋異常。
- 新一期資料尚未建立時顯示資料庫中最近存在的期間；完全沒有資料時回明確 Empty 語意與 null 期間。
- REST initial load、15 分鐘 refresh 與手動 refresh 使用同一套 period selection 規則。
- 此決策只定義 Dashboard read model，不更動既有結算排程、重算或 Billing／Invoice lifecycle。
- 詳細 UI 與驗收例子見 #1460 BIL-DEC-002。
### DEC-012：Live Load 不推算案場層級契約容量
**狀態：已確認（2026-09-03，Ken）**
- 本決策修正 DEC-004 原 payload 對案場 contractCapacityKw／utilizationPercent 的假設；DEC-004 的 5 秒 server-side coalescing、currentPowerKw 與 freshness 規則維持不變。
- Live Load 的 REST／WebSocket read model 只需回傳案場 currentPowerKw、latestMeterAt 與 freshness／source status，不回傳由 SUM(group.contractCapacity) 產生的案場 contractCapacityKw、utilizationPercent 或 remainingCapacityKw。
- 原因是現有 contractCapacity 屬 Charge Group 排程容量；系統沒有 authoritative building-level 契約容量或足以判斷群組容量是否可加總的上游電力拓撲。
- Group Capacity 仍透過 REST 回傳各群組自己的 contract capacity／allocated power，並透過 Hybrid channel 更新 occupied／available／waiting／blocked 等既有 runtime 資訊。
- FE 不得從群組陣列自行相加或計算案場利用率／餘裕；未知 currentPowerKw 仍依 null／freshness 規則呈現。
- V1 不新增 building capacity 設定、拓撲、告警門檻或管理 UI，也不修改 SlotCalculator、queue、rotation、OCPP 或其他作業邏輯。
- 詳細 UI、Backend 與驗收規則見 #1462 LOAD-DEC-001。
### DEC-013：Live Load Series 軸線與 Bucket Contract
**狀態：已確認（2026-09-03，Ken）**
- 保留 LIVE、TODAY、SEVEN_DAYS 三種 read-only 檢視。
- LIVE：rangeStartAt = generatedAt 往前 60 分鐘，bucketDurationSeconds = 60，最多 60 點。
- TODAY：依 building timezone 從案場當日 00:00 至 generatedAt，bucketDurationSeconds = 900，最多 96 點。
- SEVEN_DAYS：依 building timezone 從今天前第 6 個日曆日 00:00 至 generatedAt，bucketDurationSeconds = 3600，最多 168 點；語意是含今天的 7 個日曆日，不是 rolling 168 hours。
- Y 軸固定為「充電功率（kW）」；每個 point 為該 bucket 的 time-weighted averagePowerKw，不是 kWh、契約容量、容量利用率或 bucket peak。
- Backend 必須先依 Connector 最新有效 Power.Active.Import 重建 site power timeline，再做 time-weighted average；不可直接對不同 Connector、不同回報頻率的 raw MeterValue rows 加總或算術平均。
- REST series 至少回傳 rangeCode、rangeStartAt、rangeEndAt、timezone、bucketDurationSeconds 與 points；每個 point 至少包含 bucketStartAt、bucketEndAt、averagePowerKw、bucketState、dataStatus。
- 最後一個尚未結束的 bucket 標示 bucketState = OPEN；已結束者為 FINALIZED。成功確認為零時 averagePowerKw = 0、dataStatus = COMPLETE；資料不可確認時為 null 並搭配 dataStatus = PARTIAL／ERROR，不得補零。
- Y 軸從 0 起算，上限依有效 series 自動取整；不使用群組容量合計作為固定上限或容量線。
- FE 可依 viewport 減少可見 tick label 避免重疊，但不得刪除／合併 Backend points 或改變 range；tooltip 顯示完整 bucket 起訖與區間平均功率。
- currentPowerKw 大數字是 generatedAt 的目前功率，與最後一個進行中 bucket 的區間平均值可以不同，UI 必須分別標示。
- 歷史 series 由 REST 提供，WebSocket 依 DEC-004 提供 currentPowerKw；open／finalized bucket 更新通道已由 DEC-014 確認。
- 本決策只增加唯讀查詢、DTO 與圖表呈現，不改變 MeterValue 採集間隔、設備控制或充電作業。
### DEC-014：REST Series Snapshot + WebSocket Bucket Replacement
**狀態：已確認（2026-09-03，Ken）**
- REST 是完整 Live Load series 的 authoritative snapshot；用於 bootstrap、range 切換、手動 refresh、WebSocket reconnect 與 sequence gap recovery。
- LIVE_LOAD_UPDATED 一般 event 只包含 currentPowerKw 與 LIVE／TODAY／SEVEN_DAYS 三個 open bucket replacements，不包含完整歷史陣列。
- 三種 open buckets 一併推送，server 不追蹤 client 目前選取的 range，也不新增 range subscription protocol。
- 每個 bucket 以 rangeCode + bucketStartAt 識別，並帶 bucketEndAt、averagePowerKw、bucketState、dataStatus 與 freshness metadata。
- 跨越 1 分鐘／15 分鐘／1 小時邊界時，event 必須傳送剛完成的 finalized bucket；同一 event 可同時傳送下一個 open bucket。
- FE 只做 replacement：相同 key 取代，新的 key 加入並依 DEC-013 裁切視窗；不得用 currentPowerKw 或 event arrival time 自行積分／重算平均。
- currentPowerKw 是目前 snapshot；open bucket averagePowerKw 是從 bucketStartAt 至 event occurredAt 的區間平均，兩者可以不同。
- sequence gap、重連、schemaVersion 不支援或 buildingId 不符時，FE 不補猜 bucket，重新取得 REST snapshot。
- WebSocket 斷線期間沿用 DEC-003 的 60 秒 REST polling fallback；恢復後先取得 authoritative snapshot 再繼續 replacements。
- 沿用 DEC-004 的 5 秒 server-side coalescing，沒有資料／freshness 變化時不固定空推送。
- 本決策不改變 MeterValue 採集、charging、queue、rotation 或 OCPP 作業。
### DEC-015：Bucket Time State 與 Data Quality 分離
**狀態：已確認（2026-09-03，Ken）**
- 不使用同一欄位混合表示「時間未結束」與「資料不完整」；正式分成 bucketState 與 dataStatus。
- bucketState enum 為 OPEN／FINALIZED，只描述時間區間是否結束。
- dataStatus enum 為 COMPLETE／PARTIAL／ERROR，只描述資料品質；OPEN + COMPLETE 與 FINALIZED + PARTIAL 都是合法組合。
- 重建 site power timeline 時，fresh fact 明確顯示 Connector 未充電則貢獻 0；正在充電則必須有仍在 effective freshness cutoff 內且可正規化的有效 Power.Active.Import。
- 最新有效 Power 只可在 cutoff 內沿用；超過 cutoff、缺值、負值、unit 無法解析、充電／交易狀態不明或可能 offline charging 時，對應時間片段為 unknown。
- bucket 只要存在 unknown 充電功率，就回 averagePowerKw = null、dataStatus = PARTIAL；不得回已知部分合計、coverage percentage、插值或預測。
- 查詢／計算失敗回 null + ERROR；完整且整段零負載回 0 + COMPLETE。
- OPEN bucket 只計算已經過時間，不對未來補 0；finalized replacement 重新套用同一品質規則。
- FE 對 PARTIAL／ERROR 畫缺口並提供文字狀態，不以前值補點、不跨缺口連線，也不只靠顏色。
- 詳細規則與 fixture／驗收需求見 #1462 LOAD-DEC-005。
- 本決策不改變 MeterValue 採集或任何 charging lifecycle。
### DEC-016：「需留意事項」只彙整既有明確狀態
**狀態：已確認（2026-09-03，Ken）**
- 使用者可見名稱由 NEEDS ATTENTION 改為「需留意事項」，主標題使用「目前有 N 類項目需要留意」。
- 本區塊是 read-only category summary／deep link，不是待辦、派工、通知升級或自動修復 workflow。
- V1 只納入既有 authoritative state：CP OFFLINE、Connector FAULTED、Queue BLOCKED、明確 source STALE／PARTIAL／ERROR，以及 #1460 四步驟結算流程既有未完成／異常狀態。
- 不新增 Queue mismatch、waiting timeout／SLA、rotation scheduler-health、案場容量／餘裕告警、預測規則或跨案場排名。
- Operational categories 可隨既有 post-commit event／freshness transition 更新；結算類別維持 REST refresh，不新增 billing WebSocket。
- Backend 回傳 stable category code、count、必要 display parameters 與 target identifier；FE 不用中文自由文字判斷類型。
- 摘要項目只能導覽至既有管理頁或 Dashboard 區塊，不執行任何業務 mutation。
- categoryCount／類別內 distinct 依 DEC-018 確認；current Live Load 納入範圍依 DEC-017 確認；固定順序／顯示全部非零類別／responsive layout 依 DEC-019 確認。Empty State 依 DEC-020／#1463 ATT-DEC-005、Partial／Error 依 DEC-021／ATT-DEC-006、deep link 依 DEC-022／ATT-DEC-007 確認。
- 詳細 UI、Backend 與驗收規則見 #1463 ATT-DEC-001。
### DEC-017：只有 Current Live Load 品質異常進入需留意事項
**狀態：已確認（2026-09-03，Ken）**
- current Live Load freshness = STALE 或 dataStatus = PARTIAL／ERROR 時，產生一個「即時負載資料不完整」category。
- 判定直接使用 Backend current source state；不新增 FE timer、bucket gap count 或其他推測門檻。
- currentPowerKw = 0 + COMPLETE 與 bucketState = OPEN + dataStatus = COMPLETE 都是正常狀態，不產生 category。
- finalized 歷史 bucket 的 null + PARTIAL／ERROR 只留在 series／tooltip，不產生 category、不增加摘要總數。
- REST overview 與需留意事項 WebSocket replacement 使用同一判定；current source 恢復 FRESH／COMPLETE 後移除 category。
- category deep link 只定位至 Dashboard Live Load 區塊，不建立新頁面或任何 mutation。
- 最終 fixture 必須分別驗證 current quality failure 會出現摘要，以及 historical-only gap 不會出現摘要。
- 詳細規則見 #1463 ATT-DEC-002 與 #1462 LOAD-DEC-006。
### DEC-018：Attention Category Count 與 Affected Count 分離
**狀態：已確認（2026-09-03，Ken）**
- 頁首 categoryCount = affectedCount > 0 的 category 數量，文案為「目前有 N 類項目需要留意」。
- 每個 category 另回 affectedCount；categoryCount 不等於 affectedCount 加總，也不代表設備、事件或根因總數。
- CP／Connector／Queue／Settlement 分別依自身穩定 ID 或 step code 做 category 內 distinct；即時負載資料不完整 category 存在時 affectedCount = 1。
- affectedCount = 0 的 category 不出現在 categories array，也不計入 categoryCount。
- 不跨 category 去重，不建立 CP／Connector／source status 的共同根因推導或 suppression。
- REST overview 與 WebSocket replacement 使用同一份 Backend-produced categoryCount／affectedCount；FE 不重新計算。
- 摘要來源為 PARTIAL／ERROR 時不得用 categoryCount = 0 冒充無異常；其整體顯示規則依 #1463 後續決策。
- 詳細 UI／驗收例子見 #1463 ATT-DEC-003。
### DEC-019：Attention Allowlist 固定順序並顯示全部非零類別
**狀態：已確認（2026-09-03，Ken）**
- V1 categories 固定順序為 CHARGE_POINT_OFFLINE、CONNECTOR_FAULTED、LIVE_LOAD_DATA_UNRELIABLE、QUEUE_BLOCKED、SETTLEMENT_INCOMPLETE_OR_ERROR。
- REST overview 與 WebSocket replacement 都回傳全部 affectedCount > 0 的 allowlisted categories，並保持固定相對順序。
- affectedCount = 0 的 category 省略；不依 affectedCount、時間或顏色動態重排。
- 不做 Top N、顯示上限、查看全部、Drawer、展開、分頁或使用者自訂排序。
- FE 依 response／contract 順序 render；DOM、keyboard focus 與視覺順序一致，不用 CSS order 改變語意。
- Desktop 使用 auto-fit grid；Tablet 兩欄；390 px Mobile 單欄。換行不得改變 categoryCount／affectedCount 或建立水平捲軸。
- Unknown category code 採安全 fallback 並記錄診斷，不映射成既有類別。
- 新增 category 必須另行更新 allowlist、順序、來源、文案與 contract tests。
- 詳細 UI 與驗收規則見 #1463 ATT-DEC-004。
### DEC-020：Attention Empty State 必須由 Backend 的完整結果明確判定
**狀態：已確認（2026-09-04，Ken）**
- attention aggregate 明確回傳 dataStatus、categoryCount、categories 與 updatedAt；若時間沿用 overview generatedAt，OpenAPI contract 必須寫清楚。
- 只有 dataStatus = COMPLETE、categoryCount = 0、categories = [] 三項同時成立，FE 才顯示「目前沒有需留意事項」。
- HTTP 200、categories 欄位缺漏、空白畫面或 request 尚未完成，不等同於已確認沒有異常。
- Empty State 保留區塊但縮為一列中性偏綠狀態，不產生五張零值卡片，也不沿用紅色警示樣式。
- WebSocket replacement 可使 UI 在非零 categories 與 COMPLETE Empty State 間切換；FE 只 render Backend 結果，不掃描其他區塊重新計算。
- dataStatus = PARTIAL／ERROR 時不得以 categoryCount = 0 宣稱正常；呈現與 count contract 依 DEC-021／#1463 ATT-DEC-006。
- 本決策只定義 read-only presentation state，不新增告警引擎、通知、待辦或任何作業 mutation。
- 詳細 UI、mock 與驗收條件見 #1463 ATT-DEC-005。
### DEC-021：Attention Aggregate 的 PARTIAL 與 ERROR 呈現契約
**狀態：已確認（2026-09-04，Ken）**
- dataStatus = PARTIAL 表示部分來源有可用結果；categories 保留目前已確認的非零類別，categoryCount 等於該陣列數量。
- PARTIAL 且 categoryCount > 0 時，FE 顯示「已確認 N 類」與黃色「數量可能不完整」提示；categoryCount = 0 時只顯示部分資料無法確認，不得顯示正常 Empty State。
- aggregate PARTIAL 是 presentation completeness，不新增第六個 category、不計入 categoryCount；特定 current Live Load 品質異常仍依 DEC-017 使用既有 LIVE_LOAD_DATA_UNRELIABLE category。
- dataStatus = ERROR 時 categoryCount = null、categories = []，FE 顯示「需留意事項暫時無法取得」，不得用 0 或綠色狀態冒充正常。
- Backend 視情況提供 updatedAt、errorAt 與 lastSuccessfulAt；FE 不用本機時間或 HTTP 200 推測資料狀態。
- Error State 不新增區塊專用 Retry，沿用頁面既有 refresh；網路重連與 REST fallback 仍沿用既有 DEC-003／005。
- REST snapshot／WebSocket replacement 回復有效狀態後，以 Backend 最新結果取代 Partial／Error。
- 本決策只定義 read-only response 與 presentation，不修改 OCPP、Queue、結算或其他作業邏輯。
- 詳細 UI、mock 與驗收規則見 #1463 ATT-DEC-006。
### DEC-022：Attention Deep Link 由 Frontend 固定映射，不接受任意 URL
**狀態：已確認（2026-09-04，Ken）**
- 五個 V1 category code 固定對應：CHARGE_POINT_OFFLINE → /cp/list、CONNECTOR_FAULTED → /connector/list、LIVE_LOAD_DATA_UNRELIABLE → #load、QUEUE_BLOCKED → #connectors、SETTLEMENT_INCOMPLETE_OR_ERROR → #billing。
- Backend 回 stable category code 與必要 identifiers，不回任意 URL；Frontend 以 allowlist 映射 route／anchor。
- affectedCount 不改變目的地；V1 不新增 filter query parameter、category detail API 或 Queue 專用頁。
- Unknown code 不建立未知 link，且不得 fallback 至任一既有類別。
- 同頁 anchor 後移動 keyboard focus 至目標 section；跨頁使用既有 router 與 route permission。
- 整張 card 是單一可存取 link，顯示可見操作文案；不得巢狀互動元件。
- Deep link 只做導覽，不執行 mutation，也不改變 OCPP、Queue、結算或其他作業邏輯。
- 詳細 mapping、mock 與驗收規則見 #1463 ATT-DEC-007。
### DEC-023：Charge Point 連線 KPI 沿用 Persisted Connection State
**狀態：已確認（2026-09-04，Ken）**
- KPI scope 為指定 building 下 `enabled = true` 的 Charge Point；ONLINE 為分子，enabled total 為分母，OFFLINE／UNKNOWN 分別回傳。
- Disabled CP 不進入分子／分母；可另回 disabledCount 供 FE 說明，但不建立離線事件。
- 唯一判準是既有 persisted `ocppConnectionStatus`；Dashboard 不比較 lastHeartbeat、不新增 cutoff，也不修改 WebSocket／BootNotification／Heartbeat watchdog 的既有狀態維護。
- REST overview 回傳完整 connection summary；狀態 transition commit 後，案場級 socket 以 `NETWORK_HEALTH_UPDATED` replacement 更新整組數字。
- 沒有造成 ONLINE／OFFLINE／UNKNOWN transition 的一般 Heartbeat 不逐次推送。
- CP runtime status 與 OCPP connection state 保持分離；ONLINE + FAULTED 等組合不得被簡化或覆寫。
- FE 固定將 card 導向 `/cp/list`；event／REST payload 不回傳任意 navigation URL。
- 本決策只新增 read-only aggregation 與 presentation event，不改變設備連線、離線判定或充電作業。
- 詳細 DTO、UI 與驗收規則見 #1486 KPI-DEC-002。
### DEC-024：Connector 可服務摘要由 Backend 統一計算
**狀態：已確認（2026-09-04，Ken）**
- 分母為指定 building 下、enabled Charge Point 所屬的所有 Connector；disabled CP 下的 Connector 排除。
- 分子同時要求 parent CP persisted OCPP connection = ONLINE，且 Connector status 位於 AVAILABLE、PREPARING、ENQUEUED、CHARGING、SUSPENDED_EV、SUSPENDED_EVSE、FINISHING、RESERVED allowlist。
- FAULTED、UNAVAILABLE、null／unknown status，或 parent CP OFFLINE／UNKNOWN 均不算可服務。
- Backend 回 serviceable／total／nonServiceable／faulted counts；REST overview 與 WebSocket 共用同一 read model，FE 不從 bounded preview 重算。
- Connector status 或 parent CP connection transition commit 後，以 `CONNECTOR_OVERVIEW_UPDATED` replacement 更新整組 summary；不為每個 Connector 建 socket。
- 未造成狀態 transition 的 Heartbeat 不因此推送 Connector summary。
- 整張卡由 FE 固定導向 `/connector/list`；payload 不回任意 URL。
- 本決策只定義唯讀分類與顯示，不新增 health scheduler、timeout、狀態修正或充電操作。
- 詳細 UI、DTO 與驗收規則見 #1486 KPI-DEC-003。
### DEC-025：「充電進行中」使用 Canonical ACTIVE Transaction
**狀態：已確認（2026-09-04，Ken）**
- 使用者可見名稱固定為「充電進行中」。
- Backend 對指定 building 的每個 Connector 解析最多一筆 canonical current transaction：currentTransactionId 指向 ACTIVE 優先；否則只有最新 transaction 為 ACTIVE 才計入。
- 較舊孤兒 ACTIVE row 不計；raw CHARGING、currentPowerKw、Queue 或尚未建立 StartTransaction 的 operation 不可單獨增加 Session count。
- ACTIVE Session 即使處於 suspended／finishing，或 parent CP offline／disabled，仍顯示至 transaction 正式結束，避免隱藏待 reconciliation 資料。
- REST overview 提供完整 activeSessionCount；transaction start／stop commit 後以 `CONNECTOR_OVERVIEW_UPDATED` replacement 更新。
- 卡片次要 `currentPowerKw` 直接讀 Live Load current snapshot，並由 `LIVE_LOAD_UPDATED` 獨立更新；功率 unknown 不把已知 Session count 清為 0。
- FE 固定將卡片導向 `/connector/list`；payload 不回傳任意 URL。
- 本決策只定義唯讀統計，不新增 timeout、自動結束、交易補寫或其他 charging mutation。
- 詳細 DTO、UI 與驗收規則見 #1486 KPI-DEC-004。
### DEC-026：「等待供電」使用 Queue ELIGIBLE 的 Distinct Connector
**狀態：已確認（2026-09-04，Ken）**
- Backend 以指定 building 範圍內 `e_connector_priority.charge_status = ELIGIBLE` 的 `COUNT(DISTINCT connector_id)` 回傳 waitingForPowerCount；同一 Connector 的 MANUAL／OFF_PEAK 多筆 Queue row 不重複計數。
- NOT_PLUGGED 不代表目前有供電需求，不納入主數字；notPluggedCount 只計有 NOT_PLUGGED、且沒有任何 ELIGIBLE row 的 distinct Connector，確保「另有」與主數字互斥。
- BLOCKED 不納入等待供電，沿用「需留意事項」既有 Queue BLOCKED category；CHARGING、PAUSED、FINISHED、null／unknown 也不納入。
- REST overview 提供完整 aggregate；Queue state commit 且 aggregate 改變後，以 `CONNECTOR_OVERVIEW_UPDATED` replacement 更新 waitingForPowerCount／notPluggedCount。
- FE 不從 bounded preview、runtime、等待秒數、slot 或 scheduler 狀態重算，整張卡固定導向 `/connector/list`。
- 本決策只定義唯讀統計與傳輸，不新增 Queue timeout、SLA、scheduler、狀態轉換或修正行為。
- 詳細 DTO、UI 與驗收規則見 #1486 KPI-DEC-005。
### DEC-027：「今日已完成充電量」重用 Usage Today Bucket
**狀態：已確認（2026-09-04，Ken）**
- 使用者可見名稱固定為「今日已完成充電量」，避免「今日累積電量」被誤解為包含 ACTIVE transaction 的即時估算。
- 主數字與次要完成次數分別讀取 #1461 Usage response 中 `date = rangeEndDate` daily bucket 的 validEnergyKWh／sessionCount；同一 response 不建立第二個獨立計算結果。
- eligibility、building timezone、transaction startTimestamp 日期歸屬、跨日不拆分與 0／null／PARTIAL／ERROR／cache／STALE 規則全部沿用 #1461 USG-DEC-001～009。
- ACTIVE 不以 MeterValue 差值估算；完成並取得最終 energy_consumed 後，才於下一次成功 REST refresh 納入。
- 取得方式為 REST 首載、每 5 分鐘 refetch 與手動刷新；V1 不新增 Usage／Energy WebSocket event。
- FE 固定將 Card 導向同頁 `#usage`，移除昨日同時段比較，不自行重算或寫入任何交易資料。
- 詳細 UI 與驗收規則見 #1486 KPI-DEC-006。
### DEC-028：KPI 狀態採 Source-isolated Presentation Contract
**狀態：已確認（2026-09-04，Ken）**
- 每個 KPI 依賴的 source／section 提供 value（可為 null）、dataStatus、freshness 與 updatedAt；需要顯示快取來源時提供或保留 lastSuccessfulAt。
- COMPLETE 的 0 是有效值；null 是未知。Backend 子查詢失敗不得回 0，Frontend 也不得從 preview 或其他資料重算。
- PARTIAL 有 Backend 認定可安全顯示的 value 時保留並標示可能不完整；沒有安全值時回 null／顯示 `—`。
- Initial ERROR 沒有快取時顯示 `—`；refresh error 可保留目前 Backend-resolved building 的最後成功 snapshot，但必須顯示更新失敗與 lastSuccessfulAt，且不得跨 Branch／building 沿用。
- STALE 可保留最後成功值，但需顯示資料已過期且不能使用正常／綠色語意；無可用值時顯示 `—`。
- 一個 source 失敗只影響相依 Card，Overview 其他成功 sections 繼續顯示。REST snapshot 與 WebSocket replacement 的 value／null／status／freshness 語意必須一致。
- WebSocket 中斷不把值清成 0；freshness 仍由 DEC-006／007 的 Backend effective cutoff policy 決定。
- 這是唯讀 presentation contract，不新增 event type、資料修正或業務 mutation；完整 UI 與驗收規則見 #1486 KPI-DEC-007。
### DEC-029：V1 自動使用 Branch 唯一 Enabled Building，不提供案場切換
**狀態：已確認（2026-09-04，Ken）**
- Dashboard 適用所有案場，意思是同一套功能部署到每個 EMS Branch；V1 不在單一 Branch 內做跨案場總覽或 site switcher。A17 只作第一個資料與效能驗證基準，任何層都不得 hardcode A17。
- `GET /api/dashboard/overview` 不接受 Frontend `buildingId`；Backend 必須解析目前 Branch 中唯一一筆 enabled Building，並回傳 `buildingId`、案場名稱與 timezone。所有 KPI、圖表、Connector、Queue 與帳務 query 都使用同一個 resolved scope。
- Dashboard ticket request 與 WebSocket URL 也不接受 Frontend 選案場。Backend 將 ticket 綁定 admin identity 與 resolved `buildingId`；每個 event envelope 仍帶該 `buildingId`，Frontend 必須驗證一致後才套用。
- enabled Building 恰好一筆才可載入 Dashboard。零筆或多筆均視為 configuration error：Backend 不可使用 `LIMIT 1`／任選第一筆、跨 Building 彙總或產生全零 snapshot；Frontend 顯示整頁「案場設定異常」，不顯示營運數字。
- Header／Sidebar 的案場名稱是唯讀識別，不是 selector。若未來要在單一 deployment 支援多 Building，必須另開需求重新定義授權、切換、快取、ticket 與聚合，不屬於 V1。
- 本決策取代 DEC-001 中「Frontend 指定／切換 buildingId」的部分；`buildingId` 作為資料隔離與 event 驗證欄位的原則繼續保留。
### DEC-030：沿用既有 Dashboard Function 與四個既有角色
**狀態：已確認（2026-09-04，Ken）**
- V1 沿用既有 SS3A `dashboard` function，不建立 `dashboard_view`、Dashboard 專用 role 或不同角色版本的 Dashboard。
- 可存取角色固定沿用既有 mapping：`administrator`、`power_user`、`association`、`dealer`。這四個 role 看到同一份唯讀 Dashboard。
- 僅有 `adm_user`、`member`、`hq` 或 `engineer` role 不會自動取得 Dashboard；若同一 member 另有上述任一允許 role，則透過該 role 的 `dashboard` function 取得權限。
- Overview API 與 Dashboard ticket API 必須 mapping 到既有 `dashboard` function。Frontend 依 Backend 回傳的 function 決定 menu／route 是否可見，但安全邊界仍在 Backend：未授權直接呼叫 API 回 403，未持有效 ticket 不得建立 Dashboard WebSocket。
- 不以 Java／Frontend hardcode role name 判斷權限；實際授權由 SS3A role → function → API mapping 決定。部署用冪等 migration 確認四個 role mapping 與新增 API mapping，並於 Branch 重啟後載入最新授權快取。
- 此決策只控制「能否看 Dashboard」，不改變 Dashboard 的 read-only 邊界，也不授予 Remote Start／Stop、Reset、Queue、Rotation、帳務修改或 Engineer command 權限。
## 需求管理狀態
- Parent：#1422
- Related：#1423（Connector 數量彈性顯示規則）、#1462（案場即時負載與群組容量顯示規則）、#1463（需留意事項摘要與顯示規則）
- Requirement status：**本票架構決策已確認，待其他 Dashboard 需求完成後整併**
- Final specification：全部決策完成後整併至 #1422 的 v1.0 最終需求文件
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回