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

name, description

name	description
IoT 通訊與高併發處理規範	規範智能販賣機與 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

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 規格定義 (API Specifications)

Important

規格分離原則：本技能僅規範「通訊處理邏輯」。關於具體的 API 欄位、參數命名、狀態代碼對照與範例，請務必參閱專屬技能規範：

• API 技術規格與通訊協議規範

常見端點處理模式

1. B010 (心跳)：高頻點，必須進入 Redis Queue。更新 last_heartbeat_at 與感測器快照。
2. B600 (交易)：高價值點，必須進入任務隊列並支援重試。建立 Transaction 紀錄。
3. B017 (貨道)：回覆較大資料量，應確保 Service 層具備緩存 (Cache) 機制。

---

Caution

身份識別機制：禁止在 Body 傳輸 machine 或 key。系統強制透過 Bearer Token 識別並自動關聯資料。