sky121113
a599b14df1
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m6s
1. 修復帳號管理與角色權限頁面搜尋功能，支援 Enter 鍵快捷提交。 2. 完成 B013 (機台故障上報) API 實作，改用非同步隊列 (ProcessMachineError) 處理日誌上報。 3. 精簡 B013 API 參數，移除冗餘的 message 欄位，統一由雲端對照表翻譯。 4. 更新技術規格文件 (SKILL.md) 與系統 API 文件配置 (api-docs.php)。 5. 修正平台管理員帳號在搜尋過濾時的資料隔離邏輯。
357 lines
17 KiB
PHP
357 lines
17 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)。若為空則代表無指令。'
|
||
],
|
||
[
|
||
'name' => 'B012: 商品配置與商品主檔同步 (Unified Sync)',
|
||
'slug' => 'b012-unified-sync',
|
||
'method' => 'GET/PATCH',
|
||
'path' => '/api/v1/app/machine/products/B012',
|
||
'description' => '用於機台端獲取目前所有可販售商品的詳細配置。GET 為全量同步，PATCH 為增量更新。',
|
||
'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' => '商品明細物件陣列',
|
||
'example' => [
|
||
[
|
||
't060v00' => '1',
|
||
't060v01' => '可口可樂 330ml',
|
||
't060v01_en' => 'Coca Cola',
|
||
't060v01_jp' => 'コカコーラ',
|
||
't060v03' => 'Cold Drink',
|
||
't060v06' => 'https://.../coke.png',
|
||
't060v09' => 25.0,
|
||
't060v11' => 10,
|
||
't060v30' => 20.0,
|
||
't063v03' => 25.0,
|
||
't060v40' => 'Buy 1 Get 1',
|
||
't060v41' => 'SKU-001',
|
||
'spring_limit' => 10,
|
||
'track_limit' => 15
|
||
]
|
||
]
|
||
]
|
||
],
|
||
'request' => [],
|
||
'response' => [
|
||
'success' => true,
|
||
'code' => 200,
|
||
'message' => 'OK',
|
||
'data' => [
|
||
[
|
||
't060v00' => '1',
|
||
't060v01' => '可口可樂 330ml',
|
||
't060v01_en' => 'Coca Cola',
|
||
't060v01_jp' => 'コカコーラ',
|
||
't060v03' => 'Cold Drink',
|
||
't060v06' => 'https://.../coke.png',
|
||
't060v09' => 25.0,
|
||
't060v11' => 10,
|
||
't060v30' => 20.0,
|
||
't063v03' => 25.0,
|
||
't060v40' => 'Buy 1 Get 1',
|
||
't060v41' => 'SKU-001',
|
||
'spring_limit' => 10,
|
||
'track_limit' => 15
|
||
]
|
||
]
|
||
],
|
||
'notes' => '運作邏輯 (Client-side Logic): GET 執行全量同步，App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll()。PATCH 執行增量更新，App 僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。'
|
||
],
|
||
[
|
||
'name' => 'B013: 機台故障與異常狀態上報 (Error/Status Report)',
|
||
'slug' => 'b013-error-report',
|
||
'method' => 'POST',
|
||
'path' => '/api/v1/app/machine/error/B013',
|
||
'description' => '用於接收機台發出的即時硬體狀態代碼（如卡貨、門未關）。身份由 Bearer Token 識別，回傳成功代表伺服器已將任務列入異步隊列處理。',
|
||
'headers' => [
|
||
'Authorization' => 'Bearer <api_token>',
|
||
'Content-Type' => 'application/json',
|
||
],
|
||
'parameters' => [
|
||
'tid' => [
|
||
'type' => 'integer',
|
||
'required' => false,
|
||
'description' => '涉及到之具體貨道編號 (Slot No)',
|
||
'example' => 12
|
||
],
|
||
'error_code' => [
|
||
'type' => 'string',
|
||
'required' => true,
|
||
'description' => '硬體狀態代碼 (4 位 16 進位字串)',
|
||
'example' => '0403'
|
||
],
|
||
],
|
||
'response_parameters' => [
|
||
'success' => [
|
||
'type' => 'boolean',
|
||
'description' => '請求是否已成功接收',
|
||
'example' => true
|
||
],
|
||
'code' => [
|
||
'type' => 'integer',
|
||
'description' => '內部業務狀態碼',
|
||
'example' => 200
|
||
],
|
||
],
|
||
'request' => [
|
||
'tid' => 12,
|
||
'error_code' => '0403',
|
||
],
|
||
'response' => [
|
||
'success' => true,
|
||
'code' => 200,
|
||
'message' => 'Error report accepted'
|
||
],
|
||
'notes' => '硬體代碼對照表見後端 MachineService::ERROR_CODE_MAP 定義。
|
||
0402: 出貨成功, 0403: 貨道卡貨, 0202: 貨道缺貨, 0415: 取貨門異常...等。'
|
||
]
|
||
]
|
||
]
|
||
]
|
||
]; |