Files

star-cloud-deploy-demo / deploy-demo (push) Successful in 1m4s

Details

[FEAT] 完善 IoT API 規范化、機台管理介面優化與 B005 改為 GET

1. 將 B005 (廣告同步) 從 POST 改為 GET，符合 RESTful 規範。
2. 完善 B009 (庫存回報) 回應規格，加入業務代碼 (200 OK)。
3. API 文件 UI 優化：新增 Method Badge (方法標籤)，並修正 JSON 中文/斜線轉義問題。
4. 機台管理介面優化：實作「唯讀庫存與效期」面板，並將日誌圖示改為「👁️」。
5. 標準化 ID 識別邏輯：資料表全面移除對 sku 的依賴，改以 id 為主、barcode 為輔。
6. 新增 Migration：正式移除 sku 欄位並同步 barcode 指向。
7. 更新多語系支援 (zh_TW, en, ja)。

2026-04-07 14:37:57 +08:00

6.4 KiB

Raw Blame History

name, description

name	description
API 技術規格與通訊協議規範	本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與後端 (Cloud) 通訊的 API 細節、參數命名規則、狀態代碼對照與認證機制，作為系統開發的唯一規格來源。

API 技術規格與通訊協議規範 (API Technical Specs)

本文件集中定義所有機台與雲端通訊的 API 規格，確保硬體端與軟體端在資料交換格式與業務定義上保持完全一致。

1. 核心命名原則

語意化優先：捨棄舊版 M_ 前綴，統一使用 snake_case (如 firmware_version)。
類型嚴格：文件定義的類型 (Integer, Float, String) 必須在後端 Model 與前端文件中心嚴格遵守。

2. 身份認證 (Authentication)

Bearer Token：所有 API 必須在 Header 帶入 Authorization: Bearer <api_token>。
身分綁定：後端透過 Token 自動識別 machine_id，禁止在 Body 帶入 machine 或 key 欄位。

3. 機台核心 API (IoT Endpoints)

3.1 B000: 機台本地管理員同步登入

用於機台 Android 端維護人員登入與進入設定頁。此 API 無狀態，且為例外不強制檢查 Bearer Token 的端點。

URL: POST /api/v1/app/admin/login/B000

Request Body:

參數	類型	必填	說明	範例
`machine`	String	是	機台編號 (serial_no)	`M-001`
`Su_Account`	String	是	系統管理員或公司管理員帳號	`admin`
`Su_Password`	String	是	密碼	`password123`
`ip`	String	否	用戶端 IP (相容舊版)	`192.168.1.100`
`type`	String	否	裝置類型代碼 (相容舊版)	`2`

Response Body:

Important

為了相容 Java APP 現有邏輯，這裡嚴格規定成功必須回傳字串 Success。

參數類型說明範例

message String 驗證結果 (Success 或 Failed) Success

參數	類型	說明	範例
`message`	String	驗證結果 (`Success` 或 `Failed`)	`Success`

3.2 B005: 廣告清單同步

用於機台端獲取目前應播放的廣告檔案 URL 清單。

URL: GET /api/v1/app/machine/ad/B005
Request Body: 無 (GET 請求)
Response Body:

參數類型說明範例

success Boolean 請求是否成功 true

code Integer 內部業務狀態碼 200

data Array 廣告物件陣列 [{"t070v04": "https://..."}]

參數	類型	說明	範例
`success`	Boolean	請求是否成功	`true`
`code`	Integer	內部業務狀態碼	`200`
`data`	Array	廣告物件陣列	`[{"t070v04": "https://..."}]`

data 陣列內部欄位：

t070v01: 廣告名稱 (Name)
t070v02: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
t070v03: 廣告位置 (Position/Flag) — (3: 待機廣告, 1: 販賣頁, 2: 來店禮)。
t070v04: 廣告 URL。
t070v05: 播放順位 (Sort Order)。

3.3 B009: 貨道庫存即時回報 (Supplementary Report)

當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。

B009 權限驗證邏輯 (RBAC Compliance)

系統會依據 account 欄位進行三層式權限核查：

系統層 (System Admin)：當 company_id 為 null 時，具備全局管理權限，直接放行。
公司層 (Company Admin)：當 is_admin 為 true 時，檢查機台的 company_id 是否與該帳號一致。
人員層 (Operator/User)：當帳號僅為一般人員時，檢查 machine_user 授權表，確認該帳號有被分配至此機台。

URL: PUT /api/v1/app/products/supplementary/B009
Request Body:

參數類型必填說明範例

account String 是操作人員帳號 0999123456

data Array 是貨道數據陣列 [{"tid":"1", "t060v00":"1", "num":"10"}]
data 陣列內部欄位：
tid: 貨道編號 (Slot No)
t060v00: 商品資料庫 ID
num: 實體剩餘庫存數量

參數	類型	必填	說明	範例
`account`	String	是	操作人員帳號	`0999123456`
`data`	Array	是	貨道數據陣列	`[{"tid":"1", "t060v00":"1", "num":"10"}]`

Response Body (Success 200):

參數	類型	說明	範例
`success`	Boolean	同步是否成功	`true`
`code`	Integer	內部業務狀態碼	`200`
`message`	String	回應訊息	`Slot report synchronized success`
`status`	String	固定回傳 `49` 代表同步完成	`49`

Response Body (Forbidden 403):

參數	類型	說明	範例
`success`	Boolean	同步失敗	`false`
`status`	String	回傳空字串 `""` 防止觸發指令	`""`
`code`	Integer	HTTP 狀態碼	`403`
`message`	String	錯誤訊息	`Unauthorized`

3.4 B010: 心跳上報與狀態同步

用於確認機台在線狀態、更新感測數據、提交事件日誌並獲取雲端指令。

URL: POST /api/v1/app/machine/status/B010