sky121113
f2147ae6c4
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m4s
1. 將 B005 (廣告同步) 從 POST 改為 GET，符合 RESTful 規範。
2. 完善 B009 (庫存回報) 回應規格，加入業務代碼 (200 OK)。
3. API 文件 UI 優化：新增 Method Badge (方法標籤)，並修正 JSON 中文/斜線轉義問題。
4. 機台管理介面優化：實作「唯讀庫存與效期」面板，並將日誌圖示改為「👁️」。
5. 標準化 ID 識別邏輯：資料表全面移除對 sku 的依賴，改以 id 為主、barcode 為輔。
6. 新增 Migration：正式移除 sku 欄位並同步 barcode 指向。
7. 更新多語系支援 (zh_TW, en, ja)。
238 lines
11 KiB
PHP
238 lines
11 KiB
PHP
<?php
|
||
|
||
return [
|
||
'title' => 'Star Cloud IoT API 說明文件',
|
||
'version' => 'v1.0.0',
|
||
'description' => '此文件提供 Star Cloud 智能販賣機 IoT 端點通訊協議說明，供硬體端與前端開發者調研與串接使用。',
|
||
'categories' => [
|
||
[
|
||
'name' => '機台核心通訊 (IoT Core)',
|
||
'apis' => [
|
||
[
|
||
'name' => 'B005: 廣告清單同步 (Ad Sync)',
|
||
'slug' => 'b005-ad-sync',
|
||
'method' => 'GET',
|
||
'path' => '/api/v1/app/machine/ad/B005',
|
||
'description' => '用於機台端獲取目前應播放的廣告檔案 URL 清單。此介面無需 Request Body。',
|
||
'headers' => [
|
||
'Authorization' => 'Bearer <api_token>',
|
||
'Content-Type' => 'application/json',
|
||
],
|
||
'parameters' => [],
|
||
'response_parameters' => [
|
||
'success' => [
|
||
'type' => 'boolean',
|
||
'description' => '請求是否成功',
|
||
'example' => true
|
||
],
|
||
'code' => [
|
||
'type' => 'integer',
|
||
'description' => '內部業務狀態碼',
|
||
'example' => 200
|
||
],
|
||
'data' => [
|
||
'type' => 'array',
|
||
'description' => '廣告物件陣列。內部欄位包含：t070v01 (名稱), t070v02 (秒數), t070v03 (位置：1:販賣頁, 2:來店禮, 3:待機廣告), t070v04 (URL), t070v05 (順位)',
|
||
'example' => [
|
||
[
|
||
't070v01' => '測試機台廣告',
|
||
't070v02' => 15,
|
||
't070v03' => 3,
|
||
't070v04' => 'https://example.com/ad1.mp4',
|
||
't070v05' => 1
|
||
]
|
||
]
|
||
],
|
||
],
|
||
'request' => [],
|
||
'response' => [
|
||
'success' => true,
|
||
'code' => 200,
|
||
'message' => 'OK',
|
||
'data' => [
|
||
[
|
||
't070v01' => '測試機台廣告',
|
||
't070v02' => 15,
|
||
't070v03' => 3,
|
||
't070v04' => 'https://example.com/ad1.mp4',
|
||
't070v05' => 1
|
||
]
|
||
]
|
||
],
|
||
],
|
||
[
|
||
'name' => 'B009: 貨道庫存即時回報 (Inventory Report)',
|
||
'slug' => 'b009-inventory-report',
|
||
'method' => 'PUT',
|
||
'path' => '/api/v1/app/products/supplementary/B009',
|
||
'description' => '當人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。需進行 RBAC 權限核查。',
|
||
'headers' => [
|
||
'Authorization' => 'Bearer <api_token>',
|
||
'Content-Type' => 'application/json',
|
||
],
|
||
'parameters' => [
|
||
'account' => [
|
||
'type' => 'string',
|
||
'required' => true,
|
||
'description' => '操作人員帳號',
|
||
'example' => '0999123456'
|
||
],
|
||
'data' => [
|
||
'type' => 'array',
|
||
'required' => true,
|
||
'description' => '貨道數據陣列。tid: 貨道號, t060v00: 商品 ID, num: 庫存量',
|
||
'example' => [
|
||
['tid' => '1', 't060v00' => '1', 'num' => '10']
|
||
]
|
||
],
|
||
],
|
||
'response_parameters' => [
|
||
'success' => [
|
||
'type' => 'boolean',
|
||
'description' => '同步是否成功',
|
||
'example' => true
|
||
],
|
||
'code' => [
|
||
'type' => 'integer',
|
||
'description' => '內部業務狀態碼',
|
||
'example' => 200
|
||
],
|
||
'message' => [
|
||
'type' => 'string',
|
||
'description' => '回應訊息',
|
||
'example' => 'Slot report synchronized success'
|
||
],
|
||
'status' => [
|
||
'type' => 'string',
|
||
'description' => '固定回傳 49 代表同步完成',
|
||
'example' => '49'
|
||
],
|
||
],
|
||
'request' => [
|
||
'account' => '0999123456',
|
||
'data' => [
|
||
['tid' => '1', 't060v00' => '1', 'num' => '10']
|
||
]
|
||
],
|
||
'response' => [
|
||
'success' => true,
|
||
'code' => 200,
|
||
'message' => 'Slot report synchronized success',
|
||
'status' => '49'
|
||
],
|
||
],
|
||
[
|
||
'name' => 'B010: 心跳上報與狀態同步 (Heartbeat)',
|
||
'slug' => 'b010-heartbeat',
|
||
'method' => 'POST',
|
||
'path' => '/api/v1/app/machine/status/B010',
|
||
'description' => '機台定期向雲端回報當前頁面、版本、溫度及門禁狀態。身份由 Bearer Token 識別。',
|
||
'headers' => [
|
||
'Authorization' => 'Bearer <api_token>',
|
||
'Content-Type' => 'application/json',
|
||
],
|
||
'parameters' => [
|
||
'current_page' => [
|
||
'type' => 'integer',
|
||
'required' => true,
|
||
'description' => '當前頁面編號。對照表：
|
||
0: 離線, 1: 主頁面, 2: 販賣頁, 3: 管理頁, 4: 補貨頁, 5: 教學頁
|
||
6: 購買中, 7: 鎖定頁, 60: 出貨成功, 61: 貨道測試, 62: 付款選擇
|
||
63: 等待付款, 64: 出貨, 65: 收據簽單, 66: 通行碼, 67: 取貨碼
|
||
68: 訊息顯示, 69: 取消購買, 610: 購買結束, 611: 來店禮, 612: 出貨失敗',
|
||
'example' => 1
|
||
],
|
||
'firmware_version' => [
|
||
'type' => 'string',
|
||
'required' => true,
|
||
'description' => '軟體或韌體版本號',
|
||
'example' => '1.0.5'
|
||
],
|
||
'model' => [
|
||
'type' => 'string',
|
||
'required' => false,
|
||
'description' => '機台型號',
|
||
'example' => 'STAR-V1'
|
||
],
|
||
'temperature' => [
|
||
'type' => 'float',
|
||
'required' => false,
|
||
'description' => '感測環境溫度',
|
||
'example' => 25.5
|
||
],
|
||
'door_status' => [
|
||
'type' => 'integer',
|
||
'required' => false,
|
||
'description' => '門禁狀態 (0: 關閉, 1: 開啟)',
|
||
'example' => 0
|
||
],
|
||
'log' => [
|
||
'type' => 'string',
|
||
'required' => false,
|
||
'description' => '事件日誌主訊息',
|
||
'example' => 'Door opened'
|
||
],
|
||
'log_level' => [
|
||
'type' => 'string',
|
||
'required' => false,
|
||
'description' => '日誌等級 (info, warning, error)',
|
||
'example' => 'info'
|
||
],
|
||
'log_payload' => [
|
||
'type' => 'object',
|
||
'required' => false,
|
||
'description' => '詳細上下文 (JSON 對象)',
|
||
'example' => ['error_code' => 500, 'component' => 'door_sensor']
|
||
],
|
||
],
|
||
'response_parameters' => [
|
||
'success' => [
|
||
'type' => 'boolean',
|
||
'description' => '請求是否處理成功',
|
||
'example' => true
|
||
],
|
||
'code' => [
|
||
'type' => 'integer',
|
||
'description' => '內部業務狀態碼',
|
||
'example' => 200
|
||
],
|
||
'message' => [
|
||
'type' => 'string',
|
||
'description' => '回應訊息說明',
|
||
'example' => 'OK'
|
||
],
|
||
'status' => [
|
||
'type' => 'string',
|
||
'description' => '雲端指令代碼。對照表：
|
||
49: reload B017 (貨道同步), 51: reboot (重啟系統)
|
||
60: reboot card machine (刷卡機重啟), 61: checkout (觸發結帳)
|
||
70: unlock (解鎖), 71: lock (鎖定), 85: reload B0552 (遠端出貨)
|
||
待定義: change (遠端找零 - 目前 Java App 尚無對接)',
|
||
'example' => '49'
|
||
],
|
||
],
|
||
'request' => [
|
||
'current_page' => 1,
|
||
'firmware_version' => '1.0.5',
|
||
'model' => 'STAR-V1',
|
||
'temperature' => 25.5,
|
||
'door_status' => 0,
|
||
'log' => 'Door opened',
|
||
'log_level' => 'info',
|
||
'log_payload' => [
|
||
'error_code' => 500,
|
||
'component' => 'door_sensor'
|
||
],
|
||
],
|
||
'response' => [
|
||
'success' => true,
|
||
'code' => 200,
|
||
'message' => 'OK',
|
||
'status' => '49'
|
||
],
|
||
'notes' => '機台收到 B010 回應中的特定 `status` 代碼後，應根據對照表執行對應的指令動作或 API 呼叫 (如 B017)。若為空則代表無指令。'
|
||
]
|
||
]
|
||
]
|
||
]
|
||
]; |