專案

一般

配置概況

動作
複製連結

Feature #1422

進行中

[功能開發] Backend Admin 營運 Dashboard（全案場適用，A17 首站）

是由 陳國瑋 於 約 2 個月 前加入. 於 15 天 前更新.

狀態:
New
優先權:
Normal
被分派者:
-
開始日期:
完成日期:
完成百分比:

0%

預估工時:
(總計: 0.00 小時)

概述

閱讀方式與需求定位

請並排開啟 HTML Mock v0.4，依下方 01 → 08 的順序閱讀：由上到下，同一列由左到右。編號是本 Description 的對照索引，尚未加在 Mock 畫面上。

本功能把目前空白的 Branch Admin「Dashboard」做成唯讀營運總覽，讓使用者快速看懂設備、供電、充電用量與結算狀態；需要處理事情時，再前往既有管理頁。不改變充電、輪充、Queue 或帳務作業邏輯。

  • 適用所有案場；A17 只是 Mock 展示與首站驗證案例，不能把其名稱、數量或設定寫死。
  • Mock 中的數字都是假資料，僅用來對照畫面，不是正式驗收的固定數值。
  • 目前最新 review 套件為 v0.4 Draft（2026-09-16），已同步本 Description 與已確認的 Drawer／摘要分類決策；仍非 v1.0 開發基準。
  • 第 01～08 節說明畫面；第 09 節集中說明資料更新與異常狀態；第 10～12 節供開發、驗收與版本追蹤。各子票保留完整決策細節。

畫面配置與對照圖

下圖表示桌面版的區塊位置，不表示各區實際尺寸。左側 Sidebar 是案場識別與導覽；主內容的閱讀順序如下：

左側 Sidebar      主內容（由上往下）
                  ┌─────────────────────────────────────────┐
                  │ 01 頁首：案場名稱      連線／更新／刷新    │
                  ├─────────────────────────────────────────┤
                  │ 02 需留意事項                           │
                  ├─────────────────────────────────────────┤
                  │ 03 六張 KPI：03-1 → 03-2 → … → 03-6     │
                  ├─────────────────────┬───────────────────┤
                  │ 04 案場即時負載      │ 05 群組容量       │
                  │    目前功率＋趨勢    │    與 Slots       │
                  ├─────────────────────┴───────────────────┤
                  │ 06 Connector 即時狀態                   │
                  │    五項摘要 → 預覽卡片 → 查看全部         │
                  ├─────────────────────┬───────────────────┤
                  │ 07 30 日充電用量     │ 08 結算流程       │
                  └─────────────────────┴───────────────────┘

小螢幕依同一內容順序換行；各區的卡片數與欄數依下方規則調整，不以縮小文字或頁面水平捲動容納內容。

01｜頁首與左側案場識別

要讓使用者知道：目前正在看哪個案場，以及資料是否仍在更新。

對照 Mock 頂部「案場營運總覽」與左側「目前案場」：

位置 顯示內容 行為與規則
左側案場識別、主內容標題下方 Backend 回傳的案場名稱；Mock 為「寶台 A17・地下停車場」 唯讀識別，不是案場切換選單。
頁首右側第一行 即時連線正常／無法連線／連線中斷 只表示兩個即時區塊的 WebSocket 連線情況，不代表所有設備正常。
頁首右側第二行 一般資料最後更新時間 對應最近一次 Overview 資料；與即時連線狀態分開顯示。
右側刷新按鈕 重新整理一般資料 取得一次 Overview，不重建 WebSocket；整頁重新載入才重新嘗試連線。

案場範圍： 每個 EMS Branch 必須恰好有一個 enabled Building，由 Backend 決定本次資料範圍。若零筆或多筆，顯示「案場設定異常」並隱藏營運數字；不可任選第一筆、跨案場加總或填入 0。

Sidebar 中其他導覽是 Mock 的展示脈絡，不代表本需求要重新開發這些管理頁；正式版沿用既有選單、路由及權限。

開發對照： #1424 DEC-029～033。Backend 提供案場識別、時間與狀態；FE 顯示並處理設定錯誤。

02｜需留意事項

要讓使用者知道：哪些「已確認的狀況」值得進一步查看。 這是摘要，不是新的告警、派工或自動修復系統。

Mock 目前顯示「3 類」：Connector 故障 1 個 Connector、Queue 阻塞 2 個項目、結算未完成／異常 2 個步驟。3 是類別數，不是 1＋2＋2，也不是不同設備總數。

類別、數字與點擊目的地

只顯示數量大於 0 的類別，依以下固定順序排列；不依數量、時間或顏色重排。

順序 類別 數字代表什麼 點擊後
1 Charge Point 離線 既有 OCPP 連線狀態為 OFFLINE 的 CP 數；同一 CP 只計一次 既有 /cp/list
2 Connector 故障 既有狀態為 FAULTED 的 Connector 數；同一 Connector 只計一次 既有 /connector/list
3 即時負載資料不完整 「目前負載」為 STALE／PARTIAL／ERROR 時算 1 類、受影響數量固定 1 同頁 04 案場即時負載
4 Queue 阻塞 既有 BLOCKED Queue 項目數；依 Queue entry ID 去重 同頁 06 Connector 即時狀態
5 結算未完成／異常 Backend 已確認未完成或異常的結算步驟數 同頁 08 結算流程
  • 同一類別內去除重複；不同類別不推論共同原因，也不跨類合併。
  • 只看「目前負載」的資料品質；歷史圖表的缺口不另外增加此摘要，尚未結束但資料完整的時間區間也不是異常。
  • CP 離線與尚未結束的充電 Session 分別呈現，不推論「仍在離線充電」或「待 reconciliation」。
  • 所有非零類別全部顯示。桌面自動換行、平板兩欄、手機單欄；不做 Top N、展開、Drawer 或分頁。

正常、部分失敗與全部失敗

情況 使用者看到什麼
完整查詢成功，確定 0 類 保留精簡狀態列：「目前沒有需留意事項」，附「所有已檢查的狀態目前皆正常」與更新時間。
部分來源失敗 顯示已確認的項目，註明「部分狀態暫時無法確認，顯示數量可能不完整」；有項目時標題為「已確認 N 類項目需要留意」。
整體無法取得 顯示「需留意事項暫時無法取得」，數量為未知，不顯示 0 類正常。

每張卡為單一連結，支援滑鼠、Tab 與 Enter。同頁導覽會把焦點移至目標區塊；不自動篩選列表、不新增詳情 API，也不執行任何作業。

開發對照： #1463 ATT-DEC-001～008；更新方式為第 09 節的共用 REST。

03｜六張 KPI：由左到右

要讓使用者快速掌握六項營運數字。六張全部使用一般 REST 更新，不訂閱 WebSocket。 因此可能與下方即時區塊有約 5 分鐘更新差異，這是已接受的 V1 行為。

03-A｜畫面、含意與操作對照

編號／Mock 名稱 Mock 假資料 要回答的問題 整卡點擊後
03-1 Charge Point 連線 4 / 4 台啟用；0 台離線、0 台尚未確認 已啟用的 CP 中，有多少目前被系統記錄為在線？ /cp/list
03-2 Connector 可服務 11 / 12 個；1 個不可服務，其中 1 個故障 有多少 Connector 沒有已知故障、不可用或連線問題？可服務不等於空閒。 /connector/list
03-3 充電進行中 3 Sessions 系統目前有幾筆尚未結束的充電 Session？不保證每筆此刻都正在輸出電力。 /connector/list
03-4 等待供電 2 個；另有 1 個未插槍（不計入） 有多少 Connector 的 Queue 狀態為 ELIGIBLE、正在等候供電？ /connector/list
03-5 今日已完成充電量 84.6 kWh；已完成 6 次充電 歸屬今天、已完成且符合條件的充電，共有多少電量與次數？ 同頁 07 用量區（#usage）
03-6 上月電費 —；8 月結算未完成，10 / 11 筆 上一完整日曆月的門牌帳單應收電費總額是多少？ 同頁 08 結算區（#billing）

03-B｜Backend 計算與 FE 呈現規則

  1. CP 連線： 分母是本案場 enabled CP；分子使用既有 persisted OCPP ONLINE 狀態。ONLINE＋OFFLINE＋UNKNOWN＝啟用總數。disabled 另列，不算離線；Dashboard 不用 Heartbeat 時間另建連線判定。
  2. Connector 可服務： 分母只含 enabled CP 下的 Connector；分子還必須同時符合 parent CP ONLINE，以及既有狀態為 AVAILABLE、PREPARING、ENQUEUED、CHARGING、SUSPENDED_EV、SUSPENDED_EVSE、FINISHING 或 RESERVED。FAULTED、UNAVAILABLE、未知狀態、parent CP 非 ONLINE 都排除。不可服務＝總數－可服務；故障只作「其中」說明，不重複加總。
  3. 充電進行中： 每個 Connector 沿用既有 current transaction 解析規則，最多取一筆 canonical ACTIVE transaction（系統認定的目前交易），忽略較舊的孤兒 ACTIVE。Queue 或尚未建立 StartTransaction 的操作不算。CP 暫時離線／停用時，尚未結束的 Session 仍計入，但不推論離線充電。小字固定「依未結束的充電 Session 計算」，不再顯示功率。
  4. 等待供電： 只計 ELIGIBLE 的不同 Connector；多筆 Queue 不重複計。NOT_PLUGGED 另列且排除已屬 ELIGIBLE 者，不加回主數字；BLOCKED 放在需留意事項，不新增等待逾時或 SLA。
  5. 今日已完成充電量： 直接重用第 07 節 Usage 的今日日期桶（rangeEndDate），不再建立另一套今日查詢；不估算進行中交易、不做昨日同時段比較。交易依開始日歸屬，跨日不拆分。
  6. 上月電費： Backend 依案場時區取上一完整日曆月，使用該案場 e_bill_settlement.cost_predict；paid／pending 都納入。全部計算 COMPLETE 才回金額，否則回 null，FE 顯示「—」、月份及完成筆數。不顯示部分合計、不退回更早月份、不做本月預估。

FE 直接呈現 Backend 的聚合結果，不從 Connector 預覽卡重算。第 03-3 的 Session 數與第 06 節的「充電進行中」分類，來源與含意不同，不要求數字相等。

03-C｜排版與互動

畫面寬度 KPI 排列
≥ 1240 px 6 欄 × 1 列
768～1239 px 3 欄 × 2 列
320～767 px 2 欄 × 3 列

固定上述順序，六張完整保留，不用輪播或水平捲動。每張卡是一個原生連結、只有一個 Tab 焦點；Loading／Error 等狀態仍可導覽。長文案換行，數字更新不逐卡朗讀；狀態顯示遵循第 09 節。

開發對照： #1486 KPI-DEC-001～011；Usage 公式另見 #1461。

04｜案場即時負載（中段左側）

要讓使用者知道：現在充電功率是多少，以及這段時間的負載如何變化。

由區塊上到下閱讀：

  1. 右上時間切換： 即時／今日／7 日；預設「即時」。
  2. 大數字「目前功率」： 全案場目前充電功率，單位 kW；Mock 為 21.84 kW。它是目前值，不是整段期間的平均。
  3. 下方折線圖： X 軸是案場當地時間；Y 軸是「區間平均總充電功率（kW）」。每個點代表下表的一段時間，不是累計用電量 kWh。
檢視 X 軸涵蓋範圍 每個點代表的時間區間
即時 最近 60 分鐘 1 分鐘
今日 案場當地今天 00:00 至現在 15 分鐘
7 日 含今天的最近 7 個案場日曆日 1 小時

7 日不是往回推固定 168 小時。 例如今天是 9/14，日曆範圍從 9/8 00:00 到現在。

數值如何取得

  • Backend 使用有效、未過期的最新電表功率，先統一 W／kW 單位，再建立案場功率時間線。
  • 圖表採時間加權平均：例如一分鐘內前 30 秒為 10 kW、後 30 秒為 20 kW，該點為 15 kW。不能直接把不同頻率、不同時間的 raw MeterValue 列相加或算術平均。
  • 已確認且資料新鮮的非充電狀態可為 0；充電中的功率超過 cutoff 仍未知時，對應區間為 null＋PARTIAL。圖表留缺口，不補 0、不插值、不跨缺口連線，也不只加總已知部分冒充完整總量。
  • 「時間區間尚在進行中」（OPEN）與「資料是否完整」（COMPLETE／PARTIAL／ERROR）分開表示；OPEN 不等於異常。

