# 5B config schema 程式 repo 結構檢查與實作前盤點

本文件承接 [5B config schema 邊界分析](phase-five-b-config-schema-boundary-analysis.md)、[5B config schema 實作前確認表](phase-five-b-config-schema-preimplementation-checklist.md) 與 [5B config schema 實作前確認線上驗收紀錄](phase-five-b-config-schema-preimplementation-online-acceptance-record.md)。

本文件以唯讀方式檢查程式 repo 目前的 config / plugin 結構、候選檔案、測試基準與停止線。使用者尚未確認 5B 七項前，不修改程式 repo。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已完成 |
| 建立日期 | 2026-06-07 |
| 對應節點 | 第五階段 5B config schema 程式 repo 唯讀結構檢查 |
| 程式 repo | `hs-device-control-template` |
| 本機檢查路徑 | `C:\Users\Evan\OneDrive - 鴻森智能科技有限公司\重要資料\hs-device-control-template` |
| 本機 branch | `poc/nmodbus-tcp` |
| 程式基準 | `bc3f191`，外部 DLL manual-only fake verifier |
| 文件 repo 基準 | `f2c9306`，5B config schema 線上驗收紀錄 |
| 工作樹 | 程式 repo 與文件 repo 皆乾淨 |
| 是否修改程式 repo | 否，只做唯讀盤點、測試與文件整理 |

## 1. 檢查結論

| 項目 | 結論 |
|---|---|
| 5B 承接位置 | 可承接在 `src/HS.DeviceControl.Core/Configuration/AppSettingsConfig.cs` 與 `ConfigValidator.cs`。 |
| 設定檔承接位置 | 建議維持 `samples/config/appsettings.json`，不新增第四個啟動設定檔。 |
| Loader 設定來源 | 目前 Application 層已有 `PluginLoaderOptions` 與 `ExternalDllManualVerifierOptions`，但尚未由 config 建立。 |
| 目前 plugin schema | `AppSettingsConfig` 尚無 `PluginLoader` / `Plugins` 欄位。 |
| 目前 validator | `ConfigValidator` 只驗證 Log / Debug / Watchdog 與設備 / workflow，尚未驗證 PluginLoader / Plugins。 |
| 目前 loader 讀檔 | `ConfigLoader` 只載入 `devices.json`、`workflows.json`、`appsettings.json`，5B 不需改讀檔清單。 |
| 現有 sample config | `appsettings.json` 只有 Log、Debug、Watchdog，尚未新增 plugin metadata 範例。 |
| 是否需改 Application public contract | 5B 不需要；若要改 `PluginLoaderOptions` constructor 或 public property，需另行確認。 |

## 2. 目前可承接能力

| 現有檔案 | 目前能力 | 5B 意義 |
|---|---|---|
| `AppSettingsConfig.cs` | 定義 `Log`、`Debug`、`Watchdog`。 | 可新增最小 `PluginLoader` / `Plugins` config model，但需等待七項確認。 |
| `ConfigValidator.cs` | 驗證 appsettings、devices、workflows。 | 可新增 plugin id、重複、safe default、source summary 安全驗證。 |
| `ConfigLoader.cs` | 載入三個既有設定檔並交給 validator。 | 建議不改讀檔清單，只擴充 appsettings 內容。 |
| `samples/config/appsettings.json` | 目前為舊格式 sample。 | 可加入非敏感 metadata-only 範例，並保留舊設定相容性。 |
| `ConfigValidatorTests.cs` | 已覆蓋 appsettings 與 sample config 成功 / 失敗情境。 | 可加入 5B 欄位合法、缺欄位、重複、敏感資訊拒絕測試。 |
| `ConfigLoaderTests.cs` | 已覆蓋 sample 載入、缺檔、JSON 錯誤、validation 失敗。 | 可加入新 sample 與舊 appsettings 相容性測試。 |
| `PluginLoaderOptions.cs` | 定義 expected contract version、checksum、disabled review。 | 可由 config 映射，但 5B 第一版可先只落 config model / validator。 |
| `ExternalDllManualVerifierOptions.cs` | manual external verification 預設關閉。 | 5B 若新增欄位，也必須維持預設關閉。 |

## 3. 候選新增 / 修改檔案

以下是確認後的候選範圍；本文件不授權直接實作。

| 類型 | 候選檔案 | 建議 |
|---|---|---|
| Config model | `src/HS.DeviceControl.Core/Configuration/AppSettingsConfig.cs` | 新增 `PluginLoaderSettingsConfig`、`PluginConfig`、`PluginCapabilityConfig` 類型。 |
| Config validation | `src/HS.DeviceControl.Core/Configuration/ConfigValidator.cs` | 新增 `ValidatePluginLoaderSettings` 與 `ValidatePluginDefinitions` 類似 private helper。 |
| Sample config | `samples/config/appsettings.json` | 加入非敏感 metadata-only sample，不放真實路徑、密碼、正式 IP 或 port。 |
| Config docs | `docs/config-schema.md` 與 HTML / public 鏡像 | 同步欄位與驗證規則。 |
| Core tests | `tests/HS.DeviceControl.Core.Tests/ConfigValidatorTests.cs` | 加測合法 plugin config、重複 plugin id、unsafe source summary。 |
| Core loader tests | `tests/HS.DeviceControl.Core.Tests/ConfigLoaderTests.cs` | 加測 sample 載入與舊 appsettings 相容。 |

