# 數位看板

:::success
本應用實務依據``5G智慧杆系統技術規範``，明確定義數位看板數據欄位、資料結構與多媒體檔案標準，結合角色定位及介面操作規則，兼顧多元控制器環境，協助地方單位與業者標準化整合、提升系統安全及運維效率。
:::

[toc]

## 設備角色定義

| 設備類型 | 角色定義 | 備註 |
| -------- | -------- | -------- |
| 數位看板（網路推播）| 網路周邊設備 | 透過網路接收多媒體推播 |
| 數位看板（HDMI輸入） | 物聯網設備 | 利用 HDMI 輸出源傳輸多媒體內容至數位看板，整體視為物聯網設備。 |
| 內容管理伺服器 | 應用伺服器 | 負責多媒體資源管理、下發內容及控制指令。 |

## 欄位與資料定義

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |
| Vender | String | M | 廠商 | 記錄設備實際製造廠商名稱 |
| Model | String | M | 型號 | 記錄設備型號 |
| Serial | String | M | 序號 | 記錄設備唯一序號 |
| **系統與應用欄位** |
| Token | String | M | 用戶身份驗證 Token，授權資料存取與控制。| API呼叫必須攜帶 |
| DEVSNo | String | M | 設備唯一編號（數位看板或多媒體播放器識別碼） | 智慧杆平台識別設備唯一碼 |
| station | String | M | 數位看板設置站點名稱 | 區域或地點名稱 |
| jurisdiction | String | M | 管轄機關名稱 | 管理單位 |
| display | Array<Object> | M | 螢幕顯示參數設定清單 | 支援多面板配置 |
| mediatype | Array<String> | M | 支援播放媒體類型, [PICTURE, VIDEO, AUDIO, WEB] | 多媒體內容類型 |

* **display 陣列內容**

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| model | String | M | 顯示器型號 | 品牌與型號 |
| position | String | M | 顯示器安裝位置 | 例如: 入口左側 |
| dimension | Object | M | 顯示區域大小（單位：公分） | 顯示屏幕實際尺寸 |
| resolution | String | M | 螢幕解析度，例如: 1920x1080 | 實際顯示像素 |
| colorscheme | Enum | M | 顏色方案 (MONOCHROME, GRAYSCALE, RGB) | 主色調類型 |
| colordepth | Integer | M | 色彩深度（bit, 常見值：8, 24, 32) | 色彩表現能力 |

## 多媒體檔案格式及編碼規範

| 媒體類型 | 支援格式 | 建議編碼格式 | 建議位元率 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| 圖片 | JPG, PNG, BMP | JPEG, PNG | N/A | 需適應不同解析度螢幕 |
| 視訊 | MP4 (H.264 AVC), Matroska, MPEG | H.264 (AVC), HEVC 選項 | 1 ~ 5 Mbps (依解析度調整) | 需符合硬體解碼支持　|
| 音訊 | MP3, MP4, AAC | MPEG, AAC, MP3 | 128 kbit/s | 低延遲、高音質 |
| 網頁 | HTML5 標準 | N/A | N/A | 支持動態及互動內容 |

## 資料結構與操作規則

### 資料結構範例

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "DEVSNo": "BB001",
  "station": "信義路口",
  "jurisdiction": "臺北市政府",
  "display": [
    {
      "model": "Samsung-QLED",
      "position": "入口左側",
      "dimension": {"width": 85, "height": 150},
      "resolution": "3840x2160",
      "colorscheme": "RGB",
      "colordepth": 32
    }
  ],
  "mediatype": ["PICTURE", "VIDEO", "AUDIO", "WEB"]
}

### 操作規則

| 操作 | 說明 | 輸入參數 | 備註 |
| -------- | -------- | -------- | -------- |
| 新增 | 新增數位看板設備資料 | Token, DEVSNo, station, jurisdiction, display, mediatype | DEVSNo 唯一 |
| 查詢 | 根據條件（DEVSNo、station）查詢 | Token、條件參數 | 支持分頁，避免大資料量一次回傳。 |
| 修改 | 更新顯示器或媒體類型等資料 | Token, DEVSNo 及變更欄位 | 嚴格格式驗證，DEVSNo不可修改。|
| 刪除 | 刪除指定數位看板設備 | Token, DEVSNo | 確認設備存在，操作需記錄日誌。|

### Token 使用注意事項

* **Token　管理：** 所有 API 請求皆須攜帶由伺服器核發之 Token，用於身份授權及存取控制。
* **傳輸安全：**　要求HTTPS進行所有通訊，避免資料竊取與偽冒。
* **Token 有效期限：** 建議設置過期時間並提供刷新機制，維護系統安全。
* **身份驗證失敗：** 回傳HTTP 401，提示重新登入或確認 Token。

### 資料更新頻率

| 內容類型 | 建議交換頻率 |
| -------- | -------- |
| 靜態設備資料 | 每日一次或必要時更新 |
| 多媒體內容推播 | 即時或每5~10分鐘依需同步 |

### 錯誤處理與回應建議

| 錯誤碼 | 含義 | 說明及處理建議 |
| -------- | -------- | -------- |
| 400 | 請求格式或資料錯誤 | 請檢查 JSON 結構與欄位格式 |
| 401 | Token 缺失或失效 | 重新登入並取得有效 Token |
| 403 | 權限不足 | 確認使用者權限 |
| 404 | 指定設備或資料不存在 | 確認DEVSNo及其他查詢條件 |
| 409 | 資料重複 | 避免重複新增或識別碼衝突 |
| 500 | 伺服器錯誤 | 請稍後重試，並回報系統維護 |

### 版本控管與測試建議

* API 及資料結構版本號清楚，如 v1.0，變更時同步更新文件。
* 提供主流數位看板配置與媒體類型測試資料。
* 建議使用 Postman 等工具做介面測試，確保前後端資料一致。
* 日誌完整記錄Token驗證與設備操作，方便維護與追蹤。