# 5E Windows Service 程式 repo 結構檢查與實作前盤點

本文件承接 [5E Windows Service 邊界分析](phase-five-e-windows-service-boundary-analysis.md) 與 [5E Windows Service 實作前確認表](phase-five-e-windows-service-preimplementation-checklist.md)，記錄目前程式 repo 的唯讀盤點結果與候選修改位置。此文件不代表已授權修改程式 repo。

## 0. 檢查狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已完成唯讀盤點，等待 5E 七項確認 |
| 檢查日期 | 2026-06-07 |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式基準 | `c92342b` |
| 本次是否修改程式 repo | 否 |
| 測試基準 | `HS.DeviceControl.ServiceHost.Tests` 7 passed |

## 1. 現有檔案

| 檔案 | 現況 | 5E 判斷 |
|---|---|---|
| `src/HS.DeviceControl.ServiceHost/Program.cs` | console-style smoke 入口，建立 runtime 後 start / stop。 | 可作為 service hosting path 的候選整合點，但需保留現有 path。 |
| `src/HS.DeviceControl.ServiceHost/HS.DeviceControl.ServiceHost.csproj` | `.NET 5.0`、`OutputType Exe`、未引用 Windows Service package。 | 若新增 package 需七項確認後再做。 |
| `src/HS.DeviceControl.ServiceHost/Services/ServiceHostRuntime.cs` | 已有 start / stop / queue / status 與錯誤轉換。 | 5E 應優先重用，不把 lifecycle 寫進 Program。 |
| `src/HS.DeviceControl.ServiceHost/Services/IServiceHostRuntime.cs` | Runtime public contract。 | 若需調整 public method 簽章需重新確認。 |
| `src/HS.DeviceControl.ServiceHost/Options/ServiceHostOptions.cs` | 非敏感 HostName / Operator / Source。 | 可候選補非敏感 service options。 |
| `tests/HS.DeviceControl.ServiceHost.Tests/ServiceHostRuntimeTests.cs` | 覆蓋 start、stop、fault、queue。 | 可新增 5E tests，不應移除既有測試。 |

## 2. 停止線掃描結果

| 關鍵行為 | 目前結果 |
|---|---|
| `UseWindowsService` | 未命中 |
| Windows Service package | 未命中 |
| `ServiceBase` | 未命中 |
| `IHostedService` / `BackgroundService` | 未命中 |
| `sc.exe` / service install | 未命中 |
| 正式 service account / password | 未命中 |
| 正式 log path / config path | 未固定 |

## 3. 候選實作切分

| 順序 | 候選內容 | 說明 |
|---|---|---|
| 1 | `ServiceHostWindowsServiceOptions` | 只承接非敏感欄位，例如 enabled flag、service name、display name、description。 |
| 2 | Hosting wrapper / hosted loop | 包住 `IServiceHostRuntime`，測試 start / stop / fault mapping。 |
| 3 | Program path | 在明確設定下才走 service path，預設仍可 console smoke。 |
| 4 | Manual-only runbook | 文件化 install / start / stop / uninstall，不自動執行。 |
| 5 | Tests | 驗 options validation、service path disabled、runtime delegation、stop behavior、停止線。 |

## 4. 驗證基準

| 驗證 | 指令或方式 | 結果 |
|---|---|---|
| ServiceHost tests | `dotnet test tests\HS.DeviceControl.ServiceHost.Tests\HS.DeviceControl.ServiceHost.Tests.csproj --no-restore` | 7 passed / 0 failed / 0 skipped |
| 結構掃描 | `rg UseWindowsService|WindowsService|ServiceBase|BackgroundService|IHostedService|sc.exe src tests` | 未命中真正 Windows Service 實作 |
| git 狀態 | `git status --short --branch` | 程式 repo 乾淨 |

## 5. 實作前結論

5E 可以在七項確認後進入第一批程式實作，但第一批應維持「可測試、可回退、非正式安裝」原則。未確認前不得新增 Windows Service package、installer、service install script、正式帳號、正式路徑或正式部署設定。