[DOCS]：初始化 MQTT 架構實作計畫與相關技術規範

1. 新增 MQTT 即時通訊與 Topic 規範文件 (.agents/skills/mqtt-communication-specs/SKILL.md)。
2. 建立 MQTT 基礎架構實作計畫文件 (docs/mqtt-implementation-plan.md)。
3. 更新全域開發框架規範 (framework.md)，納入 Go Gateway 與 EMQX 架構說明。
4. 重構 IoT 通訊處理規範 (iot-communication/SKILL.md)，支援 HTTP 與 MQTT 雙軌管線。
5. 更新背景 API 規範 (api-rules.md) 與技能觸發規則 (skill-trigger.md) 以符合新架構。

.agents/skills/mqtt-communication-specs/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: MQTT 即時通訊與 Topic 規範
+description: 定義 Star Cloud 與終端機台 (IoT) 之間的 MQTT 全域通訊拓撲、主題 (Topic) 結構、資料載體 (Payload) 格式與安全性認證機制。
+---
+
+# MQTT 即時通訊與 Topic 規範 (MQTT Protocol Specs)
+
+本文件定義機台與 Star Cloud 之間的高併發即時通訊標準。MQTT 主要用於處理高頻率且對即時性要求高的訊息（如心跳、遠端指令），與 HTTP REST API 形成雙軌互補架構。
+
+## 1. 連線基礎設定 (Connection Basics)
+
+### 1.1 Broker 資訊
+- **協議版本**：MQTT v3.1.1 (相容性最高)
+- **預設埠號**：1883 (TCP / 測試用), 8883 (SSL/TLS / 正式用)
+- **Keep-Alive**：建議設定為 30 ~ 60 秒。
+
+### 1.2 身份認證 (Authentication)
+機台連線時必須提供以下憑據：
+- **Username**：機台編號 (`serial_no`)，例如 `M-001`。
+- **Password**：機台正式 Token (`api_token`)，由 B014 API 取得。
+- **Client ID**：建議格式為 `SC_{serial_no}_{random_suffix}`，確保唯一性。
+
+---
+
+## 2. 主題架構 (Topic Topology)
+
+我們採用目錄式的層級結構，方便未來進行萬台設備的管理與 ACL 權限切分。
+
+| 主題名稱 (Topic) | 方向 | QoS | 用途說明 |
+| :--- | :--- | :--- | :--- |
+| `machine/{serial_no}/heartbeat` | 設備 ➜ 雲端 | 0 | 每 10 秒上報心跳、溫度、目前的頁面碼。 |
+| `machine/{serial_no}/error` | 設備 ➜ 雲端 | 1 | 發生硬體故障、卡貨或門未關時立即上報。 |
+| `machine/{serial_no}/transaction` | 設備 ➜ 雲端 | 1 | 交易完成、出貨結果的回報。 |
+| `machine/{serial_no}/command` | 雲端 ➜ 設備 | 1 | 雲端下發的即時指令（出貨、更新、重啟）。 |
+
+---
+
+## 3. 資料載體規範 (Payload Definitions)
+
+所有 Payload 統一採用 **JSON** 格式，字母一律為 **snake_case**。
+
+### 3.1 心跳上報 (Heartbeat) - `machine/{id}/heartbeat`
+比照原 B010 邏輯，但去除不必要的 HTTP Header 開銷。
+
+```json
+{
+  "current_page": 1,
+  "firmware_version": "1.0.5",
+  "temperature": 25.5,
+  "door_status": 0,
+  "timestamp": "2026-04-14T09:00:00+08:00"
+}
+```
+
+### 3.2 異常上報 (Error/Event) - `machine/{id}/error`
+比照原 B013 邏輯。
+
+```json
+{
+  "tid": 12,
+  "error_code": "0403",
+  "log": "Slot jammed at slot 12",
+  "timestamp": "2026-04-14T09:05:00+08:00"
+}
+```
+
+### 3.3 雲端指令 (Downstream Commands) - `machine/{id}/command`
+這是雲端主動下發給機台的訊息，取代原本 B010 Response 的輪詢等待。
+
+```json
+{
+  "command": "dispense",
+  "payload": {
+    "slot_no": 5,
+    "transaction_id": "T202604140001"
+  },
+  "message_id": "MSG_123456789"
+}
+```
+**常用指令集：**
+- `reboot`: 機台重啟。
+- `reload_config`: 重新下載參數 (B014)。
+- `reload_products`: 重新同步商品 (B012)。
+- `dispense`: 遠端出貨指令 (B055)。
+
+---
+
+## 4. 安全與 QOS 規範
+
+1. **存取控制 (ACL)**：EMQX Broker 必須設定 ACL，禁止機台 A 訂閱機台 B 的 Topic。機台僅能訂閱與發布包含自身 `serial_no` 的路徑。
+2. **QoS 策略**：
+   - **QoS 0**：適用於高頻率心跳，即使掉一兩次包也不影響系統判斷。
+   - **QoS 1**：適用於交易與指令，確保「至少送達一次」。App 端收到指令後應回覆回執。
+3. **遺囑訊息 (Last Will and Testament)**：
+   機台 Connect 時應設定 Last Will 於 `machine/{serial_no}/heartbeat`，Payload 為 `{"status": "offline"}`。當連線異常中斷時，雲端能立刻得知。
+
+---
+
+## 5. 與 REST API 的同步關係
+當 MQTT 通訊正常時，機台應停止定時呼叫 B010 HTTP API。若 MQTT 斷線超過 3 分鐘，則退回 (Fallback) 使用 HTTP 輪詢模式以維持基礎通訊。