# 4C ServiceHost 實作與驗收紀錄

本文件記錄 2026-06-06 第四階段 4C ServiceHost 第一版的本機實作、驗證結果與限制。此紀錄承接 [4C ServiceHost 程式 repo 結構檢查表](phase-four-c-servicehost-code-structure-preimplementation-checklist.md)。

本次完成的是「最小 ServiceHost 背景入口」：以 console-style 專案驗證 Host lifecycle、Adapter lifecycle、Application contract 呼叫與 health 防外洩。這不是 Windows Service 安裝，也不是正式部署模型。

## 0. 實作狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已完成 |
| 實作日期 | 2026-06-06 |
| 對應階段 | 第四階段 4C ServiceHost |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式 repo commit | 尚未 commit，待使用者確認 stage / commit / push |
| 實作結論 | 4C ServiceHost 第一版本機驗證通過 |

## 1. 新增程式內容

| 區域 | 內容 |
|---|---|
| ServiceHost project | 新增 `src/HS.DeviceControl.ServiceHost/HS.DeviceControl.ServiceHost.csproj` |
| Entry point | 新增 `Program.cs`，建立 in-memory / Mock Adapter runtime 並執行 start / stop |
| Runtime | 新增 `IServiceHostRuntime` 與 `ServiceHostRuntime` |
| State model | 新增 `ServiceHostState`：`Created`、`Starting`、`Running`、`Stopping`、`Stopped`、`Faulted` |
| Status model | 新增 `ServiceHostStatus`，回報 HostName、DeviceId、DeviceStatus、HealthState、LastError |
| Options | 新增 `ServiceHostOptions`，只保存本機 HostName / DeviceId / Operator / Source |
| Tests | 新增 `tests/HS.DeviceControl.ServiceHost.Tests` 與 `ServiceHostRuntimeTests` |
| Solution | `HS.DeviceControl.sln` 已納入 ServiceHost 與 ServiceHost.Tests |

## 2. 行為邊界

| 行為 | 實作結果 |
|---|---|
| Start | 連接 Adapter，檢查 Health，成功後進入 `Running` |
| Stop | 呼叫 Adapter disconnect，成功後進入 `Stopped` |
| Repeated stop | 已停止狀態再次 stop 會安全回傳 `ServiceHost is already stopped.` |
| Adapter connect fail | 進入 `Faulted`，保留錯誤碼並嘗試 disconnect |
| QueueTask | 僅在 `Running` 時呼叫 `ITaskControlService.Start` |
| Not running QueueTask | 回傳 `APP-0004`，不建立 task |
| Health exception | 轉為 failed health status，不把 stack trace 放入 ServiceHost status message |

## 3. 驗證結果

| 驗證項目 | 指令 / 方式 | 結果 |
|---|---|---|
| ServiceHost tests | `dotnet test tests\HS.DeviceControl.ServiceHost.Tests\HS.DeviceControl.ServiceHost.Tests.csproj` | Passed，7 / 7 |
| Application 回歸 | `dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj` | Passed，30 / 30 |
| WebApi 回歸 | `dotnet test tests\HS.DeviceControl.WebApi.Tests\HS.DeviceControl.WebApi.Tests.csproj` | Passed，7 / 7 |
| 全 solution 回歸 | `dotnet test HS.DeviceControl.sln` | Passed，482 / 482 |
| ServiceHost 主程式 | `dotnet run --project src\HS.DeviceControl.ServiceHost\HS.DeviceControl.ServiceHost.csproj` | `Running device=Connected health=Healthy` -> `Stopped device=Disconnected health=Healthy` |

## 4. 驗證節點

| 項目 | 內容 |
|---|---|
| 驗證節點名稱 | 4C ServiceHost 最小背景入口驗證 |
| 驗證目的 | 確認 ServiceHost 可用既有 Application / Adapter contract 完成 start、stop、health、QueueTask 與錯誤停止線 |
| 驗證方式 | ServiceHost 專屬 xUnit、Application / WebApi 回歸、全 solution 測試與主程式入口執行 |
| 實際結果 | 全部通過；ServiceHost 主程式可完成 Running -> Stopped |
| 是否符合預期 | 符合 |
| 發現問題或限制 | .NET 5.0 已 EOL，測試時會出現 NETSDK1138 warning；此為既有技術決策限制，不是 4C 新增錯誤 |
| 建議下一步 | 進行程式 repo stage / commit 前確認，再由使用者決定是否 commit / push |

## 5. 明確未做

- 未建立 Windows Service 安裝或 OS service registration。
- 未新增外部 queue、background worker 套件或正式排程模型。
- 未建立 Plugin Loader、plugin folder、外部 DLL 掃描或載入。
- 未修改 Application / Core / Adapter public method 簽章。
- 未修改 config schema。
- 未執行 DB DDL、ALTER TABLE、Apply、正式 DB 寫入或真實硬體連線。
- 未新增 WebApi route、auth、Swagger 或正式部署設定。

## 6. 結論

4C ServiceHost 第一版已完成本機實作與驗證。功能已足以作為後續正式 ServiceHost / Worker Service / Windows Service 化之前的安全基準；但目前仍需先完成 stage / commit 前確認，並由使用者決定是否 commit / push。