feat: 實作機台日誌核心功能與 IoT 高併發處理架構

.agents/skills/iot-communication/SKILL.md

@@ -0,0 +1,63 @@
+---
+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 進行非同步處理？
+- [ ] 是否在 API 層級進行了基礎的參數驗證？