更新與範圍邊界

三組完整歷史資料隨同一次 Overview 回傳，切換頁籤只切換已取得資料，不再發 API 或重建 WebSocket。刷新保留所選頁籤，該頁籤無資料／失敗時不自動跳到別的範圍。

WebSocket 只更新目前功率、三種範圍的進行中區間，以及跨界時剛結束的區間；FE 依 buildingId＋rangeCode＋bucketStartAt 取代對應資料，不自行積分或平均。

本區不顯示案場契約容量、容量利用率或剩餘容量。 不得把各 Charge Group 的契約容量加總，當作案場契約容量。

開發對照： #1462 LOAD-DEC-001～007；斷線處理見第 09 節。

05｜群組容量與 Slots（中段右側）

要讓使用者知道：各充電群組目前的負載、群組自身容量，以及供電名額占用情形。

Mock 依序列出 B1、B2、B3 三個 Charge Group；這些名稱與數量只是範例，正式版依 Backend 資料顯示，不固定三組。

由上到下的位置 內容與意義
區塊右上 既有時段資訊，例如 Mock 的「離峰時段」。
每個群組標題列 群組名稱、目前功率／該群組自身契約容量，單位 kW；例如 B1 的 7.33 / 99 kW。
群組容量條與說明 該群組自身容量／餘裕，以及目前充電、等待或 BLOCKED 情況。
群組 Slots 已占用名額／可配置名額；例如 1 / 14 Slots。Slots 是既有供電名額概念，不是電量。
區塊底部 OCCUPIED（已占用）、WAITING（等待）、RESERVED（保留）摘要；Mock 為 3／3／0。

Backend 沿用既有 SlotCalculator、群組容量與 Queue 狀態語意彙整 occupied／reserved／available slots；等待資訊可含 source、status、priority、statusReason、waitingSince／持續時間。只讀取和顯示，不更改名額分配、輪充派送、優先序或等待門檻。

本區使用一般 REST 更新，不跟著 WebSocket 每次變動；因此不要求與第 04 節的即時功率在每一刻完全同步。

開發對照： #1462（負載／群組）與 #1424（資料取得）。

06｜Connector 即時狀態（中下段、整列）

要讓使用者知道：有哪些 Connector，哪些值得先查看，以及個別設備的連線、運作與排隊狀態。

依畫面順序：區塊標題與資料時間 → 五項摘要 → Connector 預覽卡 → 顯示筆數／查看全部。

06-A｜五個狀態摘要：純資訊、不可點擊

固定順序 固定顯示名稱 Backend code
1 需留意 NEEDS_ATTENTION
2 充電進行中 CHARGING
3 準備／排隊 WAITING
4 可用 AVAILABLE
5 其他狀態 OTHER

Backend 對完整集合分類，每個 Connector 由上到下命中第一類，只屬於一類，五類相加必須等於總數；需留意數＝abnormalTotal。Unknown／資料不足歸「需留意」，NOT_PLUGGED 歸「其他狀態」。完整條件沿用 #1423 UI-DEC-015。

  • 有 Connector 時固定顯示五項，包括 0，不隨更新隱藏或重排。
  • 總數 0 時隱藏五項摘要，顯示 Connector 空狀態。
  • 五項均不可點擊、不進入 Tab 順序、不開 Drawer、不套篩選、不導頁，也不發 request。
  • FE 使用 Backend 的完整統計，不從畫面上少數預覽卡計算。

06-B｜預覽卡：少量不撐滿，大量保留總覽

Backend 對完整集合依已確認的優先順序與穩定的同順位排序產生最多前 8 筆，一起回傳 total、abnormalTotal 及每筆異常原因。FE 不重排、不自行判斷異常，也不把螢幕寬度送給 Backend。

畫面寬度 最多顯示卡片數 若案場只有 1 或 2 個
≥ 1240 px 8 只顯示實際 1／2 張，不補空卡、不把假資料補滿。
640～1239 px 6 同左，按可用寬度排列。
< 640 px 4 同左，維持可讀的卡片排列。

例如 30 個 Connector 的桌面版顯示前 8 張，註明「顯示 8 / 30，另有 22 個未顯示」，由「查看全部」進入完整清單；手機顯示前 4 張。隱藏異常數使用 Backend 異常總數扣除可見異常數，不把未顯示者當成正常。

每張卡保留 Connector／Charge Point 識別、位置／類型及已有的功率、Queue 等資訊；以下狀態必須分層，不合成一個「在線／離線」：

同一個 Connector
  ├─ 所屬 CP 的 OCPP 連線：ONLINE／OFFLINE／UNKNOWN
  ├─ Connector 運作狀態：AVAILABLE／CHARGING／FAULTED…
  └─ Queue 狀態與原因：ELIGIBLE／BLOCKED／NOT_PLUGGED…

Heartbeat／BootNotification 不能把 FAULTED 或 CHARGING 覆寫成 AVAILABLE；Connector runtime 以既有 StatusNotification 為主要來源。未知功率顯示「—」，不是 0。

點預覽卡開啟單支詳情，再依既有入口前往管理頁／Engineer Tools；目的頁仍需原有權限，Dashboard 不授予操作能力。

06-C｜「查看全部」：完整清單 Drawer

Drawer 不是另一個頁面，而是覆蓋在目前 Dashboard 上、從右側滑出的暫時面板。 桌面保留一部分 Dashboard 作為背景脈絡；平板與手機可改為全螢幕 Sheet。關閉後回到原本 Dashboard 位置，不會把使用者帶離本頁。

本區有兩種用途不同的 Drawer，不能混成同一個資料流程：

入口 開啟內容 用途
點一張 Connector 預覽卡 單支 Connector 詳情 Drawer 查看該 Connector 的詳細資訊。
點「查看全部」 Full List Drawer 搜尋、篩選及分頁瀏覽目前案場的完整 Connector 清單。

Full List Drawer 支援搜尋（Connector ID、Charge Point ID、車位）、「摘要分類」與 Charge Group 篩選。「摘要分類」固定提供：全部、需留意、充電進行中、準備／排隊、可用、其他狀態。首頁五項摘要仍是純資訊，不可點擊，也不會替 Drawer 預先套用條件。

目前 Dashboard
      │ 點「查看全部」
      ▼
┌─ 右側 Full List Drawer ─────────────┐
│ 搜尋 [                    ]          │
│ 摘要分類 [全部 ▼]  Charge Group [▼] │
│ 完整清單：固定優先排序、每頁 20 筆    │
│ 上一頁／下一頁、頁次／總筆數          │
└─ 關閉後回到原 Dashboard ────────────┘
  • 正式版使用／擴充既有 POST /api/connector/search，size 固定 20，sortMode 固定 DASHBOARD_PRIORITY；沿用 page 與 Spring Page 回應格式。
  • 「摘要分類」使用穩定的 displayBucket 條件；未傳代表「全部」，可傳 NEEDS_ATTENTION／CHARGING／WAITING／AVAILABLE／OTHER。
  • V1 不把 Connector runtime status 與 Queue status 混成另一組篩選選項；既有管理頁的原始 status 篩選維持不變。
  • 先對完整資料集搜尋與篩選，再排序、分頁；不能只過濾已下載的 8 張卡或當頁資料。
  • 0～20 筆不顯示換頁控制；30 筆為 2 頁、100 筆為 5 頁。改搜尋／篩選時回第 1 頁。
  • 關閉再開保留搜尋、篩選及頁碼；重新載入或離開 Dashboard 後返回則重設。只存在本次頁面記憶體，不存 URL、瀏覽器儲存或 Backend 偏好。
  • 不提供排序控制、每頁筆數選單、直接跳頁、Grid／Table 切換或 virtualization；不透過 WebSocket 推送完整清單。既有 /connector/list 的排序不變。

開發對照： #1423 UI-DEC-006～021、#1424 DEC-034～043。預覽區塊由 WebSocket 整包取代；完整清單仍走 REST。

07｜30 日充電用量（底部左側）

要讓使用者知道：最近 30 天完成了多少充電、每天分布如何，以及每次平均充多少電。

區塊固定最近 30 個案場日曆日（含今天），保留右上的 kWh／Sessions 切換；不提供 7／90 日或自訂範圍。

圖表與右側三項摘要

位置 資訊 定義
圖表 X 軸 日期 依案場時區，固定 30 個每日資料桶。
kWh 模式 Y 軸 每日有效充電量（kWh） 當日符合條件、已完成交易的最終電量合計。
Sessions 模式 Y 軸 每日有效充電次數（次） 當日 COMPLETED 且 energy_consumed > 0 的交易筆數。
右側第 1 項 有效充電量 30 日有效電量合計；Mock 2213.6 kWh。
右側第 2 項 充電 Sessions 30 日有效次數；Mock 136。
右側第 3 項 平均每次充電量 有效充電量 ÷ 有效次數，由 Backend 計算；Mock 16.28 kWh／次。

日期歸屬與資料來源

9/13 23:30 開始 ──── 跨午夜 ──── 9/14 01:00 結束
                                  ↓
                     完成後，整筆歸入 9/13
                     不拆成 9/13 與 9/14 兩筆
  • 只使用 completed transaction 已有的最終 energy_consumed，按既有單位換算 kWh，以 start_timestamp 判斷歸屬日。
  • ACTIVE 不估算；0 Wh 不算有效 Session；異常 Completed 排除並標示 PARTIAL。
  • 不讀 raw MeterValue 重算用量、不呼叫 MeterValueTariffCalculationService，也不按費率時段或帳務邊界切分。
  • 查詢成功但某日無使用，該日為 0；未知為 null。30 日全無使用時，顯示 0 kWh／0 次／—，並提示沒有紀錄，不建立告警。
  • 平均每次充電量在 0 次時回 null，不除以零。
  • 初次失敗顯示 Error；刷新失敗可保留同案場最後成功資料與時間，標示失敗／過期，不冒充新資料。

時間使用率已移除，不再實作其分母、門檻或資料查詢。Usage 與第 04 節 Live Load 是不同資料來源與公式。

開發對照： #1461 USG-DEC-001～010；更新方式為共用 REST。

08｜結算流程（底部右側）

要讓使用者知道：最近有結算資料的那一期，四個步驟分別完成到哪裡。 沿用 Mock 的四列流程，不改成「本月帳務摘要」。

Mock 標題為「8 月結算流程」。正式版月份由 Backend 依最近結算資料回傳 periodYear／periodMonth／timezone，FE 只格式化，不自行用今天推算。

由上到下 使用者看到的內容 Mock 假資料
1. Connector 結算 設備電量與費率計算的完成狀態 11 / 12
2. 門牌結算 私人與公用費用歸戶的完成狀態 10 / 11
3. 帳務覆核 既有帳務 paid／pending 分布與覆核狀態 7 paid、4 pending；進行中
4. 發票結算 既有發票結算狀態 draft；未完成

四列均為純資訊、不可點擊，不在 Dashboard 執行計算、重跑、覆核、請款或開立發票。既有 Backend aggregation／DTO 只讀取狀態，不改月結排程。

Mock 對照： v0.4 已在結算標題顯示資料年份，並在 footer 提供「查看帳單」→ /bill/list 與「查看請款／發票」→ /invoice/list；四個流程列仍為純資訊、不可點擊。

別與 03-6「上月電費」混淆：

03-6 上月電費 08 結算流程
目的 看應收電費金額 看四步驟的完成狀態
期間 上一完整日曆月 最近有結算資料的期間
期間是否一定相同 不一定 不一定
不完整時 不顯示部分金額，保留完成筆數 各列呈現實際狀態

開發對照： #1460 BIL-DEC-001～003；更新方式為共用 REST。

09｜共用規則：資料更新、異常與權限

09-A｜只保留兩條清楚的資料路徑

首載／每 5 分鐘／手動刷新
            │
            ▼
GET /api/dashboard/overview
            ├─ 六張 KPI、需留意事項
            ├─ 群組容量／Slots、30 日用量
            ├─ 結算流程、上月電費
            └─ 負載三組完整歷史；首載另提供即時區初始畫面

