[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) 以符合新架構。
2026-04-14 13:02:08 +08:00
parent daf8b1ebcc
commit 32fa28dc0f
6 changed files with 436 additions and 28 deletions
--- a/.agents/rules/api-rules.md
+++ b/.agents/rules/api-rules.md
@@ -66,15 +66,22 @@ trigger: always_on

 ---

-## ⚡ 5. 高併發處理與隊列
+## ⚡ 5. IoT 高併發流向與 MQTT Gateway 整合

-為了系統穩定性，以下 API **嚴禁直寫資料庫**，必須進入 **Redis Queue** 異步處理：
-1.  **B010**: 心跳上傳（每 5-10 秒一次）。
-2.  **B600 / B602**: 交易與出貨紀錄。
-3.  **B220**: 零錢機庫存變動。
-4.  **B710**: 計時器狀態同步。
+為了系統穩定性與高吞吐量，機台通訊的架構依循以下規範，**嚴禁直寫資料庫**：

-後端應立即回傳 `202 Accepted` 或業務定義的成功碼，由 Job 背景完成數據持久化。
+### 5.1 MQTT 通訊端點 (高頻與事件驅動)
+以下高頻或即時事件，未來將**全面改採 MQTT 協議**，透過 EMQX 與 Go Gateway 橋接：
+1.  **B010 (心跳)**：機台發布至 `machine/{serial_no}/heartbeat`。
+2.  **B013 (錯誤與狀態)**：機台發布至 `machine/{serial_no}/error`。
+3.  **B600 / B602 (交易紀錄)**：機台發布至 `machine/{serial_no}/transaction`。
+
+處理管線：
+`機台 ➜ EMQX ➜ Go Gateway ➜ Redis List (mqtt_incoming_jobs) ➜ Laravel daemon (mqtt:listen) ➜ Job 異步寫入 DB`
+
+### 5.2 HTTP 通訊端點 (資料拉取與特殊事件)
+基於歷史相容、大檔傳輸（如 `B012 商品同步`）或高度安全性（如 `B014 金鑰下載`）的端點，維持使用 HTTP REST API。
+若此類 API 產生寫入行為，後端應盡可能立即回傳 `202 Accepted`，並透過 Laravel Job 在背景完成數據持久化。

 ---

--- a/.agents/rules/framework.md
+++ b/.agents/rules/framework.md
@@ -6,19 +6,28 @@ trigger: always_on

 ## 1. 專案概述
 *   **目標**：打造一個強大且穩定的智能販賣機後台管理系統（Cloud 平台），負責管理機台、商品、銷售數據以及提供給端點機台串接的 API。
-*   **核心架構**：採用 **傳統單體式架構 (Monolithic Architecture)** 配 Laravel Blade 模板引擎進行伺服器端渲染 (SSR)。
+*   **核心架構**：採用 **Monorepo 單體式架構**，以 Laravel 為核心進行伺服器端渲染 (SSR) 與 API 服務，並搭配 **Go MQTT Gateway** 作為高併發 IoT 通訊的前置接收層。兩者透過 **Redis** 進行異步橋接，確保職責分離與系統穩定性。
 *   **工作流程**：後端處理業務邏輯與資料庫存取，並透過 Blade 引擎渲染包含 Tailwind CSS 類別的 HTML。前端互動行為由輕量級 Alpine.js 負責，UI 元件以 Preline UI 為主體。

 ## 2. 技術棧 (Tech Stack)
+
+### 2.1 後端核心 (Laravel)
 *   **後端框架**：PHP 8.5 / Laravel 12
