star-cloud/docs/b010_technical_spec.md

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 台機台，每 5 秒一個心跳，全站 QPS 約 2,000。
• DB 壓力：直接同步寫入 MySQL machines 與 machine_logs 將導致磁碟 I/O 鎖定。

2.2 解決策略 (Redis 緩衝)

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

---

3. 資料庫結構擴充 (Schema Gap)

必須對原有的 machines 表進行欄位擴充，以承載 B010 的回傳值：

新增欄位	類型	說明
serial_no	VARCHAR(50) UNIQUE	機台序號 (API machine)
model	VARCHAR(50)	機台型號 (API M_Stus)
current_page	TINYINT	當前頁面代碼 (API M_Stus2)
door_status	VARCHAR(10)	門禁狀態 (open/closed)
api_token	VARCHAR(100)	獨立安全憑證 (取代共用 Key)

---

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

• API Key 遷移：從目前全系統硬編碼的共用 Key，逐步遷移至每台機台專屬的 api_token。
• 實裝方式：
  • 後台管理介面新增「核發機台 Token」功能。
  • 建立專屬 IotAuthMiddleware，驗證請求中的 Token 與 machines 表是否匹配。

---

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

• 在線判定：心跳超時（建議超過 60 秒）即在 UI 將機台顯示為「離線」。
• 自動維護：排程 Job 定期掃描 machines.last_heartbeat_at，對長期失聯的機台發出系統告警。

---

6. 待確認事項 (To-be-confirmed)

6.1 指令下發與回應 (Command Flow)

1. 指令優先順序：當後台同時有多個指令待執行 (如：改庫存 + 重啟) 時，應如何定義優先權？
2. 執行狀態回饋：機台收到心跳指令後的執行結果確認，應採「被動判定」(機台下次心跳狀態正確則視為成功) 還是「主動回報」(機台另呼叫 API)？

6.2 效能與日誌策略 (Performance & Logs)

3. Redis 更新頻率：即時狀態從 Redis 批量同步至 MySQL 的建議時間間隔 (目前暫估 1~5 分鐘)。
4. 心跳日誌級別：是否確認「正常心跳」不寫入資料庫日誌，僅記錄「異常/變更」事件？

6.3 在線/離線判定 (Presence)

5. 離線超時定義：預計多久未收心跳判定為離線？(建議 30~60 秒)。
6. 斷線告警機制：機台斷線時，是否需即時產出系統警示或推播給相關人員？

6.4 安全性驗證 (Auth)

7. Token 傳遞方式：將 API Key 遷移至專屬 Token 時，機台端是否能配合在 Header (Authorization: Bearer <token>) 帶入，或必須保留在 JSON Payload 中？

6.5 欄位細節 (Field Details)

8. URL {workid} 定義：URL 中的 {workid} 應對應為 serial_no (機台序號) 還是資料庫自增 id？
9. M_Stus2 告警觸發：20 多種頁面狀態碼中，哪些特定的錯誤代碼需要在管理後台觸發即時紅字警示？