EMS

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

07｜30 日充電用量：本票要完成什麼¶

讓使用者知道最近 30 天完成了多少充電、每天如何分布，以及每次平均充多少電。 畫面位於底部左側，右邊是 08 結算流程；上方 03-5「今日已完成充電量」重用本票今天的資料桶。

30 日充電用量                              kWh／Sessions
┌──────────────────────────┬─────────────────────────┐
│ 每日圖表                  │ 1. 有效充電量            │
│ X：30 個案場日期          │ 2. 充電 Sessions         │
│ Y：kWh 或有效充電次數      │ 3. 平均每次充電量         │
└──────────────────────────┴─────────────────────────┘

V1 保留 kWh／Sessions 切換，移除時間使用率，第三項改為平均每次充電量；不是新增日期範圍選擇器。

1. 依畫面位置定義資訊¶

短說明須讓人看懂：「僅包含已完成交易；進行中交易完成後納入」、「用量依交易開始日歸屬」、「Sessions 僅計算已完成且有充電量的交易」。平均值說明為「有效充電量 ÷ 充電 Sessions」。

今天仍在進行中，不表示今天已完成結算。這張圖是按 Session 開始日整理的使用趨勢，不是逐日電網電表的精確日切報表。（USG-DEC-001～004／006）

2. 日期怎麼算：30 個日曆日，交易歸開始日¶

Backend 依唯一 enabled Building 與其 timezone 決定 rangeStartDate／rangeEndDate；request 不傳 buildingId，FE 不用瀏覽器時區重算。（USG-DEC-001／003）

例如案場今天為 2026-09-03，日期為 8/5～9/3，共 30 日。查詢開始時間使用半開區間：

rangeStartDate 00:00（含） ───── rangeEndDate 次日 00:00（不含）

一筆交易只歸入 start_timestamp 在案場時區對應的日期，整筆最終電量與有效 Session 不因跨日拆分：

9/2 23:30 開始 ──── 跨午夜 ──── 9/3 01:00 完成
                                  ↓
                         整筆電量與 1 次有效 Session
                         都歸入 9/2（若為正電量）

在範圍內開始但仍 ACTIVE 的交易先不納入；完成後，下一次 REST 刷新補入原開始日，因此過去某日的數字可能增加。若開始日在 30 日範圍外，不能因為今天才結束而歸入今天。

3. Backend 計算規則：電量、次數、平均值¶

3.1 哪些交易要算¶

每日與整段摘要必須用同一套條件。不可直接使用 transactions.size() 當有效次數。（USG-DEC-002／004）

3.2 三項公式¶

validEnergyKWh = SUM(符合條件的 energy_consumed，單位 Wh) ÷ 1000
validSessionCount = COUNT(COMPLETED 且 energy_consumed > 0)
averageEnergyPerSessionKWh = validEnergyKWh ÷ validSessionCount

• 平均值由 Backend 在同一 read model 計算，用 decimal 與明確 rounding；FE 不自行相除或重算摘要。
• validSessionCount＝0 時平均值回 null，FE 顯示「—」及「尚無有效充電 Session」，不是 0 kWh／次，也不可除以零。
• 電量／次數為 PARTIAL／ERROR 時，平均值不能標完整。
• 異常 Completed 排除筆數要可見，不能把 null 當 0 後靜默忽略。（USG-DEC-006）

3.3 資料來源必須與即時負載分開¶

既有 e_transactions
status／energy_consumed／start_timestamp
              │
              ├─ 本票 30 日用量
              └─ #1486 今日已完成充電量（重用今日 bucket）

MeterValue Power.Active.Import
              └─ #1462 案場即時負載（不是本票用量公式）

Usage 只讀已保存的交易結果；不查 raw MeterValue 估算、不呼叫 MeterValueTariffCalculationService、不做費率時段／帳務邊界分段，不建立第二套電量寫入公式。Live Load 算法不能回頭改寫 Usage。（USG-DEC-010）

4. 每日 0、未知、整段無使用：畫面不能混為一談¶

正常／部分可用的每日 series 必須升冪包含恰好 30 個日期；每個 bucket 至少有 date、validEnergyKWh、sessionCount、bucketStatus。（USG-DEC-007）

全部 30 日成功但沒有有效使用¶

sourceStatus＝COMPLETE、dataState＝EMPTY，仍回傳 30 個零值 bucket；摘要為 0 kWh／0 次／null。（USG-DEC-008）

FE 保留容器、使用中性色，顯示：

最近 30 日尚無有效充電紀錄
完成充電後，使用趨勢將顯示於此

三項摘要顯示 0 kWh／0／—。不用紅黃警示、不顯示載入失敗、不建立「需留意事項」，也不建立假交易。

5. 更新失敗與恢復¶