-*   **核心組件**：Redis (用於高併發 IoT 隊列與快取，為系統穩定之必要條件)
+*   **核心組件**：Redis (用於高併發 IoT 隊列、MQTT 橋接與快取，為系統穩定之必要條件)
+*   **資料庫**：MySQL 8.0
+*   **開發環境**：Laravel Sail (Docker / WSL2)
+
+### 2.2 IoT 通訊層 (MQTT Gateway)
+*   **MQTT Broker**：EMQX 5 (負責維持機台長連線與訊息路由)
+*   **Gateway 語言**：Go (負責訂閱 MQTT Topic、預處理訊息、轉發至 Redis)
+*   **橋接機制**：Redis List (`mqtt_incoming_jobs`)，由 Laravel 常駐指令 (`mqtt:listen`) 消費
+
+### 2.3 前端
 *   **前端視圖 (View)**：Laravel Blade
 *   **前端互動 (JS)**：Alpine.js (專注於行為，不負責渲染)
 *   **介面與樣式 (CSS)**：Tailwind CSS + Preline UI (直接寫作於 Blade 模板中)。
    *   **重要規範**：Preline UI 僅作為「原子組件」與「JS 互動邏輯」的參考庫。整體的「佈局」與「美學」必須嚴格遵守「極簡奢華風 UI 實作規範 (SKILL.md)」。
 *   **前端建置工具**：Vite
-*   **資料庫**：MySQL 8.0
-*   **開發環境**：Laravel Sail (Docker / WSL2)

 ## 3. 目錄結構與慣例

@@ -29,31 +38,111 @@ trigger: always_on
 *   **Routes**：`routes/web.php` 用於後台管理介面；`routes/api.php` 提供外部或機台調用介面 (需 V1 版本化)。
 *   **Services** (建議)：`app/Services/{Domain}/`，將商業邏輯與資料異動封裝於 Service 中。
 *   **Traits**：`app/Traits/ApiResponse.php` 用於統一 API JSON 回傳格式。
-*   **Jobs**：`app/Jobs/{Domain}/`，**高併發 IoT 場景之必要實作**。所有日誌、心跳上報必須進入 Redis Queue 進行背景異步處理，嚴禁在 API 直連 DB 寫入日誌。
+*   **Jobs**：`app/Jobs/{Domain}/`，用於異步處理 IoT 資料寫入、通知發送等背景任務。
+*   **Console Commands**：`app/Console/Commands/`，包含 MQTT 橋接守護進程 (`mqtt:listen`) 等常駐指令。

 ### 3.2 前端 (Blade / Tailwind / Alpine)
 *   **Views (頁面)**：位於 `resources/views/`。通常依功能建立資料夾（如 `resources/views/admin/machines/index.blade.php`）。
 *   **Layouts (版面)**：位於 `resources/views/layouts/`。定義全站的共用版面結構（如 header, sidebar, footer）。
 *   **Components (組件)**：位於 `resources/views/components/`。封裝可重用的 Blade 元件（如 Button, Modal, Table），支援透過 `<x-button>` 語法呼叫。

