# 5A PluginLoader 實作前確認表

本文件承接 [4E 後續功能節點決策確認表](phase-four-e-post-minimal-decision-confirmation.md)。使用者已確認 4E 七項決策，因此本節點正式進入 5A PluginLoader 實作前確認。

本文件仍不是程式實作授權。完成本文件確認前，不得建立 `IPluginLoader` public contract、不得建立真正 Loader、不得掃描 plugin folder、不得載入外部 DLL、不得修改 config schema、不得建立 DB audit table、不得導入 WebApi auth / Swagger，也不得建立 Windows Service。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已確認 |
| 建立日期 | 2026-06-07 |
| 確認日期 | 2026-06-07 |
| 對應節點 | 5A PluginLoader 安全模型與最小 Loader |
| 前置確認 | 4E 七項決策皆已同意 |
| 使用者確認 | 5A 七項決策皆已同意 |
| 程式 repo 基準 | `a8b522b` main 已合併 `poc/nmodbus-tcp`；4D 功能基準為 `6f34bb9` |
| 本文件目的 | 固定 5A 的最小實作範圍、候選檔案、測試策略、停止線與七項確認 |
| 是否啟用程式修改 | 否，本次僅完成文件確認；下一步可進入程式 repo 唯讀結構檢查與 5A 最小 PluginLoader 實作評估 |

## 1. 4E 確認紀錄

使用者已確認以下七項：

| 編號 | 4E 決策項目 | 確認結果 |
|---:|---|---|
| 1 | 先做 4E 後續節點決策確認 | 同意 |
| 2 | 第一個程式節點從 5A PluginLoader 開始 | 同意 |
| 3 | 外部 DLL 獨立 manual-only 驗證 | 同意 |
| 4 | config schema 等 Loader contract 穩定後再改 | 同意 |
| 5 | DB audit 獨立成 DB 安全節點 | 同意 |
| 6 | auth / Swagger 獨立成 WebApi 安全節點 | 同意 |
| 7 | Windows Service 獨立成正式部署節點 | 同意 |

## 1.1 5A 確認紀錄

使用者已於 2026-06-07 確認 5A 七項決策皆同意。本確認代表可進入「程式 repo 唯讀結構檢查與 5A 最小 PluginLoader 實作評估」，但仍不代表已授權建立外部 DLL 載入、config schema、DB audit、auth / Swagger 或 Windows Service。

## 2. 5A 定位

5A 的目標是把「真正 PluginLoader」從 4D metadata contract 推進到可驗證的最小 Loader 邊界，但第一步仍必須保守：

| 原則 | 說明 |
|---|---|
| 先 contract，再 implementation | 若要建立 `IPluginLoader`，需先確認 request / result / state / error 語意。 |
| 最小 Loader 不等於外部 DLL 載入 | 5A 第一版建議只做 metadata-only / catalog-driven loader 驗證，不執行 assembly loading。 |
| 外部 DLL 另走 manual-only | 測試 DLL、隔離資料夾、checksum / signature 與來源白名單需另行確認，不進一般 CI。 |
| 不擴大到 config / DB / auth / service | 5A 不修改 config schema、不建 audit table、不改 WebApi auth、不改 Windows Service。 |
| Application 層優先 | 5A 第一版建議承接既有 Application plugin contract，不進 Core、不改 Adapter。 |

## 3. 5A 候選實作範圍

以下只是候選範圍，需等本文件七項確認後，才可進入程式 repo 唯讀結構檢查與實作評估。

| 類型 | 候選內容 | 邊界 |
|---|---|---|
| Loader public contract | `IPluginLoader`、`PluginLoadRequest`、`PluginLoadResult`、`PluginLoaderOptions` | 不包含外部 DLL 載入 API，不保證執行 plugin。 |
| Metadata-only loader | 以既有 `PluginDescriptor` / catalog 資料做驗證與狀態轉換 | 不掃描正式 plugin folder，不讀未知 DLL。 |
| Trust policy model | 來源、contract version、checksum、enabled / disabled、人工核准摘要 | 只做 model / validation，不保存正式路徑或 secret。 |
| Error mapping | Loader error code / result / audit summary | 不吐出完整 exception、正式 path、token、password。 |
| Tests | Application.Tests 的 unit tests | 不跑外部 DLL、不跑 DB manual-only、不改部署設定。 |

## 4. 明確不做