一條 Dashboard WebSocket
            ├─ Connector 即時狀態：整個預覽區塊取代
            └─ 案場即時負載：目前值＋進行中／剛結束的區間

每次一般更新只呼叫一次 Overview，共用一個 5 分鐘週期，不為各區另設 timer 或 API。六張 KPI 不訂閱 NETWORK_HEALTH_UPDATED／CONNECTOR_OVERVIEW_UPDATED；不影響其他既有功能使用同名事件。

WebSocket 最小 message type 固定為 DASHBOARD_LIVE_SNAPSHOT、CONNECTOR_LIVE_BLOCK_UPDATED、LIVE_LOAD_UPDATED。WebSocket 接手後，後續 REST 刷新可更新一般資料與歷史，但不能覆寫兩區的 live state，也不能在斷線時充當即時備援。

09-B｜WebSocket 連不到，明確提示即可

連線情況 FE 行為
正常 更新兩個即時區塊，顯示連線狀態與資料時間。
首次連線失敗 頁首與兩區提示無法連線；已有初始資料則保留並標示未即時更新，無資料顯示「—」。
連上後中斷 保留最後資料與最後更新時間，明示「已停止更新」。其他 REST 區塊照常更新。

不做 REST polling 備援、自訂 backoff／jitter、背景自動重連、sequence／gap recovery、固定 5 秒 coalescing、2 秒傳播 SLO 或專用 Retry 流程。 使用者重新載入整頁才再建立連線；手動刷新一般資料不重連。

以上 DEC-031／032 取代早期較複雜的傳輸提案；不改資料公式或作業流程。

09-C｜狀態字典：0、未知、失敗不可混用

狀態 中文含意與呈現
Loading 還在取得資料，顯示載入樣式，不先填 0。
COMPLETE＋0 確認成功且數量為零；依各區規則顯示 0 或空狀態。
PARTIAL 只有部分資料可確認；保留可信結果並標明不完整，不能宣稱整體正常。
ERROR 該來源無法取得；未知數值為 null／「—」，不轉成 0。
刷新失敗、有舊資料 只保留同 building 最後成功資料，顯示 lastSuccessfulAt 與失敗提示，不假裝更新成功。
STALE 資料已過期，顯示過期與時間；不可當成正常即時數據，也不可納入需要即時性的完整總功率。

Backend 回傳 generatedAt、來源 updatedAt、dataStatus、freshness 及必要的 lastSuccessfulAt。單一子查詢失敗只影響相依區塊，其餘繼續顯示，整體標示 PARTIAL。

資料過期 cutoff 由 Backend 依來源設定全系統共用預設值，所有案場共用；FE 不硬編碼秒數。不做 per-building override、設定資料表、設定 API／UI、權限或 audit trail；A17 僅驗證預設值。

未知 code 不當成 AVAILABLE／正常。FE 以 code 判斷、中文 label 顯示；所有狀態須有文字或圖示，不只靠顏色。Production API 失敗絕不能改用 Mock 假資料。

09-D｜權限與案場隔離

  • 沿用既有 SS3A dashboard function：administrator、power_user、association、dealer 四個 role 的 Dashboard 內容與唯讀能力一致，不新增 role／function。
  • 僅有 adm_user、member、hq 或 engineer，且未取得 dashboard function 時，Overview／ticket API 回 403；多 role 使用者具允許權限時可存取。
  • FE 選單／路由與 Backend function 一致，未授權不得先載入或短暫顯示資料；隱藏選單不能取代 API／ticket 授權。
  • Overview request、ticket request、WebSocket URL 不帶 FE 指定的 buildingId。Backend 解析唯一 enabled Building，response、ticket binding 與 event envelope 帶相同 buildingId；不符案場的事件不得套用，快取不得跨案場。
  • Deep link 沿用目的頁權限，不因可看 Dashboard 就可執行 Start／Stop、Reset、Queue、帳務或 Engineer command。

開發對照： #1424 DEC-028～042。此區集中承接各畫面的共用規則，不另增作業功能。

10｜開發工作分工與子票索引

畫面改動由 FE 負責，但正式資料聚合、API、WebSocket、權限與驗證也在本需求範圍內，不能只完成靜態畫面。

工作 需要交付的內容
Backend／API DashboardController、DashboardService、typed Overview 與各區 DTO；唯一 Building resolver；依 02～08 節建立唯讀聚合。
Backend／Connector 共用預覽排序與分類 service、Top-8／完整統計；補齊既有 search DTO／query 的 displayBucket、搜尋、Charge Group、DASHBOARD_PRIORITY 與固定分頁，不影響管理頁原始 status／排序。
Backend／WebSocket 一條案場 Dashboard socket、ticket 授權、三種最小事件；Connector 區塊取代、負載目前值與區間更新。
Backend／權限文件 Overview／ticket 對應既有 dashboard function；冪等 migration 確認 role-function mapping，Java 不硬編碼 role 名稱；重啟後驗證授權快取。補 OpenAPI @Schema、method／DTO 欄位註解與 contract tests。
FE 實作 react/branch/app/(dashboard)/dashboard/page.tsx、OpenAPI types 與 React Query overview hook；依畫面順序完成元件、圖表、Drawer、狀態、RWD、鍵盤操作與固定導覽。
DB／效能 優先唯讀聚合，避免 N+1、無界查詢及重複聚合；先量測，必要時才提出 query 或普通 index 優化。
QA／發布 Backend repository／service／security／contract tests，FE fixture／互動／RWD，首站 E2E、效能 baseline、發布 smoke 與下一工作日檢查。

DB 不新增 Dashboard snapshot table、專用 cache、效能排程、UNIQUE／FOREIGN KEY／CHECK／cascade constraint。不得為本 Dashboard 改動 Queue lifecycle、priority、Slot allocation、Rotation dispatch、OCPP command、月結／費率作業。

查閱細節時，直接找對應子票

子票 對應本文 已確認決策
#1423 Connector UI／UX 06 UI-DEC-006～021（其餘既有 UI 決策沿用）
#1424 REST／WebSocket 與共用規則 01、09、10 DEC-028～043；較早未被取代的技術條件仍見子票
#1463 需留意事項 02 ATT-DEC-001～008
#1486 KPI 03 KPI-DEC-001～011
#1462 Live Load／群組 04、05 LOAD-DEC-001～007
#1461 充電用量 07、03-5 USG-DEC-001～010
#1460 結算流程 08 BIL-DEC-001～003

本次把散落的已確認決策併回所屬區塊，不再把已確認內容列在「待決策」底下。子票仍保留完整欄位、排序、狀態與驗收細節；本次不改子票內容、指派或進度。

11｜驗收、效能與完成條件

11-A｜依畫面走一次的驗收重點

對照區塊 必須驗證
01 頁首 唯一／零筆／多筆 enabled Building；案場名稱與隔離；即時連線與一般更新時間分開。
02 需留意 N 類不是受影響數量總和；固定順序、全部非零項目、類內去重；正常／PARTIAL／ERROR；五類導覽正確，不推論離線充電。
03 KPI 分子分母、canonical ACTIVE、ELIGIBLE／NOT_PLUGGED 互斥、開始日歸屬、上月全部 COMPLETE 才顯示金額；六卡全 REST、單一連結與正確欄數。
04 負載 即時／今日／7 日、X/Y 軸與時間加權；0 與 null 缺口；OPEN／FINALIZED 與品質分開；切換不發 API，斷線不備援。
05 群組 群組自身容量、Slots 與既有 Queue 語意；不把群組容量加總成案場契約容量。
06 Connector 0／1／2／8／9／30／100 筆；五類互斥、加總等於 total、需留意＝abnormalTotal，五摘要不可點；Top-8 的 8／6／4 截取與隱藏數量；Drawer 的「摘要分類」對應 displayBucket，搜尋完整集合、排序後每頁 20、開關保留／reload 重設。
07 用量 30 個日期桶、開始日跨日歸屬、只用已完成最終電量、正電量有效次數、平均值；全零／未知／部分失敗與舊資料保留。
08 結算 最近資料期間與四步驟狀態、純資訊列、兩個既有列表入口；不誤當上月金額或本月預估。
共用 四個允許 role／未授權 403、多 role、無效 ticket 拒絕 WS；null／0／unknown／large value；來源失敗隔離、同案場快取；production 無 fixture fallback。
  • 檢查 390／768／1024／1440 px 及各 breakpoint 臨界值，320 px 以上不產生頁面級水平捲軸。
  • 狀態、文字對比、focus 與鍵盤符合 WCAG 2.2 AA 基本要求；同頁導覽轉移焦點、支援 reduced motion，更新不逐卡 live announce。
  • Fixture 包含 Healthy／Critical／Partial／Stale／Empty／Large；KPI 載入、有效零、初次失敗、刷新失敗；WebSocket 正常、首次失敗、連線後中斷。
  • A17 staging E2E 覆蓋 offline、faulted、active transaction、stale meter、blocked queue、billing、partial data、403，並確認既有管理頁與 Connector 排序無回歸。

11-B｜實作前資料檢查與效能 baseline

以 A17 或具代表性等量資料做唯讀檢查，不把 Mock 數字當結果：

  • CP ONLINE／OFFLINE／UNKNOWN、runtime；Connector status／area／type 分布。
  • Active transaction 數與最長持續時間；各群組 contract／allocated／reserved／queue。
  • MeterValue 24 小時筆數、峰值與最新資料延遲；近 30 日 transaction／kWh／每日分布。
  • 最近結算資料期間的 Billing／Invoice 狀態；主要資料表筆數／分布及各 aggregate query 的 EXPLAIN。

Overview endpoint 記錄 P50／P95 baseline，附環境、資料量／分布、暖機、併發數、sample size 與量測起訖邊界。V1 不承諾固定 P95 < 1.5 秒 SLA；只有實測影響正常使用時才提出查詢／普通 index 優化，不預先增加架構。（PERF-DEC-001／DEC-042）

11-C｜E2E 與發布

功能實作的 E2E impact 為 Add；本次純 Description 整理為 No catalog change，不代表功能已完成或已通過測試。

優先級 長期案例範圍 執行 trigger
P0 Overview／ticket／WS 未授權拒絕、PARTIAL、stale safety Standard、Major、A17 release；適用時為發布阻擋條件
P1 四 role 正向、多 role、案場 scope、offline／faulted／active／Queue／billing／responsive Standard、Major、A17 release
P2 大量資料、未知 enum、效能 baseline Major、A17 release

實作階段依 maintain-ems-e2e-catalog 確認 Case ID 與 release pack；run-specific 結果放 test_report，不放長期 Catalog，Skip 不視為 Pass。

首站部署後做一次 smoke test（頁面／Overview／兩區連線或失敗提示／既有頁面），下一個工作日使用既有 application log、維運工具及 DB 負載資訊檢查。發現問題沿用既有 release／rollback 流程；不新增專用監控平台、metrics、instrumentation、自動告警、排程或 24 小時值守。（REL-DEC-001）

11-D｜Definition of Done

  • Product 確認各區數字定義、範圍，完成整體一致性 review。
  • Backend API、OpenAPI、SS3A mapping 與測試完成。
  • FE 各區、狀態、RWD、accessibility、deep link 完成。
  • 首站或代表性資料的 EXPLAIN／P50／P95 baseline 完成；必要優化完成。
  • A17 staging E2E 完成，結果與限制已記錄。
  • E2E Catalog 與 ai/02-backend-services.md、ai/03-database.md、ai/04-frontend.md 更新。
  • 首站 smoke test 與下一工作日既有 log／DB 負載檢查完成。

12｜文件版號與 Redmine 附件管理（DOC-DEC-001）

PDF、Markdown、HTML Mock 是同一套 review 文件，三份版號必須一致，每一版都新增到 #1422，不覆蓋、不刪除舊附件。

已發布版本索引

版本／日期 PDF Markdown HTML Mock 定位
v0.2 Draft／2026-07-25 #1108 #1109 #1110 初版快照；後續多項決策已取代部分內容，不可單獨當現行規格。
v0.3 Draft／2026-09-07 #1115 #1116 #1117 前一版 review 快照；保留供版本差異追溯。
v0.4 Draft／2026-09-16 #1119 #1120 #1121 目前 review 快照；整併 PKG-01～10、Drawer／摘要分類與 Full List 最小契約；尚非 v1.0。

