4D 最小 Application plugin contract 實作與驗收紀錄
本文件承接 4D 最小 Application plugin contract 實作前最後確認表，記錄 4D 最小 Application plugin contract 的程式實作範圍、測試結果與停止線。
本次完成不代表真正 PluginLoader 已完成，不代表建立 IPluginLoader，不代表掃描 plugin folder、載入外部 DLL、執行外部 plugin 程式碼、修改 Adapter public contract、修改 config schema、執行 DB DDL 或接真實硬體。
0. 驗收狀態
| 項目 | 內容 |
| 文件狀態 | 已完成 |
| 整理日期 | 2026-06-06 |
| 對應階段 | 第四階段 4D 最小 Application plugin contract |
| 程式 repo | hs-device-control-template |
| 程式 branch | poc/nmodbus-tcp |
| 前一程式基準 commit | a846212 新增 4C ServiceHost 第一版與驗收測試 |
| 4D 程式 commit | 6f34bb9 新增 4D 最小 Application plugin contract |
| push 狀態 | 已 push 至 origin/poc/nmodbus-tcp |
| GitHub Actions | Run 27064992270 success |
| 使用者確認 | 4D 最小 contract 確認 七項皆同意 |
| 本次定位 | Application 層 plugin metadata / verification / state / audit 最小 contract |
| 本次驗收結論 | 通過；Application.Tests 40 passed，solution tests 492 passed，程式 repo commit / push / Actions success |
1. 程式實作範圍
| 類型 | 檔案 | 說明 |
| 新增 state enum | src/HS.DeviceControl.Application/Plugins/PluginLoadState.cs | 定義 Discovered、Verified、Rejected、Disabled、Faulted、Loaded；Loaded 僅保留未來語意，第一版不產生。 |
| 新增 verification check | src/HS.DeviceControl.Application/Plugins/PluginVerificationCheck.cs | 定義單一檢查項目的 Name、Success、Code、Message。 |
| 新增 verification result | src/HS.DeviceControl.Application/Plugins/PluginVerificationResult.cs | 定義 Success、Code、Message、PluginId、State、Checks、Warnings、TimeTakenMs、Error。 |
| 新增 audit record | src/HS.DeviceControl.Application/Plugins/PluginAuditRecord.cs | 定義 AuditId、PluginId、Decision、Reason、Operator、Source、Checksum、CreatedAtUtc。 |
| 新增內部安全 helper | src/HS.DeviceControl.Application/Plugins/PluginContractTextSafety.cs | 只供 Application plugin contract 內部判斷 sensitive marker 與疑似正式路徑，不是 public Loader contract。 |
| 擴充 descriptor | src/HS.DeviceControl.Application/Plugins/PluginDescriptor.cs | 相容擴充 ContractVersion、Source、Enabled、DisabledReason，既有 constructor 仍保留。 |
| 擴充 catalog validation | src/HS.DeviceControl.Application/Plugins/PluginCatalogService.cs | 補 contract version、source、disabled reason 與 sensitive metadata 驗證；仍不讀檔、不掃描 folder。 |
| 擴充錯誤碼 | src/HS.DeviceControl.Application/Common/ApplicationErrorCodes.cs | 新增 APP-0332 至 APP-0335。 |
| 新增與擴充測試 | tests/HS.DeviceControl.Application.Tests/* | 補 verification result、audit record、catalog contract version/source/disabled 驗證。 |
2. Contract 行為
| Contract | 行為 |
PluginLoadState | 成功驗證只回 Verified；Loaded 只保留未來語意。 |
PluginVerificationResult.Ok | 回 Success=true、Code=NONE、State=Verified，可承接 checks / warnings / timeTakenMs。 |
PluginVerificationResult.Fail | 回 Success=false，若外部傳入 Loaded 會降為 Rejected，避免第一版產生載入狀態。 |
PluginVerificationCheck | message 會做敏感資訊與路徑遮罩。 |
PluginAuditRecord | 不寫 DB，會遮罩 token / password / connection string / 正式路徑。 |
PluginDescriptor | metadata 加上 contract version、source、enabled、disabled reason；啟用不代表可載入 DLL。 |
PluginCatalogService | 只驗 metadata，不建立 Loader，不讀取 DLL，不掃描 plugin folder。 |
3. 驗證紀錄
| 驗證項目 | 指令 / 方法 | 結果 |
| Application tests 初次執行 | dotnet test tests/HS.DeviceControl.Application.Tests/HS.DeviceControl.Application.Tests.csproj | 第一次因 NuGet AppData lock 無法取得鎖定而中止，不是測試失敗。 |
| Application tests 重跑 | dotnet test tests/HS.DeviceControl.Application.Tests/HS.DeviceControl.Application.Tests.csproj | Passed：40 passed / 0 failed / 0 skipped。 |
| Solution tests | dotnet test HS.DeviceControl.sln | Passed：492 passed / 0 failed / 0 skipped。 |
| Loader / DLL 停止線掃描 | rg "Assembly\.Load\|LoadFrom\(\|LoadFile\(\|IPluginLoader\|class PluginLoader" src tests samples | 無命中。 |
| diff check | git diff --check | 無 whitespace error；僅有 LF/CRLF 提醒。 |
| 尾端空白掃描 | rg "\s+$" 掃描本次程式檔 | 無命中。 |
4. 測試覆蓋
| 測試 | 驗證內容 |
PluginCatalogServiceTests | metadata 不載入 DLL、缺少 PluginId、敏感資訊、缺少 capability、缺 contract version、unsafe source、disabled reason。 |
PluginVerificationResultTests | 成功狀態為 Verified、失敗狀態不可產生 Loaded、失敗訊息遮罩、disabled state 可表達。 |
PluginAuditRecordTests | safe summary 保留、敏感 reason 與正式路徑遮罩、AuditId 缺省時自動產生。 |
5. 停止線稽核
| 停止線 | 本次結果 |
不建立 IPluginLoader | 遵守 |
不建立 PluginLoader | 遵守 |
| 不掃描 plugin folder | 遵守 |
| 不載入外部 DLL | 遵守 |
| 不執行外部 plugin 程式碼 | 遵守 |
| 不改 Adapter public contract | 遵守 |
| 不改 config schema | 遵守 |
| 不新增 WebApi route / ServiceHost lifecycle | 遵守 |
| 不寫 DB、不執行 DDL / ALTER TABLE / Apply | 遵守 |
| 不保存密碼、Token、connection string 或正式 DLL 路徑 | 遵守 |
6. 完成判定
4D 最小 Application plugin contract 第一版已完成本機實作與測試驗證，可作為未來真正 PluginLoader 前的 metadata / verification / state / audit contract 基礎。
本次仍未建立動態 Loader；外部 DLL 載入、簽章驗證、版本信任模型落地、plugin folder 掃描、config schema 與 Adapter contract 仍需另行確認。
7. 建議下一步
建議接著查看 4D PluginLoader 完成稽核表，再同步文件 repo stage / commit / push 與線上部署查驗。