# 儲能管理

:::success
此應用實務在於協助各方標準化儲能管理系統數據串接作業，落實智慧杆高效能源管理目標。
- 建議儲能管理系統與智慧杆控制系統協同設計，實現即時監控與故障預警。
- 推薦採用 MQTT 或 RESTful API 雙向通信，提升資料交互效率。
- 定期校驗設備 DEVSNo 與系統 UUID 一致性，確保資料來源正確。
- 強化電池健康狀態監控，預防儲能系統潛在風險。

:::

[toc]

## 欄位與資料定義

### 儲能狀態資料

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |
| Vender | String | M | 廠商 | 記錄設備實際製造廠商名稱 |
| Model | String | M | 型號 | 記錄設備型號 |
| Serial | String | M | 序號 | 記錄設備唯一序號 |
| **系統與應用欄位** |
| Token | String | M | | |
| DEVSNo | String | M | 設備識別碼 | 識別碼唯一 |
| timestamp | DateTime | M | 資料紀錄時間 | ISO8601 格式 |
| batteryCapacity | Float | M | 總電池容量 (kWh) | 例: 12.5 kWh |
| batterySOC | Float | M | 電池剩餘容量(%) | State of Charge，0~100 |
| batteryVoltage | Float | M | 電池電壓 (V) | 單位伏特 |
| batteryCurrent | Float | M | 電池電流 (A) | 正值表示放電，負值充電。 |
| batteryTemperature | Float | O | 電池溫度 (°C) | 可空缺 |
| batteryHealth | String | O | 電池健康狀況 | 例: Good、Warning、Critical |
| chargePower | Float | O | 充電功率 (kW) | 正值表示充電 |
| dischargePower | Float | O | 放電功率 (kW) | 正值表示供電 |
| chargeStatus | String | M | 充放電狀態 | 例: Charging, Discharging, Idle |

### 能源管理與輸入輸出

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| inputPower | Float | O | 輸入功率（kW） | 來自外部輸入，例: 電網或太陽能 |
| outputPower | Float | O | 輸出功率（kW） | 輸出到負載的功率 |
| energyCharged | Float | O | 充入能源累積（kWh） | 累計充電量 |
| energyDischarged | Float | O | 放出能源累積（kWh）| 累計放電量 |
| gridConnected | Boolean | M | 是否連接電網 | true: 連接，false: 離線 |

## 資料結構與操作規則

### 資料結構

{
  "DEVSNo": "STC-2025A-0012",
  "timestamp": "2025-05-01T10:00:00.000Z",
  "batteryCapacity": 12.5,
  "batterySOC": 87.3,
  "batteryVoltage": 48.5,
  "batteryCurrent": -5.2,
  "batteryTemperature": 29.5,
  "batteryHealth": "Good",
  "chargePower": 3.0,
  "dischargePower": 0.0,
  "chargeStatus": "Charging",
  "inputPower": 5.0,
  "outputPower": 4.5,
  "energyCharged": 120.5,
  "energyDischarged": 110.7,
  "gridConnected": true
}

## 操作規則

| 操作 | HTTP 方法 | 說明 | 端點範例 |
| -------- | -------- | -------- | -------- |
| 新增數據 | POST | 上報當前儲能狀態與能量資料 |/api/v1/energy-management |
| 查詢數據 | GET | 根據 DEVSNo、時間區間查詢儲能資料 | /api/v1/energy-management?deviceId={}&startTime={}&endTime={} |
| 修改數據 | PUT | 更新儲能設備狀態（例：健康狀態）| /api/v1/energy-management/{deviceId} |
| 刪除數據 | DELETE | 刪除指定設備數據 | /api/v1/energy-management/{deviceId} |

* 查詢參數與使用限制
* 查詢參數：
* deviceId (必填)：設備唯一標識
* startTime (選填)：查詢開始時間
* endTime (選填)：查詢結束時間
* 使用限制：
* 單次查詢最大回傳1000筆
* 查詢時間範圍不超過30天
* 交換頻率：
* 儲能狀態資料建議即時上報（約1~5秒頻率）
* 歷史數據批次查詢每日或每小時更新均可

## 錯誤處理規則與回傳格式

### 錯誤處理原則

* 請求格式錯誤或必填欄位缺失回傳 400
* 未授權或Token驗證失敗回傳 401
* 無權限操作回傳 403
* 查無相關資料回傳 404
* 伺服器內部錯誤回傳 500

### 錯誤回傳範例

{
  "status": "error",
  "code": 400,
  "message": "batterySOC 欄位缺失或格式錯誤",
  "errors": [
    {
      "field": "batterySOC",
      "code": "MISSING_FIELD",
      "message": "必填欄位不得省略"
    }
  ]
}