-## 4. 開發標準 (Coding Standards)
+### 3.3 MQTT Gateway (Go)
+Go 專案以 Monorepo 形式置於專案根目錄下的 `mqtt-gateway/` 資料夾，獨立於 Laravel 程式碼：
+*   **進入點**：`mqtt-gateway/main.go`
+*   **模組管理**：`mqtt-gateway/go.mod` / `go.sum`
+*   **內部分層**：
+    *   `mqtt-gateway/internal/handler/` — 各 Topic 的訊息處理邏輯（如 heartbeat、transaction、error）。
+    *   `mqtt-gateway/internal/bridge/` — Redis 橋接層，負責將處理後的 JSON 推入 `mqtt_incoming_jobs` List。
+    *   `mqtt-gateway/config/` — 環境變數與 EMQX / Redis 連線設定。
+
+> [!CAUTION]
+> Go Gateway 的職責僅限於「接收、驗證、轉發」。**嚴禁**在 Go 中實作任何商業邏輯（如庫存扣減、通知發送），所有業務處理必須統一在 Laravel Service 層完成。
+
+## 4. IoT 通訊架構 (MQTT + HTTP 雙軌制)
+
+本系統的機台通訊採用 **MQTT 與 HTTP 雙軌並行** 的策略，依據通訊特性選擇最適合的協議。
+
+### 4.1 整體資料流向
+
+```
+機台 (Android APP)
+     │
+     ├─ [高頻/即時] MQTT 長連線 ──→ EMQX Broker ──→ Go Gateway ──→ Redis List ──→ Laravel mqtt:listen ──→ Job ──→ MySQL
+     │
+     └─ [低頻/大檔] HTTP REST ──→ Laravel API Controller ──→ (必要時) Job ──→ MySQL
+```
+
+### 4.2 MQTT 通訊端點 (高頻與事件驅動)
+以下端點因高頻率或即時性需求，採用 MQTT 協議通訊：
+
+| API 代碼 | Topic 格式 | 用途 | QoS |
+| :--- | :--- | :--- | :--- |
+| B010 | `machine/{serial_no}/heartbeat` | 心跳上報 (每 10 秒) | 0 |
+| B013 | `machine/{serial_no}/error` | 故障與異常狀態上報 | 1 |
+| B600 | `machine/{serial_no}/transaction` | 交易紀錄回傳 | 1 |
+
+**雲端→機台指令下發**：透過 `machine/{serial_no}/command` Topic 推送，取代原本 B010 Response 中的 `status` 欄位輪詢機制，實現毫秒級即時指令。
+
+### 4.3 HTTP 通訊端點 (資料拉取與敏感操作)
+以下端點因資料量大、安全性要求高或為 Request/Response 模式，維持使用 HTTP REST API：
+
+| API 代碼 | 用途 | 維持 HTTP 的原因 |
+| :--- | :--- | :--- |
+| B000 | 維運人員登入 | 無狀態認證，HTTP 更自然 |
+| B012 | 商品配置同步 | 大量資料的 GET 拉取 |
+| B014 | 金鑰與參數下載 | 高安全性敏感操作，需嚴格 RBAC |
+| B009 | 貨道庫存回報 | 低頻操作，由維運人員觸發 |
+
+### 4.4 Redis 橋接機制 (Go ↔ Laravel)
+Go Gateway 與 Laravel 之間透過 Redis List 進行單向異步橋接：
+
+*   **Redis Key**：`mqtt_incoming_jobs`
+*   **Go 端 (生產者)**：將 MQTT 收到的 Payload 包裝成標準 JSON 後，執行 `RPUSH mqtt_incoming_jobs {json}`。
+*   **Laravel 端 (消費者)**：常駐指令 `php artisan mqtt:listen` 持續執行 `BLPOP mqtt_incoming_jobs`，取得 JSON 後解碼並分派至對應的 Laravel Job (如 `ProcessHeartbeat`, `ProcessTransaction`)。
+
+**JSON 橋接格式規範**：
+```json
+{
+  "type": "heartbeat",
+  "serial_no": "M-001",
+  "received_at": "2026-04-14T09:00:00+08:00",
+  "payload": {
+    "current_page": 1,
+    "firmware_version": "1.0.5",
+    "temperature": 25.5
+  }
+}
+```
+
+> [!IMPORTANT]
+> **為何不讓 Go 直接寫入 Laravel Queue？** 因為 Laravel Queue 的 Payload 包含 PHP 序列化物件字串 (`serialize()`)，Go 無法安全產生此格式。透過獨立的 Redis List + 純 JSON，可徹底解耦兩端的技術依賴。
+
+### 4.5 MQTT 連線認證
+機台連線 EMQX 時，使用 `serial_no` 作為 Username、`api_token` 作為 Password。驗證流程：
+
+1.  **Laravel 端 (Token 派發時)**：B014 下發 `api_token` 時，同步執行 `Redis::set("machine_auth:{serial_no}", hash(api_token))`。
+2.  **EMQX 端 (連線驗證時)**：配置 Redis Auth Plugin，直接查詢 Redis 進行極速驗證 (毫秒級)，不經過 MySQL。
+3.  **Token 更新/撤銷時**：Laravel 更新或刪除機台 Token 時，必須同步更新或刪除 Redis 中的對應快取。
+
+## 5. 開發標準 (Coding Standards)
 *   **命名規範**：
    *   Controllers: `PascalCaseController.php` (例如 `MachineController.php`)
    *   Models: `PascalCase.php` (例如 `Machine.php`)
    *   Blade Views: `kebab-case.blade.php` 或按資源名稱 (例如 `index.blade.php`, `create.blade.php`)
    *   Routes uri: `kebab-case` (例如 `/machine-logs`)
