# 第五階段 Loader 到 Service 後續文件 / 實作 / 驗收範圍補齊表

本文件承接 [5A PluginLoader 實作前確認表](phase-five-a-pluginloader-preimplementation-checklist.md)。使用者已確認 5A 七項決策，並要求將後續 Loader、外部 DLL、config schema、DB audit、auth / Swagger、Windows Service、文件實作與驗收範圍補齊。

本文件是第五階段後續總控文件，用於固定範圍、順序、驗收條件與停止線。本文件不是程式實作授權；未經個別節點確認前，不得新增外部 DLL 載入、正式 DB DDL、正式 Apply、auth secret、Swagger 正式開放設定或 Windows Service 安裝。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已建立 |
| 建立日期 | 2026-06-07 |
| 前置確認 | 4E 七項決策已確認；5A 七項決策已確認 |
| 對應節點 | 5A 到 5F |
| 本文件目的 | 補齊 Loader、外部 DLL、config schema、DB audit、auth / Swagger、Windows Service 的文件、實作與驗收範圍 |
| 是否啟用程式修改 | 否，本文件只固定後續工作邊界 |
| 程式 repo 基準 | `a8b522b` main 已合併 `poc/nmodbus-tcp`；4D 功能基準為 `6f34bb9` |

## 1. 第五階段節點總表

| 節點 | 主題 | 文件範圍 | 實作範圍 | 驗收範圍 | 停止線 |
|---|---|---|---|---|---|
| 5A | 最小 PluginLoader | 程式 repo 唯讀結構檢查、最小 Loader contract、實作前確認、實作紀錄、完成稽核 | Application 層 metadata-only / catalog-driven Loader、`IPluginLoader` 最小 contract、標準 result / error mapping | Application.Tests、solution tests、Loader / DLL 停止線掃描、stage / commit 前確認 | 不掃描正式 plugin folder、不載入外部 DLL、不改 config schema、不建 DB audit table |
| 5A-2 | 外部 DLL manual-only 驗證 | 外部 DLL 信任模型、測試 DLL 來源、checksum / signature、隔離資料夾、人工驗收紀錄 | 僅可建立測試用 fixture 或手動驗證入口；不得在一般 CI 載入未知 DLL | manual-only 載入、拒絕不可信來源、版本不合拒絕、錯誤隔離與 unload / recovery 紀錄 | 不載入未知 DLL、不連正式案場 plugin、不在 CI 自動跑外部 DLL |
| 5B | config schema | plugin 設定欄位草案、schema 版本、相容性、範例 config、回滾策略 | `plugins` / `loader` 設定讀取、validation、safe default、範例檔 | Config Validator tests、缺欄位 / 不合法路徑 / disabled plugin 測試、舊設定相容性檢查 | 不保存密碼、token、正式機敏路徑；不改啟動方式 |
| 5C | DB audit | audit event 欄位、DDL 前確認、manual-only DB 驗證設計、cleanup 策略 | audit model / writer / fake gateway；必要時另行授權測試 DB schema | fake gateway tests、DDL dry-run / precheck、manual-only write / read / cleanup | 不對正式 DB 執行 DDL / ALTER TABLE / Apply；不寫入未遮蔽敏感資料 |
| 5D | WebApi auth / Swagger | auth 邊界、Swagger 開放條件、角色 / token 決策、API 測試矩陣 | 最小 auth middleware / policy、dev-only Swagger gate、錯誤格式 | API tests：未授權、權限不足、成功、Swagger dev-only / production disabled | 不保存 secret、不啟用正式外網設定、不改 production 權限 |
| 5E | Windows Service | Service 安裝方式、帳號權限、log path、recovery、stop / restart、rollback runbook | Windows Service wrapper / hosted lifecycle / install script 草案；以本機或測試環境為限 | manual-only install / start / stop / restart / uninstall、log 與 recovery 驗證 | 不安裝到正式機、不修改公司機器服務設定、不連真實硬體 |
| 5F | 整合驗收 | Loader + config + audit + WebApi + ServiceHost + Windows Service 整合驗收表、發布前確認 | 只整合已完成且已確認節點；不得補做未確認功能 | solution tests、API tests、manual-only DB / service 驗收、文件網站線上驗收、rollback 檢查 | 任一節點未完成或未確認時，不得宣告第五階段完成 |

## 2. 文件交付清單

