sky121113 8feca33f13 [FEAT] 優化機台日誌管理、新增庫存變動紀錄與取貨碼/通行碼介面改善

1. 新增機台異常日誌手動解除功能，包含資料庫欄位更新與 UI 操作按鈕。
2. 實作機台庫存變動紀錄系統 (Machine Stock Movements)，支援追蹤補貨與銷售產生的庫存異動。
3. 重構取貨碼 (Pickup Code) 與通行碼 (Pass Code) 管理介面，採用極簡奢華風 UI 並拆分 Partial Views 提升可維護性。
4. 優化取貨操作日誌，明確區分「取貨成功」與「取貨失敗」，並加入顏色標籤增強辨識度。
5. 擴充多語系支援 (繁中、英文、日文)，確保所有新功能與操作狀態均有對應翻譯。
6. 更新 IoT API 規格文件與相關 Service 邏輯，加強指令確認 (ACK) 處理機制。

2026-05-04 08:43:35 +08:00

13 KiB

Raw Blame History

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)

本系統採用兩階段認證模式：

2.1 維運人員認證 (User Authentication)

核發端點：B000 (登入)。
使用端點：B014 (參數下載)。
方式：使用 Laravel Sanctum 核發之 User Token。
Header：Authorization: Bearer <user_token>。

2.2 機台通訊認證 (Machine Authentication)

適用 API：B012, B009 等後續通訊。
方式：使用機台專屬之 api_token。
Header：Authorization: Bearer <api_token>。

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
token	String	臨時身份認證 Token (用於 B014)	1

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)

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

URL: PUT /api/v1/app/products/supplementary/B009
Authentication: Bearer Token (Header)
Request Body: 無 (由 Token 自動識別機台)

參數	類型	必填	說明	範例
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.5 B012: 商品配置與商品主檔同步 (Unified Sync)

用於機台端獲取目前所有可販售商品的詳細配置。

URL: GET /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: [DEPRECATED / REMOVED] 機台故障與異常狀態上報

Warning

此 REST API 已廢棄並移除。機台異常上報已全面遷移至 MQTT 即時通訊架構。詳細錯誤代碼請參閱：MQTT 通訊規範 - B013 硬體代碼對照表

3.12 B010: [DEPRECATED / REMOVED] 心跳上報與狀態同步

Warning

此 REST API 已廢棄並移除。機台心跳上報與指令下發已全面遷移至 MQTT 架構。 (註：溫度數據已標準化為 Integer，且雲端採「變動即記錄」規則)。詳細格式請參閱：MQTT 通訊規範 - B010 心跳上報

3.7 B014: 機台參數與金鑰下載 (Config Download)

用於機台引導階段 (Provisioning)，向雲端請求支付金鑰、發票設定及機台正式 API Token。

URL: GET /api/v1/app/machine/setting/B014
Authentication: User Token (Sanctum Header)
Request Body: 無 (由 Query String 帶入 machine 參數)

參數	類型	必填	說明	範例
machine	String	是	機台編號 (serial_no)	M-001

Response Body (Success 200):

欄位 (Key)	說明	備註
t050v01	機台序號	即 machine_id
api_token	機台正式 Token	初始化後應存於本地，後續 API 認證用
t050v41	玉山特店編號	ESUN Merchant ID
t050v42	玉山終端編號	ESUN Terminal ID
t050v43	玉山 Hash Key	ESUN Hash
t050v34	發票特店 ID	Invoice Merchant ID
t050v35	發票 Hash Key	Invoice Key
t050v36	發票 Hash IV	Invoice IV
TP_APP_ID	趨勢支付 AppID	TrendPay ID
TP_APP_KEY	趨勢支付 Key	TrendPay Key

Caution

安全性規範：B014 會回傳敏感金鑰與正式 Token，背景必須強制進行 RBAC 校驗。只有當前登入的人員具備該機台管理權限時，後端才允許發放資料。

3.8 B017: 貨道庫存同步 (Slot Synchronization)

用於機台端主動向遠端後台拉取目前所有貨道的最新庫存、效期與配置狀態。通常發生於機台開機初始化、補貨/維護模式結束，或是機台需要確保本地端庫存資料與雲端一致時主動請求。

URL: GET /api/v1/app/machine/reload_msg/B017
Authentication: Bearer Token (Header)
Request Body: 無 (由 Token 自動識別機台)
Response Body:

參數	類型	說明	範例
success	Boolean	請求是否成功	true
code	Integer	200	200
data	Array	貨道數據陣列 (依 slot_no 排序)	見下表

data 陣列內部欄位：

欄位	類型	說明	範例
tid	String	貨道編號	"1"
num	Integer	當前庫存數量	10
expiry_date	String	商品效期	"2026-12-31"
batch_no	String	批號	"B202604"
product_id	Integer	商品 ID	1
capacity	Integer	貨道容量上限	15
status	String	貨道狀態 ("1": 啟用, "0": 停用)	"1"

3.9 B660: 取貨碼驗證與消耗 (Pickup Code)

處理機台端的代碼取貨流程。採用兩階段流程以確保庫存準確性。

[B660] 取貨碼驗證與消耗 (兩階段)

Path: /api/v1/app/machine/pickup/verify/B660
Method: POST (驗證) / PUT (消耗)
Description: 驗證 8 位數取貨碼，並於出貨完成後回報消耗以扣除庫存。

[B670] 通行碼驗證 (維護專用)

Path: /api/v1/app/machine/passcode/verify/B670
Method: POST
Description: 工程人員現場測試專用通行碼，不涉及庫存消耗。

參數	類型	必填	說明	範例
code	String	是	使用者輸入的 8 位數取貨碼	"12345678"

Response (Success 200):

pickup_code_id: 代碼內部 ID，供第二階段 PUT 使用。
slot_no: 建議出貨貨道。
product_name: 商品名稱。

B. 消耗階段 (PUT)

當機台確認出貨成功後發送，雲端此時才正式執行 decrement 庫存與標記代碼已使用。

參數	類型	必填	說明	範例
pickup_code_id	Integer	是	驗證階段取得的 ID	45
status	Integer	是	出貨結果 (1: 成功, 0: 失敗)	1

3.10 B670: 通行碼驗證 (Pass Code)

專供維修或工程人員現場測試使用的通行碼。

URL: POST /api/v1/app/machine/passcode/verify/B670
Authentication: Bearer Token (Header)
Request Body:

參數	類型	必填	說明	範例
code	String	是	8 位數通行碼	"88888888"