# 5E Windows Service 實作工作包

本文件承接 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. 建議實作順序

1. 先新增非敏感 options 與 validation，不保存 service account、password、token、正式 IP、正式路徑或正式機器名稱。
2. 新增可測試 runner / wrapper，僅代理 `IServiceHostRuntime.Start()`、`Stop()`、`GetStatus()`，不直接操作 OS service。
3. 保留 `Program.Main` 既有 console smoke path；service hosting path 必須可關閉、可回退、可用測試覆蓋。
4. 若發現必須新增 `Microsoft.Extensions.Hosting.WindowsServices` 或類似套件，先停下確認，不在未確認時引入。
5. 補 ServiceHost tests，覆蓋 disabled path、start delegation、stop delegation、fault mapping 與 options safety。
6. 跑 ServiceHost.Tests、Application.Tests、solution tests、停止線掃描與污染掃描。
7. 建立 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. 下一步確認格式

```text
5E Windows Service 最小實作前最後確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意
```