| 節點 | 建議文件 |
|---|---|
| 5A | 5A 程式 repo 結構檢查表、5A 最小 PluginLoader 實作前最後確認、5A 實作與驗收紀錄、5A 完成稽核表 |
| 5A-2 | 外部 DLL manual-only 驗證前確認、外部 DLL manual-only 驗收紀錄 |
| 5B | Plugin config schema 實作前確認、config schema 實作與驗收紀錄 |
| 5C | DB audit table / writer 實作前確認、DB audit manual-only 驗證前確認、DB audit 驗收紀錄 |
| 5D | WebApi auth / Swagger 實作前確認、實作工作包、API 安全驗收紀錄 |
| 5E | Windows Service 實作前確認、Windows Service manual-only 驗收紀錄 |
| 5F | 第五階段整合驗收紀錄、第五階段完成稽核表、第五階段線上驗收紀錄 |

## 3. 實作範圍原則

| 原則 | 說明 |
|---|---|
| 一次只打開一個高風險邊界 | Loader、DLL、config、DB、auth、Service 不混在同一個實作節點內。 |
| 先 fake / unit，再 manual-only | 先以 unit tests 和 fake gateway 固定 contract，再用人工 gate 驗證外部系統。 |
| 先測試環境，再正式環境 | 外部 DLL、DB audit、Windows Service 都必須先有測試環境驗收紀錄。 |
| 不把 secret 寫入 repo | config schema 可描述欄位，但不得保存密碼、token、正式 IP 或正式路徑。 |
| 不把案場客製寫入 Core | 案場 plugin、設備 DLL 與部署設定必須留在外部或測試 fixture，不污染共用 Core。 |

## 4. 驗收範圍原則

| 類型 | 必要驗收 |
|---|---|
| 文件驗收 | 文件 repo index、README、進度總覽、`status.json`、Cloudflare Pages 頁面可追溯。 |
| 程式驗收 | 對應測試專案通過，必要時全量 solution tests 通過。 |
| 安全驗收 | 停止線掃描通過，例如不得呼叫外部 DLL loading API、不得新增正式 DDL、不得暴露 secret。 |
| DB 驗收 | fake gateway 必測；真實 DB 只允許 manual-only gate，且需 write / read / cleanup 或 read-only 證據。 |
| API 驗收 | 未授權、權限不足、成功、錯誤格式與 Swagger 開放條件皆需覆蓋。 |
| Service 驗收 | install / start / stop / restart / uninstall、log path、recovery 與 rollback 皆需有紀錄。 |

## 5. 必須停下確認的情境

| 情境 | 原因 |
|---|---|
| 新增或修改 public method 簽章 | 會影響 Application / WebApi / ServiceHost contract。 |
| 導入新的核心套件 | 會影響長期維護、授權與部署。 |
| 新增 DB table 或執行 DDL / ALTER TABLE | 會影響資料庫 schema 與資料風險。 |
| 載入外部 DLL 或執行 plugin 程式碼 | 會引入信任、隔離、卸載與安全風險。 |
| 保存 secret、正式 IP、正式路徑或正式帳號 | 會造成敏感資訊外洩風險。 |
| 修改 WebApi auth / Swagger 正式部署設定 | 會影響外部暴露面與權限模型。 |
| 安裝或修改 Windows Service | 會影響本機或正式機執行環境。 |

## 6. 建議執行順序

1. 先做 5A 程式 repo 唯讀結構檢查，確認最小 PluginLoader 實作候選檔案與停止線。
2. 再做 5A 最小 metadata-only PluginLoader 實作前最後確認。
3. 完成 5A 後，再拆出外部 DLL manual-only 驗證，不與 config / DB / auth / Service 混做。
4. 5B 再補 config schema，避免在 Loader contract 尚未穩定時鎖死設定格式。
5. 5C 獨立處理 DB audit，先 fake gateway，再 manual-only 測試 DB。
6. 5D 獨立處理 auth / Swagger，先本機 API tests，再討論部署設定。
7. 5E 獨立處理 Windows Service，限本機或測試環境 manual-only 驗收。
8. 5F 最後做整合驗收與第五階段完成稽核。

## 7. 下一步建議

5A、外部 DLL manual-only、5B、5C 與 5D 已完成最小實作與驗收紀錄。建議下一步先完成 5D 程式 repo stage / commit / push 前確認與 Actions 查核，再進入 5E Windows Service 最小實作前最後確認。