# B010 API (機台心跳與指令) 技術規範與執行指南

本文件整合了 B010 API 的業務邏輯討論與技術執行分析，作為 Star Cloud 實作機台通訊核心的指導準則。

---

## 1. 業務邏輯與指令下發 (Command Flow)

### 1.1 指令下發機制
B010 是 Cloud 向機台下達遠端指令（如：開鎖、重啟、改庫存）的唯一通道。
*   **指令隊列**：指令需先寫入 `remote_commands` 表，狀態標記為 `pending`。
*   **撈取邏輯**：當機台定期呼叫 B010 時，後端 Service 會查詢該機台是否有等待執行的指令。
*   **回應處理**：若有指令，則在 Response 的 `status` 欄位回傳對應的指令碼（如 51:重啟, 70:開鎖）。
*   **優先順序**：當同時有多個指令待執行時，需按緊急程度（如：重啟 > 開鎖 > 載入配置）定義優先順序回傳。

### 1.2 執行回饋 (Feedback Loop)
*   **確認機制**：機台收到指令後，必須確保執行結果能回報至雲端。
*   **判定方案**：
    *   **被動判定**：若機台在其後的 B010 心跳中回報狀態正常（如：軟體版本更新成功、頁面碼正確），即視為成功。
    *   **主動判定**：對於關鍵指令（如遠端出貨），機台需另外呼叫狀態更新 API (如 B055 PUT) 回報結果。

---

## 2. 執行面挑戰：高併發與效能 (Performance)

### 2.1 寫入瓶頸分析
*   **數據規模**：10,000 台機台，每 10 秒一個心跳，全站 QPS 約 1,000。
*   **DB 壓力**：直接同步寫入 MySQL `machines` 與 `machine_logs` 將導致磁碟 I/O 鎖定。

### 2.2 解決策略 (Redis 緩衝)
*   **即時狀態流動**：
    *   **最後在線時間**、**溫度**、**門禁狀態**、**頁面碼** 等動態數據優先存入 **Redis**。
    *   **批量更新 (Lazy Update)**：每 1~5 分鐘由後台任務將 Redis 數據批量寫回 MySQL `machines` 表。
*   **日誌優化**：
    *   **正常心跳不寫入資料庫日誌**，僅在**狀態變更**（如：門被打開、溫度過高、軟體報錯）時，才觸發資料庫日誌記錄。

---

## 5. 安全性與驗證策略 (Security)

*   **API Key 遷移**：從目前全系統硬編碼的共用 Key，逐步遷移至每台機台專屬的 `api_token`。
*   **驗證方式**：機台端需在 Header 帶入 `Authorization: Bearer <api_token>` 進行身份驗證。
*   **實裝方式**：
    *   後台管理介面新增「核發機台 Token」功能。
    *   建立專屬 `IotAuthMiddleware`，驗證請求中的 Token 與 `machines` 表是否匹配。

---

## 6. 離線與告警機制 (Heartbeat Logic)

*   **在線判定**：心跳超時超過 **30 秒** 即在 UI 將機台顯示為「離線」。
*   **告警機制**：機台斷線時，系統需即時產出**警示或推播通知**給相關人員。
*   **自動維護**：排程 Job 定期掃描 `machines.last_heartbeat_at`，處理長期失聯機台。

---

## 7. 業務邏輯細節 (Fine-grained Logic)

*   **指令成功判定**：採「**被動判定**」。機台收到指令後，若在其後的 B010 心跳中回報狀態正確（如：頁面碼已變更），即視為指令執行成功。

---

## 8. 待確認事項 (已結案)

目前已根據 2026-03-12 的討論完成所有關鍵決策。