討論 #1424
進行中Feature #1422: [功能開發] Backend Admin 營運 Dashboard（全案場適用，A17 首站）
[架構] Dashboard REST／WebSocket 資料分工與事件契約
概述
閱讀基準： 主需求 #1422 與 HTML Mock v0.4／附件 #1121。以下沿用主票區塊編號，依畫面由上到下、由左到右說明。Mock 數字皆為假資料；功能適用所有案場，A17 不是固定規則。
本票要完成什麼：讓整張 Dashboard 用簡單、一致的方式取得資料¶
本票負責案場範圍、權限、REST／WebSocket 分工、資料狀態與前後端契約。畫面／公式分別由 #1423、#1460、#1461、#1462、#1463、#1486 定義，不在本票建立第二套算法。
既有 GET /api/connector/dashboard 只有部分Connector統計；管理頁search與單支detail socket可重用，但不能直接當成整張Dashboard的資料來源。需要新的typed Overview與最小Dashboard socket。
先記住三件事：
- 一次Overview取得一般資料，首載／每5分鐘／手動刷新。
- 一條Dashboard WebSocket只更新「06 Connector即時狀態」與「04 案場即時負載」。
- Socket連不到就提示並保留資料；不另建REST備援、自動重連或gap recovery。
1. 先依畫面順序看資料通道¶
「REST-owned」表示由Overview負責更新；「WS-owned live state」表示socket接手後只由socket負責更新，兩者不能互相覆寫。（DEC-031／032）
| 主票位置／畫面 | 首次資料 | 後續更新 | Dashboard socket斷線時 |
|---|---|---|---|
| 01 案場名稱／一般資料時間 | Overview | 共用5分鐘／手動Overview | 照常更新一般資料與其品質 |
| 02 需留意事項 | Overview | 同上，REST-only | 照常；不改成其他備援模式 |
| 03 六張KPI | Overview | 同上，全部REST | 照常；不訂閱KPI WS事件 |
| 04 目前功率／open buckets | Overview bootstrap | LIVE_LOAD_UPDATED replacement | 保留最後值／時間、標停止更新；無資料— |
| 04 即時／今日／7日完整歷史 | 一次Overview給三組 | 同一Overview更新歷史；WS另負責open／跨界finalized | 一般歷史可刷新，但不得冒充即時recovery |
| 05 群組容量／Slots／Queue摘要 | Overview | 共用5分鐘／手動Overview | 照常，非WS |
| 06 五項摘要／Top-8預覽 | Overview bootstrap | CONNECTOR_LIVE_BLOCK_UPDATED整區replacement | 保留最後值／時間、標停止更新；無資料— |
| 07 30日用量、03-5今日已完成量 | 同一Overview／Usage read model | 共用5分鐘／手動Overview | 照常，非Usage WS |
| 08 結算流程、03-6上月電費 | Overview | 共用5分鐘／手動Overview | 照常，非Billing WS |
按需打開的介面另外處理，不混入首頁更新：
| 介面 | 資料通道 |
|---|---|
| 06「查看全部」Full List Drawer | 開啟、搜尋、「摘要分類」／Charge Group 篩選、換頁時 POST /api/connector/search，REST server pagination |
| 單支Connector detail | 既有detail API；打開時才使用既有單Connector socket，關閉釋放 |
「一條Dashboard socket」指首頁本體，不是禁止按需使用既有單支detail flow；也不能因此替每張preview card建立socket。
2. 整體資料流程與scope¶
登入使用者
↓
既有 SS3A dashboard function 授權
↓
Backend 解析本 Branch 唯一 enabled Building
├─ 不是恰好1筆 → 設定異常，不載入營運數字
└─ 恰好1筆
├─ GET /api/dashboard/overview
│ ├─ 一般區塊＋三組歷史
│ └─ 兩個live blocks初始畫面
└─ 短效、一次性Dashboard ticket
↓
raw WebSocket
├─ DASHBOARD_LIVE_SNAPSHOT
├─ CONNECTOR_LIVE_BLOCK_UPDATED
└─ LIVE_LOAD_UPDATED
2.1 案場由Backend決定（DEC-029）¶
- 每個EMS Branch恰好一筆enabled Building；零筆／多筆回明確configuration error，FE顯示整頁「案場設定異常」並隱藏營運資料。
- 不任選第一筆、不跨Building加總、不顯示假0；不沿用任選預設案場的查詢方式。
- Overview／ticket request、WebSocket URL不傳FE指定buildingId；Drawer的Dashboard read mode也依相同resolver。
- Overview response、ticket binding、event envelope明確帶相同Backend-resolved buildingId；FE只套用相符資料，cache按buildingId隔離。
- Header／Sidebar顯示Backend案場識別，timezone供日期與時間呈現；不提供site selector。
- A17只用來驗證，不能出現在固定數字／公式／cutoff／query分支。
2.2 權限沿用dashboard function（DEC-030）¶
| 條件 | 應有結果 |
|---|---|
| administrator／power_user／association／dealer，經既有dashboard function授權 | 相同唯讀Dashboard、Overview與ticket能力 |
| 只有adm_user／member／hq／engineer，未取得dashboard function | Overview／ticket為403；無有效ticket不能建立Dashboard socket |
| 多role使用者已有允許權限 | 依既有function機制授權，不因同時擁有其他role拒絕 |
不新增role／function、不在Java硬編碼role判斷；補Overview／ticket API mapping，依主票以冪等migration確認role-function mapping並驗證重啟後授權快取。
FE依function控制menu／route，未授權不先載入或短暫顯示資料；隱藏menu不能代替Backend授權。既有管理頁／Engineer Tools導覽沿用目的頁權限，Dashboard不附帶Start／Stop、Reset、Queue、帳務或工程指令能力。
3. Overview REST契約：一個週期、一份一般資料¶
新增typed GET /api/dashboard/overview，回傳案場識別、generatedAt、各source的品質／時間及各section。（DEC-002保留部分／DEC-032）
| 時機 | Request |
|---|---|
| 頁面首次載入 | 一次Overview |
| Dashboard保持掛載期間每300秒 | 每輪一次Overview，不是每卡各一次 |
| 使用者手動刷新 | 一次Overview，不動socket |
| 卸載Dashboard | 釋放timer與socket資源 |
同一成功response的REST-owned sections共用generatedAt；需要各別品質判斷的來源另外回dataStatus、freshness、updatedAt及必要lastSuccessfulAt。
3.1 接手前後不得覆寫錯的資料¶
首載REST bootstrap
↓
兩個live blocks可以先顯示初始資料
↓
收到DASHBOARD_LIVE_SNAPSHOT → socket接手
↓
之後Overview刷新：
一般區塊／歷史 → 可更新
Connector live／目前功率與open buckets → 不覆寫
只有整頁reload才重取ticket、重新嘗試socket。手動刷新不重建連線；socket中斷也不解除live ownership讓REST冒充備援。
3.2 REST失敗不代表全頁歸零¶
單一source失敗只影響相依section，其他成功部分繼續顯示，Overview標PARTIAL或可診斷source status。初次無成功資料顯示Error／—；後續失敗可依各區契約保留同building成功cache，附更新失敗與lastSuccessfulAt，不假裝最新。
不能catch後回0、不能從preview／其他卡猜值，production不能退回fixture。需留意事項aggregate ERROR依#1463顯示不可取得，不能拿舊cards冒充本次結果；不是所有section都能不分狀態套同一fallback。
4. WebSocket契約：三種訊息、區塊取代¶
V1沿用raw WebSocket，不引入STOMP。每個掛載的Dashboard本體只有一條案場socket。（DEC-008保留部分／009／031）
4.1 Ticket與envelope¶
Ticket短效、一次性，綁定登入管理員與Backend-resolved Building，只有具dashboard function者可取得。
| Envelope欄位 | 用途 |
|---|---|
| schemaVersion | FE判斷是否支援此契約版本 |
| type | 下表三種訊息之一 |
| buildingId | 案場隔離，不接受不符scope資料 |
| occurredAt | 事件資料時間 |
| data | 對應type的typed區塊payload |
不傳raw DB row、JWT、ticket、currentIdTag或不必要個資；前端不對不支援schema或錯scope猜測套用。
4.2 訊息內容¶
| type | 什麼時候／送什麼 | FE如何套用 |
|---|---|---|
| DASHBOARD_LIVE_SNAPSHOT | 建連後，兩個live blocks完整目前狀態 | 接手目前live state，不等於重送整個Dashboard／全部歷史 |
| CONNECTOR_LIVE_BLOCK_UPDATED | Connector五項summary＋totals＋Backend排序Top-8 | 整個區塊replacement，FE不自己算分類／排名 |
| LIVE_LOAD_UPDATED | currentPowerKw、LIVE／TODAY／SEVEN_DAYS三種open bucket；跨界可帶剛結束finalized | 目前值與bucket各自取代，按buildingId＋rangeCode＋bucketStartAt合併 |
不用細碎delta讓FE重算total、bucket、priority或平均功率。Backend可以內部debounce／coalescing保護資源，但不承諾固定5秒更新或P95 2秒SLO，也不為這個要求先建專用架構。
4.3 連不到／中斷時就明示¶
| 情況 | 頁首與兩個live blocks |
|---|---|
| 首次連線失敗 | 明示無法連線；已有初始資料可保留並標未即時更新，沒有資料則—與「即時資料暫時無法取得」。 |
| 已連線後中斷 | 明示連線中斷，保留最後成功資料／時間並標「已停止更新」。 |
| 其他REST區塊 | 仍依共用Overview正常更新，不因socket中斷停止。 |
不做： REST polling fallback、定時更新模式切換、自訂capped exponential backoff、jitter、背景自動重連、visibility reconnect、sequence／gap recovery、專用Retry。使用者整頁reload才再嘗試。
Connection state與source freshness獨立：連著不代表資料FRESH，斷線也不改寫Backend已回傳的來源品質。
4.4 部署前提（DEC-009）¶
V1為單一active ems_branch instance。未來多instance／HA的session fan-out與授權一致性另案設計，不在本功能預做。
5. 品質欄位：0、未知、失敗、過期分開¶
| 狀態 | 契約與畫面 |
|---|---|
| COMPLETE且數值0 | 成功確認的0，不是缺值 |
| null | 未知，不轉0 |
| PARTIAL且Backend有安全值 | 可顯示，明示不完整；FE不自行加出部分合計 |
| PARTIAL無安全值 | null／—，例如不完整的案場功率、未全數完成的上月金額 |
| ERROR | 文字說明來源無法取得，不冒充正常 |
| STALE | 文字標過期與資料時間，不使用正常成功樣式 |
（DEC-006保留部分／015／028／033）
Backend依資料來源設定全系統stale cutoff：Connector、MeterValue、Billing可不同，但所有案場共用；FE不硬編碼秒數。V1不做per-building override、設定table／API／UI、設定權限或audit trail。
6. Connector：相同snapshot支援首頁與完整清單¶
6.1 Summary／Top-8契約¶
Backend從完整案場Connector集合分類、排序，再回固定五個bucket、total、abnormalTotal與最多8筆items。（DEC-034～038，詳細#1423）
| 不變條件 | 說明 |
|---|---|
| 五類順序 | NEEDS_ATTENTION、CHARGING、WAITING、AVAILABLE、OTHER |
| 分類互斥 | 每Connector恰好一類，count總和=total；NEEDS_ATTENTION.count=abnormalTotal |
| 原始事實 | OCPP connection、runtime、Queue分層保留，不被displayBucket取代 |
| Unknown／NOT_PLUGGED | Unknown不當AVAILABLE／OTHER；NOT_PLUGGED依#1423既定mapping歸OTHER |
| 非空／空 | 非空固定五項含0；空時FE顯示Empty，Backend仍五個0 |
| 摘要互動 | 純資訊不可點擊，不進Tab、不發request |
| FE預覽 | Desktop≥1240顯示8、Tablet640～1239顯示6、Mobile<640顯示4；不傳viewport／requestedLimit |
| Item metadata | displayBucket、isAbnormal、severity、priorityReason；FE不重判 |
| Footer | FE只依totals與visible slice算隱藏總數／異常數，不從Top-8推完整統計 |
Preview與Full List共用priority：OFFLINE＋ACTIVE → FAULTED → OFFLINE／STALE／BLOCKED → SUSPENDED_EVSE／UNAVAILABLE → SUSPENDED_EV → CHARGING → PREPARING／Waiting → AVAILABLE。同層持續時間由久至新、Connector ID穩定排序，詳細多條件處理見#1423 UI-DEC-007。
排序是只讀呈現，不改Queue priority；OFFLINE＋ACTIVE不產生「離線充電／待reconciliation」推論（主票及#1463／#1486較新決策）。
6.2 完整清單仍用既有REST search¶
完整集合（Backend限制目前案場）
↓ 全部條件filter
↓ 共用DASHBOARD_PRIORITY sort
↓ 固定size=20 paginate
↓ Spring Page回應
沿用POST /api/connector/search、SearchConnectorDto的page／size與Spring Page metadata；補 keyword 所需的 Charge Point ID／車位、displayBucket、Charge Group、OpenAPI及contract tests。不得先分頁才filter／sort。
Dashboard Full List 的分類欄位命名為「摘要分類」，request 使用 displayBucket；未傳為全部，值限 NEEDS_ATTENTION／CHARGING／WAITING／AVAILABLE／OTHER。它直接重用Summary分類，不把 Connector runtime status 與 Queue status 混成另一組選項。既有管理頁的原始 status 條件維持相容。（DEC-043）
Drawer固定sortMode=DASHBOARD_PRIORITY，不提供使用者sidx／sord控制；/connector/list未用此mode時保留原欄位排序。（DEC-039～041）
Request 最小欄位為 page、固定 size=20、keyword、可選 displayBucket、可選 chargeGroupId、固定 sortMode；不得傳 buildingId。Response 每筆至少回 connectorId、chargePointId、location／floor／parkingSpaceNo、chargeGroup、displayBucket、isAbnormal／severity／priorityReason、OCPP connection／runtime／Queue 分層狀態、nullable currentPowerKw、updatedAt／freshness；外層沿用 Spring Page metadata。完整欄位表以 #1423 第6.3節為準。
只提供前後頁、頁次／總數；0～20不顯示換頁，多頁first／last按鈕正確。改搜尋／篩選回第1頁。Search／filter／page只存目前page memory，close/reopen保留，reload/navigation重設；不存URL、history、local／sessionStorage、Backend或WS。
不提供page-size、頁碼列、直接跳頁、Grid／Table、virtualization或完整inventory WS。
7. 其他區塊：只對接既有決策，不另建算法¶
依主票畫面順序：
| 區塊 | 本票須遵守的關鍵規則 | 完整公式 |
|---|---|---|
| 02 Attention | 明確既有狀態、非零類別數、類內distinct、固定順序／路由；只看current負載品質，無推論或新告警 | #1463 ATT-DEC-001～008 |
| 03 KPI | enabled CP persisted連線；Connector可服務allowlist；canonical ACTIVE；ELIGIBLE distinct／未插槍互斥；today Usage重用；上月全COMPLETE金額。全部REST、不重複功率 | #1486 KPI-DEC-001～011 |
| 04 Live Load | 60分鐘/1分、今天/15分、含今天7日/1小時；時間加權kW；OPEN與品質分離，未知功率null＋PARTIAL；無插值／跨缺口線 | #1462 LOAD-DEC-001～007 |
| 05 Group／Queue | 群組自身容量／Slots，不加總成案場契約容量；只顯示既有source、status、priority、reason、waitingSince／duration | #1462、#1423 UI-DEC-010／011 |
| 07 Usage | 固定30日、COMPLETED最終Wh／開始日、正電量次數、Backend平均；不碰raw MeterValue／費率分段，不顯示時間使用率 | #1461 USG-DEC-001～010 |
| 08 結算流程 | 最近已存在資料期間、四列純資訊、Footer既有帳單／請款頁；不等同上月電費的固定上一日曆月 | #1460 BIL-DEC-001～003 |
8. 工程分工與交付¶
| 負責方 | 交付內容 |
|---|---|
| Backend／REST | current-building resolver、DashboardController／Service、typed Overview／各section DTO與source isolation、共用聚合。 |
| Backend／WS | ticket、handler、session registry、三種typed message，短效一次性授權與single-instance前提。 |
| Backend／Connector | 共用summary／Top-8 ranking；既有search補 displayBucket／keyword／Charge Group、最小response欄位、DASHBOARD_PRIORITY與20筆分頁，管理頁原始status／排序相容。 |
| Backend／Load | current／三range歷史query與時間加權、open／finalized replacement，品質依#1462。 |
| Backend／權限與文件 | dashboard API mapping、OpenAPI @Schema、method與DTO欄位註解、security／contract tests。 |
| FE | /dashboard頁面、單一Overview hook／300秒timer與socket hook、REST／WS state分離、unmount釋放、全部畫面與states、RWD／keyboard／來源時間。 |
| QA／效能 | 權限／scope／typed contract、socket failure無備援、source隔離、各子票數據與RWD、baseline與首站驗證。 |
不改OCPP、Queue／Rotation、Slot allocation、charging lifecycle、帳務計算或排程，不新增告警引擎、Dashboard inventory或業務mutation。
9. 效能與驗收¶
9.1 先量測，不先加架構（DEC-042）¶
A17或代表性等量資料執行aggregate query EXPLAIN，量測Overview endpoint P50／P95，記錄環境、主要table row count／分布、暖機、併發、sample size、量測起訖，使結果可重現。
避免N+1、無界查詢、重複聚合；只有量測證明影響正常使用，才提出query／普通index優化。不把P95<1.5秒當V1 SLA，不先建snapshot table、專用cache、效能排程或新constraint。跨案場SLA若日後需要另定資料量／負載模型。
9.2 驗收清單¶
- 唯一Building正常、零／多筆設定錯誤；request不含FE案場選擇、response／ticket／event一致，cache／event不跨scope。
- 四允許role與多role正向、未授權403、無有效ticket拒絕WS；無credential／個資洩漏或mutation。
- 首載／每300秒／手動每輪一個Overview，無各section timer；同response generatedAt一致、source失敗隔離。
- 初次Error不假0／fixture；refresh只保留同案場資料與時間，依各區品質規則顯示。
- socket接手後，timer／手動Overview不覆寫live；斷線時也不形成fallback。
- Dashboard本體一條raw socket、三typed訊息只更新兩區，full list走REST、detail按需釋放。
- 首次失敗／後續中斷都有提示，最後資料／時間保留、無資料—；無backoff、jitter、自動／visibility重連、sequence/gap recovery、專用Retry。
- 其他REST區塊在socket中斷後照常；整頁reload才新建連線。
- 五bucket互斥、Top-8與8／6／4、priority穩定、summary不可點，0／1／2／8／9／30／100與各斷點正確。
- search完整集合依 keyword／displayBucket／Charge Group filter→sort→20分頁、30／100為2／5頁、0～20無換頁；六個「摘要分類」選項、最小response契約與page memory正確，管理頁原始status／sorting無回歸。
- Load、Attention、KPI、Usage、Billing公式與來源狀態符合第7節子票；無額外range、時間使用率或預估費用。
- 320px以上無頁面水平捲軸；390／768／1024／1440可讀；文字狀態／focus／對比符合WCAG 2.2 AA基本要求。
- EXPLAIN與P50／P95條件完整，無固定秒數SLA。
- production無API／WS error→fixture fallback。
功能實作E2E impact為Add，依主票與各子票新增／更新UI、REST／WS failure、權限、RWD與大量資料case，按priority／trigger納release pack；本次不產生PASS／FAIL或宣稱已跑測試。
10. 決策追溯：現行與已撤回分開¶
| 決策 | 現行有效內容／本文位置 |
|---|---|
| DEC-002 | 保留Overview bootstrap；第3節；fallback部分撤回 |
| DEC-006 | Backend管理source cutoff原則；第5節，設定範圍依033 |
| DEC-008 | raw WS；第4節，sequence/gap recovery撤回 |
| DEC-009～030 | 未被取代的部署／只讀／公式／顯示／權限保留；非兩區WS方案由031取代 |
| DEC-029／030 | 唯一enabled Building與dashboard function；第2節 |
| DEC-031／032 | 兩區WS、無備援；共用5分鐘Overview；第1、3～4節 |
| DEC-033 | 全系統per-source defaults、無案場override；第5節 |
| DEC-034～041 | Connector summary／preview／Drawer記憶體／固定分頁排序；第6節 |
| DEC-042 | 可重現效能baseline而非1.5秒SLA；第9節 |
| DEC-043 | Full List「摘要分類」使用 displayBucket；request／response 最小契約；第1、6、8～9節 |
| 已撤回提案 | 取代規則 |
|---|---|
| DEC-001 FE選building | DEC-029 Backend唯一案場 |
| DEC-003 capped exponential backoff／60秒fallback | DEC-031 無備援與自動重連 |
| DEC-004 固定5秒coalescing產品契約 | DEC-031 只容許內部資源保護，不承諾秒數 |
| DEC-005 Operational Event P95 2秒SLO | DEC-031 不列V1驗收承諾 |
| DEC-007 per-building cutoff override | DEC-033 全系統來源預設 |
| DEC-014 reconnect／gap recovery部分 | DEC-031撤回；REST歷史＋WS區間ownership保留 |
| DEC-021／023～028要求Attention／KPI走WS部分 | DEC-031／032改共用REST；各公式／呈現仍保留 |
歷史討論仍在原票J5641及更早journals，本次不刪除。現行架構已整理至DEC-043，完成全Dashboard一致性review後才整併v1.0；不以本次文字整理視為已進入實作。
需求管理與本次編輯¶
- 本票仍是已確認需求的追蹤票，不代表已完成開發或通過測試；指派、狀態、進度、附件與父子關係均維持原狀。
- 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 契約）；功能實作時仍須遵循主票與本票驗收。
- 2026-09-16：依 Ken 確認新增 DEC-043；Full List Drawer 使用 displayBucket 作為「摘要分類」，明列 request／response 最小契約並保留管理頁原始 status 相容性。本輪只更新需求，不變更 WebSocket、作業邏輯、Issue 狀態／進度或附件。
是由 陳國瑋 於 30 天 前更新
DEC-003 已確認¶
Ken 同意 Dashboard WebSocket 採以下恢復機制：
- 重連等待：1、2、4、8、16、30 秒，30 秒封頂
- 每次加入 ±20% jitter
- 中斷期間每 60 秒以完整 Overview API 更新
- 保留最後資料，但明示「即時連線中斷／定時更新模式」
- Socket open 後必須取得新的 live snapshot，才停止 REST polling
- 401／403、schema 不支援或無效 building scope 不進行無限重試
此決策已整併至 Description；票券維持 New / 0%／需求待確認。
是由 陳國瑋 於 29 天 前更新
DEC-004 已確認¶
Ken 同意 Live Load 採 Backend server-side 5 秒 coalescing：
- 5 秒內的 MeterValue 合併為最新、完整的
LIVE_LOAD_UPDATED - 不向 Dashboard 逐筆轉送 raw MeterValue
- 沒有讀值或 freshness 變化時不做空推送
- Faulted、離線、Transaction、Queue 等 operational event 不受 5 秒窗口延遲
- 聚合與 timer 依
buildingId隔離 - 未知／stale 數值遵循既有 null 與 freshness 規則
此決策已整併至 Description；票券維持 New / 0%／需求待確認。
是由 陳國瑋 於 29 天 前更新
DEC-005 已確認¶
Ken 同意將需求正式定義為：
Operational Event propagation SLO：正常運作條件下，P95 ≤ 2 秒。
量測自 Backend database transaction commit 成功起，至 FE 驗證並套用 WebSocket replacement event 止。適用 Connector／CP connection／Transaction／Queue 等營運事件；不包含設備回報前延遲、Live Load 5 秒 coalescing、REST-only 區塊或 WebSocket 斷線降級期間。
驗收報告需同時列出 sample size、P50、P95、P99、max、未達標比例及 event delivery／parse failure，不可只提供平均值。此決策已整併至 Description；票券維持 New / 0%／需求待確認。
是由 陳國瑋 於 29 天 前更新
- 概述 已更新 (差異)
DEC-006 已確認並修正適用範圍¶
Ken 確認 stale cutoff 由 Backend 集中管理，並指出 Dashboard 是所有案場共用功能，不可只依 A17 定義。
已修正為：
- A17 只是第一個驗證／導入案場
- Cutoff 依資料來源、協定、排程與正常回報週期定義
- REST 與 WebSocket 共用同一套 freshness policy
- FE 不硬編碼 cutoff
- 禁止 A17-specific 判斷
- A17 baseline 只驗證通用預設值，不決定其他案場規則
- per-building override 是否開放，另列下一項待確認決策
票券維持 New / 0%／需求待確認。
是由 陳國瑋 於 29 天 前更新
- 概述 已更新 (差異)
DEC-007 已確認¶
Ken 同意允許受控的 per-building stale cutoff override：
- precedence：
building + source override>global source default - override 依資料來源分開設定
- Backend 負責設定、驗證、權限、effective policy 與異動稽核
- FE 只使用 Backend 回傳的 effective freshness，不維護案場特例
- 移除 override 後回復 global default
- 禁止以 A17／特定 building 的程式碼條件形成隱性例外
此決策已整併至 Description；票券維持 New / 0%／需求待確認。
是由 陳國瑋 於 29 天 前更新
- 概述 已更新 (差異)
DEC-008 已確認¶
Ken 同意 Dashboard V1 延用 raw WebSocket，不引入 STOMP：
- 一個 building 一條 Dashboard socket
- 使用
schemaVersion + type + buildingId + sequence + occurredAt + dataenvelope - 新 session 先送完整 live snapshot，再送 replacement events
- 未知 event type 安全忽略；不支援的 schema version 停止套用且不得無限重連
- Backend DTO、FE type／parser／fixture 與 contract tests 同步維護
- 未來真的需要動態 topic 或 broker routing 時再另案評估 STOMP
此決策已整併至 Description；票券維持 New / 0%／需求待確認。
是由 陳國瑋 於 28 天 前更新
- 概述 已更新 (差異)
DEC-009 已確認¶
Ken 同意 Dashboard V1 的部署前提為同一 Branch deployment scope 僅運行一個 active ems_branch instance：
- Dashboard 仍適用所有案場，不是 A17／單案場限定
- V1 沿用 in-memory ticket、session registry、coalescing 與 sequence
- 部署與 release checklist 必須確認 replicas = 1
- Sticky session 不視為跨 instance fan-out 解法
- 未來 HA／水平擴充需另案設計 shared fan-out、routing、sequence／deduplication 與 recovery
至此 #1424 原列的架構待確認事項皆已有決策。本票維持 New / 0%，等其他 Dashboard 需求確認完成後一起整併至 #1422 最終規格。
是由 陳國瑋 於 27 天 前更新
- 概述 已更新 (差異)
確認 DEC-033：Dashboard V1 撤回 per-building stale cutoff override。
V1 僅保留 Backend 依資料來源設定的全系統 default；所有案場共用同一套規則，A17 只作驗證。取消設定資料表、管理 API／UI、設定權限、precedence 與 audit trail。原 DEC-007 已標成「由 DEC-033 取代」。這項變更只縮小 Dashboard 開發範圍，不改變既有 OCPP watchdog、MeterValue、Connector、Queue 或帳務作業邏輯。
是由 陳國瑋 於 26 天 前更新
- 概述 已更新 (差異)
【架構同步】新增 DEC-040：Connector Full List 固定使用 REST server pagination，每頁 20 筆；沿用／擴充既有 POST /api/connector/search、page／size 與 Spring Page metadata。搜尋／篩選變更回第 1 頁且查完整 Server dataset；不透過 Dashboard WebSocket 傳 inventory，也不提供 page-size selector、直接跳頁或 virtualization。
DEC-039 的 page-session state 生命週期保持不變；使用者排序另由 #1423 UI-DEC-020 確認。此為唯讀查詢／呈現契約，不改變 Connector、Queue、OCPP 或 charging 作業邏輯。議題維持 New／0%。E2E impact：需求階段 No catalog change；實作時補 UI／REST contract 與 pagination case。
是由 陳國瑋 於 26 天 前更新
- 概述 已更新 (差異)
【架構同步】新增 DEC-041：Connector Full List 固定採 Backend priority sorting，不提供使用者 sorting control／state。既有 POST /api/connector/search 增加 stable DASHBOARD_PRIORITY read mode；Server 對完整集合依序 filter → 共用 priority ranking → 固定 20 筆 pagination。
Dashboard 不使用使用者輸入的 sidx／sord；既有 /connector/list 未使用此 mode 時保留原欄位排序。此決策不新增 WebSocket inventory、排序偏好持久化或任何 operational mutation。
本票維持 New／0%。E2E impact：需求階段 No catalog change；實作時補 API contract、跨頁固定順序及既有管理頁 sorting regression case。
是由 陳國瑋 於 26 天 前更新
- 概述 已更新 (差異)
【需求文件整理】依 Ken 確認，#1424 description 已重整為「現行有效版」。
- 保留全部仍有效的 Building scope、SS3A 權限、Overview、WebSocket、freshness、Connector、Live Load、Attention、KPI、Usage、結算、FE／BE／QA與驗收規則。
- 現行 WebSocket 只更新 Connector 即時狀態與案場即時負載；其他 sections 共用 Overview 首載／5 分鐘／手動刷新。
- 從現行 Acceptance Criteria 移除已被 DEC-031～033 取代的 capped exponential backoff、60 秒 REST fallback、sequence／gap recovery、visibility reconnect、固定 5 秒 coalescing、P95 2 秒 SLO及 per-building cutoff override。
- 舊方案沒有刪除歷史：完整舊 description 可由 J5641 及更早 journals 追溯；現行 description 另保留「已取代的討論歷程索引」。
- 這次只是 requirement source 去矛盾，不改變 Ken 已確認的產品行為；Issue 維持 New／0%。
E2E impact：No catalog change。正式 Dashboard 實作仍屬 Add，必須依現行 Acceptance Criteria 建立相應長期 E2E cases；本次未執行產品／整合／E2E 測試。
是由 陳國瑋 於 26 天 前更新
【架構決策確認｜DEC-042】
Ken 已確認 Overview 效能驗證採「可重現 baseline」，不將 P95 < 1.5 秒 設為 V1 產品 SLA。
實作／首站驗證要求：
- 以 A17 或具代表性的等量資料執行 aggregate query EXPLAIN，並量測 endpoint P50／P95。
- Test report 記錄環境、主要資料表 row count／資料分布、暖機方式、併發數、sample size 與量測起訖邊界。
- 避免 N+1、無界查詢與不必要重複聚合；只有實測影響正常使用時才提出 query／普通 index 優化。
- 不為固定秒數預先新增 snapshot table、專用 cache、效能排程或其他架構。
- 若未來需要跨案場固定 SLA，另案定義資料量級、負載模型與測試條件。
本次僅更新需求紀錄，未修改產品程式或 mock。Issue 維持 New／0%。E2E impact：需求階段 No catalog change；正式實作時補可重現的 performance baseline 報告與相應測試。
是由 陳國瑋 於 25 天 前更新
【架構決策同步｜DEC-031／032】
已依 Ken 確認，清除 Parent #1422 殘留的 KPI WebSocket 要求。
#1424 現行 description 原本已正確，因此本次不改寫 description；仍以以下規則為準：
- 六張 KPI 只由共用 Overview REST 在首載、每 5 分鐘及手動刷新時更新。
- Dashboard 不為 KPI 新增或訂閱 NETWORK_HEALTH_UPDATED／CONNECTOR_OVERVIEW_UPDATED。
- Connector 即時狀態仍由 CONNECTOR_LIVE_BLOCK_UPDATED 更新。
- 案場即時負載仍由 LIVE_LOAD_UPDATED 更新。
- 最小 message type 維持 DASHBOARD_LIVE_SNAPSHOT、CONNECTOR_LIVE_BLOCK_UPDATED、LIVE_LOAD_UPDATED。
Issue 維持討論／New／0%；沒有新增 WebSocket event 或作業邏輯。
是由 陳國瑋 於 15 天 前更新
DEC-043 已確認：Drawer 摘要分類與 search 契約¶
- Full List Drawer 透過既有 REST search 取得完整集合；使用
displayBucket作為「摘要分類」條件。 -
displayBucket未傳代表全部；有效值為 NEEDS_ATTENTION／CHARGING／WAITING／AVAILABLE／OTHER。 - Dashboard 不重用原始
status製作 runtime／Queue 混合 selector；既有管理頁 status 與排序能力維持相容。 - Description 已補 request／response 最小契約、OpenAPI／contract test 工作與驗收條件。
- WebSocket 分工不變：首頁 Connector live block 仍走 WebSocket，Full List 仍走 REST；未增加斷線備援或作業邏輯。
本輪只更新需求；Tracker／Status／Done ratio／指派與附件均不變。E2E impact：No catalog change。