後續版本規則

  • v0.x Draft： 討論階段快照。Redmine 決策與工作 Mock 可持續演進，到 review checkpoint 才一起發布下一套。
  • v1.0： 所有需求確認、整體一致性檢查與 Product review 完成後的開發基準；不可預先稱 v0.x 為最終文件。
  • v1.x： 不改主要範圍的澄清／文件修正；重大 scope／contract 改變須先在 Redmine 建立新決策，再決定 major version。
  • 三份封面／頁首、檔名、日期、版號及本索引一致。每版 note 記錄 decision cutoff、變更摘要與三個 attachment IDs。
  • 檔名固定為 backend-admin-dashboard-requirements-v{version}.pdf、同名 .md，以及 backend-admin-dashboard-mock-v{version}.html；舊 v0.2 不回溯更名。
  • 有新決策時下一 checkpoint 可發布 v0.4 Draft；全部確認後才發布 v1.0。版本索引只新增列，舊附件永久保留。
  • v1.0 前以本票及子票的現行 Description／較新已確認決策為需求依據；附件是當時的 review 快照，差異須明確標示。

Description 編輯紀錄：

  • 2026-09-16：發布 v0.4 Draft，修正 PKG-01～10，並同步 Drawer、「摘要分類」與 Full List 最小資料契約；舊版附件完整保留。
  • 2026-09-14：依附件 #1117 的實際畫面順序重整 Description，加入區塊配置、狀態分層、日期歸屬與資料流示意；未更動產品範圍。

決策補充（2026-09-16）： Full List Drawer 的篩選正式命名為「摘要分類」，直接使用首頁同一套 displayBucket；首頁五項摘要仍不可點擊，V1 不另建混合 runtime／Queue status 篩選。同步補上 Drawer 定義、Full List 最小 request／response 契約與驗收條件；本輪不發布新附件。

檔案

下載所有檔案
a17-ems-dashboard-requirements.pdf (429 KB) a17-ems-dashboard-requirements.pdf A17 EMS Dashboard 完整需求說明書 v0.2（17 頁） 陳國瑋, 2026-08-10 14:41
a17-dashboard-requirements.md (30.2 KB) a17-dashboard-requirements.md 需求說明書可編輯 Markdown source v0.2 陳國瑋, 2026-08-10 14:41
a17-operations-dashboard.html (43.6 KB) a17-operations-dashboard.html Dashboard 假資料 HTML mockup 陳國瑋, 2026-08-10 14:41
backend-admin-dashboard-requirements-v0.3.pdf (354 KB) backend-admin-dashboard-requirements-v0.3.pdf Backend Admin Dashboard v0.3 Draft review bundle 陳國瑋, 2026-09-07 05:08
backend-admin-dashboard-requirements-v0.3.md (31.4 KB) backend-admin-dashboard-requirements-v0.3.md Backend Admin Dashboard v0.3 Draft review bundle 陳國瑋, 2026-09-07 05:08
backend-admin-dashboard-mock-v0.3.html (112 KB) backend-admin-dashboard-mock-v0.3.html Backend Admin Dashboard v0.3 Draft review bundle 陳國瑋, 2026-09-07 05:08
backend-admin-dashboard-requirements-v0.4.pdf (336 KB) backend-admin-dashboard-requirements-v0.4.pdf v0.4 Draft｜需求說明書 PDF 陳國瑋, 2026-09-16 11:47
backend-admin-dashboard-requirements-v0.4.md (36.2 KB) backend-admin-dashboard-requirements-v0.4.md v0.4 Draft｜需求說明書 Markdown 陳國瑋, 2026-09-16 11:47
backend-admin-dashboard-mock-v0.4.html (118 KB) backend-admin-dashboard-mock-v0.4.html v0.4 Draft｜HTML Mock 陳國瑋, 2026-09-16 11:47

子任務 7 (7 進行中 — 0 已結束)

討論 #1423: [UI/UX] Dashboard Connector 即時狀態數量彈性顯示規則New鍾正剛動作
討論 #1424: [架構] Dashboard REST／WebSocket 資料分工與事件契約New動作
討論 #1460: [Dashboard] 結算流程區塊顯示規則New動作
討論 #1461: [Dashboard] 30 日充電用量區塊顯示與資料規則New動作
討論 #1462: [Dashboard] 案場即時負載與群組容量顯示規則New動作
討論 #1463: [Dashboard] 需留意事項摘要與顯示規則New動作
討論 #1486: [Dashboard] 即時關鍵指標與計算規則New動作
動作
複製連結
 #2

是由 陳國瑋 於 約 2 個月 前更新

需求文件已上傳

已完成附件上傳與回讀驗證：

  • a17-ems-dashboard-requirements.pdf（attachment #1108）：17 頁完整需求說明書
  • a17-dashboard-requirements.md（attachment #1109）：可編輯 source
  • a17-operations-dashboard.html（attachment #1110）：假資料互動 mockup

本 Issue 作為 Dashboard 主需求與整體進度追蹤票。Backend、Frontend、Database／Performance、QA／Release 的工作清單與 Definition of Done 已列於 Description。

目前狀態維持 New / 0%，未指定人員、工時或 due date。進入實作前先完成 Description 中的 A17 Phase 0 baseline 與待決策事項；確認後再依團隊分工建立 child issues。

動作
複製連結
 #3

是由 陳國瑋 於 約 2 個月 前更新

  • 子任務 #1423 已新增
動作
複製連結
 #4

是由 陳國瑋 於 約 2 個月 前更新

需求釐清子票

已建立 #1423 [UI/UX] Dashboard Connector 即時狀態數量彈性顯示規則，用於確認：

  • 0／1／2／8／9／30／100 個 Connector 的顯示策略
  • Status summary、bounded preview、異常優先排序
  • Desktop／Tablet／Mobile preview limit
  • 查看全部採 Drawer 或獨立頁面
  • Overview API 只回 summary + bounded preview 的合約方向
  • UI／API acceptance criteria 與未決事項

目前 #1423 是 需求待確認，不視為已進入開發。確認後才整併至 #1422 的 v1.0 最終需求文件；實作階段再另外建立 FE／BE／QA child issues。

動作
複製連結
 #5

是由 陳國瑋 於 約 2 個月 前更新

  • 子任務 #1424 已新增
動作
複製連結
 #6

是由 陳國瑋 於 約 2 個月 前更新

新增資料更新架構討論子票

已建立 #1424 [架構] Dashboard REST／WebSocket 資料分工與事件契約，用於確認：

  • Header、Needs Attention、KPI、Live Load、Group Capacity、Connector Grid、Usage Trend、Billing Pipeline 的 REST／WebSocket 分工
  • Dashboard 僅使用一條案場級 WebSocket，避免每個 Connector 建立一條連線
  • REST bootstrap、initial live snapshot、section replacement events
  • ticket／SS3A scope、sequence、schema version、stale、重連與 REST polling fallback
  • MeterValue coalesce、operational event SLA 與 A17 壓測條件
  • FE、Backend 與 contract test 的開發影響

目前 #1424 為 New / 0%／需求待確認。完成待決策事項後才會整併至 #1422 v1.0 最終需求文件，再拆 FE／BE／QA 實作票。

動作
複製連結
 #7

是由 陳國瑋 於 29 天 前更新

Dashboard 適用範圍更正

Ken 確認 Dashboard 並非 A17 專用，而是所有案場共用功能；A17 只作為第一個驗證與導入案場。

主需求 Description 已補充多案場適用原則：

  • Contract 與資料隔離明確使用 buildingId
  • API／WebSocket／UI／freshness policy 不得硬編碼 A17
  • A17 Phase 0 只驗證通用方案，不決定其他案場規則
  • stale cutoff 由 Backend 依資料來源統一管理

細部 freshness 決策記錄於 #1424 DEC-006。

動作
複製連結
 #8

是由 陳國瑋 於 28 天 前更新

#1424 WebSocket 架構決策確認完成

#1424 的 10 項待確認架構問題均已由 Ken 逐項確認，涵蓋：

  • buildingId scope 與授權
  • 完整 REST bootstrap／fallback
  • capped exponential backoff 與 60 秒 polling
  • Live Load 5 秒 coalescing
  • Operational Event propagation SLO P95 ≤ 2 秒
  • Backend stale policy 與 per-building override
  • raw WebSocket versioned contract
  • V1 單一 ems_branch instance 部署限制

#1424 仍維持 New / 0%，待 #1423 與其他需求討論完成後，再一起整併至 #1422 v1.0 最終需求文件並拆分實作票。

動作
複製連結
 #9

是由 陳國瑋 於 28 天 前更新

Dashboard V1 scope 已收斂：本功能只查詢、彙整及顯示既有狀態。Queue 僅顯示 waiting duration 與既有 BLOCKED 等狀態；不新增 Queue SLA、timeout、override、Admin 設定或 Rotation health，也不得改動 queue／rotation／OCPP 作業邏輯。未另外建立 future ticket。

動作
複製連結
 #10

是由 陳國瑋 於 28 天 前更新

同步 UI-DEC-012：Connector preview 固定 Cards，完整清單 Drawer 使用單一 responsive list；V1 不做 Grid／Table toggle、顯示偏好保存或 Backend viewMode contract。

動作
複製連結
 #11

是由 陳國瑋 於 28 天 前更新

  • 子任務 #1460 已新增
動作
複製連結
 #12

是由 陳國瑋 於 28 天 前更新

已建立並連結帳務摘要討論子票 #1460。Parent V1 scope、BE／FE 工作與 E2E 用語均由 Billing Pipeline 收斂為單張唯讀 Billing Summary：分開顯示 calculation、Billing、Invoice 既有狀態，導向既有帳務頁，不在 Dashboard 執行操作。

動作
複製連結
 #13

是由 陳國瑋 於 28 天 前更新

更正帳務區塊紀錄：attachment #1110 的現有設計是「6 月結算流程」四步驟面板。先前新增的單張 Billing Summary 定案已撤回，#1460 改回待重新確認；Parent 不再指示 FE／BE 實作該新提案。

動作
複製連結
 #14

是由 陳國瑋 於 28 天 前更新

同步 #1460 BIL-DEC-001：V1 沿用 attachment #1110 的四步驟結算流程；假資料改接正式 API。Parent 已恢復明確的 BE read-only aggregation 與 FE 原版面串接範圍，不新增 Billing Summary。

動作
複製連結
 #15

是由 陳國瑋 於 28 天 前更新

同步 #1460 BIL-DEC-002：四步驟結算流程使用 Backend 回傳的最近結算資料期間（periodYear／periodMonth／timezone），Frontend 不自行推算月份；最新期間即使異常仍照實顯示。功能維持唯讀，不調整既有月結排程或帳務作業邏輯。

動作
複製連結
 #16

是由 陳國瑋 於 28 天 前更新

同步 #1460 BIL-DEC-003：結算四列維持純資訊；面板 footer 提供兩個既有 route 導覽。Backend 不回傳 URL、不新增 drill-down endpoint。#1460 區塊需求已確認，但主 Feature 仍在需求確認階段，維持 New／0%。

動作
複製連結
 #17

是由 陳國瑋 於 28 天 前更新

  • 子任務 #1461 已新增
動作
複製連結
 #18

是由 陳國瑋 於 28 天 前更新

已依 Ken 確認建立 #1461 並同步 USG-DEC-001：30 日充電用量固定最近 30 個案場日曆日（含今天），依 building timezone 計算；保留 kWh／Sessions 切換，移除原先超出 mockup 的 7／90 日與自訂範圍需求。

動作
複製連結
 #19

是由 陳國瑋 於 28 天 前更新

因新建 #1461 被 Redmine tracker workflow 誤設 Closed，母票進度曾被連帶顯示為 25%；子票已恢復 New，本次將主 Feature 校正回 New／0%。仍在需求確認階段，尚未進入開發。

動作
複製連結
 #20

是由 陳國瑋 於 28 天 前更新

