4C ServiceHost contract 草案 / 實作前確認表
本文件承接 4A WebApi / ServiceHost / Plugin Loader 邊界分析、第四階段 4B / 4C / 4D 執行切分表、第四階段標準 / 文件 / 施作範圍 / 驗收條件總表 與 4B WebApi 第一版實作與 API / DB 驗收紀錄，整理 4C ServiceHost 進入程式實作前需要確認的背景生命週期、Adapter lifecycle、Health、Log / Trace、部署模型、測試策略與停止線。
本文件已取得使用者七項確認，確認紀錄見 4C ServiceHost 決策確認紀錄。本次確認只授權程式 repo 結構檢查與最小 ServiceHost 第一版，不代表已同意 Windows Service 安裝、Worker Service 套件、外部 queue、正式 DB 啟動流程、部署設定、真實硬體控制或任何高風險啟動方式變更。
0. 確認狀態
| 項目 | 內容 |
|---|
| 文件狀態 | 已確認 |
| 整理日期 | 2026-06-06 |
| 確認日期 | 2026-06-06 |
| 對應階段 | 第四階段 4C ServiceHost |
| 程式 repo | hs-device-control-template |
| 程式 branch | poc/nmodbus-tcp |
| 程式基準 commit | 9527773 新增 4B WebApi 第一版與驗收測試 |
| 目前程式狀態 | 已有 HS.DeviceControl.Application、HS.DeviceControl.WebApi；尚未建立 HS.DeviceControl.ServiceHost |
| 本文件可做 | 固定 ServiceHost 定位、責任邊界、停止線、候選專案、測試策略與七項確認 |
| 本文件不做 | 不新增 Windows Service 安裝、不改 public method 簽章、不改 config schema、不執行 DB DDL、不接真實硬體 |
1. 第一版定位
4C ServiceHost 第一版的定位是「正式背景執行入口」，負責常駐生命週期、任務協調、Adapter lifecycle、Health 與 Log / Trace 串接。它不是 HTTP API，也不是新的 Workflow engine。
| 原則 | 說明 |
|---|
| ServiceHost 只做背景入口 | 負責啟動、停止、常駐迴圈、健康摘要與依賴組裝。 |
| 流程仍在 Application / Core | ServiceHost 不寫 Workflow node 邏輯，不直接修改 TaskStateMachine。 |
| HTTP 仍由 WebApi 負責 | ServiceHost 不提供 Controller、route、middleware 或 Swagger。 |
| 設備仍走 Adapter 邊界 | ServiceHost 不直接操作 PLC、COM、TCP、UDP、Modbus 或真實硬體 protocol。 |
| DB 不自動 Apply | 啟動前可做非破壞性 schema preview / health check，但不得執行 DDL、ALTER 或 Apply。 |
| 第一版不等於正式部署 | 未確認部署方式、服務帳號、Secret 管理、監控與復原策略前，不可視為正式背景服務。 |
2. 建議專案與引用方向
若使用者確認進入程式實作，第一版建議先採「console / Generic Host 風格的背景入口」，不要直接做 Windows Service 安裝或正式部署設定。
| 項目 | 建議 |
|---|
| 候選專案 | src/HS.DeviceControl.ServiceHost/HS.DeviceControl.ServiceHost.csproj |
| 候選測試專案 | tests/HS.DeviceControl.ServiceHost.Tests/HS.DeviceControl.ServiceHost.Tests.csproj |
| Target framework | net5.0，與現有 solution 一致 |
| ServiceHost 可引用 | HS.DeviceControl.Application、必要的 Core / Adapter contract |
| ServiceHost 不引用 | HS.DeviceControl.WebApi、Web controller、未確認的 Plugin Loader、未確認的正式 DB 啟動器 |
| 第一版啟動形式 | 先用 console / Generic Host 風格驗證背景 lifecycle；Windows Service 包裝另行確認 |
HS.DeviceControl.WebApi -> HS.DeviceControl.Application
HS.DeviceControl.ServiceHost -> HS.DeviceControl.Application
HS.DeviceControl.Application -> Core / Adapters / Infrastructure contracts
3. ServiceHost 責任邊界
| 類型 | 可負責 | 不可負責 |
|---|
| Host lifecycle | Starting、Running、Stopping、Stopped、Faulted 狀態摘要與 graceful stop。 | 不直接修改 Task terminal state，不把錯誤吞掉。 |
| 任務協調 | 呼叫 Application task contract，協調待執行任務與取消請求。 | 不在 Host 寫 Workflow node、NextNode、Retry 或狀態機規則。 |
| Adapter lifecycle | 透過已確認的 Adapter / dispatcher 邊界做 Connect、Disconnect、GetStatus。 | 不直接寫硬體 protocol，不直接操作 UI 或真實設備連線資訊。 |
| Health | 彙整 Host alive、Application health、Adapter status、TaskStore / Schema preview 狀態。 | 不暴露 secret、connection string、IP、Port、完整 stack trace。 |
| Log / Trace | 透過既有 LogWriter / TraceStore 記錄 TaskId、NodeId、DeviceId、CommandName、Operator、HostName、AppVersion。 | 不繞過既有錯誤處理，不直接裸寫 SQL log。 |
| Schema preview | 可在啟動前或 health 中做非破壞性 preview 摘要。 | 不執行 DDL、ALTER TABLE、正式 Apply。 |
| 部署 | 第一版只記錄候選模式與停止線。 | 不新增 Windows Service 安裝、排程器、外部 queue 或正式部署腳本。 |
4. 背景生命週期草案
| 狀態 | 語意 | 第一版驗收重點 |
|---|
Starting | Host 正在載入設定、組裝 Application service 與建立 Adapter registry。 | 啟動失敗需回傳標準錯誤並寫 log。 |
Running | Host 可接受背景任務協調與 health 查詢。 | 不在 paused / stopping 狀態執行新任務。 |
Stopping | Host 已停止接收新任務，正在處理停止流程。 | 需定義 in-flight 任務處理策略，不能直接吞掉取消或例外。 |
Stopped | Host 已完成停止與 Adapter disconnect。 | 多次 stop 應安全，不造成重複斷線錯誤。 |
Faulted | Host 啟動或執行期間遇到不可恢復錯誤。 | 需保留 ErrorCode、ExceptionType、Message 與追蹤資訊。 |
第一版 stop 行為建議採保守策略：停止接收新任務、送出取消或停止訊號、等待已確認的 Application / Core 邊界處理狀態，不在 Host 內自行改寫終態規則。
5. Adapter lifecycle 草案
| 項目 | 建議 |
|---|
| 啟動連線 | 第一版可先以 mock / in-memory Adapter 驗證 lifecycle，不接真實硬體。 |
| 連線策略 | 是否啟動時 connect all 或 lazy connect，需使用者確認後再實作。 |
| 狀態查詢 | 透過 Adapter GetStatus 或既有 Application device status contract。 |
| 停止斷線 | Host stop 時需確保 Adapter disconnect 被呼叫，且失敗時留下標準錯誤。 |
| 重試策略 | 不在本文件新增硬體重連策略；若需要重連、backoff、熔斷，需另行確認。 |
| 真實硬體 | 本輪禁止真實 PLC、COM、TCP、UDP、Modbus 或案場設備連線。 |
6. Health / Log / Trace 草案
| 類型 | 第一版建議欄位 | 注意事項 |
|---|
| Host health | status、startedAtUtc、uptimeMs、lastError、checkedAtUtc | 不暴露 secret 或完整 stack trace。 |
| Dependency health | Application、TaskStore、Adapter registry、Schema preview | 只回安全摘要。 |
| Task trace | TaskId、WorkflowId、NodeId、Status、TimeTakenMs | 透過既有 Log / Trace contract。 |
| Device trace | DeviceId、CommandName、Status、ErrorCode | 不直接記錄敏感連線資訊。 |
| Host metadata | Operator、HostName、AppVersion、Source | 需與現有 Log 規則一致。 |
7. DB 與 Schema 邊界
| 分類 | 可執行 | 不可執行 |
|---|
| 自動測試 | ServiceHost lifecycle fake tests、Application fake service、manual gate disabled 測試。 | 不要求真實 MySQL 連線。 |
| Schema preview | 可呼叫既有 ManualApplyPreview 非破壞性流程，確認 CanApply=False、DdlExecutionAllowed=False。 | 不執行 DDL。 |
| 真實 DB | 只在另行確認測試 DB、環境變數、AllowRead / AllowWrite 與 cleanup 後執行。 | 不碰正式 DB，不保存 connection string。 |
| Host startup | 可記錄 readiness 結果並決定是否進入 Faulted。 | 不在啟動時自動建表、ALTER、Apply 或 cleanup。 |
8. 測試策略
| 測試 | 目的 | 是否本輪授權 |
|---|
| Contract 文件驗證 | 確認 4C 責任、停止線、候選檔案與七項確認已整理。 | 是 |
| ServiceHost project compile | 若進入實作，確認專案與引用方向正確。 | 待確認 |
| Lifecycle tests | 驗證 start / stop / repeated stop / faulted 行為。 | 待確認 |
| Adapter lifecycle tests | 驗證 mock adapter connect / disconnect / status。 | 待確認 |
| Health tests | 驗證 Host / Application / Adapter health 摘要。 | 待確認 |
| Log / Trace tests | 驗證 Host metadata 與錯誤資訊不遺失。 | 待確認 |
| 真實 DB tests | 只在另行確認測試 DB 與 gate 後執行。 | 否 |
| Windows Service install test | 需要 OS service 模型與權限確認。 | 否 |
9. 第一版候選檔案
| 類型 | 候選檔案 |
|---|
| ServiceHost 專案 | src/HS.DeviceControl.ServiceHost/HS.DeviceControl.ServiceHost.csproj |
| 啟動入口 | src/HS.DeviceControl.ServiceHost/Program.cs |
| 背景服務 | src/HS.DeviceControl.ServiceHost/Services/* |
| Options / settings | src/HS.DeviceControl.ServiceHost/Options/*，但不改既有 config schema |
| Health / lifecycle model | src/HS.DeviceControl.ServiceHost/Models/* |
| 測試專案 | tests/HS.DeviceControl.ServiceHost.Tests/* |
| Solution | HS.DeviceControl.sln |
| 文件 | 決策確認表、實作紀錄、完成稽核、commit / push 前確認、驗收紀錄 |
10. 七項確認表
使用者已確認以下七項，可進入 4C 程式 repo 結構檢查與最小 ServiceHost 第一版實作。
| 編號 | 決策項 | 建議確認 | 實作影響 |
|---|
| 1 | 4C 先以 ServiceHost contract 草案 / 實作前確認為準 | 同意後才可把本文件視為 4C 起點。 | 目前仍不改程式。 |
| 2 | ServiceHost 第一版只做背景入口，不提供 HTTP | 同意。 | HTTP route 仍屬 WebApi。 |
| 3 | 第一版採 console / Generic Host 風格，不先做 Windows Service 安裝 | 同意。 | 降低 OS service 與部署權限風險。 |
| 4 | ServiceHost 只呼叫 Application contract，不寫 Workflow / Node 邏輯 | 同意。 | 維持 Core / Application 邊界。 |
| 5 | Adapter lifecycle 先用 mock / 已確認邊界驗證，不接真實硬體 | 同意。 | 禁止真實 PLC、COM、TCP、UDP、Modbus 連線。 |
| 6 | DB / Schema 只允許非破壞性 preview / readiness，不做 DDL / Apply | 同意。 | 避免啟動時改 DB。 |
| 7 | 進入程式實作前，需先做程式 repo 結構檢查並回報新增 / 修改檔案 | 同意。 | 使用者確認後才可新增 ServiceHost 專案與測試。 |
11. 仍需停止的項目
- 不新增
HS.DeviceControl.ServiceHost。
- 不新增 Windows Service 安裝、系統服務註冊、排程服務或部署腳本。
- 不新增外部 queue、背景服務框架或正式部署套件。
- 不提供 HTTP route、Controller、middleware 或 Swagger。
- 不建立 Plugin Loader。
- 不掃描 plugin folder。
- 不載入外部 DLL。
- 不修改 Core / Adapters / Infrastructure / Application public method 簽章。
- 不修改
devices.json / workflows.json / appsettings.json schema。
- 不執行 DB DDL、ALTER TABLE、正式 Apply 或正式 DB 寫入。
- 不保存密碼、Token、IP、Port、完整 connection string 或正式環境資訊。
- 不接真實硬體或案場客製邏輯。
12. 建議下一步
建議使用者先回覆 4C 七項確認。若七項均同意，下一步再做「4C 程式 repo 結構檢查與 stage / commit 前風險盤點」，確認 Application contract、現有 WebApi、solution 結構與測試專案後，才決定是否新增最小 ServiceHost 第一版。