[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/iot-communication/SKILL.md

@@ -9,13 +9,25 @@ description: 規範智能販賣機與 Cloud 平台間的高頻通訊處理流程
 
 ## 1. 處理管線 (Processing Pipeline)
 
-所有來自機台的非即時性資料（日誌、心跳、狀態上報）必須遵循以下 pipeline：
+所有來自機台的非即時性資料（日誌、心跳、狀態上報）必須遵循以下 pipeline。依據通訊協議不同，進入點有兩條路徑：
 
+### 1.1 HTTP 管線 (低頻/大檔操作)
+適用於 B000, B009, B012, B014 等低頻或大資料量的端點：
 1.  **API Controller (接收層)**：驗證 Request 合法性，隨即分派 (Dispatch) 任務至 Queue，並回傳 `202 Accepted`。
 2.  **Job (異步層)**：由背景 Worker 讀取隊列任務，呼叫對應 Service 處理。
 3.  **Service (邏輯層)**：封裝商業邏輯，更新資料庫。
 4.  **Model (儲存層)**：執行資料存取。
 
+### 1.2 MQTT 管線 (高頻/即時操作)
+適用於 B010 (心跳), B013 (異常), B600 (交易) 等高頻或即時性端點：
+1.  **Go Gateway (接收層)**：訂閱 EMQX Topic，提取 `serial_no`，包裝成標準 JSON。
+2.  **Redis List (橋接層)**：Go 執行 `RPUSH mqtt_incoming_jobs {json}`。
+3.  **Laravel `mqtt:listen` (消費層)**：常駐指令 `BLPOP` 取出 JSON，根據 `type` 分派至對應 Job。
+4.  **Job ➜ Service ➜ Model**：與 HTTP 管線後半段相同。
+
+> [!TIP]
+> 兩條管線的 **Job / Service / Model 層完全共用**，差異僅在「進入點」。這確保了業務邏輯不會因為通訊協議不同而分裂。
+
 > [!IMPORTANT]
 > **嚴禁**在 API Controller 直接進行資料庫寫入操作（針對機台發訊端點）。
 
@@ -53,9 +65,14 @@ public function handle(MachineService $service): void
 
 ## 4. 速率限制 (Rate Limiting)
 
-- 所有的 IoT API 必須在 `routes/api.php` 中使用 `throttle:api` 或自定義 Middleware。
+### 4.1 HTTP 端點
+- 所有的 IoT HTTP API 必須在 `routes/api.php` 中使用 `throttle:api` 或自定義 Middleware。
 - 針對單一機台 ID 應限制其每一分鐘的最高連線數，防止遭受攻擊或機台 Bug 導致的連線暴衝。
 
+### 4.2 MQTT 端點
+- 限速由 **EMQX Broker** 的 Rate Limiting 功能負責（非 Laravel Middleware）。
+- Go Gateway 層可額外實作簡易的 Token Bucket，當某台機台每秒超過閾值時丟棄訊息並記錄 Warning Log。
+
 ## 5. 檢核項目 (Checklist)
 - [ ] 是否使用了 `ApiResponse` Trait？
 - [ ] 業務邏輯是否已封裝至 `App\Services`？
@@ -64,13 +81,16 @@ public function handle(MachineService $service): void
 ## 6. API 規格定義 (API Specifications)
 
 > [!IMPORTANT]
-> **規格分離原則**：本技能僅規範「通訊處理邏輯」。關於具體的 API 欄位、參數命名、狀態代碼對照與範例，請務必參閱專屬技能規範：
-> - **[API 技術規格與通訊協議規範](file:///home/mama/projects/star-cloud/.agents/skills/api-technical-specs/SKILL.md)**
+> **規格分離原則**：本技能僅規範「通訊處理邏輯」。關於具體的欄位定義與資料格式，請參閱對應的專屬技能規範：
+> - **HTTP 端點**：[API 技術規格與通訊協議規範](file:///home/mama/projects/star-cloud/.agents/skills/api-technical-specs/SKILL.md)
+> - **MQTT 端點**：[MQTT 即時通訊與 Topic 規範](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md)
 
 ### 常見端點處理模式
-1.  **B010 (心跳)**：高頻點，必須進入 Redis Queue。更新 `last_heartbeat_at` 與感測器快照。
-2.  **B600 (交易)**：高價值點，必須進入任務隊列並支援重試。建立 `Transaction` 紀錄。
-3.  **B017 (貨道)**：回覆較大資料量，應確保 Service 層具備緩存 (Cache) 機制。
+1.  **B010 (心跳)**：高頻點，走 **MQTT 管線** (`machine/+/heartbeat`)。更新 `last_heard_at` 與感測器快照。
+2.  **B013 (異常)**：事件驅動點，走 **MQTT 管線** (`machine/+/error`)。寫入 `machine_logs` 並觸發告警。
+3.  **B600 (交易)**：高價值點，走 **MQTT 管線** (`machine/+/transaction`)。建立 `Transaction` 紀錄並支援重試。
+4.  **B012 (商品同步)**：大資料量，走 **HTTP 管線**。應確保 Service 層具備緩存 (Cache) 機制。
+5.  **B055 (遠端出貨)**：雲端下發指令，走 **MQTT 下行管線** (`machine/{id}/command`)。
 
 ---