Files

star-cloud-deploy-demo / deploy-demo (push) Successful in 45s

Details

1. 於 routes/api.php 新增 B000 登入驗證路由，並設定速率限制。
2. 更新 .agents/skills/api-technical-specs/SKILL.md，補上 B000 規格並根據 Java App 實作精簡 B010 指令碼。
3. 同步更新 config/api-docs.php 中的 API 說明文件。
4. 調整 RemoteController 指令歷史紀錄上限為 5 筆以優化效能。
5. 統一機台編輯頁面之圖片上傳文字說明與標題。
6. 補齊多語系翻譯檔案 (zh_TW, en, ja) 出現的新字串。

2026-04-02 17:24:13 +08:00

4.2 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 B010: 心跳上報與狀態同步

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

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

Request Body:

參數	類型	必填	說明	範例
`current_page`	Integer	是	當前頁面代碼 (見下表)	`1`
`firmware_version`	String	是	韌體版本號	`1.0.5`
`model`	String	是	機台型號	`STAR-V1`
`temperature`	Float	否	環境溫度	`25.5`
`door_status`	Integer	否	門狀態 (0:關 / 1:開)	`0`
`log`	String	否	事件日誌簡述	`Door opened`
`log_level`	String	否	info, warn, error	`info`
`log_payload`	Object	否	額外日誌 JSON 對象	`{"code":500}`

Response Body:

參數	類型	說明	範例
`success`	Boolean	請求是否處理成功	`true`
`code`	Integer	內部業務狀態碼	`200`
`message`	String	回應訊息	`OK`
`status`	String	雲端指令代碼 (見下表)	`49`

B010 代碼對照表

頁面代碼 (current_page)：

0: 離線 / 1: 主頁面 / 2: 販賣頁 / 3: 管理頁
4: 補貨頁 / 5: 教學頁 / 6: 購買中 / 7: 鎖定頁
60: 出貨成功 / 61: 貨道測試 / 62: 付款選擇
63: 等待付款 / 64: 出貨 / 65: 收據簽單
66: 通行碼 / 67: 取貨碼 / 68: 訊息顯示
69: 取消購買 / 610: 購買結束 / 611: 來店禮
612: 出貨失敗

雲端指令代碼 (status)：

49: reload B017 (貨道同步)
51: reboot (重啟系統)
60: reboot card machine (刷卡機重啟)
61: checkout (觸發結帳)
70: unlock (解鎖)
71: lock (鎖定)
85: reload B0552 (遠端出貨)
待定義: change (遠端找零 - 註：指令中心有此功能，但目前 Java App 尚無對接對應的連動事件)

3.3 B017: 貨道與庫存同步 (規劃中)

URL: POST /api/v1/app/machine/reload_msg/B017
說明：當機台收到 B010 回應 status: 49 時，應呼叫此 API 同步最新貨道佈局。

3.4 B600: 交易數據回傳 (規劃中)

URL: POST /api/v1/app/B600
說明：交易完成後提交支付方式、金額、商品與出貨結果。

4.2 KiB Raw Blame History Unescape Escape