# 充電樁

:::success
充電樁管理系統應用實務依據 OCPP 1.6 標準與智慧杆技術規範，涵蓋充電樁狀態監控、交易管理與設備控制，適用於電動車充電樁與智慧杆系統整合。
:::

## 欄位與資料定義

### 基礎設備資訊

| 欄位名稱 | 格式 | 必備 | 說明 | OCPP 對應訊息 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |
| Vender | String | M | 廠商 | 記錄設備實際製造廠商名稱 |
| Model | String | M | 型號 | 記錄設備型號 |
| Serial | String | M | 序號 | 記錄設備唯一序號 |
| **系統與應用欄位** |
| chargePointId | String | M | 充電樁唯一識別碼 | ChargePoint.id |
| poleId | String | O | 智慧杆編號 | 關聯杆體資訊 |
| vendor | String | M | 製造商名稱 | BootNotification |
| firmwareVersion | String | M | 韌體版本 | BootNotification |
| connectorType | String | M | 充電接口類型 | Enum：Type1 / Type2 /CCS |
| maxPower | Float | M | 最大輸出功率(kW) | 硬體規格 |
| voltage | Float | O | 當前電壓(V) | MeterValues |
| current | Float | O | 當前電流(A) | MeterValues |

### 充電狀態資訊

| 欄位名稱 | 格式 | 必備 | 說明 | OCPP 對應訊息 |
| -------- | -------- | -------- | -------- | -------- |
| sessionId | String | M | 充電工作階段 ID | StartTransaction |
| status | String | M | 充電狀態 | Enum： Available Preparing / Charging / Suspended / Error |
| startTime | DateTime | O | 充電開始時間 | StartTransaction |
| endTime | DateTime | O | 充電結束時間 | StopTransaction |
| energyDelivered | Float | O | 已供電量(kWh) | MeterValues |
| currentPower | Float | O | 即時功率(kW) | MeterValues |
| userId | String | O | 使用者識別碼 | IdTag |
| transactionId | Integer | O | 交易流水號 | TransactionId |

### 控制指令參數

| 欄位名稱 | 格式 | 必備 | 說明 | OCPP 對應訊息 |
| -------- | -------- | -------- | -------- | -------- |
| command | String | M | 控制指令 | Enum： RemoteStart / RemoteStop / Reset / UnlockConnector |
| targetPower | Float | O | 目標充電功率(kW) | ChargingProfile |
| schedule | JSON | O | 充電排程設定 | SetChargingProfile |
| authId | String | O | 授權識別碼 | 用於 RemoteStart |

## 資料結構與操作規則

### 主要資料結構

// 充電樁狀態回報（即時）
{
  "chargePointId": "CP-001",
  "poleId": "POLE-1024",
  "status": "Charging",
  "connectorType": "CCS",
  "voltage": 380.5,
  "current": 32.1,
  "currentPower": 12.2,
  "energyDelivered": 45.7,
  "sessionId": "SESSION-20231001-001",
  "userId": "USER-5566",
  "timestamp": "2023-08-15T14:30:00Z"
}

// 控制指令範例
{
  "command": "RemoteStart",
  "chargePointId": "CP-001",
  "authId": "CARD-887766",
  "targetPower": 60.0,
  "schedule": {
    "startTime": "2023-08-15T22:00:00Z",
    "duration": 120
  }
}

### API 端點與操作

| 操作類型 | HTTP 方法 | 端點路徑 | 說明 |
| -------- | -------- | -------- | -------- |
| 狀態回報 | POST | /api/v1/charging/status | 即時傳輸充電狀態 |
| 啟動充電 | POST | /api/v1/charging/sessions/start | 遠端啟動充電 |
| 停止充電 | POST | /api/v1/charging/sessions/stop | 遠端停止充電 |
| 查詢紀錄 | GET | /api/v1/charging/sessions | 依時間範圍查詢充電紀錄 |
| 更新設定 | PUT | /api/v1/charging/config | 修改充電樁參數設定 |

### 交換頻率與限制

* 即時數據：充電狀態變化5秒內上報，功率值每秒採樣
* 批量數據：交易紀錄每15分鐘批次上傳
* 控制指令：需在1秒內回應
* API 限流：每設備每秒最多10次請求

## 錯誤處理機制

### 錯誤代碼表

| 錯誤碼 | 說明 | 處理建議 |
| -------- | -------- | -------- |
| 400 | 指令參數缺失/格式錯誤 | 檢查JSON結構與數值範圍 |
| 403 | 充電樁忙碌/無法執行指令 | 檢查設備狀態後重試 |
| 404 | 充電樁 ID 不存在 | 驗證設備註冊狀態 |
| 409 | 充電槍未就緒 | 檢查連接器狀態 |
| 500 | 充電樁內部錯誤 | 重試或聯繫廠商技術支援 |

### 錯誤回傳格式

{
  "errorCode": "OCPP-4001",
  "message": "連線器未解鎖，無法啟動充電",
  "details": {
    "chargePointId": "CP-001",
    "connectorId": 1,
    "timestamp": "2023-08-15T14:35:00Z"
  }
}

## OCPP 1.6 對應實作

### 主要指令對應表

| OCPP指令 | API端點 | 說明 |
| -------- | -------- | -------- |
| BootNotification | POST /device/register | 設備註冊 |
| Heartbeat | POST /healthcheck | 心跳檢測 |
| StartTransaction | POST /sessions/start | 啟動交易 |
| StopTransaction | POST /sessions/stop | 結束交易 |
| MeterValues | POST /telemetry | 計量數據上傳 |

### 安全驗證機制

* TLS 1.2 + 加密：所有 API 傳輸強制使用 HTTPS
* 雙向認證：充電樁需憑數位證書連接
* OCPP-JSON 編碼：訊息採用 RFC7159 標準

### 測試建議

提供以下測試情境模擬資料
* 正常充電流程（含啟動/計量/停止）
* 異常中斷情境（斷電/網路中斷）
* 併網負載測試（多槍同時充電）