# 外部 DLL manual-only 程式 repo 結構檢查與實作前確認

本文件承接外部 DLL manual-only 七項邊界確認，先做程式 repo 唯讀盤點與實作前範圍收斂。此文件不修改程式 repo，不載入 DLL，不掃描 plugin folder，不新增 config schema，也不改 Adapter public contract。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已確認 |
| 建立日期 | 2026-06-07 |
| 確認日期 | 2026-06-07 |
| 使用者回覆 | 7 項皆同意 |
| 前置確認 | 外部 DLL manual-only 邊界確認 7 項皆同意 |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式 commit | `9e7302a` |
| 工作樹 | 檢查時乾淨 |
| 本文件性質 | 程式 repo 唯讀檢查與下一步實作前確認 |

## 1. 唯讀結構檢查結果

| 檔案或區域 | 目前狀態 | 對 external DLL manual-only 的判斷 |
|---|---|---|
| `src/HS.DeviceControl.Application/Plugins/IPluginLoader.cs` | 目前只有 `LoadPlugin(PluginLoadRequest request)`，回傳 metadata 驗證結果。 | 可作為前置 metadata gate，不應直接改成真實 DLL 載入入口。 |
| `PluginLoadRequest` | 已包含 `PluginId`、預期 contract version、預期 checksum、operator、request source。 | 足以支援 metadata 驗證；若做 DLL manual-only，應新增獨立 request，避免把本類變成路徑或載入參數容器。 |
| `PluginLoadResult` | 成功狀態固定為 `Verified`，失敗會標準化錯誤與安全訊息。 | 可作為前置證據；DLL manual-only 需新增獨立 result 或 plan，避免混淆「已驗證」與「已載入」。 |
| `PluginLoadState` | `Loaded` 僅保留給未來 lifecycle，5A 不產生。 | 下一步仍不得在預設流程產生 `Loaded`。 |
| `PluginLoaderOptions` | 目前只有 metadata contract、checksum、disabled review 選項。 | 不應直接加入正式 DLL 路徑；若需要 gate，應用獨立 manual-only options。 |
| `PluginDescriptor` | 明確說明不包含 DLL 載入或執行資訊，`Source` 只允許安全摘要。 | 不應新增真實路徑欄位；plugin folder schema 留到 5B。 |
| `PluginLoaderService` | 只從 catalog 取得 metadata，做 request、catalog、metadata、enabled、contract、checksum 檢查。 | 可在新 service 前先呼叫此 gate，但不得把真實 DLL 載入塞入此 service。 |
| `ApplicationErrorCodes` | 已有 `APP-0341` 到 `APP-0345` 給 metadata loader。 | DLL manual-only 可另開 `APP-0351` 起的錯誤碼，避免混淆 metadata 與 external binary gate。 |
| `Application.Tests` | 已覆蓋 valid metadata、invalid request、not found、disabled、contract mismatch、checksum mismatch、unsafe source、catalog failure。 | 可新增 fake / plan / gate tests；CI 不執行真實 DLL 載入。 |

## 2. 停止線掃描結果

| 檢查項目 | 結果 |
|---|---|
| 正式程式外部載入 API | 未發現正式程式使用外部載入 API。 |
| plugin folder 掃描 | 未發現正式程式掃描 plugin folder。 |
| `.dll` 字串 | 只出現在既有測試樣本與舊文件紀錄。 |
| `Loaded` 狀態 | 目前為保留值與防呆測試，5A 成功結果不產生 `Loaded`。 |
| 程式 repo 工作樹 | `poc/nmodbus-tcp` 乾淨。 |

## 3. 建議的最小實作範圍

若使用者同意進入下一步，建議只建立 external DLL manual-only 的「規劃與 gate」能力，不進行真實載入：

| 候選項目 | 建議 |
|---|---|
| request | 新增 `ExternalDllManualVerificationRequest`，只接受安全摘要、預期 checksum、預期 contract version、manual gate 與 operator 摘要。 |
| plan | 新增 `ExternalDllManualVerificationPlan`，描述是否允許進入 manual-only 驗證、需要哪些人工條件、禁止哪些行為。 |
| result | 新增 `ExternalDllManualVerificationResult`，回傳 `Success`、`Code`、`Message`、`Checks`、`Warnings`、`TimeTakenMs`、`Error`，不得回傳完整路徑。 |
| service | 新增 `IExternalDllManualVerifier` 與 metadata-only / fake implementation，預設只建立 plan 與拒絕未開 gate 的請求。 |
| options | 新增 `ExternalDllManualVerifierOptions`，預設 `AllowManualExternalDllVerification=false`。 |
| error code | 建議使用 `APP-0351` 到 `APP-0356`，涵蓋 gate disabled、request invalid、source unsafe、checksum mismatch、contract mismatch、verification rejected。 |
| tests | 只新增 fake / unit tests 與 stop-line tests，不新增真實 DLL fixture。 |

## 4. 建議測試矩陣

| 測試 | 預期 |
|---|---|
| gate disabled | 回傳標準拒絕結果，不嘗試載入。 |
| request missing plugin id | 回傳 request invalid。 |
| unsafe source summary | 回傳 source unsafe，訊息需遮蔽。 |
| checksum mismatch | 回傳 checksum mismatch。 |
| contract mismatch | 回傳 contract mismatch。 |
| gate enabled with fake verifier | 只產生 manual-only plan / verified metadata result，不產生真實 DLL 載入。 |
| stop-line scan | 確認本批未使用外部載入 API、未掃描 plugin folder、未新增 config schema、未產生 `Loaded` 成功狀態。 |

## 5. 明確不納入

- 不載入真實 DLL。
- 不新增 DLL fixture。
- 不新增 plugin folder 或 trust policy schema。
- 不修改 `PluginDescriptor` 成為路徑容器。
- 不修改 Adapter public contract。
- 不修改 WebApi、ServiceHost 或 Windows Service。
- 不建立 DB audit table。
- 不執行正式 DB DDL、ALTER TABLE 或 Apply。
- 不保存或輸出完整路徑、密碼、token、connection string、正式 IP 或正式 port。

## 6. 實作前七項確認

若要進入下一步程式 repo 修改，建議確認以下七項：

1. 同意本批只做 external DLL manual-only 的 request / result / plan / options / fake verifier，不載入真實 DLL。
2. 同意預設 gate 關閉，未明確設定時一律回拒絕結果。
3. 同意不新增 plugin folder schema、不修改 samples config、不改 5B config schema 範圍。
4. 同意不修改 Adapter public contract、WebApi route、ServiceHost 啟動方式或 Windows Service。
5. 同意新增 `APP-0351` 起的錯誤碼與 Application.Tests fake 測試。
6. 同意本批驗證只跑 Application.Tests、solution tests 與停止線掃描，不執行真實 DLL manual test。
7. 同意若後續要真正載入 DLL、使用外部載入 API、建立 fixture 或讀取本機 DLL 路徑，必須再次停下確認。

建議確認文字：

```text
外部 DLL manual-only 程式結構與實作前確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意
```

## 7. 下一步

使用者已於 2026-06-07 回覆 7 項皆同意；本文件已授權進入 external DLL manual-only fake verifier 程式實作。實作後驗收紀錄見 `phase-five-external-dll-manual-only-implementation-acceptance-record.md`。