Files

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

Details

1. 實作遠端指令去重機制 (Supersede)：避免重複下達相同待執行指令。
2. 修正遠端指令發送後的 Toast 提示邏輯，確保頁面跳轉後正確顯示回饋。
3. 增加 RemoteCommand 操作者 (user_id) 紀錄與狀態列舉擴充 (superseded)。
4. 修復機台列表「最後頁面」欄位對照錯誤，同步更新 Machine Model 與 API 規格。
5. 優化遠端指令中心 UI：放大卡片字體、調整側面欄間距，符合極簡奢華風規範。
6. 更新 API 技術規格書 (SKILL.md) 與 config/api-docs.php，補全所有機台代碼 (66-611) 與指令。
7. 補全繁體中文、英文、日文多語系翻譯檔案。

2026-04-02 14:57:41 +08:00

3.3 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 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 (貨道同步)
50: reload B005 (基礎參數)
51: reboot (重啟系統)
60: reboot card machine (刷卡機重啟)
61: checkout (結帳)
70: unlock (解鎖) / 71: lock (鎖定)
72: sellCode reload B023 (即期品)
75: exp reload B026 (效期)
79: read B050 (參數讀取)
81: sync timer status (B710)
85: reload B0552 (出貨腳本)

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

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

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

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

3.3 KiB Raw Blame History Unescape Escape