# 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 共用協調層、部署維運與停止線是否同意。

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

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