From 4bf53db3beda9f485ddf43c0ffe0c8d6de339464 Mon Sep 17 00:00:00 2001
From: sky121113 <sky121113@gmail.com>
Date: Thu, 7 May 2026 10:16:29 +0800
Subject: [PATCH] =?UTF-8?q?[FIX]=20=E5=84=AA=E5=8C=96=E6=A9=9F=E5=8F=B0?=
 =?UTF-8?q?=E9=80=A3=E7=B7=9A=E8=A6=8F=E7=AF=84=E8=88=87=E4=B8=8A=E7=B7=9A?=
 =?UTF-8?q?=E6=97=A5=E8=AA=8C=E9=82=8F=E8=BC=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. 更新 SKILL.md 與 Java 範例，將 MQTT Client ID 格式由隨機後綴改為固定格式 SC_{serial_no}，以確保單機連線唯一性。
2. 同步更新 config/api-docs.php，在 API 文件中加入 MQTT 連線參數規範說明。
3. 修正 ProcessHeartbeat.php 邏輯，當機台狀態從 offline 轉為 online 時，自動寫入「Machine is online」日誌，完善連線紀錄回溯。
---
 .agents/skills/mqtt-communication-specs/SKILL.md |  4 ++--
 app/Jobs/Machine/ProcessHeartbeat.php            | 13 ++++++++++++-
 config/api-docs.php                              | 11 +++++++++++
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/.agents/skills/mqtt-communication-specs/SKILL.md b/.agents/skills/mqtt-communication-specs/SKILL.md
index fd495ae..e24c67c 100644
--- a/.agents/skills/mqtt-communication-specs/SKILL.md
+++ b/.agents/skills/mqtt-communication-specs/SKILL.md
@@ -26,7 +26,7 @@ description: 定義 Star Cloud 與終端機台 (IoT) 之間的 MQTT 全域通訊
 機台連線時必須提供以下憑據：
 - **Username**：機台編號 (`serial_no`)，例如 `SN00001`。
 - **Password**：機台 `api_token` 的 SHA256 雜湊值，由 B014 API 取得。
-- **Client ID**：格式建議為 **`SC_{serial_no}_{random_suffix}`**（加上隨機碼以確保連線唯一性，避免重複連線時互踢）。
+- **Client ID**：格式建議為 **`SC_{serial_no}`**（確保同一機台僅能有一個連線，新連線將踢除舊連線）。
 
 **EMQX 認證機制**：
 - **資料結構**：Redis Hash (`HSET`)。Key 格式為 `{prefix}machine_auth:{username}`，包含 `password` 欄位。
@@ -65,7 +65,7 @@ App (Android) 透過 **WSS** 穿越公網連線 Broker。路徑：`App → Cloud
 ```java
 Mqtt3Client client = MqttClient.builder()
     .useMqttVersion3()
-    .identifier("SC_" + machineID + "_" + randomSuffix)
+    .identifier("SC_" + machineID)
     .serverHost("mqtt.setdomains.work")
     .serverPort(443)
     .sslWithDefaultConfig()
diff --git a/app/Jobs/Machine/ProcessHeartbeat.php b/app/Jobs/Machine/ProcessHeartbeat.php
index c966624..cbe517d 100644
--- a/app/Jobs/Machine/ProcessHeartbeat.php
+++ b/app/Jobs/Machine/ProcessHeartbeat.php
@@ -48,9 +48,20 @@ class ProcessHeartbeat implements ShouldQueue
         // === 狀態異動觸發 (Redis 快取，讓 MQTT 也支援日誌) ===
         $cacheKey = "machine:{$this->serialNo}:state";
         $oldState = \Illuminate\Support\Facades\Cache::get($cacheKey);
+        // 1. 偵測狀態由離線轉在線 (寫入日誌)
+        if ($machine->status === 'offline') {
+            \App\Jobs\Machine\ProcessStateLog::dispatch(
+                $machine->id,
+                $machine->company_id,
+                "Machine is online",
+                'info',
+                []
+            );
+        }
+
         $newState = $oldState ?? [];
 
-        // 1. 韌體版本比對 (有改才傳，有改才記)
+        // 2. 韌體版本比對 (有改才傳，有改才記)
         if (isset($this->payload['firmware_version'])) {
             $fv = (string) $this->payload['firmware_version'];
             if (!isset($oldState['firmware_version']) || (string)$oldState['firmware_version'] !== $fv) {
diff --git a/config/api-docs.php b/config/api-docs.php
index cf6bc33..b823737 100644
--- a/config/api-docs.php
+++ b/config/api-docs.php
@@ -461,6 +461,17 @@ return [
         ],
     ],
 
+    'mqtt_connection_specs' => [
+        'description' => '機台連線 MQTT Broker 時的必要憑據。',
+        'specs' => [
+            'Host' => 'mqtt.setdomains.work',
+            'Port' => '443 (WSS / 公網) 或 1883 (TCP / 內部)',
+            'Username' => '機台序號 (serial_no)',
+            'Password' => 'API Token 的 SHA256 雜湊值 (由 B014 取得)',
+            'ClientID' => 'SC_{serial_no} (固定格式，確保單機唯一連線)',
+        ]
+    ],
+
     'mqtt_topics' => [
         [
             'name' => '指令與通訊 (Commands & Flow)',