[DOCS] 更新 MQTT 即時通訊規範，新增 App 端 WSS 連線標準

1. 補齊各連線通道 (TCP/SSL/WS/WSS) 的埠號建議表。
2. 新增 App 端 (Android) WSS 連線專節，包含 URL 參數與密碼雜湊要點。
3. 提供 HiveMQ Client 初始化範例程式碼。
4. 定義 MQTT 優先、HTTP 兜底的 Fallback 通訊機制與時間窗口。

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

@@ -11,9 +11,17 @@ description: 定義 Star Cloud 與終端機台 (IoT) 之間的 MQTT 全域通訊
 
 ### 1.1 Broker 資訊
 - **協議版本**：MQTT v3.1.1 (相容性最高)
-- **預設埠號**：1883 (TCP / 測試用), 8883 (SSL/TLS / 正式用)
 - **Keep-Alive**：建議設定為 30 ~ 60 秒。
 
+**各連線通道埠號：**
+
+| 通道 | 埠號 | 用途 | 使用者 |
+| :--- | :--- | :--- | :--- |
+| TCP | 1883 | Docker 內部 / 區網測試 | Go Gateway、開發除錯 |
+| SSL/TLS | 8883 | 加密 TCP (正式環境) | Go Gateway (選配) |
+| WebSocket | 8083 | EMQX 原生 WS 監聽 | NPM 反向代理目標 |
+| **WSS (公網)** | **443** | App 端透過 NPM 反代連線 | **Android / iOS App** |
+
 ### 1.2 身份認證 (Authentication)
 機台連線時必須提供以下憑據：
 - **Username**：機台編號 (`serial_no`)，例如 `SN00001`。
@@ -35,6 +43,48 @@ description: 定義 Star Cloud 與終端機台 (IoT) 之間的 MQTT 全域通訊
 
 ---
 
+## 1-A. App 端 WSS 連線規範 (WebSocket Secure)
+
+App (Android) 透過 **WSS** 穿越公網連線 Broker。路徑：`App → Cloudflare → NPM (port 8083 反代) → EMQX`。
+
+### 連線參數
+
+| 參數 | 值 |
+| :--- | :--- |
+| **URL** | `wss://mqtt.setdomains.work:443/mqtt` |
+| **Username** | `{machineID}` (即 `serial_no`) |
+| **Password** | `{api_token}` 原始值（B014 取得，**不做 SHA256**） |
+| **Client ID** | `SC_{machineID}_{random}` |
+| **Clean Session** | `true` |
+
+> [!CAUTION]
+> App 傳入原始 Token，EMQX 端的 `password_hash_algorithm` 須設為 `sha256`，由 Broker 自動雜湊比對 Redis 中的值。
+
+### Android 範例 (HiveMQ)
+
+```java
+Mqtt3Client client = MqttClient.builder()
+    .useMqttVersion3()
+    .identifier("SC_" + machineID + "_" + randomSuffix)
+    .serverHost("mqtt.setdomains.work")
+    .serverPort(443)
+    .sslWithDefaultConfig()
+    .webSocketConfig().serverPath("/mqtt").applyWebSocketConfig()
+    .simpleAuth().username(machineID).password(apiToken.getBytes()).applySimpleAuth()
+    .willPublish()
+        .topic("machine/" + machineID + "/heartbeat")
+        .payload("{\"status\":\"offline\"}".getBytes())
+        .applyWillPublish()
+    .buildBlocking();
+```
+
+### Fallback 策略
+- **指數退避重連**：1s → 2s → 4s → ... → 最大 60s。
+- WSS 斷線超過 **3 分鐘** → 退回 HTTP 輪詢 (B010)，背景每 60 秒嘗試重連 WSS。
+- WSS 恢復 → 立即切回 MQTT，停止 HTTP 輪詢。
+
+---
+
 ## 2. 主題架構 (Topic Topology)
 
 我們採用目錄式的層級結構，方便未來進行萬台設備的管理與 ACL 權限切分。
@@ -106,6 +156,9 @@ description: 定義 Star Cloud 與終端機台 (IoT) 之間的 MQTT 全域通訊
    - **QoS 1**：適用於交易與指令，確保「至少送達一次」。App 端收到指令後應回覆回執。
 3. **遺囑訊息 (Last Will and Testament)**：
    機台 Connect 時應設定 Last Will 於 `machine/{serial_no}/heartbeat`，Payload 為 `{"status": "offline"}`。當連線異常中斷時，雲端能立刻得知。
+4. **傳輸加密**：
+   - **App 端 (公網)**：強制使用 WSS (`wss://`)，TLS 由 NPM / Cloudflare 終止。
+   - **Go Gateway (內網)**：預設走 TCP (`tcp://emqx:1883`)，區網環境可免 TLS。正式環境建議升級至 `ssl://emqx:8883`。
 
 ---
 
@@ -137,7 +190,15 @@ Laravel `mqtt:listen` 使用 `BLPOP` 長時間阻塞等待。為防止 PHP 端
 ---
 
 ## 6. 與 REST API 的同步關係
-當 MQTT 通訊正常時，機台應停止定時呼叫 B010 HTTP API。若 MQTT 斷線超過 3 分鐘，則退回 (Fallback) 使用 HTTP 輪詢模式以維持基礎通訊。
+
+App 端的通訊策略為 **MQTT 優先、HTTP 兜底**：
+
+| 狀態 | 心跳 | 指令接收 | 交易回報 |
+| :--- | :--- | :--- | :--- |
+| WSS 連線正常 | MQTT 發布 (10s) | MQTT 訂閱 | MQTT 發布 |
+| WSS 斷線 < 3 分鐘 | 暫停，等待重連 | 不可用 | 暫存本地，重連後補發 |
+| WSS 斷線 ≥ 3 分鐘 | HTTP B010 輪詢 | 不可用 (降級) | HTTP B600 回報 |
+| WSS 恢復 | 切回 MQTT | 恢復 MQTT 訂閱 | 切回 MQTT |
 
 ---