討論 #1463: [Dashboard] 需留意事項摘要與顯示規則 - EMS - SYLKSOFT - Bug Tracking System

討論 #1463

> **閱讀基準：** [主需求 #1422](https://redmine.sylksoft.com/issues/1422) 與 [HTML Mock v0.4／附件 #1121](https://redmine.sylksoft.com/attachments/1121)。以下沿用主票區塊編號，依畫面由上到下、由左到右說明。Mock v0.3／附件 #1117](https://redmine.sylksoft.com/attachments/1117)。以下沿用主票區塊編號，依畫面由上到下、由左到右說明。Mock 數字皆為假資料；功能適用所有案場，A17 不是固定規則。 

 ## 02｜需留意事項：本票要完成什麼 

 **讓使用者不用掃完整頁，就知道有哪些已確認的異常或未完成狀態值得查看。** 位置在頁首下方、六張 KPI 上方。這不是待辦、派工、自動修復或新的告警引擎。 

 依畫面順序：**左側標題與類別數 → 右側各類卡片 → 點擊前往既有頁面／同頁區塊**。 

 ```text 
 目前有 3 類項目需要留意 
      │ 
      ├─ 設備故障：1 個 Connector → Connector 列表 
      ├─ Queue 阻塞：2 個項目       → 本頁 Connector 即時狀態 
      └─ 結算待確認：2 個步驟       → 本頁結算流程 

 頁首是「3 類」，不是 1＋2＋2＝5 台設備。 
 ``` 

 以上是 v0.4 v0.3 假資料，不代表 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 目前負載品質，與歷史缺口分開 

 ```text 
 目前 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 文件套件已依 全 Dashboard 完成一致性 review 後，才依 #1422 DOC-DEC-001 發布並保留 v0.2／v0.3；目前閱讀基準為 PDF #1119、Markdown #1120、HTML #1121。此版仍是 review Draft，尚非 v1.0。 發布同版號 PDF／Markdown／HTML 套件；現有 v0.3 Draft 不覆寫，本次不發布新版附件。 
 - 2026-09-14：僅重整 Description、說明與排版，將已確認決策併入對應畫面／工程工作；決策編號保留供追溯。E2E impact：No catalog change（沒有修改產品行為、公式或 API 契約）；功能實作時仍須遵循主票與本票驗收。

專案

一般

配置概況

EMS

討論 #1463