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 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://..."}]

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 欄位進行三層式權限核查：

1. 系統層 (System Admin)：當 company_id 為 null 時，具備全局管理權限，直接放行。
2. 公司層 (Company Admin)：當 is_admin 為 true 時，檢查機台的 company_id 是否與該帳號一致。
3. 人員層 (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	Integer	貨道編號 (Slot No)	1
  t060v00	String	商品資料庫 ID (或是 Barcode)	"1"
  num	Integer	實體剩餘庫存數量	10
  type	Integer	貨道物理類型 (1: 履帶, 2: 彈簧)。若未提供，預設為 1。	1

Tip

自動化上限同步邏輯： 當後端收到 B009 時，會根據 type 自動從該商品的配置中選取 spring_limit 或 track_limit 並自動更新該貨道的 max_stock 欄位。機台端無需手動計算上限。

• Response Body (Success 200):

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

---

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

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

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

• Authentication: Bearer Token (Header)

• 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 (遠端出貨)

---

3.5 B012: 商品配置與商品主檔同步 (Unified Sync)

用於機台端獲取目前所有可販售商品的詳細配置。App 端應依據呼叫的方法決定數據處理方式。

• URL: GET|PATCH /api/v1/app/machine/products/B012
• Authentication: Bearer Token (Header)
• Request Body: 無 (由 Token 自動識別機台)

運作邏輯 (Client-side Logic):

• GET：執行 全量同步。App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll() 以確保與伺服器完全一致。
• PATCH：執行 增量更新。App 於收到成功回應後，僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。

欄位	型別	說明	範例
t060v00	String	商品資料庫 ID	"1"
t060v01	String	商品名稱	可口可樂 330ml
t060v01_en	String	英文名稱	Coca Cola
t060v01_jp	String	日文名稱	コカコーラ
t060v03	String	商品規格/簡述	Cold Drink
t060v06	String	圖片 URL	https://.../coke.png
t060v09	Float	標準零售價	25.0
t060v11	Integer	貨道庫存上限 (預設履帶)	10
t060v30	Float	會員價	20.0
t063v03	Float	本機銷售價格 (同定價)	25.0
t060v40	String	行銷計畫 (Marketing Plan)	Buy 1 Get 1
t060v41	String	物料編碼 (Material Code)	SKU-001
spring_limit	Integer	彈簧貨道上限 (建議使用此欄位)	10
track_limit	Integer	履帶貨道上限 (建議使用此欄位)	15