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 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

---

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 B005: 廣告清單同步

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

• URL: POST /api/v1/app/machine/ad/B005

• Request Body: (無須額外 Body 參數，僅需傳送空 JSON {})

• Response Body:

  參數	類型	說明	範例
  success	Boolean	請求是否成功	true
  data	Array	廣告物件陣列	[{"t070v04": "https://..."}]

data 陣列內部欄位：

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

---

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

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

• URL: PUT /api/v1/app/products/supplementary/B009

• Request Body:

  參數	類型	必填	說明	範例
  account	String	是	操作人員帳號	technician_01
  vmcType	String	否	VMC 韌體/機型類別	XinYuan
  data	Array	貨道數據陣列	[{"tid":"1", "t060v00":"SKU001", "num":"10"}]

• data 陣列內部欄位：

• tid: 貨道編號 (Slot No)

• t060v00: 商品編碼 (SKU / Product Code)

• num: 實體剩餘庫存數量

• Response Body:

  參數	類型	說明	範例
  success	Boolean	同步是否成功	true
  status	String	固定回傳 49 代表已處理	49

---

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

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