Files

sky121113 17b5c1a316 [DOCS] 現代化 IoT API (B010) 通訊協議與文件中心 UI/UX 重整

2026-03-26 14:59:49 +08:00

4.8 KiB

Raw Blame History

name, description

name	description
IoT 通訊與高併發處理規範	規範智能販賣機與 Cloud 平台間的高頻通訊處理流程，包含 API 接收、異步隊列、業務邏輯拆分與日誌記錄。

IoT 通訊與高併發處理規範 (IoT Communication Skill)

本規範確保 Star-Cloud 系統在處理成千上萬台機台的高頻發報時，能維持伺服器響應速度與資料一致性。

1. 處理管線 (Processing Pipeline)

所有來自機台的非即時性資料（日誌、心跳、狀態上報）必須遵循以下 pipeline：

API Controller (接收層)：驗證 Request 合法性，隨即分派 (Dispatch) 任務至 Queue，並回傳 202 Accepted。
Job (異步層)：由背景 Worker 讀取隊列任務，呼叫對應 Service 處理。
Service (邏輯層)：封裝商業邏輯，更新資料庫。
Model (儲存層)：執行資料存取。

Important

嚴禁在 API Controller 直接進行資料庫寫入操作（針對機台發訊端點）。

2. 異步任務實作範例

2.1 API Endpoint

public function storeLog(Request $request, int $id): JsonResponse
{
    // 1. 驗證
    $data = $request->validate([...]);
    
    // 2. 異步分派
    ProcessMachineLog::dispatch($id, $data);
    
    // 3. 快速回應
    return $this->successResponse([], 'Accepted', 202);
}

2.2 Job 處理邏輯

Job 應保持單純，僅作為 Service 的觸發點：

public function handle(MachineService $service): void
{
    $service->recordLog($this->machineId, $this->logData);
}

3. 隊列配置規範

連接驅動 (Driver)：預設使用 Redis 以確保高併發吞吐量。
重試機制 (Retry)：IoT 任務應設定合理的重試次數，避免因網路短暫波動遺失日誌。
失敗處理 (Failed Jobs)：關鍵業務（如訂單同步）必須監控 failed_jobs。

4. 速率限制 (Rate Limiting)

所有的 IoT API 必須在 routes/api.php 中使用 throttle:api 或自定義 Middleware。
針對單一機台 ID 應限制其每一分鐘的最高連線數，防止遭受攻擊或機台 Bug 導致的連線暴衝。

5. 檢核項目 (Checklist)

是否使用了 ApiResponse Trait？
業務邏輯是否已封裝至 App\Services？
是否使用了 Redis Queue 進行非同步處理？

6. 核心 API 規格 (Core API Specs)

6.1 B010: 心跳上報與狀態同步 (Finalized)

這是機台最頻繁呼叫的端點，用於確認在線狀態、更新感測數據並獲取雲端指令。

Endpoint: POST /api/v1/app/machine/status/B010
認證: Authorization: Bearer <api_token> (必需)
Content-Type: application/json

Request Body:

參數	類型	必填	說明
`current_page`	Integer	是	當前頁面編號 (對照見下表)
`firmware_version`	String	是	韌體版本號
`model`	String	是	機台型號 (如 STAR-V1)
`temperature`	Float	否	環境溫度
`door_status`	Integer	否	門狀態 (0: 關, 1: 開)
`log`	String	否	事件日誌訊息
`log_level`	String	否	日誌等級 (info/warn/error)
`log_payload`	Object	否	額外日誌上下文 (JSON 對象)

Response Body:

參數	類型	說明
`success`	Boolean	請求是否處理成功
`code`	Integer	內部業務狀態碼
`message`	String	回應訊息說明
`status`	String	雲端指令代碼 (對照見下表)

狀態代碼對照表

頁面代碼 (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 (貨道同步)
50: reload B005 (基礎參數)
51: reboot (重啟)
60: reboot card machine (刷卡機重啟)
61: checkout (結帳)
70: unlock (解鎖)
71: lock (鎖定)
72: sellCode reload B023 (即期品)
75: exp reload B026 (效期)
79: read B050 (參數讀取)
81: sync timer status (B710)
85: reload B0552 (出貨腳本)

{
    "success": true,
    "code": 200,
    "message": "OK",
    "status": "49"
}

status: 若為字串 (如 "49") 代表有掛載指令，機台應執行對應動作。
202 Accepted: 系統將以 202 或 200 回應，代表已進入 Redis Queue 異步處理。

Caution

身份識別機制：禁止在 Body 帶入 machine 或 key。系統完全透過 Bearer Token 識別機台身份並綁定資料。

4.8 KiB Raw Blame History Unescape Escape