同步 #1461 USG-DEC-002：有效充電量只加總符合條件的 COMPLETED energy_consumed，由 Wh 轉 kWh；ACTIVE 不估算，異常 Completed 排除、回傳筆數並標示 PARTIAL。維持 read-only，不新增電量重算邏輯。

動作
複製連結
 #21

是由 陳國瑋 於 28 天 前更新

同步 #1461 USG-DEC-003：Usage daily bucket 依 building timezone 的交易開始日歸屬，整筆有效電量與 Session 跨日不拆分。Frontend 使用 Backend bucket，不自行重新分組；不影響帳務或 Transaction。

動作
複製連結
 #22

是由 陳國瑋 於 28 天 前更新

同步 #1461 USG-DEC-004：Dashboard 充電 Sessions 僅計算 COMPLETED 且 energy_consumed > 0 的交易並依開始日歸屬；0 Wh Completed 與 ACTIVE 不納入。不改變既有 Transaction lifecycle。

動作
複製連結
 #23

是由 陳國瑋 於 28 天 前更新

同步 #1461 USG-DEC-005：V1 移除時間使用率，不開發 Backend denominator、歷史設備啟用區間或 threshold。替代的第三個摘要仍待確認，不會先寫入實作範圍。

動作
複製連結
 #24

是由 陳國瑋 於 28 天 前更新

同步 #1461 USG-DEC-006：Usage 第三摘要改為平均每次充電量；Backend 回傳 validEnergyKWh ÷ validSessionCount，0 Sessions 為 null。Working mock 已同步替換，最終 HTML／PDF 待所有需求鎖定後產出。

動作
複製連結
 #25

是由 陳國瑋 於 28 天 前更新

同步 #1461 USG-DEC-007：Usage REST 固定 30 個 daily buckets；成功無有效 Session 為 0，未知為 null，部分未知時 section = PARTIAL。最終 mock fixture 必須清楚區分零值與資料缺口。

動作
複製連結
 #26

是由 陳國瑋 於 28 天 前更新

同步 #1461 USG-DEC-008：Usage 30 日成功但全零時使用 COMPLETE + EMPTY，摘要 0／0／—，以中性文案呈現且不建立 Needs Attention。最終 mock／fixture 須包含 Empty 情境。

動作
複製連結
 #27

是由 陳國瑋 於 28 天 前更新

同步 #1461 USG-DEC-009：Usage initial error 與 refresh error 分開；有 cache 時保留同 building 最後成功資料及 lastSuccessfulAt，依 Backend freshness 轉 STALE；無 cache 顯示 —／Error。#1461 區塊需求已確認，但主 Feature 仍維持 New／0%。

動作
複製連結
 #28

是由 陳國瑋 於 28 天 前更新

  • 子任務 #1462 已新增
動作
複製連結
 #29

是由 陳國瑋 於 28 天 前更新

同步 #1462 LOAD-DEC-001：移除案場層級契約容量／利用率／餘裕需求，保留案場即時總功率與各群組自身容量；不影響任何充電作業邏輯。

動作
複製連結
 #30

是由 陳國瑋 於 28 天 前更新

同步 #1462 LOAD-DEC-002：Live Load 保留即時／今日／7 日三種檢視；軸線與 bucket 規則仍待逐項確認。

動作
複製連結
 #31

是由 陳國瑋 於 28 天 前更新

同步 #1462 LOAD-DEC-003：加入 Live Load 三種 range／bucket、案場時區、time-weighted averagePowerKw 的 BE／FE 工作與驗收條件。

動作
複製連結
 #32

是由 陳國瑋 於 28 天 前更新

同步 #1462 LOAD-DEC-004：補入 REST 完整 series、WebSocket open／finalized bucket，以及 FE replacement／gap recovery 的實作與驗收責任。

動作
複製連結
 #33

是由 陳國瑋 於 28 天 前更新

同步 #1462 LOAD-DEC-005：加入 bucket time state／data quality 分離與 strict null-on-unknown 的 BE、FE、驗收規則。

動作
複製連結
 #34

是由 陳國瑋 於 28 天 前更新

  • 子任務 #1463 已新增
動作
複製連結
 #35

是由 陳國瑋 於 28 天 前更新

同步 #1463 ATT-DEC-001：Needs Attention 改為「需留意事項」；移除等待過久、Queue mismatch、未定義 severity 等推導語意，只保留既有明確狀態的唯讀摘要。

動作
複製連結
 #36

是由 陳國瑋 於 28 天 前更新

同步 #1463 ATT-DEC-002／#1462 LOAD-DEC-006：目前負載不可信才進入摘要；歷史 bucket gap 只在圖表呈現。

動作
複製連結
 #37

是由 陳國瑋 於 28 天 前更新

同步 #1463 ATT-DEC-003：需留意頁首採非零 categoryCount，各類回 distinct affectedCount，不跨類推導 root cause。

動作
複製連結
 #38

是由 陳國瑋 於 28 天 前更新

同步 #1463 ATT-DEC-004：固定 allowlist 順序、顯示全部非零 categories，並加入 390／768／1024／1440 responsive 驗收。

動作
複製連結
 #39

是由 陳國瑋 於 27 天 前更新

同步 #1463 ATT-DEC-005 與 #1424 DEC-020：成功零類別保留精簡正常狀態，資料不完整或失敗時不得宣稱沒有需留意事項。維持 Feature／New／0%。

動作
複製連結
 #40

是由 陳國瑋 於 27 天 前更新

同步 #1463 ATT-DEC-006 與 #1424 DEC-021：Attention PARTIAL／ERROR 僅影響 read-only 顯示，不新增作業邏輯。維持 Feature／New／0%。

動作
複製連結
 #41

是由 陳國瑋 於 27 天 前更新

同步 #1463 ATT-DEC-007 與 #1424 DEC-022；需留意事項區塊決策已齊，但全 Dashboard 尚未鎖版，父需求維持 Feature／New／0%。

動作
複製連結
 #42

是由 陳國瑋 於 27 天 前更新

  • 子任務 #1486 已新增
動作
複製連結
 #43

是由 陳國瑋 於 27 天 前更新

建立子討論 #1486「即時關鍵指標與計算規則」，先盤點 mock 六張 KPI；尚未確認的「本月預估電費」不進 final specification。父需求維持 New／0%。

動作
複製連結
 #44

是由 陳國瑋 於 27 天 前更新

同步 #1486 KPI-DEC-001：第六張 KPI 改選「上月電費」，不做本月預估；金額語意仍待確認。父需求維持 Feature／New／0%。

動作
複製連結
 #45

是由 陳國瑋 於 27 天 前更新

同步 KPI-DEC-001：上月電費的期間、金額來源、完整性門檻與 #billing 導覽已確認；其餘 KPI 繼續逐項討論。

動作
複製連結
 #46

是由 陳國瑋 於 27 天 前更新

同步 KPI-DEC-002 的 Backend、Frontend 與驗收範圍：enabled CP 分母、ONLINE 分子、OFFLINE／UNKNOWN／disabled 分開，Card 導向 /cp/list。

動作
複製連結
 #47

是由 陳國瑋 於 27 天 前更新

同步 KPI-DEC-003 的 Backend、Frontend 與驗收範圍：可服務分子／分母、固定 allowlist、unknown 安全處理、Connector overview replacement 與 /connector/list 導覽。

動作
複製連結
 #48

是由 陳國瑋 於 27 天 前更新

同步 KPI-DEC-004 的 Backend、Frontend 與驗收範圍；正式名稱為「充電進行中」，只做唯讀 ACTIVE Session 統計，不新增交易作業邏輯。

動作
複製連結
 #49

是由 陳國瑋 於 27 天 前更新

同步已確認的 KPI-DEC-005 至主需求：補上等待供電的 Backend、Frontend 與驗收工作；主數字只計 ELIGIBLE distinct Connector，未插槍另列。

動作
複製連結
 #50

是由 陳國瑋 於 27 天 前更新

同步 KPI-DEC-006 至主需求：補上 today Usage bucket 的 Backend 重用、第五張 KPI 的 FE 顯示與驗收規則；不新增 active-energy 估算。

動作
複製連結
 #51

是由 陳國瑋 於 27 天 前更新

同步 KPI-DEC-007 至主需求：將原本泛稱的 Loading／Error／Partial／Stale 工作改為可驗收的 Backend、Frontend、fixture 與 cache isolation 規則。

動作
複製連結
 #52

是由 陳國瑋 於 27 天 前更新

同步 #1486 KPI-DEC-008：六張 KPI 採 6×1／3×2／2×3 responsive grid，固定順序、完整顯示且不使用水平 carousel；Backend 不新增 viewport-specific contract。

動作
複製連結
 #53

是由 陳國瑋 於 27 天 前更新

補充 KPI-DEC-008 的 Backend 邊界：Responsive 為純 FE presentation，同一份 snapshot 支援所有寬度，不新增 viewport-specific API／WebSocket 分支。

動作
複製連結
 #54

是由 陳國瑋 於 27 天 前更新

同步 #1486 KPI-DEC-009：補齊六張 KPI 的原生 link、固定目的地、keyboard focus、accessible name、reduced motion 與 WebSocket 非逐筆 live announcement；Backend 不新增 URL／ARIA 欄位或 mutation。KPI 子區塊需求確認已完成。

動作
複製連結
 #55

是由 陳國瑋 於 27 天 前更新

已同步 #1424 DEC-029 至主需求：補上 Backend current-building resolver、Frontend 唯讀案場識別、零筆／多筆 enabled Building 的整頁錯誤狀態、contract／QA／驗收條件，並將原「單站或 buildingId」待決策標記為已確認。

動作
複製連結
 #56

是由 陳國瑋 於 27 天 前更新

本輪 E2E Catalog 影響

  • No catalog change（本輪）：本輪只確認需求、更新 Redmine contract 與假資料 mock，尚未改變 production UI／API／business behavior。
  • 整體 Feature classification 仍為 Add：進入實作時，須依本票既有 E2E Impact 新增 Dashboard 長期案例；本次新增的 site-scope coverage 至少包含唯一 enabled Building 正常載入、零筆／多筆 configuration error、request 無 buildingId，以及 WS event buildingId mismatch。
  • 本輪只執行 Catalog 格式 validator（178 cases，PASS），未啟動任何 release pack／E2E 測試，無 waiver。
動作
複製連結
 #57

是由 陳國瑋 於 27 天 前更新

已同步 #1424 DEC-030 至主需求，修正原本「新增 SS3A function」的不精確描述，並補上 Backend migration／cache、Frontend menu／route、允許與拒絕角色、WebSocket ticket，以及 P0／P1 測試責任。此權限只允許讀取 Dashboard，不附帶任何操作權限。

動作
複製連結
 #58

是由 陳國瑋 於 27 天 前更新

已同步 #1424 DEC-031 至主需求：只有 Connector 即時狀態與案場即時負載使用 Dashboard WebSocket；斷線只提示並保留最後資料／時間，不做 REST fallback、backoff 或自動重連。Backend、Frontend 與 QA 的最小開發範圍已列入 description；非即時 REST refresh 方式保留待確認。

動作
複製連結
 #59

是由 陳國瑋 於 27 天 前更新

本輪 E2E Catalog 影響

  • No catalog change（本輪）：本輪只更新 Redmine 需求與假資料 HTML mock，尚未改變 production UI／API／WebSocket 行為。
  • 整體 Feature classification 仍為 Add：進入實作時，Standard release pack 需納入 P0／P1 Dashboard 案例。
  • P0 預計涵蓋 Overview／ticket／WebSocket 授權、building scope、null／stale safety。
  • P1 預計涵蓋兩個 live block 的 initial snapshot／replacement、WebSocket 首次連線失敗與連線後中斷、最後資料保留、無 REST fallback／自動重連，以及其他 REST 區塊不受影響。
  • 本輪已執行 Catalog validator：178 cases，PASS。
  • 未啟動 Unit／Integration／E2E release pack，無 waiver。
動作
複製連結
 #60

是由 陳國瑋 於 27 天 前更新

確認 DEC-032：所有非即時區塊統一使用「頁面首載＋每 5 分鐘一個 Overview request＋手動刷新」，不再設定多套區塊週期。兩個 WebSocket 即時區塊維持獨立 ownership，定時 REST 不作斷線備援。