所有 Usage 資料與「今日已完成充電量」共用 Overview 首載／5 分鐘／手動刷新；每輪只有一個 Overview request，不另設 Usage API／timer／WebSocket，不重建 Dashboard socket。（#1424 DEC-032）

lastSuccessfulAt 與 error metadata 由 Backend／已成功 snapshot 提供，不用本機時間冒充來源更新。未達過期門檻也仍須標「更新失敗」。Cache key 綁定 Backend-resolved buildingId，不跨案場沿用。

Backend 隔離子查詢、提供可診斷 error code／status／updatedAt，不洩漏敏感 exception；不新增專用 Backend 歷史 cache。刷新只讀 Overview，不重算 Transaction／MeterValue／Billing，不用 production fixture fallback。（USG-DEC-009）

6. FE／Backend 交付範圍¶

明確不做（USG-DEC-005）： 時間使用率 label／數值／Tooltip／placeholder，以及 timeUtilizationPercent、availableConnectorHours、歷史啟用區間分母、availability history、利用率 threshold／排名／告警。原有 durationSeconds 及其其他用途不受影響。

另不做 7／90 日／自訂範圍、Usage history export、交易／MeterValue 明細表、Usage WS publisher，或電量／Session 的寫入、修正、重算操作。

7. 驗收清單與 Fixture¶

• 日期為案場時區的最近 30 日且含今天；每日升冪恰好 30 桶，今天標示進行中。
• kWh／Sessions 切換不改日期、不影響 socket；沒有額外日期範圍控制。
• 開始日半開區間、跨日歸屬與完成後補原日期正確，不拆 MeterValue。
• 電量只加 COMPLETED 非 null、非負 Wh 並 ÷1000；Sessions 只計正電量；0 Wh 本身不報錯。
• null／負值 Completed 排除筆數可見且 PARTIAL；ACTIVE／CANCELLED／ERROR 不誤列排除異常。
• 平均由 Backend decimal 計算、顯示兩位；0 次為 null／—，FE 不重算。
• Usage 不查 raw MeterValue、不用 MeterValueTariffCalculationService、不受 Live Load 計算改變。
• 單日 0／null 視覺不同；漏日期不補 0；全段成功零值為 COMPLETE＋EMPTY、0／0／—。
• Initial Error 為—與 Error 圖；Refresh Error 保留同案場資料＋lastSuccessfulAt，按 Backend deadline 轉 STALE，成功後恢復。
• 單一來源失敗不拖垮其他區塊，無 fixture fallback、無業務 mutation。
• UI／API 均無時間使用率及其分母／threshold。

正常 Mock 保留，另外提供：單日 0＋另一日 null 的 PARTIAL、30 日 Empty、Initial Error、Refresh Error、有舊資料的 Stale、Recovery；錯誤文字可被螢幕閱讀器讀取，不只靠顏色。

8. 決策索引與查核背景¶

001～009 於 2026-09-03、010 於 2026-09-07 已確認；早期「狀態待確認」已由 007～009 定案。附件 #1110 的時間使用率是舊設計；目前視覺以 v0.4／#1121 的平均每次充電量與 30 個日期桶為準，版本套件依 #1422 管理。

既有程式碼查核（沿用舊票，本次未重新查 DB）： e_transactions 有 status、start_timestamp、stop_timestamp、meter_start／stop、energy_consumed、duration_seconds。TransactionService 完成交易時以 meterStop－meterStart 寫 Wh，狀態為 COMPLETED；既有狀態含 ACTIVE／COMPLETED／CANCELLED／ERROR。費率分段 service 保留原帳務用途，不帶入 Usage。

2026-09-03 A17 基線，範圍 8/5～9/3（不是固定驗收值）： Building BLD000000014，4 CP／12 Connector；78 COMPLETED（77 正電量、1 零、0 null／負值），另 1 ACTIVE，10 筆跨日；78 筆最終電量均與 meterStop－meterStart 一致。有效電量 2171.915 kWh、77 次、平均 28.21 kWh／次；excludedEnergyTransactionCount＝0。

只供追溯、不是 V1 要做的指標： 原基線零 Wh 交易 15 秒／EVDisconnected，正電量最短 69 秒；有效 Sessions duration 合計 1,124,353 秒（312.320h），38 筆與 timestamp 差 -1 秒、為秒級截斷，timestamp 合計 312.331h。當時 12 Connector 皆屬 enabled CP、30 日無新增，以當前 12×30×24 分母曾算 3.6148%，Mock 4.08% 為假資料。這段「時間使用率」探索已撤回，不能據此恢復分母、設備歷史或利用率功能。

需求管理與本次編輯¶

• 本票仍是已確認需求的追蹤票，不代表已完成開發或通過測試；指派、狀態、進度、附件與父子關係均維持原狀。
• 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 契約）；功能實作時仍須遵循主票與本票驗收。