[FIX] 優化機台連線規範與上線日誌邏輯

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

@@ -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()

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) {

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)',