+    *   Go 檔案: `snake_case.go` (例如 `heartbeat_handler.go`)
 *   **回傳格式**：
    *   Web 路由：回傳 `view()`，表單驗證失敗時直接使用 Laravel 內建的 redirect with errors。
    *   API 路由：回傳標準 JSON 格式的 `JsonResponse`。

-## 5. UI 與前端開發指南
+## 6. UI 與前端開發指南
 *   **樣式撰寫**：全面使用 Tailwind CSS utility classes，**避免撰寫自訂 CSS**（除非少數特定動畫或覆寫）。
 *   **UI 元件庫**：遵循 **Preline UI** 的類別與 HTML 結構進行開發。
 *   **前端腳本**：
    *   優先使用 **Alpine.js** (`x-data`, `x-show`, `@click` 等) 在 HTML 標籤內完成簡單的 DOM 狀態切換與互動邏輯。
    *   避免在 Blade 內撰寫冗長的 `<script>` Vanilla JS；若邏輯過於複雜，可將 Alpine state 獨立成 js 檔案再於 Vite 引入，但原則上保持輕量。

-## 6. 多語系 I18n 規範 (Multi-language Standards)
+## 7. 多語系 I18n 規範 (Multi-language Standards)
 *   **視圖開發**：所有使用者可見的文字、按鈕、提示訊息，必須使用 Laravel 的 `@lang('key')` 或 `__('key')` 函式包裹。
 *   **語系 Key 命名**：語系 Key 必須採用 **英文原始詞彙 (English phrases)** 作為 Key 名稱為原則，以提高代碼可讀性並作為預設回退（除非該字串過長，才建議使用點號分隔的 key）。
    *   範例：使用 `__('Account Settings')`。
@@ -61,7 +150,7 @@ trigger: always_on
    *   主語系檔案位於 `lang/` 目錄。
    *   開發新功能時，必須同步更新以下三個 JSON 翻譯檔：`zh_TW.json` (主要)、`en.json` (預設)、`ja.json` (日文)。

-## 7. AI 協作規則 (給 Antigravity AI)
+## 8. AI 協作規則 (給 Antigravity AI)
 *   **角色設定**：你是一位專業的全端開發工程師助手。
 *   **代碼生成指令**：
    *   所有的解釋說明請使用 **繁體中文**。
@@ -70,23 +159,24 @@ trigger: always_on
    *   **【多語系強制要求】** 任何新增的 Blade UI 區塊，禁止硬編碼 (Hard-coded) 中文或英文。必須使用 `__('...')` 並同步在 `lang/*.json` 補上翻譯。
    *   生成 UI 區塊時，必須優先參考與產生 **Preline UI** 風格與結構的標記語法。
    *   開發新功能時，請建立標準的 Controller 搭配對應的 `resources/views/.../` 目錄。
+    *   **【Go Gateway 開發】** 修改 `mqtt-gateway/` 內的 Go 程式碼時，嚴禁加入商業邏輯。Go 僅負責訊息接收、格式轉換與 Redis 轉發。

-## 8. 運行機制 (Docker / Sail)
+## 9. 運行機制 (Docker / Sail)
 由於專案運行在 Docker 容器環境中，請勿直接在宿主機 (Host) 執行 php 或 composer 指令。請使用專案內建的 `sail` 指令：

-*   **啟動環境**：`./vendor/bin/sail up -d`
+*   **啟動環境**：`./vendor/bin/sail up -d`（將同時啟動 Laravel、MySQL、Redis、EMQX、Go Gateway）
 *   **執行 PHP 指令**：`./vendor/bin/sail php -v`
 *   **執行 Artisan 指令**：`./vendor/bin/sail artisan route:list`
 *   **執行 Composer**：`./vendor/bin/sail composer install`
 *   **執行 Node/NPM**：`./vendor/bin/sail npm run dev`

-## 8. 部署與查修環境 (CI/CD)
+## 10. 部署與查修環境 (CI/CD)
 *   **自動化部署**：專案具備基於 Gitea Actions 的 CI/CD 自動化部署流程 (`.gitea/workflows/`)。
 *   **Demo 環境 (對應 `demo` 分支)**：
    *   透過 `deploy-demo.yaml`，合併或推送到 `demo` 分支會自動部署至 `demo-cloud.taiwan-star.com.tw`。
    *   登入伺服器查修：`ssh gitea_work`，路徑為 `/var/www/star-cloud-demo`。

