---
# System prepended metadata

title: 路燈控制器
tags: [IDA]

---

# 路燈控制器

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)

```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 |	伺服器錯誤 |	請稍後重試或聯絡系統維護人員 |

* 成功回應範例
    ```json
    {
      "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）
* 結構變更需保證向下相容並公告更新內容
* 紀錄所有控制指令與操作日誌，方便追蹤與問題排查。





