# 5E Windows Service 實作與驗收紀錄

本文件記錄第五階段 5E Windows Service 最小 hosting gate 的程式實作、測試、停止線、提交、推送與 Actions 驗收。5E 本輪只完成 ServiceHost 內可測試的 hosting gate、非敏感 options、runner delegation、console smoke path 保留與明確 `--windows-service` smoke path；沒有安裝 Windows Service，沒有新增 service installer、正式 service account、正式 log / config path、外部 DLL loading、DB DDL 或正式部署設定。

## 0. 基本資訊

| 項目 | 內容 |
|---|---|
| 驗收日期 | 2026-06-08 |
| 對應節點 | 第五階段 5E Windows Service |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式基準 commit | `c92342b` |
| 程式 commit | `0789d35` |
| Commit 訊息 | 新增 5E Windows Service 最小 hosting gate |
| GitHub Actions | `27098568634` success |
| 文件狀態 | 第一批實作、提交、推送與 Actions 驗收紀錄已建立 |

## 1. 程式修改範圍

| 類別 | 檔案 |
|---|---|
| Windows Service options | `src/HS.DeviceControl.ServiceHost/Options/WindowsServiceHostOptions.cs` |
| Windows Service runner | `src/HS.DeviceControl.ServiceHost/Services/WindowsServiceHostRunner.cs` |
| ServiceHost entry point | `src/HS.DeviceControl.ServiceHost/Program.cs` |
| ServiceHost tests | `tests/HS.DeviceControl.ServiceHost.Tests/ServiceHostRuntimeTests.cs` |

## 2. 實作內容

| 項目 | 結果 |
|---|---|
| Options | 新增 `WindowsServiceHostOptions`，預設關閉，僅保存 service name、display name、description 等非敏感識別資訊。 |
| Options validation | 阻擋敏感或環境特定字串，不回顯原始值。 |
| Runner | 新增 `WindowsServiceHostRunner`，只代理既有 `IServiceHostRuntime.Start()`、`Stop()`、`GetStatus()`，不操作 OS service。 |
| Fault mapping | runtime 例外會轉成 `APP-0004` 與安全摘要，不暴露例外原文或 stack trace。 |
| Console smoke path | 保留既有無參數 `Program.Main` 輸出與 exit code。 |
| Windows hosting smoke path | 只在明確帶入 `--windows-service` 時執行 runner smoke path，仍不執行服務安裝。 |
| Package | 未新增 `Microsoft.Extensions.Hosting.WindowsServices` 或其他 package。 |

## 3. 測試與驗收結果

| 驗證項目 | 結果 |
|---|---|
| `dotnet test tests\HS.DeviceControl.ServiceHost.Tests\HS.DeviceControl.ServiceHost.Tests.csproj --no-restore -m:1 /p:BuildInParallel=false /p:UseSharedCompilation=false` | 19 passed / 0 failed / 0 skipped。 |
| `dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj --no-restore -m:1 /p:BuildInParallel=false /p:UseSharedCompilation=false` | 67 passed / 0 failed / 0 skipped。 |
| `dotnet test HS.DeviceControl.sln --no-restore -m:1 /p:BuildInParallel=false /p:UseSharedCompilation=false` | 548 passed / 0 failed / 0 skipped。 |
| Console smoke path | `HS.DeviceControl.ServiceHost: Running...` 後 `Stopped...`，exit code 0。 |
| Windows hosting smoke path | `windows-service HS.DeviceControl.ServiceHost: Running...` 後 `Stopped...`，exit code 0。 |
| 停止線掃描 | 未命中 Windows Service 安裝 API / installer、外部 DLL loading、DB DDL、WebApi auth 擴張、plugin folder scan。 |
| 污染字串掃描 | 程式 repo 指定文件與程式範圍未命中既定污染字串；本紀錄不重複列出字串內容。 |
| 程式 repo commit / push | `0789d35` 已推送至 `poc/nmodbus-tcp`。 |
| GitHub Actions | `27098568634` completed success。 |

備註：solution 測試仍有既有 `.NET 5.0` EOL warning，與本次 5E 修改無關。

## 4. 停止線確認

本次 5E 實作沒有做下列事項：

- 不安裝、解除安裝、啟動、停止或修改任何 OS 層 Windows Service。
- 不新增 service installer、install / uninstall script、`sc.exe` 指令或 `New-Service` 流程。
- 不新增 `Microsoft.Extensions.Hosting.WindowsServices` package，也不呼叫 `UseWindowsService`。
- 不保存正式 service account、正式主機、正式 IP、正式路徑、正式 log path、正式 config path 或敏感 credential。
- 不新增 DB DDL、ALTER TABLE、DROP TABLE、formal Apply、正式 DB 初始化或正式 DB 寫入。
- 不變更 WebApi auth / Swagger、既有 API route 或 Application result mapping。
- 不載入外部 DLL、不掃描 plugin folder、不修改 Adapter public contract。

## 5. 驗收結論

5E Windows Service 最小 hosting gate 已在核准範圍內完成，並通過 ServiceHost、Application、solution 測試、兩條 smoke path、停止線掃描、污染掃描與 GitHub Actions。第五階段尚未完成，因 5F 整合驗收仍需在本文件同步、線上查核完成後，另由使用者回覆 5F 七項確認才可執行。