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

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

---

3.6 B013: 機台故障與異常狀態上報 (Error/Status Report)

用於接收機台發出的即時硬體狀態代碼（如卡貨、門未關），並自動由雲端後端翻譯為易讀日誌。

• URL: POST /api/v1/app/machine/error/B013
• Authentication: Bearer Token (Header)
• Request Body:

參數	類型	必填	說明	範例
tid	Integer	否	涉及之貨道編號 (Slot No)	12
error_code	String	是	硬體狀態代碼 (4 位 16 進位)	"0403"

• 回應 (Success 202):

參數	類型	說明	範例
success	Boolean	請求已接收	true
code	Integer	200	200

B013 硬體代碼對照表 (由 MachineService 自動翻譯)

代碼	英文 Key (i18n)	級別	範例繁中翻譯
0402	Dispense successful	info	出貨成功
0403	Slot jammed	error	貨道卡貨 (重大異常)
0202	Product empty	warning	貨道缺貨
0412	Elevator rise error	error	昇降機上升異常
0415	Pickup door error	error	取貨門異常
5402	Pickup door not closed	warning	取貨門未關 (警告)
5403	Elevator failure	error	昇降系統故障