---
# 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格式 | 記錄數據產生的時間戳
| 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	| 伺服器內部錯誤	| 請稍後重試，並通知系統管理員。|


