---
# System prepended metadata

title: 儲能管理
tags: [IDA]

---

# 儲能管理

:::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: 離線 |

## 資料結構與操作規則

### 資料結構

```json
{
  "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

### 錯誤回傳範例

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





