討論 #1463
進行中Feature #1422: [功能開發] Backend Admin 營運 Dashboard（全案場適用，A17 首站）
[Dashboard] 需留意事項摘要與顯示規則
概述
閱讀基準： 主需求 #1422 與 HTML Mock v0.4／附件 #1121。以下沿用主票區塊編號，依畫面由上到下、由左到右說明。Mock 數字皆為假資料；功能適用所有案場，A17 不是固定規則。
02｜需留意事項：本票要完成什麼¶
讓使用者不用掃完整頁，就知道有哪些已確認的異常或未完成狀態值得查看。 位置在頁首下方、六張 KPI 上方。這不是待辦、派工、自動修復或新的告警引擎。
依畫面順序：左側標題與類別數 → 右側各類卡片 → 點擊前往既有頁面／同頁區塊。
目前有 3 類項目需要留意
│
├─ 設備故障：1 個 Connector → Connector 列表
├─ Queue 阻塞：2 個項目 → 本頁 Connector 即時狀態
└─ 結算待確認：2 個步驟 → 本頁結算流程
頁首是「3 類」，不是 1＋2＋2＝5 台設備。
以上是 v0.4 假資料，不代表 A17 現況。名稱固定「需留意事項」、「需要留意」，不用「需要處理」暗示每項都須立即操作。（ATT-DEC-001／003）
1. 卡片內容、固定順序與導覽一次對照¶
只顯示 affectedCount > 0 的類別；五類是允許清單，不是每次一定要畫五張卡。依下表由上到下的優先順序，寬畫面由左到右顯示。（ATT-DEC-001～004／007）
| 順序／穩定 code | 使用者看見的類別 | 來源與 affectedCount | 點擊目的地 |
|---|---|---|---|
| 1 CHARGE_POINT_OFFLINE | Charge Point 離線 | persisted OCPP connection 明確 OFFLINE；以 CP ID 去重 | /cp/list |
| 2 CONNECTOR_FAULTED | Connector 故障（Mock「設備故障」） | runtime 明確 FAULTED；以 Connector ID 去重 | /connector/list |
| 3 LIVE_LOAD_DATA_UNRELIABLE | 即時負載資料不完整 | 目前 Live Load STALE／PARTIAL／ERROR；存在時 affectedCount 固定 1 | 本頁 #load |
| 4 QUEUE_BLOCKED | Queue 阻塞 | 既有 Queue BLOCKED；以 Queue entry ID 去重 | 本頁 #connectors |
| 5 SETTLEMENT_INCOMPLETE_OR_ERROR | 結算未完成／異常（Mock「結算待確認」） | #1460 已確認的未完成／異常 step code 去重 | 本頁 #billing |
每張卡呈現「數量＋正確單位＋中文類別＋一行原因＋查看提示」。Live Load 原因依 code 顯示資料已過期／部分充電功率無法取得／負載資料計算失敗，不以自由文字新增類別。
計數與排序不可由 FE 改寫¶
- categoryCount＝非零類別數；某類 1 或 100 筆，頁首都只加 1。
- 同類用穩定 ID 去重；不同類不推論共同根因，也不互相扣掉。同一設備可出現在不同類別。
- 不把 affectedCount 跨類相加當成設備、事件或根因總數。
- Backend 依固定順序回傳；FE 不按數量、時間、顏色或 severity 重排。
- 所有非零類別全部顯示，沒有 Top N、展開、Drawer、查看全部、分頁或自訂排序。
- FE 直接使用 categoryCount／affectedCount；與 categories 不一致是 contract error，不靜默修正成正常。
- Unknown code 保留可讀資訊、不冒充已知類別、不建立未知目的地 link，並記錄診斷。新增類別須另外更新允許清單、來源、順序、名稱與測試。
2. 版面如何適應數量與寬度¶
| 畫面 | 排列 |
|---|---|
| 桌面寬畫面 | CSS Grid auto-fit；標題與全部非零卡片可換行。 |
| 約 768／1024 px | 兩欄，標題占第一列全寬。 |
| 390 px／小螢幕 | 單欄，標題、卡片依序往下。 |
1～5 類都完整顯示，不能把字縮到難讀，不產生區塊或頁面水平捲軸。換行不改數字、順序；DOM、鍵盤與視覺順序一致，不靠 CSS order 改閱讀順序。（ATT-DEC-004）
這與 06 Connector 五項狀態摘要不同：本區卡片可導覽且只顯示非零類別；Connector 五項摘要不可點擊，非空案場固定五項含零。
3. 正常、部分資料與錯誤如何顯示¶
| dataStatus／資料 | 標題與內容 | 不可出現 |
|---|---|---|
| COMPLETE，categoryCount > 0 | 「目前有 N 類項目需要留意」，顯示全部非零卡片 | 任意漏掉／合併類別 |
| COMPLETE，categoryCount＝0，categories＝[]，來源確實查詢完成 | 精簡狀態列「目前沒有需留意事項」；「所有已檢查的狀態目前皆正常」＋更新時間 | 五張零卡、整區消失、紅色警示／pulse |
| PARTIAL，已確認非零類別 > 0 | 「已確認 N 類項目需要留意」＋保留卡片；黃色提示「部分狀態暫時無法確認／以下為已確認項目，顯示數量可能不完整」 | 宣稱是完整案場數字 |
| PARTIAL，categoryCount＝0 | 只提示「部分狀態暫時無法確認」 | 「0 類」或綠色正常 Empty |
| ERROR，categoryCount＝null，categories＝[] | 「需留意事項暫時無法取得」，顯示 errorAt；有 lastSuccessfulAt 可一併顯示 | 0 類正常、綠勾，或拿過期 cards 冒充本次結果 |
（ATT-DEC-005／006）
- HTTP 200、空畫面、空陣列或欄位缺漏都不足以自行推論「正常」。
- PARTIAL 黃色提示是本區的資料完整度，不是第六個 category，也不加 categoryCount。
- ERROR 只顯示不可取得，不新增區塊專用 Retry；沿用頁面既有刷新。
- 正常 Empty 使用中性偏綠樣式與勾選，但文字仍要可辨識。所有狀態不能只靠顏色。
- 最後一類消失／第一類出現時，依下一次成功 Overview 在 Empty 與 cards 間切換；資料恢復也以 Backend 結果取代畫面，不由 FE 掃其他區塊猜測。
- 不因 Partial／Error／Empty 建立通知、告警事件、派工或作業 mutation。
4. 哪些狀況不要推論成新問題¶
4.1 目前負載品質，與歷史缺口分開¶
目前 Live Load 的 STALE／PARTIAL／ERROR → 本區一個類別，數量 1
歷史 FINALIZED bucket 的 null／缺口 → 只留在負載圖，這裡不加類別
OPEN＋COMPLETE 或目前 0＋COMPLETE → 不是異常
目前值高、不明的容量比例、每個歷史缺口，都不是新增摘要的理由。source 恢復 FRESH／COMPLETE 後，Live Load 可先由 WS 更新；本區等下一次成功 Overview 移除類別，不要求同秒同步。（ATT-DEC-002）
4.2 CP 離線與 ACTIVE Session 是兩個事實¶
CP 離線只陳述既有 OCPP 狀態；#1486「充電進行中」依 canonical ACTIVE transaction 獨立計數，包含 parent CP 暫時 OFFLINE／disabled 的尚未結束 Session，但不證明設備當下有輸出。（ATT-DEC-008）
不交叉推導「可能仍在離線充電」、「待 reconciliation」、新 category／severity／badge／文案，或 offlineCharging／reconciliationRequired 欄位。需要調查走既有 CP／Connector 頁，不新增聯合提示、交易修正或自動結束流程。
4.3 其他 V1 排除範圍¶
不新增 Queue mismatch／狀態不同步、WAITING 太久、timeout／SLA、Rotation scheduler-health、容量餘裕告警、預測性維護、跨案場排名、root-cause graph／parent-child suppression／事件關聯引擎，以及工單、通知升級、逾期追蹤、Start／Stop／Reset／帳務重算。
5. 卡片只導覽，不能偷偷執行操作¶
每張卡是一個原生 link，不巢狀 button／link；顯示「查看 →」等明確提示，支援 Tab／Enter／focus-visible。（ATT-DEC-007）
- 固定 code 對應第 1 節 route／anchor，Backend 不回任意 URL。
- 1 筆或多筆受影響資料都去同一目的地；不按 count 改 routing。
- 同頁定位後將焦點移至目標標題／容器，設 scroll margin；跨頁用既有 router，Back 可回 Dashboard。
- 不自動套狀態 filter、不新增 status query parameter、category detail API 或 Queue 專用頁。
- 所有導覽沿用目的頁權限，不增加使用者權限，也不執行修復、排程、結算、通知。
Mock 導覽差異： 單檔 Mock 的故障卡以 #connectors 模擬，data-production-href 記錄正式 /connector/list；Queue、結算卡則分別定位 #connectors、#billing。不可把示範 anchor 誤當正式跨頁 route。
6. 資料取得與工程分工¶
本區是 REST-only，共用 GET /api/dashboard/overview 的首載／5 分鐘／手動刷新；沒有獨立 request／timer／WS event，也不因兩個 live blocks 斷線而增加備援。（#1424 DEC-031／032）
| 負責方 | 交付內容 |
|---|---|
| Backend | current-building scope 的唯讀聚合；固定 allowlist、順序與類內去重；categoryCount／categories；每類 code、affectedCount、display parameters、target type／identifier、updatedAt／dataStatus／freshness。 |
| Backend 狀態 | aggregate dataStatus、updatedAt／errorAt／lastSuccessfulAt；COMPLETE 整數、PARTIAL 已確認數可為 0、ERROR null＋[]；若使用 generatedAt 代來源時間須在契約說清楚。 |
| FE | 標題／卡片／原因與單位、RWD、Empty／Partial／Error、固定路由 mapping、鍵盤／焦點；不從本機時間、HTTP status 或其他區塊推論完整性。 |
| QA | 分類／計數／零值與未知、五種 route、1～5 類排版、目前／歷史品質差異、離線＋ACTIVE 不推論、只讀與權限邊界。 |
Backend 不寫回 CP／Connector／Queue／Billing／Invoice；來源失敗只影響相依資訊，不拖垮可用 Dashboard。Production 不顯示假數字。
7. 驗收清單與 Fixture¶
- 區塊稱「需留意事項／需要留意」，不是待辦或需要處理。
- 每個類別可追溯既有狀態；固定五類順序、類內 stable ID 去重，頁首只算非零類別。
- 所有 1～5 類完整顯示；390／768／1024／1440 px 無水平捲軸，DOM／鍵盤／視覺順序一致。
- Mock 三卡 1／2／2 對應 3 類，不算 5 台設備；FE 不重算或跨類去重。
- COMPLETE＋0＋[] 才顯示正常 Empty；PARTIAL 有／無非零類別、ERROR null＋[] 各依第 3 節呈現。
- PARTIAL 提示不增加類別；ERROR 不顯示舊卡冒充本次結果；無區塊專用 Retry。
- current 品質異常只產生一類／affectedCount＝1；0＋COMPLETE、OPEN＋COMPLETE、歷史缺口不納入。
- 五類固定導覽、未知 code 安全顯示、不新增 URL／filter／detail API；鍵盤與同頁焦點正確。
- CP 離線＋ACTIVE 各自呈現，不新增離線充電推論或衍生欄位。
- 共用 REST 更新，無 WS／fallback／業務 mutation；恢復後下一次成功 Overview 更新。
Fixture：正常三類、COMPLETE Empty、PARTIAL 有／無已確認類別、ERROR、目前負載 PARTIAL 一個摘要、只有歷史 gap 不出摘要、離線＋ACTIVE。Mock 的 ?attention=empty／partial／error 僅供 review，不是正式功能；正常 Mock 不為展示而捏造 CP Offline／Live Load 故障。
8. 決策索引與歷史更正¶
| 決策 | 已確認日期 | 本文位置 |
|---|---|---|
| ATT-DEC-001 中文名稱與只讀範圍 | 2026-09-03 | 開頭、第 1、4、6 節 |
| ATT-DEC-002 目前負載品質 | 2026-09-03 | 第 4.1 節 |
| ATT-DEC-003 類別／受影響數；004 固定順序／RWD | 2026-09-03 | 第 1～2 節 |
| ATT-DEC-005 Empty；006 Partial／Error | 2026-09-04 | 第 3 節 |
| ATT-DEC-007 固定導覽 | 2026-09-04 | 第 1、5 節 |
| ATT-DEC-008 離線／Session 分開 | 2026-09-06 | 第 4.2 節 |
早期 Mock 的「5 個項目需要處理」、「Queue 狀態不同步」與中途「5 個項目需要留意」已被「N 類」及既有 BLOCKED 規則取代。早期顯示上限、排序、Empty 與導覽「待確認」均已定案，不再列為未決。
相關票：#1424 共用資料／權限、#1462 Live Load、#1460 結算、#1486 KPI。
需求管理與本次編輯¶
- 本票仍是已確認需求的追蹤票，不代表已完成開發或通過測試；指派、狀態、進度、附件與父子關係均維持原狀。
- v0.4 Draft 文件套件已依 #1422 DOC-DEC-001 發布並保留 v0.2／v0.3；目前閱讀基準為 PDF #1119、Markdown #1120、HTML #1121。此版仍是 review Draft，尚非 v1.0。
- 2026-09-14：僅重整 Description、說明與排版，將已確認決策併入對應畫面／工程工作；決策編號保留供追溯。E2E impact：No catalog change（沒有修改產品行為、公式或 API 契約）；功能實作時仍須遵循主票與本票驗收。