-## 9. 瀏覽器測試規範 (Browser Testing)
+## 11. 瀏覽器測試規範 (Browser Testing)
 當需要進行瀏覽器自動化測試或手動驗證時，必須遵守以下連線資訊：

 *   **本地測試網址**：`http://localhost:8090/` (注意：非 8000 或 8080)
--- a/.agents/rules/skill-trigger.md
+++ b/.agents/rules/skill-trigger.md
@@ -14,7 +14,7 @@ Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。

 | 觸發詞 / 情境 | 對應 Skill | 路徑 |
 |---|---|---|
-| 機台通訊, IoT, 日誌上報, Log Ingestion, 異步隊列, Queue, Heartbeat, 心跳發報 | **IoT 通訊與高併發處理規範** | `.agents/skills/iot-communication/SKILL.md` |
+| 機台通訊, IoT, 日誌上報, Log Ingestion, 異步隊列, Queue, Heartbeat, 心跳發報, MQTT, Topic, Broker, EMQX | **IoT 通訊與高併發處理規範 / MQTT 通訊規範** | `.agents/skills/iot-communication/SKILL.md` <br> `.agents/skills/mqtt-communication-specs/SKILL.md` |
 | B010, B017, B600, B055, API 規格, 通訊協議, 狀態碼, 頁面碼, 範例, JSON | **API 技術規格與通訊協議規範** | `.agents/skills/api-technical-specs/SKILL.md` |
 | 介面, UI, 設計, 佈局, CSS, Tailwind, 奢華, 深色模式, Light Mode, Dark Mode, Blade, 樣式, 間距, 陰影, 動畫, 畫面, 頁面 | **極簡奢華風 UI 實作規範** | `.agents/skills/ui-minimal-luxury/SKILL.md` |
 | 查詢、撈資料、Query、Controller、下拉選單、Eloquent、N+1、`->get()`、select、交易、Transaction、Bulk、分頁、索引 | **資料庫與 ORM 最佳實踐規範** | `/home/mama/.gemini/antigravity/global_skills/database-best-practices/SKILL.md` |
