# 通訊網路
:::success
本應用實務旨在提供清晰、標準化的數據串接規範，適用於智慧杆附掛的各類通訊網路設備，幫助地方政府與系統整合商高效地管理和監控這些設備，確保通訊網路穩定運行，為智慧城市應用提供可靠的網路基礎設施。
:::
[toc]
## 欄位與資料定義
| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |
| Vender | String | M | 廠商 | 記錄設備實際製造廠商名稱 |
| Model | String | M | 型號 | 記錄設備型號 |
| Serial | String | M | 序號 | 記錄設備唯一序號 |
| **系統與應用欄位** |
| Token | String | M | 用戶身份驗證 Token | API安全憑證，每次請求必須攜帶。 |
| DEVSNo | String | M | 設備唯一識別碼 | 智慧杆附掛通訊設備的唯一編號 |
| timestamp | String | M | 數據產生時間 ISO 8601格式 | 記錄數據產生的時間戳
| deviceType | Enum | M | 設備類型 (4G_ROUTER, 5G_CPE, 5G_SMALL_CELL, 5G_ROUTER) | 明確設備種類 |
| status | Enum | M | 設備狀態 (NORMAL, FAULT, MAINTENANCE, OFFLINE) | 描述設備運行狀態 |
| ipAddress | String| M | IP位址 | 設備的IP地址 |
| manufacturer | String | O | 製造商 | 品牌名稱 |
| model | String | O | 型號 | 設備型號 |
| firmwareVersion | String | O | 韌體版本 | 韌體版本號 |
| serialNumber | String | O | 序號 | 設備序號 |
| signalStrength | Integer | O | 訊號強度 | 訊號強度指標 |
| networkOperator | String | O | 網路營運商 | 目前使用的網路營運商 |
| simCardId | String | O | SIM卡ID | SIM卡識別碼 |
| uploadSpeed | 數值 | O | 上傳速度| 單位為Mbps |
| downloadSpeed | 數值 | O | 下載速度| 單位為 Mbps |
packetLoss | 數值 | O | 封包遺失率（百分比） | 網路穩定性指標 |
| connectedDevices | Integer | O | 連接設備數量 | 目前連接到此通訊設備的裝置數量 |
| latency | Integer | O | 延遲（ms） | 單位為毫秒 |
| errorCode | String | O | 錯誤代碼 | 發生異常時的錯誤代碼 |
## 資料結構與操作規則
### 資料結構範例 (JSON)
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"DEVSNo": "Router001",
"timestamp": "2025-04-28T14:15:00Z",
"deviceType": "5G_ROUTER",
"manufacturer": "PROSCEND",
"model": "AX3 Pro",
"firmwareVersion": "10.0.5.33",
"serialNumber": "SN123456789",
"ipAddress": "192.168.1.1",
"signalStrength": 85,
"networkOperator": "中華電信",
"simCardId": "8988602000000000000",
"uploadSpeed": 50.5,
"downloadSpeed": 450.2,
"packetLoss": 0.1,
"latency": 20,
"connectedDevices": 15,
"status": "NORMAL",
"errorCode": "",
}
```
### 操作規則
| 操作 | 說明 | 輸入內容 | 備註 |
| -------- | -------- | -------- | -------- |
| 新增 | 上報通訊設備狀態與資訊 | 完整必填欄位及狀態相關參數 | DEVSNo唯一識別，確保數據準確性。 |
| 查詢 | 根據 DEVSNo、設備類型、時間區間等條件查詢 | Token、查詢條件 | 支援分頁查詢，避免數據量過大 |
| 修改 | 更新設備狀態、韌體版本、備註等資訊 | Token、DEVSNo 及需要更新的欄位 | 嚴禁修改設備識別碼等關鍵資訊 |
| 刪除 | 刪除特定設備資訊 | Token、DEVSNo | 操作須謹慎，並記錄操作日誌。|
### 安全與授權機制
* **Token 驗證：** 所有API請求須包含有效token，進行身份驗證和授權。
* **HTTPS 加密：** 建議使用HTTPS協議進行資料傳輸，確保資料安全。
* **Token 失效策略：** 設定Token有效期限，過期後需重新獲取。
* **錯誤處理：** 明確定義錯誤碼及處理方式，方便問題排查。
### 錯誤處理與回應格式
| 錯誤碼 | 說明 | 建議處理方式 |
| -------- | -------- | -------- |
| 400 | 請求格式錯誤或欄位驗證失敗 | 檢查 JSON 結構、欄位格式及必填欄位 |
| 401 | 無效的 Token | 重新登入獲取有效的 Token |
| 403 | 權限不足 | 檢查使用者權限設定 |
| 404 | 找不到指定資源 | 檢查DEVSNo是否正確 |
| 409 | 資源衝突 | 嘗試創建已存在的資源 |
| 500 | 伺服器內部錯誤 | 請稍後重試，並通知系統管理員。|
Sign in with Wallet
Connect another wallet