---
# System prepended metadata

title: 杆體資訊
tags: [IDA]

---

# 杆體資訊

:::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）

```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 筆，超過須分頁。
* 基本資料異動以日批次同步為主，如即時建置/拆除應即時更新。


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

### 錯誤回傳格式

```json
{
  "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 支援資料同步/比對