# 杆體資訊

:::success
本應用實務依據 ``5G智慧杆系統技術規範``，標準化智慧杆基本資訊之交換欄位、結構、API 操作規則及錯誤處理，協助地方政府與系統整合商高效串接、維運智慧杆資產資料。
:::

## 欄位與資料定義

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |
| vendor | String | M | 桿體原廠/供應商 | 例：台灣智慧杆公司 |
| model | String | M | 型號 | 例： |
| serial | String | M | 序號 | 例： |
| **系統與應用欄位** |
| poleId | String | M | 智慧杆唯一識別碼 | 建議使用UUID格式 |
| station | String | M | 所屬站點/管理單位名稱 | 例：忠孝東路五段路口 |
| jurisdiction | String | M | 管轄行政區域 | 例：臺北市信義區 |
| zip | String | O | 郵遞區號| 例：110 |
| address | String | O | 安裝地址 | 完整地址 |
| latitude | Float | M | 緯度 | WGS84 座標系統 |
| longitude | Float | M | 經度 | WGS84座標系統 |
| installationTime | DateTime | O | 安裝完成時間 | ISO8601 格式 |
| status | String | M | 狀態 | Active, Inactive, UnderConstruction, Decommissioned |
| Loudspeaker | Boolean | O | 擴音喇叭 | 配置資訊 |
| AED | Boolean | O | 自動體外心臟除顫器 | 配置資訊 |
| authority | String | M | 權責/維護單位名稱 | 例：臺北市政府工務局 |
| contact | String | O | 聯絡人姓名/電話 | 例：王小明 0988123456 |
| lastUpdate Time | DateTime | O | 最近更新時間 | ISO8601 格式 |
| remark |String | O | 備註說明 | 使用者填寫 |

## 資料結構與操作規則

### 資料結構（JSON）

{
  "poleId": "UUID-abc-123",
  "station": "忠孝東路五段路口",
  "jurisdiction": "臺北市信義區",
  "zip": "110",
  "address": "臺北市信義區忠孝東路五段555號",
  "latitude": 25.033964,
  "longitude": 121.562321,
  "installationTime": "2023-08-15T14:00:00Z",
  "status": "Active",
  "authority": "臺北市政府工務局",
  "vendor": "台灣智慧杆公司",
  "contact": "王小明 0988123456",
  "lastUpdateTime": "2023-10-01T11:00:00Z",
  "remark": "定期檢測，無異常"
}

### 操作規則

| 操作 | HTTP 方法 | 說明 | 端點範例 |
| -------- | -------- | -------- | -------- |
| 新增桿體資訊 | POST | 建立新智慧杆基本資訊 | /api/v1/poles |
| 查詢資訊 | GET | 依條件查詢桿體資訊 | /api/v1/poles?poleId=... |
| 修改資訊 | PUT | 更新指定桿體資訊 | /api/v1/poles/{poleId} |
| 刪除資訊 | DELETE | 刪除指定桿體資料 | /api/v1/poles/{poleId} |

查詢參數與使用限制
* 查詢可依 poleId、station、jurisdiction、status、vendor、installationTime 篩選
* 單次查詢上限 100 筆，超過須分頁。
* 基本資料異動以日批次同步為主，如即時建置/拆除應即時更新。

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

### 錯誤回傳格式

{
  "status": "error",
  "code": 400,
  "message": "必填欄位缺失或格式錯誤",
  "errors": [
    {
      "field": "address",
      "code": "MISSING_FIELD",
      "message": "address 不可為空"
    }
  ]
}

### 常見錯誤碼

| 錯誤碼 | 說明 | 處理方式 |
| -------- | -------- | -------- |
| 400 | 必填欄位缺失/格式錯誤 | 檢查資料並修正 |
| 401 | 未授權存取 | 確認 API Token |
| 403 | 無操作權限 | 確認操作身分或權限設定 |
| 404 | 查無資料 | 檢查 poleId 等查詢條件 |
| 409 | 資料衝突（如重複poleId） | 檢查唯一性，排除重複。 |
| 500 | 系統內部錯誤 | 聯絡維運 |

## 資料格式與代碼支援

### JSON 規範

* 字元集：UTF-8
* 日期時間：ISO8601 格式（如 2023-08-15T14:00:00Z）
* 坐標系統：WGS84（小數點後六位）

### 狀態代碼表

| 狀態值 | 說明 |
| -------- | -------- |
| Active | 已啟用/運作中 |
| Inactive | 已停用/未運作 |
| UnderConstruction | 施工中 |
| Decommissioned | 已報廢/拆除 |

### 測試資料與版本控管

* 提供測試範例資料集供 API 驗證
* API/Schema 版本標示於URL（如 /api/v1/poles）
* 更新紀錄與變更說明須納入系統維護文檔
* 建議設置 lastUpdateTime 支援資料同步/比對