[DOCS] 建立獨立 API 技術規格技能 (api-technical-specs) 並精簡 IoT 通訊規範

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

@@ -61,84 +61,18 @@ public function handle(MachineService $service): void
 - [ ] 業務邏輯是否已封裝至 `App\Services`？
 - [ ] 是否使用了 Redis Queue 進行非同步處理？
 
-## 6. 核心 API 規格 (Core API Specs)
+## 6. API 規格定義 (API Specifications)
 
-### 6.1 B010: 心跳上報與狀態同步 (Finalized)
-這是機台最頻繁呼叫的端點，用於確認在線狀態、更新感測數據並獲取雲端指令。
+> [!IMPORTANT]
+> **規格分離原則**：本技能僅規範「通訊處理邏輯」。關於具體的 API 欄位、參數命名、狀態代碼對照與範例，請務必參閱專屬技能規範：
+> - **[API 技術規格與通訊協議規範](file:///home/mama/projects/star-cloud/.agents/skills/api-technical-specs/SKILL.md)**
 
-- **Endpoint**: `POST /api/v1/app/machine/status/B010`
-- **認證**: `Authorization: Bearer <api_token>` (必需)
-- **Content-Type**: `application/json`
+### 常見端點處理模式
+1.  **B010 (心跳)**：高頻點，必須進入 Redis Queue。更新 `last_heartbeat_at` 與感測器快照。
+2.  **B600 (交易)**：高價值點，必須進入任務隊列並支援重試。建立 `Transaction` 紀錄。
+3.  **B017 (貨道)**：回覆較大資料量，應確保 Service 層具備緩存 (Cache) 機制。
 
-**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` 識別機台身份並綁定資料。
+> **身份識別機制**：禁止在 Body 傳輸 `machine` 或 `key`。系統強制透過 `Bearer Token` 識別並自動關聯資料。