討論 #1462
是由 陳國瑋 於 15 天 前更新
> **閱讀基準：** [主需求 #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 不是固定規則。
## 04 → 05｜本票涵蓋畫面中段的左右兩區
**左邊看「整個案場現在用了多少功率、如何變化」；右邊看「每個群組自己的容量與供電名額」。** 兩區目的不同，不能把群組容量相加後當成案場契約容量。
```text
04 案場即時負載（左） 05 群組容量與 Slots（右）
目前功率（kW） 群組名稱、目前功率／自身容量
即時／今日／7 日趨勢 該組占用／保留／可用名額、Queue
│ │
└─ 不推算案場契約容量、利用率或剩餘容量 ──┘
```
這裡只新增 Dashboard 的唯讀資料整理與呈現，不修改 MeterValue 採集、充電、輪充或名額分配。
## 1. 04 案場即時負載：由上到下閱讀
| 畫面位置 | 顯示內容 | 使用者應理解的意思 |
|---|---|---|
| 標題／說明 | 案場即時負載；各充電群組目前充電功率合計 | 這是充電功率，不是案場對電力公司的契約容量。 |
| 右上三個按鈕 | 即時、今日、7 日 | 只切換圖表時間範圍，不調整設備回報或充電控制。 |
| 大數字 | 目前功率 currentPowerKw，單位 kW；Mock 21.84 | Backend 於資料時間可確認的目前總功率，與圖上「區間平均」可能不同。 |
| 資料時間／品質 | latestMeterAt、freshness／source status | 這個目前值是否仍新鮮；未知顯示「—」。 |
| 下方折線圖 | 一條區間平均總充電功率線 | 看各時間區間的平均功率變化，不是累計 kWh。 |
### 1.1 X 軸：案場當地時間
所有時間用 Backend 回傳的 building timezone，不用 browser timezone 切日。（LOAD-DEC-002／003）
| 檢視 | 時間範圍 | 每個資料點的區間（bucket） | 最多點數 | 軸標／Tooltip |
|---|---|---|---|---|
| 即時 | generatedAt 往前 60 分鐘至 generatedAt | 1 分鐘 | 60 | HH:mm；Tooltip 顯示精確起訖分鐘。 |
| 今日 | 案場當日 00:00 至 generatedAt | 15 分鐘 | 96 | HH:mm；Tooltip 顯示日期及區間起訖。 |
| 7 日 | 今天加前 6 個案場日曆日，第一天 00:00 至 generatedAt | 1 小時 | 168 | 以 M/d 分日；Tooltip 顯示 M/d HH:mm 及區間起訖。 |
「7 日」不是固定往回 168 小時。FE 可減少軸上文字刻度以避免擠在一起，但不改時間範圍、粒度或資料點。最後區間尚未結束時標示 OPEN（進行中）。
### 1.2 Y 軸：區間平均功率
- 軸名「充電功率（kW）」，圖表說明「區間平均總充電功率」。
- 最小值從 0 開始；最大值依所選資料的有效值自動取整，不固定成 297 kW 或群組容量總和。
- 每個點為 time-weighted averagePowerKw，顯示小數點後 2 位；Tooltip：「區間平均功率 X.XX kW」。
- 只畫一條平均線，不加峰值、最小值、契約容量線、預測線。7 日 kW 與 #1461 的 30 日 kWh／Sessions 不能互相取代。
## 2. Backend 如何算功率：先整理時間線，再算平均
原始來源為 Power.Active.Import，依 unit 正規化後統一回 kW。作用範圍依 Backend 解析的 Building 與既有 enabled Connector scope，不把 A17 數量寫死。（LOAD-DEC-001／003／005）
```text
各 Connector 的功率讀值＋充電／交易事實
↓
按時間排序、W 轉 kW、檢查數值與 freshness
↓
重建各時間片段可確認的案場總功率
↓
按片段持續時間加權 → 每個 bucket 的 averagePowerKw
```
例如一分鐘內，前 30 秒為 10 kW、後 30 秒為 20 kW，該分鐘平均為 15 kW。不同 Connector 回報頻率不同，**不能直接加總或平均 raw MeterValue rows**，否則回報較密的設備會被賦予較大權重。
### 2.1 每個時間片段的判定
| 來源事實 | 對功率的處理 |
|---|---|
| 新鮮 runtime／transaction 明確表示未充電 | 貢獻 0，不必額外要求 Power MeterValue。 |
| 正在充電，Power 有效、非負、單位可換算、仍在 cutoff 內 | 使用最新有效值，可沿用至下一筆讀值或有效期限。 |
| 正在充電但 Power 缺少、負值、無法解析或過期 | unknown，不能當成 0，也不能無限沿用舊值。 |
| 充電／交易事實無法確認，包含離線且仍有未結束交易等情況 | 不假定為 0。這是資料品質判斷，**不產生「離線充電／待 reconciliation」推測性文案**。 |
正常回報間隔內沒有每秒新資料，不會自動變成缺值。cutoff 使用 #1424 DEC-033 的 Backend 全系統 per-source 預設，不新增案場 override。
### 2.2 一整個 bucket 的結果
| 情況 | averagePowerKw | dataStatus |
|---|---|---|
| 所需時間片段全部可確認 | 時間加權平均 | COMPLETE |
| 全部可確認且全程沒充電 | 0 | COMPLETE |
| 存在超過 cutoff 後仍無法確認的充電功率片段 | null | PARTIAL |
| 查詢／計算失敗 | null | ERROR |
不回「已知設備的部分功率合計」冒充完整案場功率，不做線性插值、前後平均、預測、coverage 百分比或 80%／90% 通過門檻。
## 3. 圖表狀態：時間沒結束，不等於資料不完整
bucketState 與 dataStatus 是兩件事，不能互相代替。（LOAD-DEC-005）
| 欄位 | 值 | 意義 |
|---|---|---|
| bucketState | OPEN | 時間區間尚未結束，只計已經過的 bucketStartAt～event occurredAt／rangeEndAt，不估未來。 |
| bucketState | FINALIZED | 區間已結束，不再因正常時間推進變動；結束不代表品質一定完整。 |
| dataStatus | COMPLETE | 已經過／可計算部分的資料完整。 |
| dataStatus | PARTIAL | 有功率未知，無法形成完整案場平均。 |
| dataStatus | ERROR | 查詢或計算失敗。 |
所以 OPEN＋COMPLETE 是正常「進行中」，FINALIZED＋PARTIAL 也是可能結果。
FE 顯示規則：
- OPEN 只標「進行中」，不因 OPEN 使用警告色。
- 0＋COMPLETE 畫 0 線，Tooltip 0.00 kW。
- null＋PARTIAL 留缺口，說明「部分充電功率無法取得」。
- null＋ERROR 留缺口，說明「負載資料計算失敗」。
- 不把缺口補 0、不沿用前值、不跨缺口連線；文字與螢幕閱讀器均可辨識。
## 4. 三種檢視如何取得、切換與更新
### 4.1 一次取得三組歷史，切換不發 request
Overview 首載、共用每 5 分鐘及手動刷新，**同一次**回 LIVE／TODAY／SEVEN_DAYS 三組完整歷史；不另設負載 timer、lazy-load endpoint、range request parameter 或每頁籤 API。（LOAD-DEC-004／007、#1424 DEC-032）
| 使用者行為／情況 | FE 行為 |
|---|---|
| 開啟／整頁 reload | 預設 LIVE（即時）。選擇只保存在本次頁面，不存 URL／使用者偏好。 |
| 切換即時／今日／7 日 | 切換已有 cache，同步 active／aria-pressed，不重抓 API、不動 socket。 |
| 5 分鐘／手動刷新 | 更新一般歷史，保留 selectedRange；不覆寫已由 WS 接手的 currentPowerKw／open buckets。 |
| 所選 range 為 EMPTY／ERROR | 原位顯示該範圍狀態，不自動跳別頁；其他按鈕仍可操作。 |
| 某段歷史失敗、目前值正常 | 各自呈現，不因歷史失敗清空目前值或另外兩個正常 range。 |
各 range 帶 rangeCode、起訖、bucket size、buckets、dataStatus／dataState、updatedAt 及必要的 lastSuccessfulAt。
全零＋COMPLETE 仍畫 0 線，不是 Empty。EMPTY 必須由 Backend 明確表示「成功但無可顯示歷史」；FE 不以空陣列猜 Empty。PARTIAL 保留正常點及缺口。ERROR 顯示「{範圍}負載資料暫時無法取得」；同案場有舊 series 可保留並標明更新失敗與 lastSuccessfulAt。
### 4.2 WebSocket 只送目前值與區間變動
LIVE_LOAD_UPDATED 不重送完整 60／96／168 點；帶 currentPowerKw 與三種 range 的 open buckets，跨界時可一併帶剛結束的 finalized bucket。Backend 不必知道 FE 選哪個 Tab，不新增 subscribe／unsubscribe。（LOAD-DEC-004）
Bucket 欄位：rangeCode、bucketStartAt、bucketEndAt、averagePowerKw、bucketState、dataStatus、updatedAt／freshness。
```text
區間跨界事件
├─ 上一區間 FINALIZED replacement（可能仍為 null／PARTIAL）
└─ 下一區間 OPEN
↓
FE 依 buildingId＋rangeCode＋bucketStartAt 找到原資料
↓
先取代已結束點，再加入新 OPEN，裁切至該 range 的視窗
```
相同 key 直接取代，不累加／再平均、不用 currentPowerKw 自行積分、不按抵達時間計算，也不由別的 range 換算。只接受相同 buildingId 與受支援 schemaVersion；不符時不套用、不猜資料，也不改抓 REST 做即時 recovery。
Backend 可因資源保護內部 debounce／coalescing，但不承諾固定 5 秒更新；沒有 Live Load／freshness 變化不需空推。
### 4.3 斷線：保留資料與時間，提示停止更新
頁首及本區提示連線失敗／中斷；保留最後 currentPowerKw／open buckets 與時間，無資料顯示「—」。共用 Overview 可繼續更新歷史及其他一般區塊，但不可冒充即時備援或覆寫最後 live state。
不做 REST polling fallback、backoff、自動重連、sequence／gap recovery；只有整頁 reload 才重新取得 bootstrap、短效 ticket 與建立 socket。（#1424 DEC-031／032）
## 5. 05 群組容量與 Slots：從上往下逐組看
| 位置 | 資訊 | 來源與界線 |
|---|---|---|
| 區塊標題／時段 | 群組容量與 Slots、既有時段文字 | Mock「離峰時段」僅示例。 |
| 每組標題與功率 | 群組名稱、currentPowerKw／contractCapacityKw | 只對應該組，Mock B1／B2／B3 各 99 kW 不可寫死。 |
| 容量／占用說明 | 該組 contract capacity／allocated power、容量條 | 若顯示比例，分母只能用該組 contractCapacity，清楚標為群組值。 |
| Slots／Queue | occupied／reserved／available slots、既有 queue 狀態 | 沿用 SlotCalculator 與現有 Queue 語意；Slots 為供電名額，不是 kWh。 |
支援 1、2 或多個群組，不硬編碼群組數。Group Capacity／Slots 只隨共用 REST 更新，不訂閱 Live Load WS；因此可能與左側即時數字有更新時間差。
**禁止推算案場容量（LOAD-DEC-001）：** 現有 contractCapacity 屬於 Charge Group，用於群組 slots；沒有 authoritative site capacity 與可加總的上游配電拓撲。因此不新增／回傳／顯示群組合計推導的 buildingContractCapacityKw、utilizationPercent、remainingCapacityKw，也不新增案場容量設定、拓撲、告警門檻或管理 API。
## 6. 與「需留意事項」如何配合
只看**目前值的品質**，不是數歷史缺口。（LOAD-DEC-006、#1463 ATT-DEC-002／008）
| 狀況 | 是否成為「即時負載資料不完整」類別 |
|---|---|
| current freshness STALE 或 dataStatus PARTIAL／ERROR | 是，一個類別、affectedCount＝1。 |
| currentPowerKw 0＋COMPLETE | 否，正常零負載。 |
| OPEN＋COMPLETE | 否，時間仍在進行而已。 |
| finalized 歷史 null／PARTIAL／ERROR | 否，只在圖表保留缺口與原因。 |
目前資料恢復後，本區可由 WS 更新；上方 Attention 等下一次成功 Overview 才移除該類別，不由 WS 直接修改 Attention。不推論共同根因、離線充電或待 reconciliation。
## 7. 工程交付與驗收
| 負責方 | 必須完成 |
|---|---|
| Backend | 新增 Dashboard 歷史唯讀 query／service、Power 單位／有效性檢查、時間線加權；三 range DTO、目前值／群組資料、WS 區間 replacement。 |
| FE | 左右區塊、三按鈕、軸／Tooltip／單位、缺口／各狀態、三份 cache 與 key replacement、群組數量彈性、斷線提示。 |
| QA | 時區與範圍、不同頻率樣本、邊界 finalized／open、0／null、range 失敗隔離、權限／案場隔離、無 fallback 與無作業寫入。 |
- [ ] 目前值與區間平均不互相覆寫；正確 kW 與兩位小數。
- [ ] 三組範圍、點數上限、X/Y 軸、精確 Tooltip 正確；7 日為日曆日。
- [ ] 時間加權而非 raw rows 算術平均；正常回報間隔可沿用，cutoff 後不可沿用。
- [ ] 任一未知充電片段使 bucket null＋PARTIAL；全零為 0＋COMPLETE，不做補值、跨線或 coverage 門檻。
- [ ] OPEN 與品質分開；finalized 仍套相同品質規則。
- [ ] REST 可重建完整各 range；WS 只送目前值與 open／跨界 finalized，FE 按 key replacement、視窗上限保留資料。
- [ ] 切換不發 request／動 socket；刷新保留選擇；range Empty／Error 留在原頁，不清空正常目前值。
- [ ] Socket 失敗／中斷保留資料與時間且提示，不啟動備援／自動重連。
- [ ] Attention 只反映目前品質，一個類別；歷史缺口不計。
- [ ] 1／2／多組容量與 Slots 正確，沒有案場容量合計／利用率／餘裕。
- [ ] 不修改 SlotCalculator、queue lifecycle、rotation dispatch、Transaction、MeterValue 或 OCPP／Modbus 行為；production 不退回假資料。
Fixture 保留正常示例，另提供 FINALIZED＋PARTIAL 缺口、全零、EMPTY／ERROR 與恢復；原 Mock 的 ?load=empty&load-range=today、?load=error&load-range=week 只供 review，不是正式 API／URL 契約。
## 8. 決策追溯與歷史查核依據
| 決策 | 本文 |
|---|---|
| LOAD-DEC-001 不推算案場容量 | 第 1、5 節 |
| LOAD-DEC-002 保留三檢視；003 軸線／計算 | 第 1～3 節 |
| LOAD-DEC-004 REST／WS replacement | 第 4 節 |
| LOAD-DEC-005 時間狀態與品質分離 | 第 2～3 節 |
| LOAD-DEC-006 摘要範圍 | 第 6 節 |
| LOAD-DEC-007 一次取得／切換行為 | 第 4.1 節 |
LOAD-DEC-001～006 於 2026-09-03、007 於 2026-09-04 已確認；後續傳輸以 #1424 DEC-031／032 為準。早期「軸線待確認」已由 003 定案，不再保留為未決；原 Mock 的 297 kW／7.4%／275.16 kW 案場容量資訊已撤回。
**2026-09-03 A17 唯讀基線（沿用舊票記錄，本次未重新查 DB）：** B1／B2／B3 各 99 kW、4 CP／12 Connector 且皆指派群組；297 kW 只為算術合計，不能證明上游容量。近 7 日 14,550 筆 Power.Active.Import，11 個曾回報 Connector，皆為 W；近 24h 1,342 筆，充電 Sample.Clock 約 30～34 秒、非充電 Sample.Periodic 約 900～905 秒。這是使用時間加權的既有依據，不是各案場固定頻率／數量。當時 MeterValueRepository 尚無 Dashboard 歷史負載 aggregate query。
原有參考保留：[EIA：功率與能量單位](https://www.eia.gov/energyexplained/electricity/measuring-electricity.php)、[DOE：電費與區間需量說明](https://www.energy.gov/sites/default/files/2024-04/understanding-your-utility-bill.pdf)。本圖不是正式需量計費，不以外部例子增加計費需求。
## 需求管理與本次編輯
- 本票仍是已確認需求的追蹤票，不代表已完成開發或通過測試；指派、狀態、進度、附件與父子關係均維持原狀。
- 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 契約）；功能實作時仍須遵循主票與本票驗收。
返回