## 4. 不建議在 5B 修改的檔案

| 檔案 / 範圍 | 原因 |
|---|---|
| `PluginLoaderOptions.cs` public constructor / property | 屬 Application public contract；若必須修改，需停下確認。 |
| `ExternalDllManualVerifierOptions.cs` public constructor / property | 涉及外部 DLL gate；若必須修改，需停下確認。 |
| `WebApi` 專案 | auth / Swagger 留 5D。 |
| `ServiceHost` 專案 | Windows Service / Service lifecycle 留 5E。 |
| `Infrastructure.MySql` | DB audit / DDL 留 5C。 |
| Adapter 專案 | Adapter public contract 不屬 5B。 |

## 5. 已執行唯讀檢查

| 檢查 | 指令 / 方式 | 結果 |
|---|---|---|
| 文件 repo 狀態 | `git status --short --branch` | `main...origin/main`，乾淨。 |
| 程式 repo 狀態 | `git status --short --branch` | `poc/nmodbus-tcp...origin/poc/nmodbus-tcp`，乾淨。 |
| 程式 repo 基準 | `git rev-parse --short HEAD` | `bc3f191`。 |
| AppSettings 結構 | 讀取 `AppSettingsConfig.cs` | 目前只有 `Log`、`Debug`、`Watchdog`。 |
| ConfigLoader 結構 | 讀取 `ConfigLoader.cs` | 只載入三個既有 config 檔，不需新增讀檔入口。 |
| sample config | 讀取 `samples/config/appsettings.json` | 尚未包含 plugin / loader schema。 |
| Application options | 讀取 `PluginLoaderOptions.cs`、`ExternalDllManualVerifierOptions.cs` | 已有 metadata / manual gate options，預設仍保守。 |
| 候選檔 plugin schema 掃描 | `rg PluginLoader|Plugins|AllowManualExternalDllVerification...` 於候選 config 檔 | 無命中，確認目前尚未落地 5B schema。 |
| 候選檔停止線掃描 | `rg Assembly.Load|LoadFrom|LoadFile|AssemblyLoadContext|.dll|plugin folder|DB DDL|ALTER TABLE|Swagger|Windows Service...` 於候選 config 檔 | 無新增 5B 風險命中；只命中既有 `ConfigLoader` 名稱。 |

## 6. 測試基準

| 測試 | 結果 |
|---|---|
| `dotnet test tests\HS.DeviceControl.Core.Tests\HS.DeviceControl.Core.Tests.csproj --no-restore` | 189 passed / 0 failed / 0 skipped |
| `dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj --no-restore` | 57 passed / 0 failed / 0 skipped |
| `dotnet test HS.DeviceControl.sln --no-restore` | 509 passed / 0 failed / 0 skipped |

補充：第一次在 sandbox 內執行測試時被 `obj` cache 寫入權限擋下；提升執行後通過。solution tests 仍出現既有 `.NET 5.0` EOL warning，非 5B 文件節點造成。

## 7. 實作前測試建議

使用者確認七項後，5B 最小實作建議至少新增或補強以下測試：

| 測試項目 | 建議驗證 |
|---|---|
| 舊 appsettings 相容 | 不含 `PluginLoader` / `Plugins` 的 appsettings 仍通過。 |
| 合法 plugin config | metadata-only plugin 設定可通過 validator。 |
| 重複 plugin id | 同一 config 中重複 `PluginId` 必須失敗。 |
| unsafe source summary | 疑似完整路徑、密碼、token、connection string 或正式連線資訊必須失敗。 |
| safe default | 未明確設定時 manual external verification 與 disabled review 不得自動開啟。 |
| 不改讀檔清單 | `ConfigLoader` 仍只需三個既有 config 檔。 |

## 8. 明確停止線

| 停止線 | 說明 |
|---|---|
| 不載入外部 DLL | 5B 只處理 config schema，不呼叫 assembly loading API。 |
| 不掃描 plugin folder | 第一版不新增 plugin folder path 或自動掃描。 |
| 不保存敏感資訊 | 不保存 secret、token、connection string、正式 IP、正式 port 或正式帳號。 |
| 不改 Application public contract | 不改 `PluginLoaderOptions` / `ExternalDllManualVerifierOptions` public 簽章。 |
| 不做 DB audit / DDL | DB audit table 與 DDL 留到 5C。 |
| 不做 auth / Swagger | WebApi 安全模型留到 5D。 |
| 不做 Windows Service | Windows Service 留到 5E。 |

## 9. 下一步

5B 程式 repo 唯讀結構檢查與基準測試已完成。下一步仍需等待使用者回覆 [5B config schema 實作前確認表](phase-five-b-config-schema-preimplementation-checklist.md) 七項同意，才能進入程式 repo 的最小 config schema 實作。