4D PluginLoader 程式 repo 結構檢查表

返回

4D PluginLoader 程式 repo 結構檢查表

本文件記錄 2026-06-06 進入第四階段 4D PluginLoader 最小 contract 實作前，對程式 repo hs-device-control-template 的唯讀結構檢查、可承接範圍、候選修改檔案與停止線確認。

本檢查承接 4D PluginLoader 邊界分析、4D PluginLoader 決策確認表 與 4D PluginLoader contract 草案 / 實作前確認表。檢查結果只代表可在 Application 層評估最小 metadata / verification / state / audit contract，不代表授權建立 Loader、建立 IPluginLoader public contract、掃描 plugin folder、載入外部 DLL、執行外部程式碼、修改 Adapter public contract、修改 config schema 或接真實硬體。

0. 檢查狀態

項目內容
文件狀態已完成
檢查日期2026-06-06
對應階段第四階段 4D PluginLoader
程式 repohs-device-control-template
本機路徑C:\Users\Evan\OneDrive - 鴻森智能科技有限公司\重要資料\hs-device-control-template
程式 branchpoc/nmodbus-tcp
程式基準 commita8462121ca0e62d4d4c4396497c564bc1540a339
工作樹乾淨，無待提交變更
前置確認使用者已確認 4D contract 七項決策
檢查結論可在既有 HS.DeviceControl.Application/Plugins 補最小 contract 與測試，不需新增專案或修改 solution

1. 檢查方法

檢查項目實際結果
git status --short --branch位於 poc/nmodbus-tcp...origin/poc/nmodbus-tcp，工作樹乾淨
git rev-parse HEADa8462121ca0e62d4d4c4396497c564bc1540a339
Solution 盤點HS.DeviceControl.Application、HS.DeviceControl.Application.Tests、HS.DeviceControl.ServiceHost、HS.DeviceControl.WebApi 均已在 solution 內
Plugin 關鍵字掃描未找到 IPluginLoader、PluginLoader、Assembly.Load、LoadFrom、LoadFile
Application plugin 檔案讀取已確認 PluginDescriptor、PluginCapabilityDescriptor、PluginCatalogService、PluginCatalogResult、IPluginCatalogService
ServiceHost 讀取已確認 ServiceHostRuntime 只做 start / stop / status / QueueTask，不含 PluginLoader
Adapter 邊界讀取已確認 IDeviceAdapter、DeviceAdapterDispatcher、ExecuteResult 既有 contract 可維持不變
Config schema 讀取devices.json、workflows.json、appsettings.json 沒有 plugin path、plugin folder 或 DLL path 欄位
測試盤點已有 PluginCatalogServiceTests，尚未有 verification / state / audit tests

2. 現有可承接結構

區域現況對 4D 的判定
HS.DeviceControl.Application已存在並只參考 Core / Adapters可承接 4D 第一版 contract，不新增專案
Application.Plugins已有 metadata catalog 第一版可在同資料夾補 verification / state / audit
Application.Tests已有 plugin catalog 單元測試可補 4D contract 測試
ServiceHost已有 lifecycle runtime 與 tests4D 可保留 ServiceHost lifecycle 邊界，但本輪不改 ServiceHost
Adapters已有 IDeviceAdapter、Dispatcher、Mock、Modbus4D 第一版不改 Adapter public contract
Config仍以 devices / workflows / appsettings 為主4D 第一版不新增 plugin schema
WebApi4B 第一版已存在4D 不新增 route、controller 或 HTTP plugin 管理 API

3. Application.Plugins 目前狀態

檔案現況缺口
PluginDescriptor.cs已有 PluginId、Version、DisplayName、Capabilities、Checksum，註解明確不含 DLL 載入或執行資訊尚缺 ContractVersion、Source、Enabled、DisabledReason 等 4D contract 欄位候選
PluginCapabilityDescriptor.cs已有 CapabilityId、DeviceType、CommandName、AdapterContractVersion可沿用，不需改 Adapter contract
PluginCatalogService.cs已檢查必填欄位與 sensitive marker，回傳標準 PluginCatalogResult尚未有 verification result、state 或 audit record
PluginCatalogResult.cs已有 Success、Code、Message、Error可作為 result 風格參考
IPluginCatalogService.cs只提供 ListPlugins()，註解明確不負責載入 DLL 或執行 Plugin不建議改成 Loader contract
PluginCatalogServiceTests.cs已覆蓋 metadata 不載入 DLL、缺少 PluginId、敏感資訊、缺少 capability可延伸 verification / audit 測試

4. 明確尚未存在的候選檔案

