討論 #1463
是由 陳國瑋 於 28 天 前更新
## 背景
主需求：#1422。
原始 mockup 在 Dashboard 頂部使用英文 NEEDS ATTENTION，並顯示「目前有 5 個項目需要處理」。其中「Queue 狀態不同步」只是展示假資料，若要正式成立，必須新增狀態比對／scheduler-health 判斷，與已確認的 Dashboard V1 唯讀、簡化範圍不符。
本票定義這個摘要區塊的用途與資料邊界。它不是待辦、派工或自動修復系統。
## ATT-DEC-001：改名為「需留意事項」，只顯示明確既有狀態
**狀態：已確認（2026-09-03，Ken）**
### 區塊目的
「需留意事項」回答：
> 目前有哪些已由 Backend 明確確認的異常或未完成狀態，值得管理者優先查看？
使用者不必逐一掃描所有 Dashboard 區塊。摘要項目提供類型、數量與簡短原因，並可導向既有管理頁面或 Dashboard 對應區塊。
### 中文命名
- 英文 eyebrow「NEEDS ATTENTION」改為「需留意事項」。
- 主標題使用「目前有 N 個項目需要留意」。
- 不使用「需要處理」，避免暗示每個項目都必須立即人工操作。
- N 由 Backend 正式資料彙整；mockup 的 5 只是展示假資料。
### V1 可納入的明確狀態
- Charge Point：既有 OCPP connection status 明確為 OFFLINE。
- Connector：既有 runtime status 明確為 FAULTED。
- Queue：既有 queue status 明確為 BLOCKED。
- Dashboard 資料來源：Backend freshness policy 明確判定為 STALE，或目前資料來源 ERROR／PARTIAL。
- 結算流程：#1460 四步驟資料中的既有未完成／異常狀態。
上述項目只引用既有 authoritative state 或已確認的 Dashboard dataStatus，不建立新的營運門檻。
### V1 不納入
- 「Queue 狀態不同步」等需要額外比對推導的新規則。
- WAITING 太久、Queue timeout 或 Queue SLA。
- Rotation scheduler-health。
- 案場契約容量、利用率或容量餘裕告警。
- 預測性維護、異常模型或跨案場排名。
- 自動建立工單、指派人員、通知升級或逾期追蹤。
- Remote Start／Stop、Reset、重算帳務或其他 mutation。
若未來需要上述能力，必須另案定義資料來源、判斷公式與責任人，不能直接加入本摘要。
### Backend 要開發的內容
- 依 buildingId 彙整符合確認規則的 category count 與 bounded summary items。
- 每個項目使用 stable code、count、display parameters、source updatedAt／freshness 與可供 FE 導覽的 target type／identifier。
- 不以自由文字作為 FE 判斷條件；中文文字由 FE 或明確 i18n contract 呈現。
- 只讀取既有狀態，不寫回 Charge Point、Connector、Queue、Billing／Invoice 或任何業務資料。
- 任一來源失敗時依 overview PARTIAL 規則標示，不捏造 0 筆異常。
- 去重、排序、顯示上限與各項 deep link 細節仍待後續逐項確認。
### Frontend 要開發的內容
- 顯示「需留意事項」與「目前有 N 個項目需要留意」。
- 每個摘要項目顯示數量、清楚的中文名稱及一行原因。
- 項目只能導覽／定位至既有頁面或 Dashboard 區塊，不在摘要中放置作業按鈕。
- 狀態不能只靠紅／黃色；必須有文字、數字與可存取名稱。
- Production API 失敗時不得顯示 mock 假數字。
- 正常、Empty、Partial、Error 與大量項目 fixture 在後續規則確認後補齊。
### Mockup 同步
- NEEDS ATTENTION 改為「需留意事項」。
- 「目前有 5 個項目需要處理」改為「目前有 5 個項目需要留意」。
- 「Queue 狀態不同步／標示充電，設備已待機」改為既有明確狀態「Queue 阻塞／2 個項目目前為 BLOCKED」。
- 其他數字仍是假資料，不代表 A17 production 現況。
## Acceptance Criteria
- [ ] 畫面使用「需留意事項」及「需要留意」，不把摘要描述成派工或待辦。
- [ ] 每一種正式項目都可追溯到既有 Backend state 或已確認 dataStatus。
- [ ] Queue 只使用既有 BLOCKED；不新增 mismatch、waiting timeout 或 SLA 判斷。
- [ ] 不顯示案場契約容量／餘裕告警。
- [ ] 摘要與 deep link 均為唯讀，不觸發業務 mutation。
- [ ] 未取得來源資料時不回傳 0 冒充「沒有異常」。
- [ ] mock 數字與 A17 正式驗收資料明確分開。
- [ ] Dashboard 在其餘區塊可用時，不因單一摘要來源失敗而整頁失敗。
## ATT-DEC-002：只有目前負載不可信才進入需留意事項
**狀態：已確認（2026-09-03，Ken）**
### 納入摘要的條件
「需留意事項」只在目前 Live Load read model 出現下列任一明確狀態時，建立一個「即時負載資料不完整」category：
- current Live Load freshness = STALE。
- current Live Load dataStatus = PARTIAL。
- current Live Load dataStatus = ERROR。
此 category 直接引用 Backend 已判定的 current source state，不新增時間門檻或前端推測。點擊後定位至 Dashboard 的 Live Load 區塊，不執行修復操作。
### 不納入摘要的情況
- currentPowerKw = 0 且 dataStatus = COMPLETE：代表目前已確認沒有充電負載，是正常狀態。
- 過去 finalized bucket 為 PARTIAL／ERROR 或 averagePowerKw = null：只在折線圖保留缺口、tooltip 與區塊內說明。
- 不因每一個歷史缺口分別建立摘要項目，也不把缺口數量加到頁首總數。
- OPEN bucket 只因時間尚未結束，不構成需留意事項；必須同時有 STALE／PARTIAL／ERROR 才納入。
- 不因 currentPowerKw 高或接近任何推算容量而建立告警。
### Backend／事件
- category stable code 建議為 LIVE_LOAD_DATA_UNRELIABLE；最終 enum 名稱可在實作 plan 固定，但語意不得擴張。
- REST overview 依 current Live Load source state 產生相同 category。
- WebSocket 在 current freshness／dataStatus 進入或離開上述狀態時，透過既有「需留意事項」replacement event 更新摘要。
- 歷史 series 的單一 bucket status 不觸發摘要 event。
- source 恢復 COMPLETE／FRESH 後移除此 category。
### Frontend
- 顯示名稱：「即時負載資料不完整」。
- 說明依 stable reason code 顯示「資料已過期」、「部分充電功率無法取得」或「負載資料計算失敗」。
- 點擊後捲動／定位到 Live Load；不新增獨立頁面。
- Live Load 區塊本身仍顯示對應的 stale／partial／error 狀態與重新整理操作。
- 歷史缺口維持圖表內呈現，不在「需留意事項」重複列出。
### Mock／Fixture
- 正常主 mock 維持 current Live Load FRESH／COMPLETE，不加入故障項目。
- 最終 Partial fixture 增加 current Live Load PARTIAL 及一筆「即時負載資料不完整」摘要。
- 最終歷史缺口 fixture 只顯示圖表 gap，不出現這個摘要，用來驗證兩者差異。
### Acceptance Criteria
- [ ] current STALE／PARTIAL／ERROR 只產生一個 Live Load category，不按 bucket 重複建立。
- [ ] current 0 + COMPLETE 不產生需留意事項。
- [ ] OPEN + COMPLETE 不產生需留意事項。
- [ ] finalized 歷史 gap 不進入摘要，也不增加頁首數量。
- [ ] category 可導向 Live Load，但不執行 mutation。
- [ ] source 恢復 FRESH／COMPLETE 後摘要同步移除。
- [ ] REST bootstrap 與 WebSocket replacement 使用相同判定。
## 待確認事項
- 同一設備同時符合多個狀態時的計數與去重方式。
- 項目排序與 severity 是否只用既有狀態映射。
- 首頁最多顯示幾類／幾筆，以及超出上限的呈現。
- 每一類項目的 deep link 目的地。
- 沒有任何需留意項目時的 Empty State。
- [x] 只有目前 歷史 Live Load bucket 缺口是否只在圖表呈現；目前負載 STALE／PARTIAL／ERROR 進入本區塊；歷史 bucket 缺口只在圖表呈現（ATT-DEC-002）。 是否進入本區塊。
## 需求管理狀態
- Parent：#1422
- Related：#1424（REST／WebSocket 資料分工）、#1460（結算流程）、#1462（Live Load）
- Requirement status：**ATT-DEC-001／002 已確認；去重、排序、上限、deep link 與 Empty State 逐項確認** status：**ATT-DEC-001 已確認，其餘顯示與計數規則逐項確認**
- Final specification：全部 Dashboard 區塊確認後整併至 #1422 v1.0 文件
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回