動作
複製連結
 #61

是由 陳國瑋 於 27 天 前更新

E2E impact（DEC-032）：本輪為需求與假資料 mock 更新，分類為 No catalog change；尚未進入實作，未執行 test plan。整體 Dashboard feature 實作時仍屬 Add，Standard pack 至少需涵蓋：P0 首次 Overview 失敗不得顯示 fixture／假 0、scope／auth／null 安全；P1 首載＋單一 5 分鐘 timer＋手動刷新、同 response generatedAt、refresh error 保留同 building 資料，以及定時 REST 不覆寫／備援兩個 WS live blocks。Catalog validator 已通過：178 cases（P0=56、P1=70、P2=47、P3=5）。

動作
複製連結
 #62

是由 陳國瑋 於 27 天 前更新

DEC-032 登錄後的一致性整理：將 DEC-031 段落中「REST refresh 仍待確認」改為已由 DEC-032 確認；不改動 Issue 狀態或完成度。

動作
複製連結
 #63

是由 陳國瑋 於 27 天 前更新

同步 #1462 LOAD-DEC-007：Live Load 預設即時；三組歷史 series 一次取得，切換不發 request／不重建 socket，刷新保留選擇，Empty／Error 不自動換頁籤。另清除待決策區仍寫 60 秒 refresh 的舊文案。

動作
複製連結
 #64

是由 陳國瑋 於 27 天 前更新

E2E impact（LOAD-DEC-007）：本輪只更新已確認需求與假資料 mock，分類為 No catalog change；尚未改變 production 行為，也未執行 test plan。整體 Dashboard 實作仍為 Add。Standard pack 的 P1 應驗證預設 LIVE、一次 Overview 含三組 series、切換不發 HTTP／不重建 WebSocket，以及定時／手動 refresh 保留 selectedRange；Major／A17 release 的 P2 應驗證單一 range EMPTY／ERROR／PARTIAL、0 + COMPLETE、cached refresh error 與 currentPowerKw 狀態相互獨立。Catalog validator PASS：178 cases（P0=56、P1=70、P2=47、P3=5）；無 waiver。

動作
複製連結
 #65

是由 陳國瑋 於 27 天 前更新

2026-09-04 需求鎖版前一致性稽核（第一輪）

稽核範圍

  • Parent #1422 與 Discussion #1423、#1424、#1460、#1461、#1462、#1463、#1486。
  • 現行 react/branch Dashboard／menu／Connector WebSocket 程式碼、java/ems_branch Building／WebSocket／既有 API 邊界。
  • Working HTML mock 與舊版 a17-dashboard-requirements.md。
  • 已登錄於各票的 A17 read-only baseline；A17 僅作驗證基準，不是功能適用範圍。

目前可作為鎖版基線的規則

範圍 現行規則 主要依據
案場 scope 每個 EMS Branch 自動使用唯一 enabled Building；0／多筆為設定錯誤；無 selector #1424 DEC-029
權限 沿用既有 dashboard function；Backend API／ticket 強制授權；Dashboard 唯讀 #1424 DEC-030
REST 首載＋每 5 分鐘＋手動刷新；每輪只有一個 Overview request #1424 DEC-032
WebSocket 一條案場級 socket，只更新 Connector 即時狀態與案場即時負載；斷線保留最後資料並提示；無 fallback／自動重連／sequence recovery #1424 DEC-031
KPI 六張固定指標與公式；目前以 REST-owned 為準 #1486
需留意事項 REST-only，五類 allowlist、固定順序、非零類別全顯示 #1463
Live Load／Group 三種歷史範圍一次由 REST 取得；WS 只接手 current／open bucket；不推算案場契約容量 #1462
Connector Backend 排序的 bounded preview；Desktop 8／Tablet 6／Mobile 4；完整清單走 REST Drawer #1423
Usage 最近 30 個案場日曆日、kWh／Sessions、平均每次充電量；不含時間使用率 #1461
Billing 最近既有結算期間的四步驟流程；footer 固定導向 /bill/list、/invoice/list；另有上月電費 KPI #1460、#1486

鎖版前必須整理的內容（不是新增功能）

  1. 舊傳輸規則仍散落在 description：#1422、#1423、#1424、#1462、#1463、#1486 仍有 NETWORK_HEALTH_UPDATED／CONNECTOR_OVERVIEW_UPDATED／ALERTS_UPDATED、60 秒 fallback、backoff、sequence／gap recovery、5 秒 coalescing、P95 2 秒 SLO、KPI／Attention／Group WebSocket 等舊 checklist／AC。雖然頁首有 supersession 說明，但不可讓開發人員從下方舊段落抄規格；最終整併時必須刪除或移至明確的歷史附錄。
  2. 命名會誤導功能範圍：Parent subject 仍寫 A17，## 待決策 內其實幾乎全部已確認。鎖版時建議改為「Backend Admin 案場營運 Dashboard（A17 首站驗證）」及「已確認決策摘要」。
  3. 舊 Markdown 不可當正式需求：a17-dashboard-requirements.md v0.2 仍包含 60 秒 polling、近 24 小時、契約容量利用率、SLA／severity、actionUrl、使用者可選 range 等已撤回內容。最終文件必須重新產生，不可在此草稿上零碎補丁後宣稱完成。
  4. HTML mock 尚未完全同步：
    • Connector 目前一次畫 12 張、Mobile 兩欄，尚未呈現 8／6／4 preview、單欄 Mobile、summary、總數／更新時間、查看全部 footer、完整清單 Drawer。
    • Connector card 尚未完整分層顯示 CP connection／runtime／Queue，互動 div tabindex 也需改為語意正確的原生控制。
    • Billing 標題缺年份，且缺少 /bill/list、/invoice/list 兩個 footer link。
    • 尚缺 Group 數量、Connector 0／1／2／8／9／30／100、Usage／Billing 狀態等 review fixtures。
    • 「充電進行中」卡的 optional 次要功率若保留，只能視為 REST snapshot 並帶時間，不可再宣稱由 WebSocket 即時更新；為避免重複且符合簡化原則，最終稿建議直接省略該 optional 次要值。
  5. Connector preview contract 需技術收斂：Backend 不應為 8／6／4 三種 viewport 產生三套 payload。建議回傳已排序前 8 筆、total、abnormalTotal 與每筆 Backend 判定的 severity／reason；FE 只按 viewport 截為 8／6／4，再做純顯示用剩餘筆數算術，不重新分類或排序。
  6. 現有程式碼整合邊界：
    • /dashboard 目前確實空白；舊 DashboardStatsCard 是 hard-coded fixture，不可接 production。
    • 現有 useAdminConnectorSocket 是單 Connector、會自動重試一次且支援手動 reconnect；Dashboard 必須使用獨立 hook，不能沿用或改壞既有 detail flow。
    • 現有 Connector dashboard 有 value || 0；新 Dashboard 不可沿用這個 null→0 行為。
    • BuildingRepository.findDefault() 會取 enabled Building 的其中一筆；Dashboard 必須使用嚴格解析器驗證恰好一筆。
    • 正式 route 已確認存在 /cp/list、/connector/list、/bill/list、/invoice/list、/charge-group/list、/event/list；static menu 另有「資訊儀表123」及不存在的 /billing/list，屬 FE 實作時一併清理項目。

尚未鎖定、需 Ken 逐題確認

第一題：#1424 DEC-007 的 per-building stale cutoff override 會要求新增設定儲存、管理 API／UI、權限與 audit；這與後續「Dashboard 只是顯示資訊、不要過度複雜」方向衝突。建議 V1 撤回 per-building override，只保留 Backend 依資料來源配置的全系統 default；A17 僅用於驗證 default 是否合理。若未來個別案場確有不同回報週期，再另開 Feature。

鎖版後建議建立的實作子票（目前尚未建立）

  1. BE：Overview read model／嚴格 Building scope／各區塊 aggregate／SS3A。
  2. BE：案場級 Dashboard ticket／WebSocket，只含兩個 live blocks。
  3. FE：正式 Dashboard、單一 5 分鐘 query、獨立 WS hook、RWD／Drawer／states／a11y／deep links。
  4. QA／Release：contract、授權、0／null／partial／stale、viewport、A17 query plan／效能、E2E catalog 與文件更新。

需求管理狀態

  • 8 張票維持 New／0%；本輪不代表開始開發。
  • 本輪 E2E impact：No catalog change（只有需求稽核）；整體 Feature 進入實作時仍為 Add。
  • 最終 HTML／需求文件／PDF 只會在上述衝突清除、剩餘決策逐題確認後產生。
動作
複製連結
 #66

是由 陳國瑋 於 27 天 前更新

稽核補充：E2E Catalog 對齊

目前 documents/E2E_TEST_CASE_INVENTORY.md 只有一筆 UI-009，標為 P3／Planned；但 #1422 已把授權、building scope、null／stale safety 列為 P0，核心顯示／RWD／營運狀態列為 P1。此差異不在需求討論階段直接修改 catalog；建立實作票並進入測試規劃 gate 時，必須把單一 P3 placeholder 拆成或升級為正式 P0／P1／P2 cases，並指定 Standard／Major／A17 release trigger。Skip 不可視為 Pass。

動作
複製連結
 #67

是由 陳國瑋 於 27 天 前更新

已同步 #1424 DEC-033：Dashboard V1 的 freshness 只使用 Backend per-source global defaults；所有案場共用，A17 只作驗證。V1 不開發 per-building override、設定資料表、管理 API／UI、額外權限或 audit。Parent 仍維持 New／0%，尚未進入實作。

動作
複製連結
 #68

是由 陳國瑋 於 27 天 前更新

已同步 #1486 KPI-DEC-010：Parent 的 BE／FE checklist 已移除「充電進行中」KPI 次要 currentPowerKw 與 WebSocket 更新要求。第三張卡只顯示 ACTIVE Session 主數字及「依未結束的充電 Session 計算」；即時功率只在 Live Load 區塊顯示。Parent 維持 New／0%。

動作
複製連結
 #69

是由 陳國瑋 於 27 天 前更新

【主需求同步】已將 #1423 UI-DEC-013／#1424 DEC-034 納入主需求：Backend 提供同一份 Top-8 Connector preview；Frontend 依 Desktop／Tablet／Mobile 顯示 8／6／4 筆，完整清單另走 REST Drawer。同步更新 BE／FE／QA 開發清單；仍屬需求確認，未進入實作。

動作
複製連結
 #70

是由 陳國瑋 於 27 天 前更新

【主需求同步】納入 #1423 UI-DEC-014／#1424 DEC-035：Connector Status summary 採 Backend authoritative 互斥 displayBucket，bucket counts 加總等於 total；FE 不從 Top-8 preview 重算，Card／Drawer 保留分層原始狀態。同步更新 BE／FE／QA 清單；bucket mapping 仍待下一項確認，未進入實作。

動作
複製連結
 #71

是由 陳國瑋 於 27 天 前更新

【主需求同步】納入 #1423 UI-DEC-015／#1424 DEC-036：Connector summary 固定 NEEDS_ATTENTION／CHARGING／WAITING／AVAILABLE／OTHER 五類與 precedence；Unknown 歸需留意、NOT_PLUGGED 歸其他，NEEDS_ATTENTION count = abnormalTotal。同步更新 BE／FE／QA 開發清單；仍為需求確認，未進入實作。

動作
複製連結
 #72

是由 陳國瑋 於 27 天 前更新

【主需求同步】納入 #1423 UI-DEC-016／#1424 DEC-037：Backend REST／WebSocket 固定回五個 Connector summary bucket（含零值）；total > 0 時 FE 固定顯示五項，total = 0 時顯示 Connector Empty State，且有效 0 不得視為缺值。已同步 Backend／Frontend／QA 工作與驗收條件。E2E impact：目前僅需求與 Mock，正式產品行為未變，故本次 No catalog change；進入實作時須新增或更新對應 Dashboard UI／contract 案例。議題維持 New／0%。

動作
複製連結
 #73

是由 陳國瑋 於 26 天 前更新

