# 氣象與空氣品質

:::success
本應用實務依據``5G智慧杆系統技術規範``，為氣象與空氣品質數據提供標準化資料結構與接口規則，確保系統整合與資料交換的可靠性與一致性，協助地方單位及系統整合業者高效建立智慧環境監測平台。
:::

[toc]

## 欄位與資料定義

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |
| Vendor | String | M | 廠商 | 記錄設備實際製造廠商名稱 |
| Model | String | M | 型號 | 記錄設備型號 |
| Serial | String | M | 序號 | 記錄設備唯一序號 |
| **系統與應用欄位** |
| Token | String | M | 使用者身份驗證 Token | API 安全憑證，所有請求需帶此欄位。 |
| DEVSNo | String | M | 設備代碼 | |
| timestamp | String | M | 感測數據採樣時間 | ISO 8601 日期格式 |
| **感測器資訊** |
| Latitude | 數值 | O | 經度 | 以度表示 |
| Longitude | 數值 | O | 緯度 | 以度表示 |
| Status | Enum | M | 感測器狀態 (NORMAL, FAULT, MAINTENANCE, OFFLINE) | 用來判斷感測器健康狀況 |
| errorCode | String | O | 錯誤代碼 | 發生異常時填寫，否則空值 |
| **氣象資訊** |
| Temp | 數值 | M | 溫度 | 以攝氏溫度表示 |
| RH | 數值 | M | 相對濕度 | 以百分比表示 |
| WindSpeed | 數值 | O | 風速 | meter/sec |
| SolarRadiation | 數值 | O | 日射量 | MJ/m^2^ |
| **空氣品質資訊** |
| PM25 | 數值 | M | 細懸浮微粒濃度(µg/m^3^) | 環保監測核心數據 |
| PM10 | 數值 | O | 懸浮微粒濃度(µg/m^3^) | |
| SO2 | 數值 | O | ppb | 二氧化硫 |
| CO | 數值 | O | ppm | 一氧化碳 |
| NO2 | 數值 | O | ppb | 二氧化氮 |
| NO | 數值 | O | ppb | 一氧化氮 |
| O3 | 數值 | O | ppb | 臭氧 |

## 資料結構與操作規則

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

{
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "DEVSNo": "AQSensor001",
  "timestamp": "2025-04-28T14:15:00Z",
  "Temp": 25.4,
  "RH": 60.3,
  "PM25": 15.7,
  "PM10": 28.4,
  "CO": 0.4,
  "NO2": 12.1,
  "NO": 2.9,
  "O3": 20.5,
  "Status": "NORMAL",
  "errorCode": "",
}

### 操作規則

| 操作 | 說明 | 輸入內容 | 備註 |
| -------- | -------- | -------- | -------- |
| 新增 | 上報感測器數據 | 完整必填欄位及狀態資訊 | DEVSNo唯一識別，時間戳必須合理。 |
| 查詢 | 根據條件查詢歷史或即時感測資料 | Token、DEVSNo、時間區間等 | 支援分頁，避免大量資料一次回傳。 |
| 修改 | 更新感測器狀態或補充說明 | Token、DEVSNo 及變更欄位 | 僅限狀態、錯誤碼及備註，不可更改設備基本參數。|
| 刪除 | 刪除感測器資料紀錄 | Token、DEVSNo 及時間條件 | 謹慎操作，需記錄日誌。|

### Token 使用注意事項

* 透過 Token 控制授權。
* 所有通訊須使用 HTTPS 保障資料安全。
* Token 過期須重新認證，API拒絕無效 Token 的請求。

### 資料交換頻率

* 即時環境監控建議每5分鐘更新一次資料。
* 可視需求調整批次上報頻率。

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

| 錯誤碼 | 含義 | 建議處理方式 |
| -------- | -------- | -------- |
| 400 | 請求格式或資料錯誤 | 檢查 JSON 格式、必填欄位、資料合理性。|
| 401 | Token 無效或缺失 | 重新登入獲取有效 Token |
| 403 | 權限不足 | 確認使用者權限 |
| 404 | 查無資料 | 檢查輸入設備ID及查詢條件 |
| 409 | 資料衝突 | 避免重複新增或不合理狀態更新 |
| 500 | 伺服器內部錯誤 | 稍後再試，並向系統管理員回報問題。|

* 成功回應範例

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

## 資料格式與代碼支援

### JSON 格式

* 明確結構化數據，方便API前後端對應。

### 狀態說明

| 狀態值 | 說明 |
| -------- | -------- |
| Active | 已啟用 / 運作中 |
| Inactive | 已停用 / 未運作 |

### 測試資料建議

* 建議提供多筆測試資料涵蓋正常與異常狀態情境。
* 建議以模擬感測器裝置進行接口測試，驗證數據格式及狀態同步功能。

### 版本控管建議

* API及資料格式應明確標示版本號，方便後續維護。