EMS

目的¶

Branch Admin 的充電樁狀態頁目前透過 GET /api/connector/status/{connectorId} 輪詢取得狀態。請新增 Branch API websocket solution，讓 react/branch 的 Connector Status 畫面可以即時取得 connector status update，降低輪詢延遲與 API loading。

此需求目標是 Branch Admin UI：react/branch，不是 LINE LIFF react/web。

現況¶

• Branch API 目前只註冊 OCPP websocket：/ws/ocpp/{chargePointId}，給 charge point 連線使用。
• Branch Admin connector edit page 目前使用 ConnectorStatus component。
• FE hook useConnectorStatus(connectorId) 目前呼叫 GET /api/connector/status/{connectorId}，並在 AVAILABLE / PREPARING / CHARGING 狀態下每 2 秒 refetch。
• Branch 後端已會在 connector 狀態改變時透過 ConnectorEventPublisher 建立 connector event data 並送 RabbitMQ 給 HQ。
• #1366 已補齊 websocket payload 所需的 statusLabel 與 status label mapping。

需求¶

新增 Branch Admin browser websocket endpoint，建議路徑：

/ws/connector/{connectorId}

Branch Admin FE 連線後應立即收到 initial connector data；後續當 connector status / charging metrics / off-peak queue 資訊變更時，Branch API 應即時推送 UPDATED message 給正在觀看該 connector 的 admin sessions。

WebSocket Message Shape¶

建議與 HQ / LIFF connector websocket payload 保持一致，但 Branch Admin 不需要 buildingId 作為 routing key。

{
  "eventType": "UPDATED",
  "connectorId": "connector-id",
  "timestamp": "2026-07-07T23:00:00",
  "connectorData": {
    "id": "connector-id",
    "areaType": "public",
    "status": "CHARGING",
    "statusLabel": "充電中",
    "connectorType": "J1772",
    "image": null,
    "startTime": "2026-07-07T22:30:00",
    "totalEnergy": 12.34,
    "energyUsage": 3.21,
    "remainTime": 45,
    "currentVoltage": 220.0,
    "currentCurrent": 16.0,
    "currentPower": 3.52,
    "costPredict": 25.0,
    "currentTariff": 7.5,
    "enableOffPeak": true,
    "nextOffPeakTimeStart": "2026-07-07T23:00:00",
    "nextOffPeakTimeEnd": "2026-07-08T06:00:00"
  }
}

connectorData.status 是 FE UI 邏輯判斷來源；connectorData.statusLabel 只作為中文顯示文字。

Backend 實作要求¶

• 在 ems_branch 新增 browser 用 connector websocket，不影響現有 OCPP /ws/ocpp/* endpoint。
• WebSocket session registry 以 connectorId 管理，可同時支援多個 admin sessions 觀看同一 connector。
• 連線建立後，使用與 GET /api/connector/status/{connectorId} 相同的資料來源產生 initial data。
• 後續 update 應接在既有 connector update flow 上，優先 reuse ConnectorEventPublisher / ConnectorEventData / ConnectorStatusMapper，避免 websocket payload 與 RabbitMQ 給 HQ 的 payload 不一致。
• unknown/null status 不可 fallback 成 AVAILABLE；statusLabel 應回 未知狀態 或沿用 #1366 mapping。
• WebSocket 應支援 heartbeat / ping-pong 或至少能正確清除 closed/error sessions。
• 需確認 Security / CORS / allowed origins，不可讓 OCPP endpoint 的設定誤套到 admin browser endpoint。

Frontend 實作要求¶

• react/branch 的 Connector Status component 改為：HTTP initial/fallback + WebSocket realtime update。
• WebSocket 成功連線後，不應再依賴 2 秒 polling 更新狀態。
• WebSocket 斷線時可保留 HTTP refetch fallback，避免頁面失去狀態更新能力。
• FE 應使用集中式 status mapping，並支援 #1365 定義的 status UI 行為與色碼：AVAILABLE、ENQUEUED、PREPARING、CHARGING、SUSPENDEDEVSE、SUSPENDEDEV、FINISHING、RESERVED、UNAVAILABLE、FAULTED、unknown/null。
• statusLabel 只顯示中文，不作為 CTA 邏輯來源。

Acceptance Criteria¶

• Branch API 提供 Branch Admin browser 可連線的 connector websocket endpoint。
• Admin 開啟 connector status 畫面後，會收到 initial connector data。
• Connector status 由 OCPP StatusNotification、start/stop charging、off-peak queue 狀態改變時，Admin UI 能收到 websocket update。
• WebSocket payload 包含 connectorData.status 與 connectorData.statusLabel。
• Branch Admin UI 不再需要在正常 websocket 連線時每 2 秒 polling connector status。
• WebSocket 斷線時，UI 有 fallback 或 reconnect 行為。
• 現有 OCPP /ws/ocpp/* 連線不受影響。
• 補上 backend unit/integration tests 或至少 websocket handler/session registry 測試；FE 補上 hook/component 測試或 manual QA cases。

Related¶

• #1365 LINE LIFF Connector Status UI mapping
• #1366 Connector WebSocket payload add statusLabel