---
# System prepended metadata

title: 緊急求救對講機
tags: [SPDAGB]

---

# 緊急對講機

:::success
本應用實務提供緊急對講機數據必要欄位、結構與通訊規範，兼顧事件管理、設備監控與資料安全，協助地方政府與系統業者標準化開發、快速串接及穩定營運。
:::

[toc]

## 欄位與資料定義

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊**	|				
| Vender | String | M | 廠商 | 記錄設備實際製造廠商名稱 |
| Model | String | M | 型號 |	記錄設備型號 |
| Serial | String | M | 序號 | 記錄設備唯一序號 |
| **系統與應用欄位**	|				
| Token	| String | M	| 使用者身份驗證 Token	| API安全授權憑證，必須妥善保存。 |
| DEVSNo	| String | M |	緊急對講機設備唯一識別碼 | 智慧杆控制器附掛緊急對講機識別碼 |
| timestamp	| String | M |	資料生成或事件發生時間	ISO 8601格式。| 用於事件時序分析 |
| eventType	| Enum | M	| 事件類型	CALL_INITIATED（通話開始）、CALL_ENDED（通話結束）、CALL_MISSED（未接通話）、EMERGENCY_TRIGGERED（緊急警報觸發）	| 辨識事件性質 |
| callDuration	| Integer | O |	通話時長（秒）	| 僅在 CALL_ENDED 事件存在 |
| callerId	| String | M |	呼叫者身份標識（如使用者ID或位置ID）| 用於辨識呼叫來源 |
| receiverId | String | M |	接收者身份標識	| 通常為監控中心或接聽設備 ID|
| callStatus | Enum | M |	通話狀態, CONNECTED（已接通）、FAILED（失敗）、IDLE（空閒）| 反映通話結果 |
| audioQuality	| Enum | O |	音訊品質評估 (GOOD、FAIR、POOR)	| 根據通話質量監測系統評估 |
| status | Enum | M |	設備狀態 (NORMAL、FAULT、MAINTENANCE、OFFLINE)|	監控設備健康狀態|
| errorCode | String | O |	錯誤代碼 |	發生故障時提供錯誤描述|

## 資料結構與操作規則

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

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "DEVSNo": "INTERCOM001",
  "timestamp": "2025-04-28T14:15:00Z",
  "eventType": "CALL_INITIATED",
  "callerId": "User123",
  "receiverId": "ControlCenter",
  "callStatus": "CONNECTED",
  "audioQuality": "GOOD",
  "status": "NORMAL",
  "errorCode": ""  
}
```

### 操作規則

| 操作 | 說明 | 輸入內容 | 備註 |
| -------- | -------- | -------- | -------- |
| 新增	| 上報緊急對講機事件及狀態資料 |	完整必填欄位及狀態相關參數	| DEVSNo 唯一識別，timestamp 必須合理。|
| 查詢	| 根據 DEVSNo、時間區間、事件類型等查詢 |	Token, 查詢條件	| 支援分頁查詢，避免大量資料回傳
| 修改	| 更新設備狀態、錯誤碼及備註	| Token, DEVSNo 及需更新之欄位	| 嚴禁修改歷史事件資訊 |
| 刪除	| 刪除設備資料	| Token, DEVSNo 及條件	| 操作須謹慎，並有完整日誌記錄。|

### Token 使用注意事項

* 所有API調用須攜帶有效token，確保身分驗證與授權。
* 建議 HTTPS 加密通訊，避免資料攔截與竄改。
* Token過期或無效請求應以 HTTP 401 回覆，提示重新驗證。

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

| 錯誤碼 | 含義 | 建議處理方式 |
| -------- | -------- | -------- |
| 400	| 請求格式錯誤	| 檢查欄位格式及必填欄位完整性 |
| 401	| Token 無效	| 取得新的授權 Token |
| 403	| 權限不足	| 檢查使用者身份與操作權限 |
| 404	| 查無資料	| 驗證 DEVSNo 及查詢條件正確性 |
| 409	| 資料衝突	| 避免重複新增或資料不一致 |
| 500	| 伺服器錯誤	| 請稍後重試並回報系統管理者 |

* 成功回應範例
```json
{
  "code": 200,
  "message": "資料回傳成功",
  "data": {}
}
```


