145 lines
4.8 KiB
Markdown
145 lines
4.8 KiB
Markdown
---
|
||
name: IoT 通訊與高併發處理規範
|
||
description: 規範智能販賣機與 Cloud 平台間的高頻通訊處理流程，包含 API 接收、異步隊列、業務邏輯拆分與日誌記錄。
|
||
---
|
||
|
||
# IoT 通訊與高併發處理規範 (IoT Communication Skill)
|
||
|
||
本規範確保 Star-Cloud 系統在處理成千上萬台機台的高頻發報時，能維持伺服器響應速度與資料一致性。
|
||
|
||
## 1. 處理管線 (Processing Pipeline)
|
||
|
||
所有來自機台的非即時性資料（日誌、心跳、狀態上報）必須遵循以下 pipeline：
|
||
|
||
1. **API Controller (接收層)**：驗證 Request 合法性，隨即分派 (Dispatch) 任務至 Queue，並回傳 `202 Accepted`。
|
||
2. **Job (異步層)**：由背景 Worker 讀取隊列任務，呼叫對應 Service 處理。
|
||
3. **Service (邏輯層)**：封裝商業邏輯，更新資料庫。
|
||
4. **Model (儲存層)**：執行資料存取。
|
||
|
||
> [!IMPORTANT]
|
||
> **嚴禁**在 API Controller 直接進行資料庫寫入操作（針對機台發訊端點）。
|
||
|
||
## 2. 異步任務實作範例
|
||
|
||
### 2.1 API Endpoint
|
||
```php
|
||
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 的觸發點：
|
||
```php
|
||
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 (出貨腳本)
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "OK",
|
||
"status": "49"
|
||
}
|
||
```
|
||
* `status`: 若為字串 (如 "49") 代表有掛載指令，機台應執行對應動作。
|
||
* `202 Accepted`: 系統將以 202 或 200 回應，代表已進入 Redis Queue 異步處理。
|
||
|
||
> [!CAUTION]
|
||
> **身份識別機制**：禁止在 Body 帶入 `machine` 或 `key`。系統完全透過 `Bearer Token` 識別機台身份並綁定資料。
|