# 路燈控制器

5G智慧杆系統 - 路燈控制器數據串接指引

:::success
本應用實務依據``5G智慧杆技術規範``，明確定義路燈控制器數據欄位與操作規則，支持安全、標準且擴充性良好的智慧路燈資料串接。

地方政府與系統整合商可據此設計與實作 API，確保系統安全穩定、數據一致，提升智慧杆整體運維效率。
:::

依據5G智慧杆系統技術規範，路燈控制器數據包含以下關鍵資訊：

* **路燈狀態資訊**
控制器依伺服器之查詢指令，回傳其當前已連線、設備異常或其他之狀態資訊。
* **調光控制與結果資訊**
控制器依伺服器之路燈調光控制指令，以控制路燈之亮度，完成調光控制後立即回報伺服器路燈調光之控制結果資訊。
* **開關控制與結果資訊**
控制器依伺服器之路燈開關控制指令，以控制路燈之開關，完成開關控制後立即回報伺服器路燈開關之控制結果資訊。

本指引統整欄位定義、資料結構、操作規則與 JSON 格式，協助地方單位與系統整合業者正確串接執行。

[toc]

## 欄位與資料定義

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |
| Vender | String | M | 廠商 | 記錄設備實際製造廠商名稱 |
| Model | String | M | 型號 | 記錄設備型號 |
| Serial | String | M | 序號 | 記錄設備唯一序號 |
| **系統與應用欄位** |
| Token | String | M | 在伺服器端成功識別使用者身分(帳戶名及通行碼)後，提供之唯一識別碼，用以存取資料或控制設備。| |
| DEVSNo | String | M | 控制器編號 | |
| **路燈狀態資訊** |
| Status | Integer | M | 控制器當前狀態 | 1: 已連線 3: 設備異常 9: 其他 |
| **調光控制與結果資訊** |
| Level | 整數 | M | 路燈之亮度比例 | 以百分比表示 |
| Result | String | M | 路燈調光狀態執行結果 | true: 執行成功 false: 執行失敗 |
| **開關控制與結果資訊** |
| Switch | Integer | M | 路燈之開關狀態 | 0: 關閉 1: 開啟 |
| Result | String | M | 路燈開關狀態執行結果 | true: 執行成功 false: 執行失敗|

## 資料結構與操作規則

### 資料結構範例 (JSON)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "DEVSNo": "SLC123456",
  "Status": 1,
  "Level": 75,
  "Switch": 1,
}

### 操作規則

| 操作 | 說明 | 輸入內容 | 備註 |
| -------- | -------- | -------- | -------- |
| 新增 | 新增控制器資訊紀錄| 含 Token、DEVSNo 及必填欄位 | DEVSNo 唯一，不可重複。 |
| 查詢 | 依條件查詢控制器狀態與控制資訊 | 需攜帶有效 Token，可依 DEVSNo、Status 等參數查詢 | 支持分頁，避免一次返回過多數據。 |
| 修改 | 更新控制指令與結果 | Token + 指定 DEVSNo + 欲更新欄位 | DEVSNo 不可修改，控制指令格式與範圍必須合規。 |
| 刪除 | 刪除指定控制器紀錄 | Token + DEVSNo | 僅限存在資料，可記錄刪除操作日誌。|

### Token 使用注意事項

* 所有 API 請求必須攜帶 Token 以授權驗證。
* Token 應放置於 HTTP Header：

    Authorization: Bearer {token}

* Token 過期需重新登入驗證，系統應設計 Token 失效回應與刷新機制。
* 請以 HTTPS 傳輸，保障 Token 與數據安全。

### 資料交換頻率

| 項目 | 頻率 |
| -------- | -------- |
| 狀態與開關結果 | 即時或每5分鐘更新 |
| 調光控制與結果 | 每10分鐘同步或依策略調整 |

### 錯誤處理與回應格式

| 錯誤碼 | 含義 | 回應說明 |
| -------- | -------- | -------- |
| 400 | 請求格式錯誤 | 請檢查必填欄位與格式。 |
| 401 | Token 缺失或無效 |請攜帶有效 Token 進行身份驗證。 |
| 403 | 權限不足 | 使用者無權限存取資料 |
| 404 | 查無資料 | 請確認DEVSNo或查詢條件 |
| 409 | 新增資料重複 | DEVSNo 已存在 |
| 500 | 伺服器錯誤 | 請稍後重試或聯絡系統維護人員 |

* 成功回應範例

    {
      "code": 200,
      "message": "操作成功",
      "data": {
        "DEVSNo": "CTRL123456",
        "status": "ON",
        "dimResult": 73,
        "powerResult": "ON"
      }
    }

## 資料格式與代碼支援

### JSON 格式

明確結構化數據，方便API前後端對應。

### 狀態與控制欄位代碼表

| 欄位 | 代碼值 | 說明 |
| -------- | -------- | -------- |
| **Status** | 1 | 已連線 |
| | 3 | 設備異常 |
| | 9 | 其他 |
| **Switch** / Result | 0 | 關閉 |
| | 1 | 開啟 |
| | false | 開關操作失敗 |
| **Level** / Result | 0-100 | 亮度百分比 |
| | false | 調光操作失敗 |

### 測試資料建議

* 包含多種 status、控制命令與 Token 有效性的測試用例
* 模擬時間戳及異常情況（Token 過期、權限拒絕等）

### 版本控管建議

* API與資料結構標明版本（例如: v1.0）
* 結構變更需保證向下相容並公告更新內容
* 紀錄所有控制指令與操作日誌，方便追蹤與問題排查。