star-cloud/.agents/skills/api-technical-specs/SKILL.md

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: 收據簽單
• 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 (參數讀取)
• 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
• 說明：交易完成後提交支付方式、金額、商品與出貨結果。