EMS

背景¶

FE ticket #1365 需要 Branch Admin websocket connector status UI 可以取得 connectorData.statusLabel，用來顯示 status 的中文文字。請後端/API 補上此欄位，讓 websocket payload 同時提供機器可判斷的 status 與人可讀的 statusLabel。

需求¶

在 connector websocket response 的 connectorData 內新增欄位：

預期 websocket message example：

{
  "eventType": "UPDATED",
  "buildingId": "building-id",
  "connectorId": "connector-id",
  "timestamp": "2026-07-06T18:30:00",
  "connectorData": {
    "id": "connector-id",
    "buildingId": "building-id",
    "areaType": "public",
    "status": "CHARGING",
    "statusLabel": "充電中",
    "connectorType": "J1772",
    "image": null,
    "startTime": "2026-07-06T18:00: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-06T22:00:00",
    "nextOffPeakTimeEnd": "2026-07-07T06:00:00"
  }
}

Status label mapping¶

注意：statusLabel 是 UI 顯示文字，不應取代 status。FE 的狀態判斷仍以 status code 為準。

實作範圍¶

請同時處理兩條 websocket 資料來源：

1. 連線成功後的 initial connector data

   • 目前由 ConnectorWebSocketHandler.sendInitialConnectorData() 從 Branch API 取得 connector，再轉成 ConnectorEventData。
   • 這條路徑也必須填入 statusLabel。

2. RabbitMQ connector event 轉推 websocket

   • 目前 ems_branch 的 ConnectorEventPublisher.convertToEventData() 建立 connector event data。
   • ems_hq 的 ConnectorEventSubscriber 直接把 event 的 connectorData 包進 ConnectorUpdateMessage。
   • 因此 MQ event data 也必須包含並正確序列化/反序列化 statusLabel。

建議修改位置¶

• java/ems_branch/src/main/java/com/sylksoft/ems/branch/mq/model/ConnectorEventData.java
• java/ems_branch/src/main/java/com/sylksoft/ems/branch/mq/publisher/ConnectorEventPublisher.java
• java/ems_hq/src/main/java/com/sylksoft/ems/hq/mq/model/ConnectorEventData.java
• java/ems_hq/src/main/java/com/sylksoft/ems/hq/websocket/ConnectorWebSocketHandler.java
• 如 Branch HTTP connector DTO/OpenAPI 也會作為 initial websocket 來源，請同步確認是否需要在 ConnectorFromBranchDto 或 branch connector response 補 statusLabel，避免 initial data 與 event update 欄位不一致。

Acceptance Criteria¶

• websocket payload 的 connectorData 包含 statusLabel。
• initial websocket message 與後續 RabbitMQ UPDATED event 轉推 message 都包含 statusLabel。
• status 保持原本 code，不因新增 statusLabel 而改變。
• statusLabel 對應表符合本票的 Status label mapping。
• SUSPENDEDEVSE 顯示為 充電站暫停，SUSPENDEDEV 顯示為 車輛暫停。
• FINISHING 顯示為 結束中，不是 完成。
• 若 status 為 null 或未知值，statusLabel 可以為 null 或 未知狀態；但不可把 status 或 label 改成 AVAILABLE / 待命。
• 相關 DTO / OpenAPI schema 若有產生文件，需同步更新。
• 補上單元測試或序列化測試，至少覆蓋 AVAILABLE、CHARGING、SUSPENDEDEVSE、SUSPENDEDEV、FINISHING、unknown/null。

Related¶

• FE UI mapping ticket: #1365