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

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

@@ -60,4 +60,85 @@ public function handle(MachineService $service): void
 - [ ] 是否使用了 `ApiResponse` Trait？
 - [ ] 業務邏輯是否已封裝至 `App\Services`？
 - [ ] 是否使用了 Redis Queue 進行非同步處理？
-- [ ] 是否在 API 層級進行了基礎的參數驗證？
+
+## 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` 識別機台身份並綁定資料。