| 不做項目 | 原因 |
|---|---|
| 不載入外部 DLL | 來源信任、signature / checksum、隔離與測試 DLL 尚未確認。 |
| 不呼叫 `Assembly.Load` / `LoadFrom` / `LoadFile` | 這屬於外部程式碼載入，需獨立 manual-only 驗證。 |
| 不掃描正式 plugin folder | 正式路徑、白名單與權限模型尚未確認。 |
| 不修改 config schema | plugin path、enable flag、trust policy 等欄位需等 Loader contract 穩定。 |
| 不建立 DB audit table | audit event 與欄位需等 5A 結果穩定後進入 5C。 |
| 不修改 WebApi auth / Swagger | WebApi 安全模型獨立在 5D。 |
| 不建立 Windows Service | 正式部署節點獨立在 5E。 |
| 不接真實硬體或案場 plugin | 5A 只處理共用 Loader 邊界，不引入案場客製。 |

## 5. 候選檔案

實際檔案需以程式 repo 唯讀結構檢查為準；以下是 5A 第一輪候選。

| 類型 | 候選位置 |
|---|---|
| Application plugin loader contract | `src/HS.DeviceControl.Application/Plugins/IPluginLoader.cs` |
| Loader request / result / options | `src/HS.DeviceControl.Application/Plugins/PluginLoadRequest.cs`、`PluginLoadResult.cs`、`PluginLoaderOptions.cs` |
| Metadata-only loader | `src/HS.DeviceControl.Application/Plugins/PluginLoaderService.cs` 或等效 Application service |
| Error code | `src/HS.DeviceControl.Application/Common/ApplicationErrorCodes.cs` |
| Tests | `tests/HS.DeviceControl.Application.Tests/Plugins/*PluginLoader*Tests.cs` |
| 不新增 | 不新增專案、不改 `.sln`，除非程式 repo 唯讀檢查證明必要且另行確認 |

## 6. 測試策略

| 測試 | 驗證目的 |
|---|---|
| Required metadata | 缺少 plugin id、contract version、source 或 checksum 時回標準錯誤。 |
| Disabled plugin | disabled plugin 不可被視為可載入。 |
| Version mismatch | contract version 不相容時回拒絕結果。 |
| Checksum mismatch | 宣告 checksum 不符時回拒絕結果；第一版可用測試資料，不讀真實 DLL。 |
| Unsafe source / path | 來源含 secret、正式路徑、相對跳脫或不允許字串時拒絕。 |
| Error mapping | Loader error 轉成標準 result，不吞 exception，不暴露敏感資訊。 |
| No assembly loading | 測試或程式碼不得呼叫 `Assembly.Load`、`LoadFrom`、`LoadFile`。 |

## 7. 5A 七項確認

| 編號 | 決策項 | 建議 | 同意後後續動作 |
|---:|---|---|---|
| 1 | 5A 第一版是否只做 metadata-only / catalog-driven 最小 Loader | 同意 | 不直接載入 DLL，先固定 Loader request / result / state。 |
| 2 | 是否允許在 Application 層建立 `IPluginLoader` 最小 public contract | 同意 | 後續程式修改可新增 contract，但不得含外部 DLL 載入方法。 |
| 3 | 是否保留外部 DLL 載入為獨立 manual-only 驗證 | 同意 | 不在一般 CI 載入 DLL，不使用未知來源 DLL。 |
| 4 | 是否延後 config schema 修改到 5B | 同意 | 5A 不新增 plugin path / trust policy / service install 設定欄位。 |
| 5 | 是否延後 DB audit table 到 5C | 同意 | 5A 可保留 audit summary model，不執行 DDL / ALTER TABLE / Apply。 |
| 6 | 是否不修改 WebApi auth / Swagger / Windows Service | 同意 | WebApi 安全留 5D，Windows Service 留 5E。 |
| 7 | 是否先做程式 repo 唯讀結構檢查與 stage / commit 前確認 | 同意 | 實作前先回報候選檔案、測試命令與停止線。 |

## 8. 建議使用者回覆格式

```text
5A PluginLoader 實作前確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意
```

## 9. 建議下一步

5A 七項決策已確認。建議下一步先完成程式 repo 唯讀結構檢查，確認 `Application.Plugins`、測試專案、既有 plugin descriptor 與停止線後，再決定是否進入 5A 最小 PluginLoader 程式實作。