# 4C ServiceHost 程式 repo 結構檢查表

本文件記錄 2026-06-06 進入第四階段 4C ServiceHost 實作前，對程式 repo `hs-device-control-template` 的結構檢查、可修改範圍與停止線確認。

本檢查承接 [4C ServiceHost contract 草案 / 實作前確認表](phase-four-c-servicehost-contract-preimplementation-checklist.md) 與 [4C ServiceHost 決策確認紀錄](phase-four-c-servicehost-decision-confirmation.md)。檢查結果確認可建立最小 ServiceHost 第一版，但不代表授權 Windows Service 安裝、外部 queue、Plugin Loader、外部 DLL、正式 DB DDL、正式 Apply、正式部署設定或真實硬體控制。

## 0. 檢查狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已完成 |
| 檢查日期 | 2026-06-06 |
| 對應階段 | 第四階段 4C ServiceHost |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 基準狀態 | 實作前工作樹乾淨 |
| 前置確認 | 使用者已確認 4C 七項決策 |
| 檢查結論 | 可新增最小 `HS.DeviceControl.ServiceHost` 與對應測試專案 |

## 1. 現有結構檢查

| 區域 | 檢查結果 | 判定 |
|---|---|---|
| Solution | `HS.DeviceControl.sln` 已包含 Core、Adapters、ConsoleHost、Infrastructure.MySql、Application、WebApi 與各測試專案 | 可新增 ServiceHost 與 ServiceHost.Tests |
| Application contract | 已有 `Tasks`、`Devices`、`Health`、`Schema` 等薄 service / contract | ServiceHost 可只呼叫 Application，不需改 public 簽章 |
| Adapter contract | 已有 `IDeviceAdapter`、`MockDeviceAdapter`、`ExecuteResult`、`DeviceConnectionStatus` | 可用 Mock Adapter 驗證 connect / disconnect / status |
| WebApi | 已有 4B WebApi 第一版與 WebApi tests | 4C 不新增 HTTP route、不改 WebApi |
| MySql / Schema | 已有 Infrastructure.MySql 與 Schema preview 相關測試 | 4C 不做 DDL、ALTER TABLE、Apply 或正式 DB 寫入 |
| Tests | 既有 xUnit 測試專案使用 net5.0 與既有套件版本 | 可新增 `HS.DeviceControl.ServiceHost.Tests` |

## 2. 預計新增檔案

| 檔案 | 原因 |
|---|---|
| `src/HS.DeviceControl.ServiceHost/HS.DeviceControl.ServiceHost.csproj` | 建立最小 ServiceHost console-style 入口專案 |
| `src/HS.DeviceControl.ServiceHost/Program.cs` | 提供本機可執行 start / stop 驗證入口 |
| `src/HS.DeviceControl.ServiceHost/Models/ServiceHostState.cs` | 定義 Host lifecycle 狀態 |
| `src/HS.DeviceControl.ServiceHost/Models/ServiceHostStatus.cs` | 定義 Host status snapshot，不外洩敏感資訊 |
| `src/HS.DeviceControl.ServiceHost/Options/ServiceHostOptions.cs` | 收斂 HostName、DeviceId、Operator、Source 等本機選項，不新增 config schema |
| `src/HS.DeviceControl.ServiceHost/Services/IServiceHostRuntime.cs` | 定義 ServiceHost runtime 的最小介面 |
| `src/HS.DeviceControl.ServiceHost/Services/ServiceHostRuntime.cs` | 實作 start / stop / status / QueueTask，僅呼叫 Application contract 與 Adapter contract |
| `tests/HS.DeviceControl.ServiceHost.Tests/HS.DeviceControl.ServiceHost.Tests.csproj` | 建立 4C 專屬 xUnit 測試專案 |
| `tests/HS.DeviceControl.ServiceHost.Tests/ServiceHostRuntimeTests.cs` | 覆蓋 lifecycle、Adapter connect/disconnect、fault、QueueTask 與 health 防外洩 |

## 3. 預計修改檔案

| 檔案 | 原因 |
|---|---|
| `HS.DeviceControl.sln` | 將 ServiceHost 與 ServiceHost.Tests 納入 solution，讓全量測試涵蓋 4C |

## 4. 明確不修改

| 不修改項目 | 原因 |
|---|---|
| `HS.DeviceControl.Core` public contract | 4C 不改 Workflow / Node / TaskEngine 邏輯 |
| `HS.DeviceControl.Application` public contract | 4C 只使用既有 Task / Device / Health contract |
| `HS.DeviceControl.WebApi` route / controller / DTO | HTTP 邊界已屬 4B，不在 4C 擴大 |
| `HS.DeviceControl.Infrastructure.MySql` | 4C 不做 DB DDL、正式 DB 寫入或 Apply |
| `devices.json`、`workflows.json`、`appsettings.json` schema | 4C 不新增正式設定格式 |
| Plugin Loader / external DLL | 屬 4D，需另行確認 |
| Windows Service install / OS service registration | 不屬 4C 第一版 |

## 5. 驗收條件

| 驗收項目 | 通過基準 |
|---|---|
| ServiceHost 專案可編譯 | `HS.DeviceControl.ServiceHost` 可 build |
| Lifecycle 測試 | start、stop、repeated stop、faulted 需通過 |
| Adapter lifecycle 測試 | Mock adapter connect / disconnect / status 需通過 |
| Application contract 使用 | QueueTask 只呼叫 `ITaskControlService.Start` |
| Health 防外洩 | status 不輸出 stack trace 或敏感連線內容 |
| 回歸測試 | Application、WebApi、全 solution 測試需通過 |
| 實際入口 | `dotnet run --project src/HS.DeviceControl.ServiceHost/HS.DeviceControl.ServiceHost.csproj` 可呈現 Running -> Stopped |

## 6. 結論

程式 repo 結構允許 4C 進入最小 ServiceHost 第一版實作。實作範圍限於新增 ServiceHost 專案、測試專案與 solution 掛載；任何正式服務安裝、外部 queue、Plugin Loader、正式 DB、DB DDL / ALTER TABLE、正式 Apply、真實硬體或 WebApi 正式安全設定仍需另行確認。