4A WebApi / ServiceHost / Plugin Loader 邊界分析

本文件整理第三階段完成後，進入第四階段前需要先釐清的正式執行入口邊界。

本文件只做邊界分析與後續決策依據，不代表已同意新增 ServiceHost 專案、WebApi 專案、API route、Plugin Loader、外部 DLL 載入、認證授權套件、背景服務套件、正式 DB DDL、正式 Apply、敏感連線資訊保存或既有 public method 簽章調整。

1. 分析定位

4A 的目的不是直接開始寫正式 Host 或 API，而是先把第三階段已完成的 Application contract 放到正式執行平台視角下檢查：

HS.DeviceControl.Application 是否已足以作為未來 WebApi / ServiceHost 共用協調層。
WebApi 應該只負責 request / response、權限、DTO mapping 與轉交，不重寫 Workflow 或 Adapter 邏輯。
ServiceHost 應該只負責背景執行生命週期、adapter lifecycle、health、log / trace 與任務協調，不提供 HTTP。
Plugin Loader 應該先定義信任、版本、metadata 與載入停止線，不在未確認前載入外部 DLL。
第四階段若要進入現場工具、管理畫面或部署維運，必須先固定正式執行入口與安全邊界。

2. 目前基準

項目	目前狀態
文件 repo	`main`，第三階段線上驗收已完成
程式 repo	`poc/nmodbus-tcp`
程式基準 commit	`a158551`
已完成階段	3A Trace 查詢、3B ManualApplyPreview、3C Application contract、3D Application contract
測試基準	Application tests 30 passed；solution tests 468 passed
已存在共用層	`HS.DeviceControl.Core`、`HS.DeviceControl.Adapters`、`HS.DeviceControl.Application`、`HS.DeviceControl.Infrastructure.MySql`
尚未建立	`HS.DeviceControl.ServiceHost`、`HS.DeviceControl.WebApi`、Plugin Loader、正式部署服務

3. 4A 邊界總表

邊界	可討論內容	目前停止線
Application contract	對外提供任務控制、設備狀態、Schema 預覽、Health、多設備單元、Resource Lock、Command Queue 與 Plugin metadata 的協調入口。	不修改既有 public method 簽章，不在未確認前新增破壞性契約。
WebApi	未來作為遠端查詢與控制入口，只做 HTTP request / response、權限、DTO mapping、錯誤回應與呼叫 Application service。	不新增 WebApi 專案、Controller、route、middleware 或 API response contract。
ServiceHost	未來作為正式背景執行入口，負責生命週期、adapter lifecycle、任務協調、health 與 log / trace。	不新增 ServiceHost 專案、不改啟動方式、不建立 Windows Service 或排程服務。
Plugin Loader	未來處理外部 DLL 信任、版本、metadata、載入與卸載策略。	不載入外部 DLL、不建立 loader、不執行外部程式碼。
Plugin metadata	可沿用 3D 的 `PluginDescriptor` / `PluginRegistrationRequest` 概念，先整理資料與狀態語意。	不把 metadata 等同於可執行 plugin，不建立檔案掃描或 assembly loading。
DB / Schema	可引用 3A / 3B / 第二階段既有查詢與安全預覽概念。	不執行 DDL / ALTER TABLE / 正式 Apply，不保存密碼或正式連線資訊。
ConsoleHost	可保留 PoC 與人工驗證入口經驗。	不把 ConsoleHost 直接升級成正式背景服務。
UI / 現場工具	第四階段可再規劃現場工具與管理畫面。	4A 不新增 Web UI、WinForms Debug Tool 或多案場管理。
真實硬體	未來真實 Adapter 需遵守 Adapter contract 與 Application 協調層。	4A 不接真實硬體、不改 Adapter public contract。

4. 與 3C / 3D 的承接關係

3C 已先建立 Application Service contract，讓未來 WebApi / ServiceHost 不需要直接碰 Core、Adapter 或 DB gateway。

3D 已把多設備單元、資源鎖、命令佇列、Plugin metadata 與 Application error code 收斂到 Application 層，讓正式執行入口可以用同一組語意承接平台化能力。