【主需求同步】納入 #1423 UI-DEC-017／#1424 DEC-038：五個 Connector Status summary 項目固定為純資訊，不可點擊、不進 Tab 順序，也不開 Drawer、套 filter、導頁或送 request；單支 detail／完整清單仍由 preview card／「查看全部」負責。Backend 不新增 bucket click API、mapping、URL 欄位或 WebSocket event。已同步 FE／QA 驗收條件。E2E impact：目前僅需求與 Mock，正式產品行為未變，故本次 No catalog change；實作時納入 Dashboard UI accessibility／interaction 案例。議題維持 New／0%。

動作
複製連結
 #74

是由 陳國瑋 於 26 天 前更新

【主需求同步】納入 #1423 UI-DEC-018／#1424 DEC-039：Connector Full List Drawer 的搜尋、篩選與頁碼只保留於目前 Dashboard page memory；close／reopen 保留，reload／navigation 後重設。不寫 URL／history、localStorage／sessionStorage、Backend preference API 或 WebSocket。已同步 FE／QA 驗收條件。E2E impact：目前僅需求與 Mock，正式產品行為未變，故本次 No catalog change；實作時納入 Drawer state lifecycle 案例。議題維持 New／0%。

動作
複製連結
 #75

是由 陳國瑋 於 26 天 前更新

【主需求同步】Ken 已確認 Connector Full List 分頁規則（UI-DEC-019／DEC-040）。

  • Drawer 固定每頁 20 筆，只提供上一頁／下一頁與頁次／總筆數；1～20 筆隱藏換頁控制。
  • 搜尋／篩選改變時回第 1 頁，Server 對完整資料集查詢後再分頁；不做 current-page client filtering。
  • 沿用／擴充既有 POST /api/connector/search 的 page／size 與 Spring Page metadata；不新增完整 inventory WebSocket、page-size selector、直接跳頁或 virtualization。
  • FE／BE／QA 工作拆分與 30／100 筆（2／5 頁）驗收條件已同步。

本次僅更新需求與 Mock，議題維持 New／0%，不代表已進入開發。E2E impact：目前為需求／Mock 調整，No catalog change；實作時必須新增或更新 Connector Drawer REST pagination 的長期 E2E case。

動作
複製連結
 #76

是由 陳國瑋 於 26 天 前更新

【主需求同步】Ken 已確認 Connector Full List 固定排序（UI-DEC-020／DEC-041）。

  • Dashboard Drawer 不提供排序選單、可點擊欄位排序或其他使用者排序控制。
  • Backend 對完整搜尋／篩選結果套用與 Top-8 相同的 priority hierarchy 與 deterministic tie-breaker，再做固定 20 筆 pagination；不得先分頁再做單頁排序。
  • 既有 POST /api/connector/search 以 stable DASHBOARD_PRIORITY read mode 支援此規則；既有 /connector/list 欄位排序維持不變。
  • FE／BE／QA 工作與驗收條件已同步；Mock 假清單也改為固定 priority sort。

本次僅更新需求與 Mock，議題維持 New／0%，不代表已進入開發。E2E impact：No catalog change；正式實作必須新增或更新固定排序、篩選後排序、跨頁順序及管理頁無回歸案例。

動作
複製連結
 #77

是由 陳國瑋 於 26 天 前更新

【主需求一致性同步】依 #1424 現行 DEC-031，移除主票中兩句殘留的 sequence gap／背景重連恢復要求。

  • Live Load WebSocket 仍使用 Backend-produced replacement，不由 FE 自行積分／平均。
  • Socket 中斷時保留最後資料並顯示已停止更新；不啟動 REST fallback、sequence／gap recovery或背景自動重連，整頁 reload 才重新連線。
  • 本次沒有改變產品行為，只讓 #1422 Acceptance Criteria 與已確認的 #1424 DEC-031 一致；Issue 維持 New／0%。

E2E impact：No catalog change；正式實作仍需驗證中斷提示、資料保留、無 fallback及 reload reconnect。

動作
複製連結
 #78

是由 陳國瑋 於 26 天 前更新

動作
複製連結
 #79

是由 陳國瑋 於 26 天 前更新

【需求確認｜PERF-DEC-001／DEC-042】

已將 Overview 效能驗證方式同步至主需求：

  • 移除「A17 資料量下 P95 < 1.5 秒」硬性驗收門檻。
  • 改以 A17 或具代表性等量資料的 EXPLAIN、endpoint P50／P95 與完整測試條件，建立可重現 baseline。
  • 只有實測影響正常使用時才進行 query／普通 index 優化。
  • V1 不預先新增 Dashboard snapshot table、專用 cache 或效能排程。
  • Dashboard 仍適用所有案場；A17 僅為第一個驗證站點，不形成案場專屬規則。

Backend 工作項、Database／Performance、Acceptance Criteria、Definition of Done 與決策摘要均已同步。Issue 維持 New／0%；本次未修改產品程式、mock 或最終 PDF。

動作
複製連結
 #80

是由 陳國瑋 於 26 天 前更新

動作
複製連結
 #81

是由 陳國瑋 於 26 天 前更新

【需求同步｜ATT-DEC-008／KPI-DEC-011】

已移除主需求中「ACTIVE transaction 存在時，離線告警需標記可能仍在離線充電／待 reconciliation」的規則。

現行規則改為：

  • CP 離線與未結束 ACTIVE Session 是兩個獨立事實。
  • 離線告警不推論離線充電、reconciliation 或其他原因。
  • 「充電進行中」仍依 canonical ACTIVE transaction 計數，包含 parent CP 暫時 OFFLINE／disabled 的未結束 Session。
  • 不新增衍生狀態、API 欄位、提示或 workflow。

Backend 工作項、核心狀態規則、Acceptance Criteria 與決策摘要已同步。Mock 無相關推測性提示，故本輪未修改檔案。Issue 維持 Feature／New／0%。

動作
複製連結
 #82

是由 陳國瑋 於 26 天 前更新

動作
複製連結
 #83

是由 陳國瑋 於 26 天 前更新

【需求確認｜REL-DEC-001】

Ken 同意以輕量發布檢查取代強制「24 小時持續監看」。

現行要求：

  • 首個實際 rollout 案場部署後，執行一次 Dashboard smoke test。
  • 確認授權載入、Overview、兩個 live blocks 的正常／斷線提示，以及既有管理頁未出現明顯回歸。
  • 下一個工作日使用既有 application log、維運工具與資料庫負載資訊做一次檢查。
  • 不新增 Dashboard 專用監控平台、metrics、instrumentation、自動告警、排程或 24 小時值守。
  • 發現問題時沿用既有 release／rollback 流程，不建立新 workflow。
  • Pre-release 效能仍依 PERF-DEC-001／DEC-042 產出可重現 baseline。

QA／Release、Definition of Done 與決策摘要已同步；Issue 維持 Feature／New／0%。本次未修改產品程式、mock 或最終文件。E2E impact：需求階段 No catalog change。

動作
複製連結
 #84

是由 陳國瑋 於 25 天 前更新

動作
複製連結
 #85

是由 陳國瑋 於 25 天 前更新

【需求一致性清理｜DEC-031／032】

Ken 已確認清除 #1422 中被現行資料分工取代的 KPI WebSocket 要求。

已修正：

  • Charge Point 連線、Connector 可服務、充電進行中、等待供電及其他 KPI 全部只隨共用 Overview REST 更新。
  • 移除 Dashboard KPI 對 NETWORK_HEALTH_UPDATED、CONNECTOR_OVERVIEW_UPDATED 的新增／訂閱要求。
  • 修正 Backend、Frontend 與 Acceptance Criteria 中仍暗示 KPI 同時由 REST／WS 更新的文字。
  • KPI 更新時機維持頁面首載、每 5 分鐘與手動刷新；Header 顯示一般資料更新時間。
  • Overview refresh 不逐卡 live announce。

保持不變：

  • Dashboard 的三種 message type 仍為 DASHBOARD_LIVE_SNAPSHOT、CONNECTOR_LIVE_BLOCK_UPDATED、LIVE_LOAD_UPDATED。
  • Connector 即時狀態與案場即時負載仍使用 WebSocket。
  • 若其他既有功能使用同名舊 event，本需求不刪除或修改其行為。
  • 所有 KPI 計算公式與作業邏輯均不變。

Issue 維持 Feature／New／0%。本次只更新需求紀錄，未修改程式、mock 或最終文件。E2E impact：需求階段 No catalog change。

動作
複製連結
 #86

是由 陳國瑋 於 24 天 前更新

動作
複製連結
 #87

是由 陳國瑋 於 24 天 前更新

【需求同步｜USG-DEC-010】

Parent 已同步 Usage／Live Load 資料來源邊界：

  • Usage 與今日已完成充電量只採 completed transaction 的既有 energy_consumed，依 start_timestamp 的案場日曆日歸屬。
  • 不使用 raw MeterValue 估算、不呼叫 MeterValueTariffCalculationService、不做費率分段。
  • MeterValue 仍只供 #1462 Live Load。
  • Backend checklist、Acceptance Criteria 與決策摘要已改為引用 USG-DEC-001～010。

Issue 維持 Feature／New／0%。本次僅更新需求紀錄，未修改產品程式、mock 或最終文件。

動作
複製連結
 #88

是由 陳國瑋 於 24 天 前更新

  • 主旨 從 [功能開發] A17 Backend Admin 營運 Dashboard 變更為 [功能開發] Backend Admin 營運 Dashboard（全案場適用，A17 首站）
動作
複製連結
 #89

是由 陳國瑋 於 24 天 前更新

【需求管理｜主票標題修正】

Ken 已確認將主票標題由：

「[功能開發] A17 Backend Admin 營運 Dashboard」

調整為：

「[功能開發] Backend Admin 營運 Dashboard（全案場適用，A17 首站）」

目的：

  • 讓 Redmine ticket list 直接反映功能適用所有 EMS Branch。
  • A17 僅代表第一個資料驗證與 rollout 案場。
  • 避免 FE／Backend 將 API、UI、WebSocket、freshness 或 query 寫成 A17-specific。

本次只修改 Subject；Issue ID、Feature tracker、New／0%、description、relations、附件與需求內容均不變。未修改產品程式或 mock。

動作
複製連結
 #90

是由 陳國瑋 於 24 天 前更新

動作
複製連結
 #91

是由 陳國瑋 於 24 天 前更新

【文件版號管理｜DOC-DEC-001】

依 Ken 指示，PDF、Markdown 與 HTML Mock 改採同版號套件管理，所有歷史版本持續堆疊在 #1422。

規則：

  • v0.x Draft：需求討論期間的 review snapshot。
  • v1.0：全部需求確認與一致性檢查完成後的開發 baseline。
  • v1.x：v1.0 後不改變主要 scope 的澄清／文件修正。
  • 每個 review checkpoint 同步產生 PDF、Markdown、HTML 三份檔案，使用相同版號、文件日期與檔名版本。
  • 每次都新增三個附件，不覆蓋、不刪除舊版。
  • Redmine note 記錄 decision cutoff、變更摘要及三個 attachment IDs。
  • v1.0 前若附件與較新的 Redmine 決策不同，以 #1422／子票的現行決策為準。

既有附件經內容核對，登錄為同一個 v0.2 Draft 套件：

  • PDF attachment #1108
  • Markdown attachment #1109
  • HTML Mock attachment #1110

下一個 review checkpoint 將發布同步的 v0.3 Draft；需求全部鎖定後才發布 v1.0。

另清除 Description 末尾 5 組重複的附件表格文字。真正的 Redmine 附件 #1108～#1110 均完整保留，沒有刪除或覆蓋。Issue 維持 Feature／New／0%；本次未修改產品程式或本機 mock。

動作
複製連結
 #93

是由 陳國瑋 於 24 天 前更新

【文件套件發布｜v0.3 Draft】

依 DOC-DEC-001 完成同版號 review 套件並堆疊附加於 #1422；v0.2 附件 #1108～#1110 完整保留，沒有覆寫或刪除。

Decision cutoff：2026-09-07，本票及 #1423、#1424、#1460、#1461、#1462、#1463、#1486 在本次發布前已確認並寫入 Description 的決策；本票發布前最後一則需求管理紀錄為 Journal #5672。

v0.3 attachments：

  • PDF：#1115 backend-admin-dashboard-requirements-v0.3.pdf
  • Markdown：#1116 backend-admin-dashboard-requirements-v0.3.md
  • HTML Mock：#1117 backend-admin-dashboard-mock-v0.3.html

