4D PluginLoader 邊界分析
本文件承接 4A 邊界分析、4B / 4C / 4D 執行切分、第四階段標準、4B WebApi 第一版與 4C ServiceHost 第一版結果，整理 4D PluginLoader 進入任何程式實作前必須確認的信任模型、metadata contract、版本策略、隔離策略、卸載與回復策略。
本文件只做邊界分析與後續決策依據，不代表已同意建立 PluginLoader、掃描 plugin folder、載入外部 DLL、執行外部程式碼、修改 IDeviceAdapter public contract、修改 config schema、導入 plugin framework、保存正式 DLL 路徑、接真實硬體、執行正式 DB DDL 或改變程式啟動方式。
0. 文件狀態
| 項目 | 內容 |
| 文件狀態 | 已整理 |
| 整理日期 | 2026-06-06 |
| 對應階段 | 第四階段 4D PluginLoader |
| 程式基準 commit | a846212 新增 4C ServiceHost 第一版與驗收測試 |
| 已完成前置 | 4A 邊界與決策確認、4B WebApi 第一版、4C ServiceHost 第一版 |
| 本次目標 | 固定信任、版本、metadata、隔離、卸載、回復、測試與停止線 |
| 本次不做 | 不建立 Loader、不載入 DLL、不掃描資料夾、不執行 plugin、不改 Adapter / config / DB |
1. 4D 定位
4D PluginLoader 的目標不是讓任何 DLL 立刻被載入，而是先把「什麼可以被視為 plugin、誰可以信任它、版本如何判定、失敗如何隔離、如何停用與回復」整理成可測試、可驗收的 contract。
| 原則 | 說明 |
| Metadata 不等於可執行 | 3D 已有 PluginDescriptor / PluginCatalogService，但目前只代表 metadata catalog，不代表允許載入 DLL。 |
| Loader 不寫流程邏輯 | PluginLoader 不得寫 Workflow node、Retry、NextNode 或 TaskStateMachine 規則。 |
| Adapter contract 仍是設備邊界 | 未來 plugin 提供設備模組時，也必須遵守 IDeviceAdapter / command contract。 |
| ServiceHost 承接 lifecycle | 未來 Loader 若要常駐管理，應由 ServiceHost 組裝，不由 WebApi 直接載入 DLL。 |
| 外部程式碼需先不可信 | 未建立來源、簽章、checksum、版本與隔離策略前，所有外部 DLL 一律視為不可執行。 |
2. 目前程式基準
| 項目 | 目前狀態 |
| Application plugin metadata | 已有 HS.DeviceControl.Application.Plugins、PluginDescriptor、PluginCapabilityDescriptor、IPluginCatalogService、PluginCatalogService。 |
| Plugin metadata 測試 | 已有 PluginCatalogServiceTests，驗證 metadata、缺少欄位、敏感資訊與 capability 檢查。 |
| WebApi | 4B 已建立 HS.DeviceControl.WebApi，但未新增 plugin loader route。 |
| ServiceHost | 4C 已建立 HS.DeviceControl.ServiceHost，可作為未來常駐 lifecycle 承接點。 |
| Loader 程式 | 尚未存在 PluginLoader、plugin folder scanner、assembly loading 或 unload 管理。 |
3. 4D 邊界總表
| 邊界 | 可整理內容 | 目前停止線 |
| Plugin identity | PluginId、Version、DisplayName、Capabilities、Checksum、來源與狀態。 | 不把 identity 直接當成執行授權。 |
| Trust model | 來源白名單、簽章、checksum、版本相容、人工核准狀態。 | 不信任任意 folder 或使用者提供的 DLL。 |
| Metadata contract | catalog、capability、device type、command name、相容版本與停用原因。 | 不保存密碼、IP、Port、完整 DLL 路徑或正式環境資訊。 |
| Loader lifecycle | Discovered、Verified、Loaded、Disabled、Faulted 等狀態語意。 | 不建立實際 loader、不呼叫 assembly loading API。 |
| Adapter integration | 未來 plugin 若提供 Adapter，仍需走已確認的 Adapter factory / dispatcher 邊界。 | 不修改 IDeviceAdapter public contract。 |
| Config schema | 可整理候選欄位與風險。 | 不修改 devices.json、workflows.json、appsettings.json schema。 |
4. 信任模型草案
| 檢查項 | 建議規則 | 失敗處理 |
| 來源 | 第一版只允許受控來源，例如 repository 內測試 fixture 或明確白名單資料夾。 | 標記 Rejected，不載入。 |
| Checksum | metadata 宣告 checksum 需與實際 artifact 比對。 | 回傳標準錯誤並寫 audit。 |
| 簽章 | 若進入正式 DLL，需定義簽章或發佈者驗證策略。 | 未通過不可進入 Verified。 |
| 版本相容 | plugin 需宣告目標 contract version 與 capability version。 | 版本不符需禁載，不做自動降級。 |
| 敏感資訊 | metadata 不得包含 password、token、connection string、正式 IP / Port。 | 直接視為 metadata invalid。 |
| 人工核准 | 正式載入前需有 operator / approver / reason。 | 無核准不可載入。 |
5. Plugin 狀態語意草案
| 狀態 | 語意 | 是否可執行 |
Discovered | 已發現 metadata 或候選 artifact，但尚未驗證。 | 否 |
Verified | metadata、來源、checksum、版本與簽章通過。 | 仍需另行確認 |
Loaded | 已載入並可由受控 lifecycle 管理。 | 僅未來授權後 |
Disabled | 已被人工或策略停用。 | 否 |
Rejected | 驗證失敗或來源不可信。 | 否 |
Faulted | 載入或執行期間發生錯誤。 | 否，需隔離與 audit |
6. 第一版候選 contract
| 類型 | 候選命名 | 說明 |
| Metadata | PluginDescriptor extension 或 PluginManifest | 描述 plugin identity、version、checksum、capability 與相容性。 |
| Trust result | PluginVerificationResult | 回傳驗證是否通過、錯誤碼、原因與安全摘要。 |
| State | PluginLoadState | 描述 discovered / verified / loaded / disabled / faulted。 |
| Catalog | IPluginCatalogService extension | 只讀查詢 metadata，不載入 DLL。 |
| Audit | PluginAuditRecord | 記錄 operator、source、checksum、decision、reason、time。 |
| Loader | IPluginLoader | 只可在使用者另行確認後討論；本文件不建立。 |
7. 測試與驗收策略
| 測試 | 目的 | 本階段是否執行 |
| 文件驗證 | 確認 4D 邊界、信任模型與停止線已整理。 | 是 |
| Metadata validation tests | 驗證缺欄位、敏感資訊、capability 與 checksum 語意。 | 可在 contract 階段討論 |
| Trust model tests | 驗證來源不可信、checksum 不符、版本不符、未核准不可載入。 | 待確認 |
| Loader lifecycle tests | 驗證 load / unload / fault / disable / recover。 | 否，需另行確認 |
| External DLL tests | 使用測試 plugin assembly 驗證載入。 | 否，需另行確認 |
| 真實硬體 tests | 驗證 plugin device adapter 對真實設備。 | 否 |
8. 本階段不做事項
- 不建立
PluginLoader 程式。 - 不建立
IPluginLoader public contract。 - 不掃描 plugin folder。
- 不載入外部 DLL。
- 不呼叫
Assembly.Load、LoadFrom、LoadFile 或類似 API。 - 不執行外部 plugin 程式碼。
- 不新增或更換 plugin framework / DI framework / sandbox 套件。
- 不修改
IDeviceAdapter public contract。 - 不修改 config schema。
- 不保存密碼、Token、IP、Port、完整 connection string、正式 DLL 路徑或正式環境資訊。
- 不執行 DB 寫入、DDL、ALTER TABLE 或正式 Apply。
- 不接真實硬體或案場客製 plugin。
9. 建議下一步
4D 邊界分析完成後，建議下一步整理 4D PluginLoader 決策確認表，讓使用者逐項確認 trust model / metadata contract、不載入 DLL、沿用 3D metadata 起點、checksum / 版本相容 / 來源白名單、Adapter contract 不變、ServiceHost 承接 lifecycle，以及所有 Loader 實作、外部 DLL 測試、真實硬體與 DB audit 皆需另行確認。