檔案目前狀態判定
src/HS.DeviceControl.Application/Plugins/PluginVerificationResult.cs不存在可作為 4D 最小 contract 新增候選
src/HS.DeviceControl.Application/Plugins/PluginLoadState.cs不存在可作為 4D state contract 新增候選
src/HS.DeviceControl.Application/Plugins/PluginAuditRecord.cs不存在可作為 audit summary contract 新增候選
src/HS.DeviceControl.Application/Plugins/IPluginLoader.cs不存在符合停止線，不應新增
src/HS.DeviceControl.Application/Plugins/PluginLoader.cs不存在符合停止線，不應新增
tests/HS.DeviceControl.Application.Tests/PluginVerificationResultTests.cs不存在可新增單元測試候選
tests/HS.DeviceControl.Application.Tests/PluginAuditRecordTests.cs不存在可新增單元測試候選

5. ServiceHost / Adapter / Config 邊界

邊界檢查結果本輪判定
ServiceHost lifecycleServiceHostRuntime 已處理 start / stop / status / QueueTask，啟動時連接 Adapter 並查 health4D 可不改 ServiceHost；未來 Loader lifecycle 需另行確認
Adapter dispatcherDeviceAdapterDispatcher 依 DeviceCommand.DeviceId 分派，支援 connect / disconnect / status / execute不修改 IDeviceAdapter、ExecuteResult、DeviceCommand
Config schemadevices.json 與 workflows.json 仍以 DeviceId / CommandName 為核心；appsettings.json 無 plugin 區塊不新增 plugin folder、DLL path、來源白名單設定
WebApi既有 WebApi controller 不含 plugin route不新增 plugin HTTP API
External DLL關鍵字未命中 Assembly.Load、LoadFrom、LoadFile不載入外部 DLL，保持文件停止線

6. 若進入最小 contract 實作的候選範圍

以下只是候選清單，不代表本文件已修改程式 repo。

類型候選檔案建議內容
新增 state enumsrc/HS.DeviceControl.Application/Plugins/PluginLoadState.cs定義 Discovered、Verified、Rejected、Disabled、Faulted；Loaded 若保留，需標示為未授權載入狀態
新增 verification resultsrc/HS.DeviceControl.Application/Plugins/PluginVerificationResult.cs回傳 Success、Code、Message、PluginId、State、Checks、Warnings、TimeTakenMs
新增 audit recordsrc/HS.DeviceControl.Application/Plugins/PluginAuditRecord.cs記錄 AuditId、PluginId、Decision、Reason、Operator、Source、Checksum、CreatedAtUtc
視需要新增 check itemsrc/HS.DeviceControl.Application/Plugins/PluginVerificationCheck.cs若 Checks 需結構化，定義檢查名稱、成功狀態、摘要訊息
擴充 metadatasrc/HS.DeviceControl.Application/Plugins/PluginDescriptor.cs以相容方式補 ContractVersion、Source、Enabled、DisabledReason
擴充驗證src/HS.DeviceControl.Application/Plugins/PluginCatalogService.cs補 source / contract version / disabled metadata 驗證，仍不讀檔
補錯誤碼src/HS.DeviceControl.Application/Common/ApplicationErrorCodes.cs保留 APP-033x 區段，例如 verification / disabled / audit invalid
新增測試tests/HS.DeviceControl.Application.Tests/*覆蓋 required fields、sensitive data、checksum mismatch、version mismatch、disabled、audit sanitization

7. 明確不修改

不修改項目原因
HS.DeviceControl.slnSDK-style project 會自動納入新 .cs 檔；不新增專案
HS.DeviceControl.Core public contract4D 最小 contract 屬 Application 層 metadata / audit，不進 Core
HS.DeviceControl.Adapters public contract不改 IDeviceAdapter、ExecuteResult、DeviceCommand
HS.DeviceControl.ServiceHost不建立 Loader lifecycle，不改啟動方式
HS.DeviceControl.WebApi不新增 plugin route、controller、DTO 或 auth
devices.json、workflows.json、appsettings.json不新增 plugin schema、DLL path、正式來源或敏感資訊
Infrastructure.MySql不寫 DB、不建 audit table、不做 DDL / ALTER TABLE
外部 DLL / plugin folder不掃描、不載入、不執行

8. 建議驗收條件

驗收項目通過基準
Application plugin contract 編譯新增 / 修改的 Application plugin contract 可 build
Application plugin testsPluginCatalogServiceTests 延伸與新增 verification / audit tests 通過
停止線測試測試不呼叫 Assembly.Load、LoadFrom、LoadFile，不依賴 DLL file
Config 不變不修改 sample config 與 config model schema
Adapter 不變不修改 Adapter public contract 與 dispatcher 行為
回歸測試dotnet test tests/HS.DeviceControl.Application.Tests/HS.DeviceControl.Application.Tests.csproj 通過；必要時再跑 full solution

9. 結論

程式 repo 結構允許 4D 進入「最小 Application plugin contract」實作評估。建議第一版只補 Application.Plugins 的 metadata / verification / state / audit model 與 Application.Tests，不新增 Loader、不新增 IPluginLoader、不掃描 plugin folder、不載入外部 DLL、不改 Adapter public contract、不改 config schema。

建議下一步：進入 4D 最小 contract 程式實作前最後確認，確認候選檔案與測試策略後，再決定是否修改程式 repo。