# 第四階段 4B / 4C / 4D 執行切分表

本文件承接 [4A WebApi / ServiceHost / Plugin Loader 邊界分析](phase-four-a-boundary-analysis.md) 與 [4A WebApi / ServiceHost / Plugin Loader 決策確認表](phase-four-a-decision-confirmation.md)，用來回答 WebApi、ServiceHost、Plugin Loader 預計在哪個階段進入正式執行。

本文件只整理第四階段路線切分，不代表已同意新增 `WebApi` 專案、`ServiceHost` 專案、Plugin Loader、外部 DLL 載入、API route、Controller、middleware、背景服務套件、認證授權套件、config schema 調整、public method 簽章變更、正式 DB DDL 或真實硬體控制。

## 1. 結論

| 功能 | 預計執行階段 | 第一個輸出 | 程式實作條件 |
|---|---|---|---|
| WebApi | 4B | WebApi contract 草案 / 實作前確認表 | 使用者確認 API route、DTO、權限、錯誤格式與停止線後，才可建立 `HS.DeviceControl.WebApi`。 |
| ServiceHost | 4C | ServiceHost contract 草案 / 實作前確認表 | 使用者確認背景生命週期、Adapter lifecycle、Health、Log / Trace、部署方式與停止線後，才可建立 `HS.DeviceControl.ServiceHost`。 |
| Plugin Loader | 4D | Plugin Loader 信任模型與 metadata contract 草案 / 實作前確認表 | 使用者確認來源信任、版本、簽章、隔離、卸載、回復策略與停止線後，才可建立 Loader 或載入外部 DLL。 |

建議順序維持：

```text
4A 前置確認
-> 4B WebApi
-> 4C ServiceHost
-> 4D Plugin Loader
```

## 2. 為什麼不是 4A 直接實作

4A 的職責是把第三階段完成的 `HS.DeviceControl.Application` 放到正式平台視角檢查，確認 WebApi、ServiceHost、Plugin Loader 是否都應透過同一個 Application contract 承接任務控制、設備狀態、Schema Preview、Health、多設備單元、Resource Lock、Command Queue 與 Plugin metadata。

如果 4A 直接新增正式入口，會讓 API route、背景服務啟動方式、Plugin trust model、設定來源與部署規則在尚未定案時成為外部契約。這會增加後續返工，也可能讓 Workflow、Adapter、DB gateway 或 Plugin Loader 的責任邊界混在一起。

## 3. 階段切分總表

| 階段 | 主題 | 可做事項 | 不做事項 | 完成基準 |
|---|---|---|---|---|
| 4A | 正式入口前置確認 | 邊界分析、七項決策確認、4B / 4C / 4D 切分。 | 不新增正式入口、不新增 route、不建立 Loader、不改 public method 簽章、不改 config schema。 | 4A 決策確認表完成，並明確排定 WebApi、ServiceHost、Plugin Loader 的後續階段。 |
| 4B | WebApi | API contract、request / response DTO、錯誤格式、權限模型、route 候選、Application service mapping、實作前確認。 | 不直接操作 Core / Adapter / DB gateway；不做 DB DDL / ALTER / Apply；不導入 ServiceHost 或 Plugin Loader。 | WebApi contract 草案與決策確認已完成；可先盤點程式 repo 後進入最小 WebApi 第一版實作。 |
| 4C | ServiceHost | 背景生命週期、任務協調、Adapter lifecycle、Health、Log / Trace、Operator / HostName / AppVersion、部署模型、實作前確認。 | 不提供 HTTP、不與 WebApi 混責；未確認前不新增 ServiceHost 專案或 Windows Service。 | ServiceHost contract 草案與實作前確認表完成；使用者確認後才可進程式實作。 |
| 4D | Plugin Loader | 信任來源、版本、簽章、metadata、registration、錯誤隔離、卸載與回復策略、實作前確認。 | 不掃描 plugin folder、不載入外部 DLL、不執行外部程式碼；未確認前不新增 Loader。 | Plugin Loader 信任模型與 metadata contract 草案完成；使用者確認後才可進 Loader 實作。 |

## 4. 4B WebApi 執行邊界

WebApi 預計放在 4B，原因是 HTTP 入口會變成外部系統或現場工具依賴的契約，必須先固定 API 類型、權限、錯誤格式、DTO 與 Application service mapping。

| 項目 | 4B 建議內容 |
|---|---|
| 入口定位 | 遠端任務控制、查詢、取消、狀態、Health 與 Trace 查詢的 HTTP 邊界。 |
| 只允許呼叫 | `HS.DeviceControl.Application` contract。 |
| 不允許 | Controller 直接寫 Workflow / Node 邏輯、直接操作 Adapter、直接碰 DB gateway。 |
| 主要前置 | API route 候選、DTO 命名、錯誤格式、權限模型、Log / Trace 對應。 |
| 程式實作條件 | 使用者已確認 [4B WebApi contract 草案 / 實作前確認表](phase-four-b-webapi-contract-preimplementation-checklist.md) 與 [4B WebApi 決策確認紀錄](phase-four-b-webapi-decision-confirmation.md)；下一步需先盤點程式 repo。 |

## 5. 4C ServiceHost 執行邊界

