本文件承接 5E Windows Service 邊界分析、實作前確認表、程式 repo 結構檢查、測試矩陣、最後確認表與最後確認表線上驗收紀錄。此工作包只整理使用者完成七項確認後的施作順序與驗收證據，不代表已授權修改程式 repo；在使用者回覆 5E 最後七項確認前，不得新增 Windows Service 程式碼、package、installer 或安裝腳本。
0. 基本資訊
| 文件日期 | 2026-06-07 |
|---|---|
| 對應節點 | 第五階段 5E Windows Service |
| 程式 repo | hs-device-control-template |
| 程式 branch | poc/nmodbus-tcp |
| 程式基準 commit | c92342b |
| 本文件是否授權程式修改 | 否；仍需使用者回覆 5E 最後七項確認 |
| 本輪 gate 前測試 | ServiceHost.Tests 7 passed / 0 failed / 0 skipped |
1. 施作前置條件
| 前置條件 | 目前狀態 |
|---|---|
| 5D auth / Swagger | 已於 c92342b 完成並完成線上驗收 |
| 5E 最後確認表 | 已建立，等待使用者七項確認 |
| 5E 最後確認表線上驗收 | 已完成 |
| 5E 程式 repo 結構檢查 | 已完成唯讀盤點 |
| ServiceHost 現況測試 | dotnet test tests\HS.DeviceControl.ServiceHost.Tests\HS.DeviceControl.ServiceHost.Tests.csproj --no-restore 通過 |
| 程式 repo 狀態 | 目前乾淨，仍停在 c92342b，尚未新增 Windows Service 實作 |
2. 確認後預計修改檔案
| 類型 | 檔案 | 目的 |
|---|---|---|
| 新增 | src/HS.DeviceControl.ServiceHost/Options/WindowsServiceHostOptions.cs | 定義非敏感 Windows Service hosting options，例如 enabled flag、service name、display name、description |
| 新增 | src/HS.DeviceControl.ServiceHost/Services/WindowsServiceHostRunner.cs | 包裝 IServiceHostRuntime，提供可測試 start / stop / status / failure mapping |
| 修改 | src/HS.DeviceControl.ServiceHost/Program.cs | 保留既有 console smoke path；只在明確設定下切換 service hosting path |
| 視確認後修改 | src/HS.DeviceControl.ServiceHost/HS.DeviceControl.ServiceHost.csproj | 若必須引用 Windows Service hosting package，需停下再次確認套件與版本 |
| 新增或修改 | tests/HS.DeviceControl.ServiceHost.Tests | 驗證 options safety、console path、runner delegation、stop behavior、fault mapping 與停止線 |
| 新增 | docs/phase-five-e-windows-service-implementation-acceptance-record.md | 記錄 5E 實作內容、測試結果、停止線掃描與 commit |
3. 建議實作順序
- 先新增非敏感 options 與 validation，不保存 service account、password、token、正式 IP、正式路徑或正式機器名稱。
- 新增可測試 runner / wrapper，僅代理
IServiceHostRuntime.Start()、Stop()、GetStatus()，不直接操作 OS service。 - 保留
Program.Main既有 console smoke path；service hosting path 必須可關閉、可回退、可用測試覆蓋。 - 若發現必須新增
Microsoft.Extensions.Hosting.WindowsServices或類似套件，先停下確認，不在未確認時引入。 - 補 ServiceHost tests，覆蓋 disabled path、start delegation、stop delegation、fault mapping 與 options safety。
- 跑 ServiceHost.Tests、Application.Tests、solution tests、停止線掃描與污染掃描。
- 建立 5E 實作與驗收紀錄，更新文件 repo、public mirror、progress / status 與線上驗收。
4. 必跑測試與驗證
| 驗證項目 | 指令或方式 | 通過條件 |
|---|---|---|
| ServiceHost tests | dotnet test tests\HS.DeviceControl.ServiceHost.Tests\HS.DeviceControl.ServiceHost.Tests.csproj --no-restore | 既有與新增 5E tests 全部通過 |
| Application tests | dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj --no-restore | Application contract 不受影響 |
| Solution tests | dotnet test HS.DeviceControl.sln --no-restore | 全 solution 測試通過 |
| Console smoke path | 執行既有 ServiceHost console path 或對應 tests | 不破壞現有 start / stop 輸出與 exit code |
| Stop-line scan | 掃描 service install、正式 account、production path、DB DDL、外部 DLL loading、plugin folder scan | 均不得命中新增實作 |
| 污染字串掃描 | 使用既定污染關鍵字清單掃描文件與程式候選檔 | 不得命中污染字串 |
5. 不可包含項目
- 不執行
sc.exe create、New-Service、service install / uninstall / delete / start / stop。 - 不保存正式 service account、password、token、正式 IP、正式網域、正式路徑、正式 log path、正式 config path 或正式機器名稱。
- 不改 GitHub、Cloudflare、secret、正式部署權限或外部服務設定。
- 不新增 DB DDL、ALTER TABLE、formal Apply、正式 DB 初始化或正式 DB 寫入。
- 不新增 WebApi auth / Swagger 程式、不變更既有 API route。
- 不載入外部 DLL、不掃描 plugin folder、不使用
Assembly.Load/LoadFrom/LoadFile。 - 不修改 Adapter public contract。
6. 5E 實作完成後應建立或更新的文件
| 文件 | 目的 |
|---|---|
phase-five-e-windows-service-implementation-acceptance-record.md | 記錄 5E 實作內容、測試結果、停止線掃描與 commit |
phase-five-e-windows-service-online-acceptance-record.md | 記錄文件網站線上驗收、首頁入口、status.json 與 progress.json |
phase-five-remaining-gate-completion-audit.md 更新版 | 將 5E 從待實作改為已完成，並更新 5F 進入條件 |
phase-five-f-integration-acceptance-preexecution-checklist.md 更新版 | 確認 5F 可執行的前置條件是否已滿足 |
7. 下一步確認格式
5E Windows Service 最小實作前最後確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意