---
# System prepended metadata

title: 數位看板
tags: [SPDAGB]

---

# 數位看板

:::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	| 支持動態及互動內容 |

    
## 資料結構與操作規則

### 資料結構範例
    
```json
{
  "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驗證與設備操作，方便維護與追蹤。
    
    
