討論 #1423
是由 陳國瑋 於 27 天 前更新
> **Status Summary 五類 Mapping（UI-DEC-015）**：固定依序使用 `NEEDS_ATTENTION`「需留意」、`CHARGING`「充電進行中」、`WAITING`「準備／排隊」、`AVAILABLE`「可用」、`OTHER`「其他狀態」。Backend 依此 precedence 讓每個 Connector 恰好歸一類；`NEEDS_ATTENTION` count 必須等於 `abnormalTotal`。
> **Status Summary 互斥計數（UI-DEC-014）**：每個 Connector 在摘要中恰好歸入一個 Backend authoritative `displayBucket`，所有 bucket count 加總必須等於 `total`；Card／Drawer 仍分層顯示 OCPP connection、Connector runtime 與 Queue 原始狀態。 原始狀態。Bucket code、顯示名稱與 precedence 留待 UI-DEC-015 確認。
> **Connector Preview 單一 Payload（UI-DEC-013）**：Backend 對完整 Connector 集合完成排序與異常分類後，只回傳最多前 8 筆 `items`，並附 `total`、`abnormalTotal`；Frontend 不傳 viewport、不重排或重判異常，只依畫面寬度顯示前 8／6／4 筆並計算純顯示用隱藏數量。REST bootstrap 與 `CONNECTOR_LIVE_BLOCK_UPDATED` 共用同一 contract。
> **一般 REST 更新規則（#1424 DEC-032）**：頁面首次載入可用 Overview bootstrap 顯示 Connector 區塊；WebSocket 接手後，本區只接受 `CONNECTOR_LIVE_BLOCK_UPDATED`。全頁每 5 分鐘及手動 Overview refresh 不得覆寫本區 live state，socket 中斷時也不得形成 REST fallback；手動刷新不重建 socket。
> **傳輸規則更新（#1424 DEC-031）**：Connector 即時狀態仍是 V1 兩個 WebSocket 區塊之一；一個案場只建立一條 Dashboard socket，使用 Backend 排序後的整區 replacement，不建立每張 Card 一條連線。斷線時保留最後 preview 與時間並顯示「已停止更新」，不做 REST fallback、custom backoff 或自動重連。完整清單／搜尋／分頁仍使用 REST。
## 背景
A17 Dashboard 主需求為 #1422。
「Connector 即時狀態」區塊必須適應不同案場規模。案場可能只有 0、1、2 個 Connector，也可能有 20、30 個或更多；若單純把所有 Connector 卡片無上限展開，Dashboard 高度與資訊密度會隨案場規模失控。
本票的 UI-DEC-001～015 UI-DEC-001～014 已完成需求確認；內容尚待全 Dashboard 鎖版後整併至最終 v1.0 需求文件，議題仍維持 New／0%，不代表已進入開發。
## 建議原則
Dashboard 的 Connector 區塊定位為：
> 固定資訊層級的狀態摘要 + 優先項目預覽 + 查看全部
不是完整 Connector inventory。完整搜尋、篩選與大量清單由 Drawer 或 Connector 管理頁處理。
## Confirmed Display Rules
| Connector 總數 | Dashboard 顯示方式 |
|---:|---|
| 0 | Empty state，顯示尚未建立 Connector 與管理頁連結 |
| 1 | 顯示 1 張完整卡片；Desktop 最大寬度約 360px，不拉滿區塊 |
| 2 | 顯示 2 張卡片；Desktop 雙欄、Mobile 單欄，卡片左對齊 |
| 3 - 8 | 全部顯示，使用 responsive card grid |
| 9 - 30 | Backend 固定回排序後前 8 筆；Desktop／Tablet／Mobile 分別顯示前 8／6／4 張，並提供「查看全部 N 個」 |
| 30 以上 | 維持 8／4 張預覽；完整資料進 Drawer 或 Connector 管理頁 |
| 100 以上 | 完整清單視量測結果導入 server pagination／virtualization；Dashboard preview 規則不變 |
## 區塊結構
1. Header
- Connector 即時狀態
- Connector 總數
- 最後更新時間
- freshness／stale
- Refresh
2. Status summary
- 固定順序：`NEEDS_ATTENTION`「需留意」→ `CHARGING`「充電進行中」→ `WAITING`「準備／排隊」→ `AVAILABLE`「可用」→ `OTHER`「其他狀態」
- 每個 Connector 由 Backend 依上述 precedence 為每個 Connector 指定且只指定一個 `displayBucket`；各 bucket count 加總必須等於 Connector `total`
- `NEEDS_ATTENTION` 與 `isAbnormal = true` 使用相同分類，故其 count 必須等於 `abnormalTotal`
- Card／Drawer 仍分別顯示 OCPP connection、Connector runtime、Queue status，不以 `displayBucket` 取代原始狀態
- Bucket code、中文名稱與 precedence 尚待 UI-DEC-015 確認；Faulted、OCPP Offline、Unavailable、Charging、Preparing／Waiting、Available 只是先前候選，尚非最終 mapping
3. Search／Filters
- Dashboard preview block 不顯示搜尋或篩選，維持營運摘要定位
- 僅在「查看全部」responsive Drawer 內固定提供
- 可依 Connector ID、Charge Point ID、車位、Charge Group、status 搜尋／篩選
- 不使用 Connector 總數 9 作為顯示門檻；Drawer 是否可開啟由各 viewport preview limit／查看全部規則決定
4. Preview grid
- Backend payload 最多包含排序後前 8 筆，不依 viewport 改變 contract
- Desktop／Tablet／Mobile 分別顯示前 8／6／4 張
- 卡片不可因數量少而無限制拉寬
5. Footer
- 「查看全部 N 個 Connector」
- 若異常超過預覽上限，顯示「另有 N 個異常 Connector」
## Preview Sorting
**已確認：排序由 Backend 統一計算，依下列層級由高至低排列。**
1. Charge Point OFFLINE 且 Connector 存在 Active Transaction
2. Connector FAULTED
3. Charge Point OFFLINE、資料 STALE、Queue BLOCKED
4. Connector SUSPENDED_EVSE、UNAVAILABLE
5. Connector SUSPENDED_EV
6. Connector CHARGING
7. Connector PREPARING／Waiting
8. Connector AVAILABLE
規則：
- 同一層級先依異常／狀態持續時間由久至新排列，最後以 Connector ID 作 deterministic tie-breaker。
- 所有異常項目優先進入 preview。
- 異常不足 preview limit 時，再以 Charging、Preparing／Waiting、Available 補滿。
- 異常超過 limit 時，Footer 必須顯示剩餘異常數量。
- OCPP connection、Connector runtime、queue status 必須分層顯示，不得合併為單一 status。
- Unknown／資料不足不得歸入 Available；由 Backend 以保守且可解釋的 priority reason 處理。
- Backend 回傳 stable priority reason／severity code，FE 不依中文 label 重算 ranking。
## Card Minimum Content
- Connector ID／車位
- Charge Point connection badge
- Connector runtime status
- 目前功率；未知為 `null`／「無資料」，不可顯示為 0
- Active session；若排隊則顯示既有 queue source、status、priority、statusReason 與 waiting duration
- last updated／stale
- 點擊開啟 detail drawer
## Responsive
### Desktop >= 1240px
- 卡片寬度約 240 - 320px
- 自動換欄、左對齊
- 最多顯示 8 張 preview
### Tablet 640 - 1239px
- 2 - 3 欄
- Filter 可收合
- 固定顯示 6 張 preview；寬版 3 欄 × 2 列，窄版 2 欄 × 3 列
### Mobile < 640px
- 單欄
- 顯示前 4 張 preview
- 「查看全部」進全螢幕 Drawer／頁面
- 不使用頁面級水平捲軸
## Full List 建議
優先方案：
- Desktop：大型右側 Drawer，約 70 - 80vw
- Mobile：全螢幕
- 提供搜尋、status、Charge Group filters 與排序；採單一 responsive list，不提供 Grid／Table 切換
- 可進一步 deep link 至既有 Connector 管理頁
Dashboard V1 避免在 block 內放固定高度的 nested scrollbar。若最後採用 scroll container，必須可由鍵盤 focus 與捲動。
## API Implication
Overview API 建議只回 summary 與 bounded preview：
```json
{
"connectorSummary": {
"total": 30,
"buckets": [
{ "code": "NEEDS_ATTENTION", "count": 10 },
{ "code": "CHARGING", "count": 6 },
{ "code": "WAITING", "count": 3 },
{ "code": "AVAILABLE", "count": 9 },
{ "code": "OTHER", "count": 2 } "faulted": 2,
] "offline": 1,
"charging": 6,
"waiting": 3,
"available": 18
},
"connectorPreview": {
"maxItems": 8,
"total": 30,
"abnormalTotal": 10,
"items": [
{
"connectorId": "B2-04",
"isAbnormal": true,
"severity": "ERROR",
"priorityReason": "CONNECTOR_FAULTED",
"displayBucket": "NEEDS_ATTENTION" "FAULTED"
}
]
}
}
```
- 查看全部：使用／擴充既有 `POST /api/connector/search`
- 點擊單卡：`GET /api/connector/info/{connectorId}`
- Overview 不內嵌所有 Connector 完整 detail
- Preview sorting、`isAbnormal`、`severity`、`priorityReason`、`total` 與 `abnormalTotal` 由 Backend 統一，避免 FE、REST bootstrap、WebSocket 與其他 client 規則漂移
- Frontend 不傳 viewport／preview limit；單一 Top-8 response 同時支援 Desktop／Tablet／Mobile
- `connectorSummary.buckets` 使用 `connectorSummary` 的欄位名稱目前仍是示意；正式 bucket codes／labels／precedence 待 UI-DEC-015 五個 stable codes 與固定 precedence；Backend 不回 raw status 動態 key，Frontend 不自行合併類別
- `NEEDS_ATTENTION` count 必須等於 `connectorPreview.abnormalTotal`；每個 item 的 `displayBucket = NEEDS_ATTENTION` 與 `isAbnormal = true` 必須一致 確認，但任何版本都必須互斥、完整且加總等於 `total`
## Acceptance Criteria
- [ ] 0、1、2、8、9、30、100 個 Connector fixture 均不破版
- [ ] 1 個 Connector 卡片不被拉滿整個區塊
- [ ] 30 個 Connector 不會使 Dashboard block 無限制增高
- [ ] Faulted／Offline／Stale／Blocked 永遠優先於 Available
- [ ] 異常超過 preview limit 時可看到剩餘異常數量
- [ ] 每個 Connector 恰好有一個 `displayBucket`；Status summary 無重複、無遺漏，各 bucket count 加總恰好等於 `total`
- [ ] Card／Drawer 仍可同時看見 OCPP connection、Connector runtime 與 Queue 原始狀態，不會被 `displayBucket` 覆蓋
- [ ] 五類 code、中文名稱與顯示順序固定；`NEEDS_ATTENTION` count = `abnormalTotal`，Unknown 不會落入 AVAILABLE
- [ ] NOT_PLUGGED 不會落入 WAITING，與「等待供電」KPI 的既有定義一致
- [ ] 390／768／1024／1440 px 無頁面級水平捲軸
- [ ] Dashboard preview 不顯示 Search／Filters；完整清單 Drawer 固定提供且可操作
- [ ] Keyboard 可操作卡片、filter、Drawer 與 scrollable content
- [ ] Unknown status 與 `null` 數值不會 fallback 為 Available／0
- [ ] Dashboard preview 與完整 Connector list 的資料規則一致
- [ ] REST bootstrap 與 `CONNECTOR_LIVE_BLOCK_UPDATED` 都只回同一份 Top-8 payload，不存在 Desktop／Tablet／Mobile 三種 response
- [ ] FE 只對 `items` 做前 8／6／4 筆顯示截取；`hiddenCount` 與 `hiddenAbnormalCount` 的結果在各 breakpoint 正確
## 待確認事項
- [x] Desktop（≥ 1240px）preview limit 確定為 8 張。
- [x] Mobile（< 640px）採單欄，preview limit 確定為 4 張。
- [x] Tablet（640–1239px）preview limit 固定為 6 張；寬版 3 欄 × 2 列，窄版 2 欄 × 3 列。
- [x] 「查看全部」採 responsive Drawer，並提供既有 Connector 管理頁 deep link；不新增功能重複的 Dashboard 獨立清單頁。
- [x] 取消依 Connector 數量顯示搜尋／篩選的門檻；Dashboard preview 不顯示，完整清單 Drawer 內固定提供。
- [x] Preview priority sorting 由 Backend 統一負責；FE 依 API／WebSocket items 順序呈現，不重建 ranking。
- [x] Queue 區塊只顯示既有 `MANUAL`／`OFF_PEAK` source、status、priority、statusReason、waitingSince／waiting duration；不從等待時間推導新的業務狀態。
- [x] V1 不新增 Queue SLA、等待逾時、threshold、Building／Charge Group override、Admin 設定頁或 Rotation scheduler-health 規則。
- [x] `ChargingRequestSource` 維持 `MANUAL`／`OFF_PEAK`；`ROTATION` 僅為既有 dispatch mode，不新增 enum 或 Dashboard 作業規則。
- [x] V1 不提供 Grid／Table view toggle；Dashboard preview 固定 Cards，完整清單 Drawer 採單一 responsive list，不保存顯示模式偏好。
- [x] Connector preview 採單一 Top-8 payload：Backend 排序／分類並回 `total`、`abnormalTotal`；FE 僅依 viewport 顯示 8／6／4 筆及計算隱藏數量。
- [x] Status summary 採互斥 `displayBucket`：每個 Connector 恰好歸一類、bucket counts 加總等於 total；Card／Drawer 保留所有分層原始狀態。
- [x] Bucket 固定為 NEEDS_ATTENTION／CHARGING／WAITING／AVAILABLE／OTHER，依此順序判定與顯示；NOT_PLUGGED 歸 OTHER、Unknown 歸 NEEDS_ATTENTION。
## 已確認決策
### UI-DEC-001：Desktop Preview Limit 為 8 張
**狀態：已確認（2026-09-03，Ken）**
- Desktop viewport `>= 1240px` 時，Connector Dashboard block 最多顯示 8 張 preview cards。
- Connector 總數 1–8 時全部顯示；總數 9 以上時只顯示 Backend 統一排序後的前 8 張。
- Preview 依既定 severity／operational priority 排序，不得單純依 Connector ID 截取前 8 張。
- 異常項目超過 8 張時，preview 仍維持 8 張上限，Footer 顯示「另有 N 個異常 Connector」及「查看全部 N 個 Connector」。
- Connector 數量少於一列容量時，卡片維持既定寬度並左對齊，不可為填滿區塊而無限制拉寬。
- Desktop 上限只控制 Dashboard preview 高度，不限制完整 Connector list／Drawer 的資料筆數。
- 0、1、2、8、9、30、100 個 Connector fixture 均須納入視覺與互動驗收。
### UI-DEC-002：Mobile Preview Limit 為 4 張
**狀態：已確認（2026-09-03，Ken）**
- Mobile viewport `< 640px` 時，Connector preview 使用單欄 cards，最多顯示 4 張。
- Connector 總數 1–4 時全部顯示；總數 5 以上時只顯示 Backend 統一排序後的前 4 張。
- 異常項目超過 4 張時，preview 仍維持 4 張上限，Footer 必須顯示剩餘異常數及「查看全部 N 個 Connector」。
- 「查看全部」在 Mobile 開啟全螢幕清單／Drawer，不使用狹窄側邊 Drawer，也不產生頁面級水平捲軸。
- Preview cards、剩餘異常提示及查看全部按鈕都必須支援鍵盤操作與可辨識的 focus state。
- Mobile preview limit 只限制 Dashboard 首頁高度，不限制完整清單搜尋、filter、pagination／virtualization 的資料筆數。
- 390px viewport 必須納入 0、1、2、4、5、30、100 個 Connector fixture 驗收。
### UI-DEC-003：Tablet Preview Limit 為 6 張
**狀態：已確認（2026-09-03，Ken）**
- Tablet viewport `640–1239px` 時，Connector Dashboard block 最多顯示 6 張 preview cards。
- 版面空間允許時使用 3 欄 × 2 列；較窄時使用 2 欄 × 3 列，避免卡片內容被過度壓縮。
- Connector 總數 1–6 時全部顯示；總數 7 以上時只顯示 Backend 統一排序後的前 6 張。
- 異常項目超過 6 張時，preview 維持 6 張上限，Footer 顯示剩餘異常數及「查看全部 N 個 Connector」。
- 欄數由 responsive layout 依可用容器寬度決定，不以裝置 user-agent 判斷；preview 數量上限維持 6。
- 卡片寬度不足以呈現 minimum content 時必須降為較少欄數，不得截斷 Connector ID、status 或 stale indicator 等關鍵資訊。
- 768px、1024px viewport 必須納入 0、1、2、6、7、30、100 個 Connector fixture 驗收。
### UI-DEC-004：「查看全部」採 Responsive Drawer
**狀態：已確認（2026-09-03，Ken）**
- Dashboard 的「查看全部 N 個 Connector」在目前頁面開啟 responsive Drawer，保留 Dashboard 上下文。
- Desktop 使用右側 Drawer，目標寬度約 `75vw`，同時設定合理 `min-width`／`max-width`，避免超寬螢幕內容過度延展。
- Tablet 與 Mobile 使用全螢幕 Drawer／Sheet，避免狹窄側欄壓縮表格、filter 與操作區。
- Drawer 內提供 Connector ID／Charge Point ID／車位搜尋，以及 status、Charge Group 等篩選；實際顯示規則另案逐項確認。
- Drawer 內另提供 deep link 至既有 Connector 管理頁，以支援完整管理作業與可分享 URL。
- V1 不新增另一個與既有 Connector 管理頁功能重疊的 Dashboard full-list route。
- Drawer 的完整資料必須走 REST search API 與 server-side pagination；不得透過 Dashboard WebSocket 傳送全部 Connector detail。
- 開啟 Drawer 時保留 Dashboard 的 buildingId；Backend 仍須驗證該 building scope，不能只依 FE filter。
- 關閉 Drawer 後，keyboard focus 必須回到原「查看全部」按鈕；支援 Escape 關閉、focus trap、可辨識標題與 loading／empty／error states。
- Drawer 內點選 Connector 可再開啟詳細內容或導向既有 detail page，但不得同時建立無上限的 per-Connector WebSocket connections。
- Drawer 是否保存 search／filter／page 至 URL query，需在 FE implementation plan 中明確定義；至少同一輪開關不得無故重設使用者條件。
### UI-DEC-005：搜尋與篩選只存在於完整清單 Drawer
**狀態：已確認（2026-09-03，Ken）**
- Dashboard Connector preview block 不顯示 search input 或 filters，維持「狀態摘要 + 優先項目預覽 + 查看全部」的資訊層級。
- 取消「Connector 總數 9 個以上才顯示搜尋／篩選」的固定門檻；Desktop、Tablet、Mobile 的 preview limit 不同，不能共用總數 9 判斷。
- 使用者開啟「查看全部」responsive Drawer 後，Drawer 內固定提供搜尋與篩選能力。
- 搜尋至少支援 Connector ID、Charge Point ID 與車位；篩選至少支援 status 與 Charge Group。
- Search／filter 條件必須送至 REST search API 由 Server 執行，不能只篩選目前已載入頁面或 Dashboard preview items。
- Filter 結果、total、pagination 與 empty state 必須使用同一查詢條件，避免顯示筆數與內容不一致。
- Drawer 初次開啟使用預設 priority sorting；使用者套用搜尋／篩選後仍保留 deterministic secondary sort。
- 切換 building 時清除不相容的 search／filter state，並重新查詢新 building；不得混用舊 building 結果。
- Preview block 的 status summary chips 可作為進入 Drawer 的篩選捷徑，但不得直接在 preview block 原地重排／隱藏卡片；是否在 V1 提供此捷徑可於 FE plan 決定。
### UI-DEC-006：Preview Priority Sorting 由 Backend 負責
**狀態：已確認（2026-09-03，Ken）**
- Backend 是 Connector preview priority ranking 與 abnormal classification 的唯一 owner，負責跨 status layer 計算、排序並截取最多前 8 筆。
- REST Overview bootstrap 與 Dashboard WebSocket `CONNECTOR_LIVE_BLOCK_UPDATED` 必須共用相同 ranking service／policy 與 payload contract，回傳順序不得因 transport 不同而改變。
- Backend response 固定回 `total`、`abnormalTotal`，每個 item 回 Backend 判定的 `isAbnormal`、stable `priorityReason`／severity code；FE 不從中文 label、runtime 或 queue 欄位重判。
- FE 依 Backend `items` 原順序，Desktop／Tablet／Mobile 分別顯示前 8／6／4 筆；這是純 UI 截取，不是重新排序或商業分類。
- FE 可計算 `hiddenCount = max(0, total - visibleCount)`；`hiddenAbnormalCount = max(0, abnormalTotal - visibleAbnormalCount)`，其中 `visibleAbnormalCount` 只計 visible slice 內 Backend 已標記 `isAbnormal = true` 的項目。
- Backend 不接受 viewport／device／preview limit 參數，也不回傳三套 payload；同一份最多 8 筆 response 支援所有 breakpoint。
- 相同 priority 的 tie-breaker 必須 deterministic，建議依狀態持續時間／最近異動時間，再以 Connector ID 作最後穩定排序；精確規則與狀態 precedence 另行確認。
- 完整清單 Drawer 的預設排序應與 preview policy 一致；使用者主動選擇其他排序時，只影響 Drawer，不回寫或改變 Dashboard preview policy。
- 未知 status／null source 不得被當成 AVAILABLE；Backend 應以保守、可觀測的 unknown ranking 處理。
### UI-DEC-007：Connector Preview Priority Hierarchy
**狀態：已確認（2026-09-03，Ken）**
Backend 依以下層級由高至低排序：
1. Charge Point OFFLINE 且 Connector 有 Active Transaction。
2. Connector FAULTED。
3. Charge Point OFFLINE、資料 STALE、Queue BLOCKED。
4. SUSPENDED_EVSE、UNAVAILABLE。
5. SUSPENDED_EV。
6. CHARGING。
7. PREPARING／Waiting。
8. AVAILABLE。
補充規則：
- 同層級以異常／狀態持續時間由久至新排序，再以 Connector ID 作最後 tie-breaker。
- 一個 Connector 同時符合多項條件時採最高層級，並保留其他 reason 供 UI 顯示，不得產生重複 card。
- OFFLINE + Active Transaction 必須高於一般 OFFLINE，提醒可能仍在離線充電或待 reconciliation。
- SUSPENDED_EVSE 與 SUSPENDED_EV 必須分開；前者為設備端暫停，優先級高於車端暫停。
- Unknown／資料不足不得 fallback 為 AVAILABLE。
- Backend 必須回傳 stable priority reason／severity code；FE 不自行推導權重。
- Queue `BLOCKED` 沿用既有 Backend 狀態進入異常層級；WAITING／ELIGIBLE 的持續時間只供顯示，不因時間長短升級為異常。
- Ranking、summary counts、Top-8 preview、`isAbnormal` 與 `abnormalTotal` 使用同一份 snapshot／policy。
### UI-DEC-008／009：Queue Timeout／Override（已撤回）
**狀態：已由 UI-DEC-011 取代（2026-09-03，Ken）**
- 先前討論的 Queue SLA、`isOverdue`、threshold、Building／Charge Group override 與 Admin 設定，會讓唯讀 Dashboard 擴張成新的營運規則，故不納入 V1。
- FE／BE 不需實作上述 timeout policy、欄位、設定來源或管理介面；歷史討論保留於 Redmine journal 供追溯。
### UI-DEC-010：Queue Source 語意對齊
**狀態：保留並簡化（2026-09-03，Ken）**
- 現行 `ChargingRequestSource` 維持 `MANUAL`、`OFF_PEAK`，供 Dashboard 正確顯示既有 queue source。
- `ROTATION` 是既有 dispatch／slot 調度機制，不是 queue source；Dashboard 不新增 `ROTATION` enum。
- V1 不新增 Rotation scheduler-health、missed-tick 或 dispatch-lag 判定；只顯示目前系統已有的 queue／rotation 資訊。
### UI-DEC-011：Dashboard V1 為唯讀資訊投影
**狀態：已確認（2026-09-03，Ken）**
- Dashboard 的目的為查詢、彙整與顯示既有營運資訊，不建立新的充電或排程業務規則。
- Queue 卡片／Drawer 顯示既有 source、status、priority、statusReason、waitingSince 與 waiting duration；waiting duration 是資訊，不是 SLA 或 timeout。
- 既有 `BLOCKED` 可列入 Needs Attention 並使用異常樣式；WAITING／ELIGIBLE 不因等待時間長短自動變成異常。
- Backend 開發限於 read model、query／aggregation、DTO、REST bootstrap、WebSocket update 與顯示排序，不得因此修改 queue lifecycle、priority、slot allocation、rotation dispatch、OCPP command 或充電流程。
- FE 開發限於呈現 Backend 既有狀態與時間資訊，不推導新的 `isOverdue`、severity 或業務狀態。
- V1 不新增 Queue timeout 設定、override precedence、Admin 設定頁、設定權限／audit table 或 Rotation health monitor。
- 若未來營運方明確需要 Queue SLA 或 scheduler monitoring，必須另案進行需求確認；本次不先建立子票。
### UI-DEC-012：單一 Responsive 呈現，不提供 Grid／Table Toggle
**狀態：已確認（2026-09-03，Ken）**
- Dashboard Connector preview 固定使用 responsive Cards，不提供顯示模式切換。
- 「查看全部」Drawer 採單一 responsive list：Desktop 使用緊湊列式呈現，Tablet／Mobile 依寬度自動堆疊欄位。
- Breakpoint 只改變排版，不改變資料欄位、status 語意、搜尋／篩選、排序或 pagination 規則。
- FE 不實作 Grid／Table toggle、view-mode URL parameter、local storage／使用者偏好保存或兩套可切換 renderer。
- Backend 不新增 `viewMode` request／response 欄位，也不依顯示模式提供不同資料 contract。
- 驗收只需覆蓋既定 Desktop／Tablet／Mobile responsive layout，不增加兩種 view mode 的交叉測試矩陣。
### UI-DEC-013：Connector Preview 使用單一 Top-8 Payload
**狀態：已確認（2026-09-04，Ken）**
- Backend 對目前 building 的完整 Connector 集合套用 UI-DEC-007 排序與異常分類，再固定回傳最多前 8 筆 `items`；總數少於 8 時回傳全部，不補空白資料。
- Payload 同時回 `total` 與 `abnormalTotal`，每個 item 帶 Backend authoritative `isAbnormal`、`severity`、`priorityReason`；完整欄位仍依 Card Minimum Content 提供。
- Desktop 顯示前 8 筆、Tablet 前 6 筆、Mobile 前 4 筆。Frontend 只能依目前 breakpoint 截取既有順序，不得要求 Backend 另產生 viewport-specific payload，也不得重排、重判 abnormal 或從未載入資料推測分類。
- Footer 的隱藏總數與隱藏異常數由 FE 使用 Backend totals 與 visible slice 作純顯示運算；這不構成新的 domain rule。負數一律 clamp 為 0，資料不一致時顯示區塊 Partial／Error，而不是自行修正 Backend 值。
- REST Overview bootstrap 與 WebSocket `CONNECTOR_LIVE_BLOCK_UPDATED` 使用同一份 service、snapshot 與 contract；WebSocket 每次仍 replacement 整個 summary + Top-8 preview，不傳完整 Connector inventory。
- 「查看全部」Drawer 另呼叫 REST search API 取得完整清單、搜尋、篩選與 server pagination；Dashboard socket 不因 Drawer 開啟而擴大 payload。
- 本決策取代「Backend 依 Desktop／Tablet／Mobile 各自截取」及「Backend 直接回 `remainingAbnormalCount`」的舊解讀；API 不需要 viewport、device 或 requestedLimit 欄位。
### UI-DEC-014：Status Summary 採互斥 Display Bucket
**狀態：已確認（2026-09-04，Ken）**
- Status summary 是 Dashboard 專用的唯讀顯示分類。Backend 必須依目前 building 的同一份 authoritative Connector snapshot，替每個 Connector 指定且只指定一個 `displayBucket`。
- Summary 回傳 `total` 與各 bucket count；所有 bucket count 必須無重複、無遺漏，且加總恰好等於 `total`。Frontend 直接呈現 Backend counts，不可從 Top-8 preview 重算。
- `displayBucket` 不取代原始 domain state。Card、完整清單 Drawer 與 detail 仍分層顯示 Charge Point OCPP connection、Connector runtime status、Queue status／reason；同一 Connector 可以在原始資料中同時出現 OFFLINE、CHARGING、BLOCKED 等訊號，但摘要只歸一類。
- 分類只能讀取既有狀態並套用顯示 precedence，不可回寫 Connector／Queue、不觸發狀態轉換，也不新增 SLA、timeout、scheduler-health、設備控制或自動修正。
- REST Overview bootstrap 與 `CONNECTOR_LIVE_BLOCK_UPDATED` 必須共用同一 bucket aggregation；每個 Top-8 item 也回傳自己的 `displayBucket`，供 FE 樣式與可存取文案使用。
- Bucket code、顯示名稱、狀態 mapping 與 precedence 已由 UI-DEC-015 確認；FE／BE 必須使用該固定 contract，不再自行選定。 尚未在本決策中確定，列為下一項 UI-DEC-015；在確認前不得由 FE／BE 自行選定。
### UI-DEC-015：Status Summary 固定五類 Bucket 與 Precedence
**狀態：已確認（2026-09-04，Ken）**
Backend 必須依下列順序，由上而下命中第一個符合條件的 bucket；一旦命中即停止，不得重複計數：
1. `NEEDS_ATTENTION`／「需留意」：`isAbnormal = true`；包含 OCPP OFFLINE、Connector FAULTED、資料 STALE、Queue BLOCKED、SUSPENDED_EVSE、UNAVAILABLE，以及 null／unknown／資料不足。這只是 Dashboard 顯示分類，不會額外建立 #1463 Attention category 或新告警規則。
2. `CHARGING`／「充電進行中」：排除第一類後，Connector runtime 為 CHARGING、SUSPENDED_EV 或 FINISHING。
3. `WAITING`／「準備／排隊」：排除前兩類後，Connector runtime 為 PREPARING／ENQUEUED，或 Queue status 為 ELIGIBLE。
4. `AVAILABLE`／「可用」：排除前三類及 OTHER 所列特殊中性狀態後，Connector runtime 為 AVAILABLE。
5. `OTHER`／「其他狀態」：RESERVED、Queue NOT_PLUGGED／PAUSED／FINISHED，以及其他已辨識、非異常但未落入前四類的狀態。Unknown 不得歸入 OTHER 或 AVAILABLE。
Contract 與不變條件：
- Summary `buckets` 固定使用上述 stable codes 與顯示順序；中文 label 固定由 FE 映射，不依 Backend 任意字串產生。
- 每個 Connector 恰好一個 bucket；五類 count 加總等於 `total`。
- `NEEDS_ATTENTION` 與既有 abnormal classification 是同一集合，因此 `NEEDS_ATTENTION.count = abnormalTotal`；Top-8 item 的 `displayBucket = NEEDS_ATTENTION` 時 `isAbnormal` 必須為 true，反之亦然。
- Preview ranking 的細部 priority reason 仍保留。例如 OFFLINE + Active Transaction 與一般 OFFLINE 都屬 NEEDS_ATTENTION，但前者仍透過 `priorityReason` 排在較前面。
- NOT_PLUGGED 固定歸 OTHER，不歸 WAITING，避免與已確認的「等待供電」KPI（只計 distinct ELIGIBLE）語意衝突。
- `displayBucket` 只控制 Status summary 與 Card presentation，不改寫 OCPP／runtime／Queue state，不新增 mismatch、timeout、SLA、scheduler-health、設備控制或資料修正。
## 需求管理狀態
- Parent：#1422
- Requirement status：**UI-DEC-001～015 status：**UI-DEC-001～014 已確認；本區塊可在全 Dashboard 鎖版時整併，議題暫維持 New／0%**
- Final specification：確認後整併至 #1422 的 v1.0 最終需求文件
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回