Config Schema

本文件說明第一階段 devices.json 與 appsettings.json 的設定格式與驗證規則。

正式程式碼範例位於程式 repo：

samples/config/

devices.json

{
  "Devices": [
    {
      "DeviceId": "LED_001",
      "DeviceName": "燈號導引模組",
      "DeviceType": "Light",
      "ConnectionType": "Mock",
      "IpAddress": "",
      "Port": 0,
      "ComPort": "",
      "TimeoutMs": 3000,
      "Enabled": true,
      "Commands": [
        {
          "CommandName": "LightOn",
          "Description": "開啟燈號"
        }
      ]
    }
  ]
}

devices.json 驗證規則

• Devices 必須至少包含一台設備。
• DeviceId 必填，且不可重複。
• DeviceName 必填。
• DeviceType 必填。
• ConnectionType 必填。
• 第一階段 ConnectionType 僅支援 Mock。
• TimeoutMs 必須大於 0。
• 每台設備必須至少包含一個 Commands。
• 同一台設備內 CommandName 必填且不可重複。

appsettings.json

{
  "Log": {
    "Path": "logs",
    "Level": "Debug",
    "KeepDays": 30
  },
  "Debug": {
    "Enabled": true,
    "UseMockDevice": true
  },
  "Watchdog": {
    "Enabled": true,
    "TimeoutMs": 10000
  }
}

appsettings.json 驗證規則

• appsettings.json 不可為空。
• Log.Path 必填。
• Log.Level 必填。
• Log.KeepDays 必須大於 0。
• Watchdog.TimeoutMs 若有設定，必須大於 0。

目前實作狀態

Config Loader 行為

ConfigLoader.LoadFromDirectory(...) 會從指定資料夾載入以下三個檔案：

• devices.json
• workflows.json
• appsettings.json

載入成功後，會立即交由 ConfigValidator 驗證。若資料夾不存在、必要檔案缺少、JSON 格式錯誤或設定內容不合法，會回傳 ConfigLoadResult.Success = false，並在 Errors 中保留 CFG-0001 與可讀錯誤訊息。

目前 Loader 只負責載入與驗證設定物件，WorkflowConfigurationMapper 負責把 WorkflowConfiguration 轉成可執行的 WorkflowDefinition。

Config Mapper 行為

WorkflowConfigurationMapper 提供以下轉換方式：

• MapById(...)：依 WorkflowId 轉換指定 Workflow。
• MapFirst(...)：轉換第一筆 Workflow，適合第一階段只有一個代表流程時使用。
• Map(...)：轉換單一 WorkflowConfig。

Mapper 會將設定節點轉成 WorkflowNode，目前會使用 NodeId、NodeName、ExecuteCommand、SuccessNextNodeId、TimeoutMs、RetryCount。轉換完成後會呼叫 WorkflowDefinition.Validate()，確認結果可交給 WorkflowEngine 執行。

目前 DeviceId 已由 ConfigValidator 檢查存在與命令對應，但第一階段的 WorkflowDefinition 尚未保存 DeviceId；後續若要支援多設備命令分派，建議再擴充 Workflow 執行模型或 Command Executor。

ConsoleHost 設定檔啟動

ConsoleHost 目前已改為從 samples/config 載入代表流程，預設執行鏈路如下：

ConfigLoader -> ConfigValidator -> WorkflowConfigurationMapper -> WorkflowEngine

預設執行：

dotnet run --project src/HS.DeviceControl.ConsoleHost

指定設定資料夾與 WorkflowId：

dotnet run --project src/HS.DeviceControl.ConsoleHost -- samples/config LIGHT_SENSOR_DEMO

第一階段仍使用 MockDeviceAdapter，ConsoleHost 會依 devices.json 中啟用設備的命令自動建立 Mock 成功結果，用於驗證設定檔流程可完整跑通。