--- a/.agents/skills/iot-communication/SKILL.md
+++ b/.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`)。

 ---

--- a/.agents/skills/mqtt-communication-specs/SKILL.md
+++ b/.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 輪詢模式以維持基礎通訊。
--- a/docs/mqtt-implementation-plan.md
+++ b/docs/mqtt-implementation-plan.md
@@ -0,0 +1,191 @@
+# Star Cloud MQTT 基礎架構實作計畫 (Phase 1)
+
+本計畫旨在建立 Star Cloud 的高併發通訊基石，包含佈署 EMQX Broker、開發 Go MQTT Gateway，並建立與 Laravel 之間的 Redis **雙向**異步橋接機制。
+
+---
+
+## User Review Required
+
+> [!IMPORTANT]
+> **雙向通訊架構**：本計畫不只處理「機台 ➜ 雲端」的上報，也同時建立「雲端 ➜ 機台」的指令下發通道。後台管理員在按下「遠端出貨」按鈕時，Laravel 會將指令推入 Redis，由 Go Gateway 轉發至 EMQX，再即時送達機台 APP。
+
+> [!WARNING]
+> **資源配額**：Go Gateway 雖然輕量，但在 Docker 環境中仍建議設定 `mem_limit` 避免極端情況下的資源爭搶。
+
+---
+
+## 系統架構總覽
+
+```
+機台 Android APP
+     │
+     ├─ [上行] Publish ──→ EMQX ──→ Go Gateway ──→ Redis List (mqtt_incoming_jobs) ──→ Laravel mqtt:listen ──→ Job ──→ MySQL
+     │
+     └─ [下行] Subscribe ←── EMQX ←── Go Gateway ←── Redis List (mqtt_outgoing_commands) ←── Laravel MqttCommandService
+```
+
+---
+
+## Proposed Changes
+
+### 1. 基礎設施佈署 (Infrastructure)
+
+#### [MODIFY] [compose.yaml](file:///home/mama/projects/star-cloud/compose.yaml)
+- **新增 `emqx` 服務**：
+    - Image: `emqx/emqx:5.10.3`（開源版最終穩定版，Apache 2.0 授權）
+    - Ports: `1883:1883` (MQTT), `8083:8083` (WebSocket), `18083:18083` (Dashboard)
+    - 加入 `sail` 網路
+    - 配置 Redis Auth 插件環境變數，指向 `star-cloud-redis`
+- **新增 `mqtt-gateway` 服務**：
+    - 使用 `mqtt-gateway/Dockerfile` 進行 Multi-stage build
+    - 連接至 `sail` 網路
+    - 依賴 `emqx` 與 `redis`
+    - 環境變數從 `.env` 讀取
+
+#### [MODIFY] [.env](file:///home/mama/projects/star-cloud/.env)
+- 新增以下環境變數：
+```env
+# MQTT / EMQX
+MQTT_BROKER_HOST=emqx
+MQTT_BROKER_PORT=1883
+EMQX_DASHBOARD_PORT=18083
+
+# Go Gateway
+MQTT_GATEWAY_CLIENT_ID=star-cloud-gateway
+MQTT_REDIS_HOST=star-cloud-redis
+MQTT_REDIS_PORT=6379
+```
+
+---
+
+### 2. Go MQTT Gateway 開發 (The Bridge)
+
+#### [NEW] 完整目錄結構
+```
+mqtt-gateway/
+├── Dockerfile              ← Multi-stage build (builder + alpine)
+├── go.mod
+├── go.sum
+├── main.go                 ← 進入點：初始化、訊號監聽、graceful shutdown
+├── config/
+│   └── config.go           ← 讀取環境變數 (EMQX_ADDR, REDIS_ADDR 等)
+├── internal/
+│   ├── handler/
+│   │   ├── heartbeat_handler.go    ← 處理 machine/+/heartbeat
+│   │   ├── error_handler.go        ← 處理 machine/+/error
+│   │   └── transaction_handler.go  ← 處理 machine/+/transaction
+│   └── bridge/
+│       ├── redis_consumer.go       ← [下行] BLPOP mqtt_outgoing_commands，轉發至 EMQX
+│       └── redis_pusher.go         ← [上行] RPUSH mqtt_incoming_jobs
+```
+
+#### [上行邏輯] 機台 ➜ 雲端
+1. 訂閱 `machine/+/heartbeat`, `machine/+/error`, `machine/+/transaction`。
+2. 從 Topic 路徑提取 `serial_no`。
+3. 包裝成 `BridgePayload`：
+   ```json
+   {
+     "type": "heartbeat",
+     "serial_no": "M-001",
+     "payload": { "current_page": 1, "temperature": 25.5 },
+     "received_at": "2026-04-14T09:00:00+08:00"
+   }
+   ```
+4. 執行 `RPUSH mqtt_incoming_jobs {json}`。
+
+#### [下行邏輯] 雲端 ➜ 機台 (新增)
+1. Go Gateway 啟動一條 Goroutine，持續 `BLPOP mqtt_outgoing_commands`。
+2. 取得 JSON 後解析目標 `serial_no` 與 `command` 內容。
+3. Publish 至 `machine/{serial_no}/command` (QoS 1)。
+   ```json
+   {
+     "target": "M-001",
+     "command": "dispense",
+     "payload": { "slot_no": 5, "transaction_id": "T202604140001" },
+     "message_id": "MSG_123456789"
+   }
+   ```
+
+#### [NEW] mqtt-gateway/Dockerfile
+```dockerfile
+# Stage 1: Build
+FROM golang:1.23-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o gateway .
+
+# Stage 2: Run
+FROM alpine:3.20
+COPY --from=builder /app/gateway /usr/local/bin/gateway
+CMD ["gateway"]
+```
+
+---
+
+### 3. Laravel 端實作
+
+#### [NEW] app/Console/Commands/ListenMqttQueue.php
+- Artisan Command: `mqtt:listen`
+- 使用 `BLPOP mqtt_incoming_jobs` 阻塞式監聽
+- 根據 `type` 分派至對應的 Laravel Job：
+    - `heartbeat` ➜ `ProcessHeartbeatJob`
+    - `error` ➜ `ProcessMachineErrorJob`
+    - `transaction` ➜ `ProcessTransactionJob`
+
+#### [NEW] app/Services/Machine/MqttCommandService.php
+- 提供 `sendCommand(string $serialNo, string $command, array $payload)` 方法
+- 將指令 JSON 推入 Redis List `mqtt_outgoing_commands`
+- 供 Controller 呼叫（例如後台管理員按下「遠端出貨」按鈕）
+
+#### [NEW] app/Jobs/Machine/ (三個 Job)
+- `ProcessHeartbeatJob.php`: 更新 `last_heard_at`、溫度、頁面碼
+- `ProcessMachineErrorJob.php`: 寫入 `machine_logs`，觸發告警通知
+- `ProcessTransactionJob.php`: 更新庫存、建立交易紀錄
+
+#### [MODIFY] [MachineAuthController.php](file:///home/mama/projects/star-cloud/app/Http/Controllers/Api/V1/App/MachineAuthController.php)
+- 在 B014 核發 `api_token` 後，同步寫入 Redis：
+  `Redis::set("machine_auth:{$serial_no}", hash('sha256', $token));`
+- Token 更新/撤銷時，同步刪除 Redis 中的對應 Key
+
+---
+
+## Architecture Decisions (Confirmed)
+
+### ✅ EMQX 版本策略
+- **統一鎖定**：開發與正式環境皆使用 `emqx/emqx:5.10.3`（開源版最後一個穩定版本）。
+- **選擇理由**：EMQX 從 5.9.0 起合併為統一版本，6.x 改用 BSL 商業授權。`5.10.3` 是純開源 (Apache 2.0) 的最終穩定版，功能完整且免授權費用。
+
+### ✅ 下行指令安全性（無需額外 OTP）
+App 連線 MQTT 時已使用 `api_token` 作為密碼完成身份認證，因此 **MQTT 連線本身即為認證通道**。安全性由以下三層保障：
+1. **連線層**：App 使用 `serial_no` + `api_token` 連線 EMQX，未通過驗證的裝置無法訂閱任何 Topic。
+2. **ACL 層**：EMQX 存取控制確保只有 Go Gateway 能 Publish 到 `machine/{id}/command`，機台 App 無法偽造指令。
+3. **冪等性層**：每條下行指令的 Payload 包含唯一的 `message_id`，App 端應記錄已執行的 ID，防止重複執行同一條指令。
+
+> [!NOTE]
+> **結論**：上行用 Token 當密碼、下行用 ACL 當門禁、`message_id` 當防重複鎖。三層防護已足夠，不需要額外的 OTP 機制。
+
+---
+
+## Verification Plan
+
+### 1. 基礎設施驗證
+- 執行 `./vendor/bin/sail up -d`
+- 造訪 `http://localhost:18083` 確認 EMQX Dashboard 正常啟動
+- 確認 Go Gateway Container 的 logs 顯示 "Connected to EMQX" 與 "Connected to Redis"
+
+### 2. 上行通訊測試 (機台 ➜ 雲端)
+- 使用 MQTTX 工具連接 `localhost:1883`
+- 發送心跳 JSON 至 `machine/TEST-001/heartbeat`
+- 檢查 Laravel 日誌確認 `mqtt:listen` 成功接收並分派 Job
+- 檢查 MySQL `machines` 表的 `last_heard_at` 是否更新
+
+### 3. 下行通訊測試 (雲端 ➜ 機台)
+- 在 MQTTX 訂閱 `machine/TEST-001/command`
+- 透過 Laravel Tinker 呼叫 `MqttCommandService::sendCommand('TEST-001', 'reboot', [])`
+- 確認 MQTTX 收到 reboot 指令的 JSON
+
+### 4. 壓力測試
+- 使用 Go Script 模擬 500 台機台同時發送心跳
+- 監控 Redis List 長度與 Laravel Worker 的處理速率