5A PluginLoader 程式 repo 結構檢查與實作前盤點

返回

5A PluginLoader 程式 repo 結構檢查與實作前盤點

本文件承接 5A PluginLoader 實作前確認表 與 第五階段 Loader 到 Service 後續文件 / 實作 / 驗收範圍補齊表。

使用者已確認 5A 七項決策；本文件完成程式 repo 唯讀結構檢查，固定最小 PluginLoader 的候選檔案、測試命令、可承接能力與停止線。本文件仍不是程式實作授權，下一步需先整理「5A 最小 PluginLoader 實作前最後確認」。

0. 文件狀態

項目內容
文件狀態已完成
建立日期2026-06-07
對應節點5A PluginLoader 程式 repo 唯讀結構檢查
程式 repohs-device-control-template
本機 branchpoc/nmodbus-tcp
本機 commit6f34bb9，4D 最小 Application plugin contract
遠端 maina8b522b，main 已合併 poc/nmodbus-tcp
工作樹乾淨
是否修改程式 repo否，只做唯讀盤點與測試基準驗證

1. 檢查結論

項目結論
5A 承接位置可承接在 src/HS.DeviceControl.Application/Plugins。
測試承接位置可承接在 tests/HS.DeviceControl.Application.Tests。
是否需新增專案不需要，Application 與 Application.Tests 已在 solution。
是否已有 IPluginLoader尚未存在，可作為 5A 候選新增 public contract。
是否已有真正 Loader尚未存在；目前只有 metadata catalog / verification / audit contract。
是否已有外部 DLL 載入未發現 Assembly.Load、LoadFrom、LoadFile 或 AssemblyLoadContext。
是否需改 config schema5A 不需要；samples/config/appsettings.json 目前沒有 plugin / loader 設定。
是否需改 DB / WebApi / ServiceHost5A 不需要；DB audit、auth / Swagger、Windows Service 仍留到 5C / 5D / 5E。

2. 現有可承接能力

現有檔案目前能力5A 意義
PluginDescriptor.cs定義 plugin metadata、checksum、contract version、source、enabled / disabled。可作為 Loader request 的輸入來源，不需改成 DLL path。
IPluginCatalogService.cs / PluginCatalogService.cs列出並驗證 metadata catalog。5A Loader 可依 catalog result 選擇 plugin，不需掃描資料夾。
PluginVerificationResult.cs表示 metadata verification 結果與安全摘要。5A 可把 Loader 的 metadata checks 回填到 verification result。
PluginLoadState.cs已有 Discovered、Verified、Rejected、Disabled、Faulted，並預留 Loaded。5A 第一版仍建議不產生真正 Loaded。
PluginAuditRecord.cs表示 audit 安全摘要，但不寫 DB。5A 可產生 audit summary，DB 寫入留 5C。
ApplicationErrorCodes.cs已有 APP-0331 到 APP-0335 plugin 相關錯誤碼。若 5A 需要 Loader 專屬錯誤碼，需在最後確認表列出。

3. 候選新增檔案

類型候選檔案說明
Loader interfacesrc/HS.DeviceControl.Application/Plugins/IPluginLoader.cs最小 public contract；不得包含外部 DLL 載入或 assembly API。
Load requestsrc/HS.DeviceControl.Application/Plugins/PluginLoadRequest.cs建議只包含 PluginId、expected contract version、operator / request source 等安全摘要。
Load resultsrc/HS.DeviceControl.Application/Plugins/PluginLoadResult.cs建議回傳 success、plugin id、state、checks、warnings、code、message、error、time taken。
Loader optionssrc/HS.DeviceControl.Application/Plugins/PluginLoaderOptions.cs建議只放 expected contract version、是否允許 disabled 等非敏感設定；不放 path / secret。
Loader servicesrc/HS.DeviceControl.Application/Plugins/PluginLoaderService.cs以 IPluginCatalogService 的 metadata 做選擇與驗證；不得掃描 folder 或載入 DLL。
Teststests/HS.DeviceControl.Application.Tests/PluginLoaderServiceTests.cs驗證成功、缺 metadata、disabled、version mismatch、checksum mismatch、unsafe source 與停止線。

4. 候選修改檔案

檔案候選修改注意事項
ApplicationErrorCodes.cs視需要新增 Loader 專屬錯誤碼，例如 loader request invalid / plugin not found / contract mismatch。屬 public constant 變更，需在 5A 最後確認表明列。
PluginLoadState.cs原則上不修改；第一版建議仍不產生真正 Loaded。若要改狀態語意，必須停下確認。
PluginCatalogService.cs原則上不修改；Loader 可使用既有 catalog result。若要改 catalog validation，需避免破壞 4D contract。

5. 已執行檢查

檢查指令 / 方式結果
程式 repo remotegit remote -vorigin 指向 GitHub 程式 repo。
本機工作樹git status --short --branchpoc/nmodbus-tcp...origin/poc/nmodbus-tcp，無未提交變更。
遠端基準git ls-remote origin main poc/nmodbus-tcpmain=a8b522b，poc/nmodbus-tcp=6f34bb9。
DLL 停止線rg "Assembly\.Load|LoadFrom|LoadFile|AssemblyLoadContext|\.dll"未命中 production code；只在既有測試中用 mock path 驗證 unsafe source。
config schema讀取 sample config 與 ConfigValidator目前沒有 plugin / loader schema；5A 不需修改。
Application testsdotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj --no-restore40 passed，0 failed，0 skipped。

6. 明確停止線

5A 不載入外部 DLL、不掃描 plugin folder、不改 config schema、不建 DB audit table、不改 WebApi auth / Swagger、不建立 Windows Service、不接真實硬體或案場 plugin。

7. 建議下一步

本次唯讀結構檢查已確認 5A 可在 Application 層安全承接。建議下一步建立「5A 最小 PluginLoader 實作前最後確認表」，逐項確認新增 IPluginLoader、request / result / options / service、Loader 專屬 error codes、狀態語意、測試範圍與 stage / commit 前確認。