因此 4A 的重點是判斷「正式入口如何包住 Application 層」，不是把流程邏輯搬到 Host、Controller 或 Plugin Loader。

5. 建議 4A 決策確認項目

編號	決策項目	建議方向	不同意時需說明
1	4A 只做邊界分析	本節點只建立邊界分析與決策確認表，不進入程式實作。	若要直接實作，需先指定是否建立 WebApi、ServiceHost 或其他正式入口，並確認風險。
2	WebApi 邊界	WebApi 第一版只做 HTTP 邊界、權限、DTO mapping、查詢與控制請求轉交。	若 WebApi 要直接呼叫 Core / Adapter / DB，需說明如何避免流程邏輯分散。
3	ServiceHost 邊界	ServiceHost 第一版只做背景執行生命週期、任務協調、adapter lifecycle、health 與 log / trace。	若 ServiceHost 要同時提供 HTTP，需說明部署、安全與責任切分。
4	Plugin Loader 邊界	先保留 metadata / contract 層，不載入外部 DLL，待信任模型與版本策略確認後再實作。	若要立即載入 DLL，需先確認來源信任、簽章、版本、錯誤隔離與回復策略。
5	Application 層作為共用協調層	WebApi / ServiceHost / 現場工具都應透過 Application contract，不重寫 Workflow 或 Adapter 操作。	若各入口各自實作，需說明如何維護一致狀態、錯誤碼、Log 與測試。
6	部署與維運前置	在建立正式入口前，先確認設定來源、環境變數、health、log、operator、host name、app version 與敏感資訊保存方式。	若先建立入口再補維運規則，需接受後續返工與安全風險。
7	停止線維持	4A 不新增正式入口、不改 public method 簽章、不改 config schema、不執行 DB DDL、不接真實硬體。	若要突破停止線，需另開實作前確認與使用者明確同意。

6. 主要風險

風險	說明	4A 建議處理方式
過早新增 WebApi	若權限、DTO、錯誤格式與任務控制語意未固定，容易把臨時設計變成外部契約。	先做決策確認表，再進入 API contract 草案。
ServiceHost 與 WebApi 混責	背景執行與 HTTP 入口混在一起會讓部署、重啟、權限與錯誤處理難以切分。	ServiceHost 不處理 HTTP，WebApi 不直接執行 Workflow。
Plugin Loader 信任風險	外部 DLL 載入會牽涉版本、來源、簽章、隔離與錯誤回復。	先保留 metadata 與 registration 語意，不做 loader。
設定格式過早固定	入口一旦讀取正式 appsettings 或 plugin 設定，後續 schema 變更成本會提高。	4A 只列出需確認欄位，不改 config schema。
DB 權限擴大	正式入口若直接帶入 DB 寫入或 DDL，會超出 3A / 3B 安全邊界。	DDL、ALTER、正式 Apply 與密碼保存一律另行確認。
Log 不一致	多入口若各自組錯誤與 Log，追蹤 Task / Node / Device / Command 會斷裂。	統一從 Application / Core result 與既有 log contract 轉換。

7. 4A 不做事項

不新增 HS.DeviceControl.ServiceHost 專案。
不新增 HS.DeviceControl.WebApi 專案。
不新增 Controller、route、middleware 或 API response contract。
不新增 Windows Service、背景排程、外部佇列或部署腳本。
不建立 Plugin Loader、不載入外部 DLL、不掃描 plugin 目錄。
不修改 Adapter public contract、不接真實硬體。
不修改 config schema、不保存敏感連線資訊。
不執行正式 DB 寫入、DDL / ALTER TABLE、正式 Apply。
不新增 Web UI、WinForms Debug Tool、多案場管理或報表。

8. 建議下一步

先整理「4A 決策確認表」，讓使用者逐項確認 WebApi、ServiceHost、Plugin Loader、Application 共用協調層、部署維運與停止線是否同意。

七項決策確認完成後，再決定要進入哪一條：

WebApi contract 草案。
ServiceHost contract 草案。
Plugin Loader 信任模型與 metadata contract 草案。
第四階段現場工具 / 管理畫面前置規劃。