ServiceHost 預計放在 4C，原因是背景常駐入口會牽涉啟動方式、生命週期、部署、重啟恢復、Adapter 連線管理與 Health。這些規則需要在 WebApi 的 HTTP 契約穩定後再切出來，避免背景服務同時承擔 HTTP 邊界。

| 項目 | 4C 建議內容 |
|---|---|
| 入口定位 | 正式背景執行入口，負責任務協調、Adapter lifecycle、Health、Log / Trace。 |
| 只允許呼叫 | `HS.DeviceControl.Application` contract 與經確認的 Adapter 管理邊界。 |
| 不允許 | ServiceHost 同時提供 HTTP、直接承擔 API route、把流程邏輯寫進 Host。 |
| 主要前置 | 背景生命週期、啟停策略、健康檢查、重啟恢復、operator、host name、app version。 |
| 程式實作條件 | 使用者確認 `4C ServiceHost contract 草案 / 實作前確認表`。 |

## 6. 4D Plugin Loader 執行邊界

Plugin Loader 預計放在 4D，原因是它風險最高，牽涉外部 DLL 來源、版本、簽章、隔離、卸載與錯誤回復。3D 已完成 Plugin metadata 與多設備單元 Application contract，但 metadata 不等於可以執行外部程式碼。

| 項目 | 4D 建議內容 |
|---|---|
| 入口定位 | 外部設備模組或 plugin 的信任、版本、metadata、registration 與載入策略。 |
| 可沿用基礎 | 3D 的 Plugin metadata、ControlUnit、Resource Lock、Command Queue 與 Application error code。 |
| 不允許 | 未確認前掃描 plugin folder、載入外部 DLL、執行外部程式碼。 |
| 主要前置 | 信任來源、簽章、版本相容、隔離策略、卸載策略、失敗回復、審計紀錄。 |
| 程式實作條件 | 使用者確認 `4D Plugin Loader 信任模型與 metadata contract 草案 / 實作前確認表`。 |

## 7. 建議產出順序

| 順序 | 文件 / 節點 | 目的 |
|---:|---|---|
| 1 | 4A 決策確認結果回填 | 把使用者七項同意或調整回填到 4A 決策確認表。 |
| 2 | 第四階段標準 / 文件 / 施作範圍 / 驗收條件總表 | 固定第四階段總標準、文件清單、可施作項目與驗收條件。 |
| 3 | 第四階段目標模式完成稽核表 | 確認本輪文件型標準包已收斂，並保留後續程式實作停止線。 |
| 4 | 4B WebApi contract 草案 / 實作前確認表 | 已建立，固定 API route 候選、DTO、錯誤格式、權限與停止線。 |
| 5 | 4B WebApi 決策確認表 | 已確認，使用者同意採用建議路線並允許最小 WebApi 實作。 |
| 6 | 4B WebApi 第一版實作 | 下一步，先盤點程式 repo，再建立最小 WebApi 專案與測試。 |
| 7 | 4C ServiceHost contract 草案 / 實作前確認表 | 固定背景生命週期、Adapter lifecycle、Health、Log / Trace 與部署邊界。 |
| 8 | 4C ServiceHost 決策確認表 | 由使用者逐項確認是否允許進入最小 ServiceHost 實作。 |
| 9 | 4C ServiceHost 第一版實作 | 只在確認後建立最小背景入口與測試。 |
| 10 | 4D Plugin Loader 信任模型與 metadata contract 草案 | 固定信任、版本、簽章、隔離與錯誤回復策略。 |
| 11 | 4D Plugin Loader 決策確認表 | 由使用者逐項確認是否允許進入 Loader 實作。 |
| 12 | 4D Plugin Loader 第一版實作 | 只在確認後建立 Loader；外部 DLL 載入仍需視信任模型逐步開放。 |

## 8. 停止線

在 4B / 4C / 4D 任一實作前確認完成前，仍需停止：

- 不新增 `HS.DeviceControl.WebApi` 專案。
- 不新增 `HS.DeviceControl.ServiceHost` 專案。
- 不新增 Plugin Loader。
- 不新增 API route、Controller、endpoint 或 middleware。
- 不新增或更換 Web framework、認證授權、背景服務、佇列或 Plugin framework 套件。
- 不修改 Core / Adapters / Infrastructure / Application public method 簽章。
- 不修改 `devices.json` / `workflows.json` / `appsettings.json` schema。
- 不掃描 plugin folder、不載入外部 DLL、不執行外部程式碼。
- 不保存密碼、Token、IP、Port、完整 connection string、正式 DLL 路徑或正式環境資訊。
- 不執行 DB 寫入、DDL、ALTER TABLE 或正式 Apply。
- 不改程式啟動方式。
- 不接真實硬體或案場客製邏輯。

## 9. 建議下一步

4A / 4B 切分線上驗收已通過，4B WebApi contract 草案與決策確認已建立。下一步建議先唯讀盤點程式 repo 的 Application contract、solution 結構與測試專案，再進入最小 WebApi 第一版實作。

原因是 WebApi 是外部控制與查詢入口，會先決定 route、DTO、權限與錯誤格式；ServiceHost 與 Plugin Loader 可以在此基礎上保持分責，避免背景服務與外部 DLL 載入過早擴大範圍。