# 緊急對講機

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

{
  "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 | 伺服器錯誤 | 請稍後重試並回報系統管理者 |

* 成功回應範例

{
  "code": 200,
  "message": "資料回傳成功",
  "data": {}
}