主要整併內容：

  • Dashboard 適用所有案場，A17 僅作第一站與資料尺度基準。
  • 明確區分唯讀產品範圍、FE、Backend、資料契約、QA、效能與發布工作。
  • 一支 Overview REST + 一條只更新 Connector 即時狀態／案場即時負載的 WebSocket；斷線只提示並保留最後資料，無 fallback 或自動重連。
  • 收斂六個 KPI、五類需留意事項、Connector 1／2／30+ 彈性 layout、Top-8／8-6-4、drawer 固定 20 筆分頁。
  • 收斂 Live Load 三種 range 與 X/Y 軸、30 日 Usage、上月電費與既有四步驟帳務流程。
  • 納入 Loading／Empty／Partial／Error／Stale／403、responsive、accessibility、驗收、效能 baseline 與 rollout 邊界。

驗證：PDF 16 頁已轉圖檢查，無空白頁、截字或重疊；PDF 文字抽取與關鍵需求核對通過；HTML script syntax 解析通過。此版仍為 Draft，Issue 維持 Feature／New／0%，沒有進入開發，也未執行產品或 E2E 測試。

動作
複製連結
 #94

是由 陳國瑋 於 17 天 前更新

動作
複製連結
 #95

是由 陳國瑋 於 16 天 前更新

2026-09-15｜#1422 與全部子票、v0.3 文件套件一致性稽核（第一輪）

1. 稽核範圍與基準

  • Redmine：#1422、#1423、#1424、#1460、#1461、#1462、#1463、#1486 的現行 Description。
  • v0.3 套件：PDF #1115、Markdown #1116、HTML Mock #1117。
  • 本機保存的三份 v0.3 檔案已逐 byte 與上述三個附件核對，內容相同；本次不是拿尚未發布的工作檔代替 Redmine 附件。
  • 另以目前 ems_branch 的 Connector search DTO／enum 核對 Drawer 篩選是否能按現行文字直接實作。
  • 本輪只做唯讀稽核與登錄結果；未改程式、Mock、附件、Issue 狀態、進度或指派。

2. 稽核結論

現行主票與七張子票的核心產品決策已一致：

  1. Dashboard 適用所有案場；A17 只作展示與首站驗證。
  2. Dashboard 是唯讀資訊總覽，不修改充電、Queue、輪充、OCPP 或帳務作業。
  3. 只有「04 案場即時負載」及「06 Connector 即時狀態」使用 Dashboard WebSocket。
  4. 其他區塊共用一次 Overview REST：首載、每 5 分鐘及手動刷新。
  5. Socket 失敗只提示並保留最後資料；不做 REST 備援、自訂 backoff、背景自動重連或 gap recovery。
  6. Connector 五項摘要固定、互斥、非空案場包含 0，且純資訊、不可點擊。
  7. 六張 KPI 固定順序且全部走 REST；「充電進行中」與「上月電費」等現行名稱一致。
  8. 30 日 Usage 採開始日歸屬並使用 Completed 最終電量；時間使用率已撤回。
  9. 「上月電費」與「最近結算資料期間的四步驟」是不同資訊，不再混成預估費用或本月帳務摘要。

已撤回的本月預估電費、時間使用率、KPI WebSocket、per-building cutoff、離線充電推論、固定傳播 SLA 等內容，在現行票中都只以「不做／已取代」的追溯文字出現，沒有再被列成開發要求。

3. v0.4 可直接修正的 Mock／文件落差

以下不是新增產品功能，而是讓下一版附件忠實呈現已確認需求。

ID 落差 v0.4 應修正
PKG-01 #1117 的需留意卡仍顯示「設備故障」「結算待確認」；現行 #1463 固定名稱為「Connector 故障」「結算未完成／異常」。 更新可見文字、aria-label 與相關假資料說明。
PKG-02 #1117 結算區標題只有「8 月結算流程」，未顯示 #1460 已要求的資料年份；也缺少已確認的兩個 Footer 入口。 顯示「2026 年 8 月結算流程」類格式，補「查看帳單」→ /bill/list 及「查看請款／發票」→ /invoice/list；四列仍不可點。
PKG-03 #1116 的第 2 個結算步驟寫「單元結算」，但 #1117、#1422、#1460 均為「門牌結算」。 Markdown 改為「門牌結算」，PDF 隨同一來源重產。
PKG-04 #1117 的「30 日充電用量」實際只有 15 個圖表值；圖表值合計為 1,687.6 kWh／93 Sessions，卻顯示摘要 2,213.6 kWh／136 Sessions。 改成 30 個每日 bucket，圖表、兩個合計、平均值及今日 KPI 使用同一組假資料推導；補清楚的 X 軸日期與 Y 軸單位／指標。
PKG-05 Connector 預覽卡尚未把所屬 CP 的 OCPP ONLINE／OFFLINE／UNKNOWN 與 Connector runtime 分層呈現；卡面也缺 CP 識別、資料時間／stale，Queue 卡僅有簡略順位。 依 #1423 第 3.2 節補最小必要欄位；未知功率維持「—」，不把三層狀態合成一個在線狀態。
PKG-06 #1117 的「單支 detail drawer」目前其實是卡片下方的 inline strip：沒有真正 Drawer／dialog、關閉、焦點處理；「查看設備詳情」按鈕也沒有目的地或行為。 依 #1423 第 5 節做可辨識的單支詳情 Drawer，並保留前往既有管理頁／Engineer Tools 的受權限入口。
PKG-07 ?connectors=30／100 的首頁 summary 與完整清單不是同一份假資料。例：30 筆 summary 顯示需留意 2，但 Drawer 產生 10 筆 NEEDS_ATTENTION；100 筆為 2 對 38。 先建立一份 canonical fixture，再由同一集合推導五類 summary、Top-8、abnormalTotal 與完整清單，避免彼此矛盾。
PKG-08 Full List Drawer 只在寬度 ≤940px 變全螢幕；#1423 已定義 640～1239px 的 Tablet 皆為全螢幕，因此 1024px Mock 不符需求。 對齊 1240px breakpoint，並重新檢查 390／768／1024／1440px。
PKG-09 #1117 的 max-width:639px CSS 區塊提早結束，導致 usage-layout、usage-facts、load-summary、load-axis-guide 的手機規則落到全域，另有多餘右大括號。 修正 media query 範圍；確認桌面 Usage 的圖表／右側摘要及 Load summary 版位恢復。
PKG-10 #1116 仍使用 item 欄位 abnormal／reason，且把卡片目的地寫成既有詳細頁；現行 #1423／#1424 已定為 displayBucket／isAbnormal／severity／priorityReason，以及先開單支 detail Drawer。 v0.4 Markdown／PDF 統一使用現行欄位及互動名稱。

4. Redmine 在進入開發前仍需補清楚的地方

REQ-01｜Full List 的「狀態」篩選目前有兩種語意

  • #1117 選項混合 Connector runtime 與 Queue／展示概念：Faulted、Blocked、Charging、Waiting、Available。
  • 現有 SearchConnectorDto.status 實際只查 e_connectors.status；ConnectorStatus 有 AVAILABLE／PREPARING／ENQUEUED／CHARGING／SUSPENDED_EVSE／SUSPENDED_EV／FINISHING／RESERVED／UNAVAILABLE／FAULTED，沒有 BLOCKED 或 WAITING。
  • 因此工程師目前無法判斷「狀態」是：
    1. 既有 Connector runtime status；或
    2. Dashboard 五個 displayBucket；或
    3. runtime 與 Queue 混合後的新篩選集合。

為維持簡單並避免第三套分類，建議採第 2 種：將欄位明確改名為「摘要分類」，固定使用 NEEDS_ATTENTION／CHARGING／WAITING／AVAILABLE／OTHER；首頁五項摘要仍不可點，只有 Drawer 內有獨立 selector。確認後需同步更新 #1423、#1424 及 Mock。

REQ-02｜Full List search response 的最小欄位尚未列成契約

現有 RespSearchConnector 只有 Connector ID、area、location、floor、parkingSpaceNo、phaseType、runtime status；不足以直接呈現 Mock 的 CP ID、Queue／展示分類與 Dashboard priority 結果。下一次 Description 編輯應明列 Drawer 每列與 search response 的最小欄位，並列出哪些是既有欄位、哪些需擴充，避免 FE 依畫面猜 DTO。

5. 建議的下一步

  1. 先只確認 REQ-01 的篩選語意。
  2. 依確認結果補強 #1423／#1424；REQ-02 同步寫成明確欄位契約。
  3. 修正工作 Mock 與 Markdown 的 PKG-01～10，產生 v0.4 Draft PDF。
  4. 對 v0.4 三份檔案再做一次自動／人工一致性檢查，三份同版號新增掛到 #1422，不覆蓋 v0.3。
  5. 交 Ryan／FE review；其餘需求確認完畢後才發布 v1.0 開發基準。

E2E impact：No catalog change（本輪僅需求／附件一致性稽核，尚未改產品行為）。

動作
複製連結
 #96

是由 陳國瑋 於 15 天 前更新

動作
複製連結
 #97

是由 陳國瑋 於 15 天 前更新

Drawer／摘要分類決策已確認（2026-09-16）

依 Ken 確認，本票與 #1423、#1424 的 Description 已同步更新：

  • Drawer 定義： Drawer 是覆蓋在目前 Dashboard 上、由右側滑出的暫時面板，不是另一個頁面；平板／手機可呈現為全螢幕 Sheet。
  • 兩種入口： 點 Connector 預覽卡開啟單支詳情 Drawer；點「查看全部」開啟 Full List Drawer。
  • Full List 篩選： 欄位名稱定為「摘要分類」，選項為全部、需留意、充電進行中、準備／排隊、可用、其他狀態。
  • 資料語意： 「摘要分類」直接使用同一套 displayBucket；不把 Connector runtime status 與 Queue status 混成第三套 selector。
  • 首頁規則不變： 五個摘要維持純資訊、不可點擊，不會開啟 Drawer 或帶入篩選。
  • 已補上 Full List search 的最小 request／response 契約、Backend／FE 分工與驗收條件。

本輪只更新需求管理內容；未修改程式、WebSocket／充電／Queue 作業邏輯、Issue 狀態、進度、指派或附件。E2E impact：No catalog change。下一版 Mock／Markdown／PDF 會於 v0.4 Draft checkpoint 一併同步，不覆蓋 v0.3。

動作
複製連結
 #99

是由 陳國瑋 於 15 天 前更新

動作
複製連結
 #100

是由 陳國瑋 於 15 天 前更新

文件套件發布｜v0.4 Draft（2026-09-16）

依 DOC-DEC-001 完成同版號 review 套件，已新增附加於 #1422；v0.2、v0.3 均保留，沒有覆寫或刪除。

v0.4 附件

Decision cutoff 與整併內容

  • 納入 2026-09-16 前已確認的 Drawer、UI-DEC-021「摘要分類」及 DEC-043 Full List 最小契約。
  • 完成一致性稽核 PKG-01～10：需留意文案、結算年份與兩個入口、門牌結算、30 個日期桶與 X/Y 軸、Connector 卡片三層狀態、單支 detail Drawer、canonical fixture、1239 px 以下 Full List 全螢幕、手機 CSS、現行 response 欄位。
  • #1422 與 #1423、#1424、#1460、#1461、#1462、#1463、#1486 的 Description 閱讀基準均改指向 v0.4；歷史決策與舊附件仍保留。

驗證

  • HTML：JavaScript syntax 通過；390／768／1024／1440 px 無頁面水平溢位；0／1／2／8／9／30／100 個 Connector 的預覽上限、五類統計、Full List 分頁／篩選及兩種 Drawer 行為通過。
  • PDF：17 頁全部轉圖抽查，無空白頁、截字或表格跨頁破損；文字抽取與關鍵術語核對通過。
  • 三份檔案版號與日期一致。

本版仍為 review Draft，不是 v1.0 開發 baseline；沒有修改產品程式，也沒有變更 Issue 狀態、進度或指派。E2E impact：No catalog change（本次僅需求、Mock 與文件）。

動作
複製連結

匯出至 Atom PDF