# 5E Windows Service 邊界分析

本文件承接 [第五階段 Loader 到 Service 後續文件 / 實作 / 驗收範圍補齊表](phase-five-loader-to-service-scope-acceptance-plan.md) 與 [5D auth / Swagger 實作前文件線上驗收紀錄](phase-five-d-auth-swagger-preimplementation-online-acceptance-record.md)。5E 的主題是讓既有 `HS.DeviceControl.ServiceHost` 具備正式 Windows Service 化的前置邊界，但本文件不代表已授權修改程式 repo、安裝 service 或改變啟動方式。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已建立，等待 5E 七項確認 |
| 建立日期 | 2026-06-07 |
| 對應節點 | 第五階段 5E Windows Service |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式基準 | `c92342b` |
| 本次是否修改程式 repo | 否，只做唯讀檢查、測試基準與文件整理 |
| 目前前置狀態 | 5D auth / Swagger 已於 `c92342b` 完成並完成線上驗收；5E 前置文件與最後確認 gate 已建立，仍需七項確認後才可修改程式 repo 或新增 Windows Service |

## 1. 既有 ServiceHost 狀態

| 檢查項目 | 結果 |
|---|---|
| 專案 | `src/HS.DeviceControl.ServiceHost/HS.DeviceControl.ServiceHost.csproj` |
| 目標框架 | `.NET 5.0` |
| 輸出型態 | Console-style `Exe` |
| 入口 | `Program.Main` 直接建立 `ServiceHostRuntime`、啟動、輸出狀態後停止 |
| Runtime | `ServiceHostRuntime` 已具備 `Start`、`Stop`、`GetStatus`、`QueueTask` |
| Options | `ServiceHostOptions` 目前只有 `HostName`、`Operator`、`Source` |
| 測試基準 | `dotnet test tests\HS.DeviceControl.ServiceHost.Tests\HS.DeviceControl.ServiceHost.Tests.csproj --no-restore` 通過 7 tests |

## 2. 尚未存在的 Windows Service 能力

| 能力 | 目前狀態 | 風險 |
|---|---|---|
| `UseWindowsService` | 未存在 | 會改變 host lifetime 與部署方式 |
| Worker / hosted service | 未存在 | 會改變啟動與停止模型 |
| service install / uninstall | 未存在 | 需要系統權限與正式機器確認 |
| recovery policy | 未存在 | 會影響故障後重啟行為 |
| service account | 未存在 | 涉及權限、檔案路徑、網路資源與資安 |
| log / config path | 未固定 | 正式路徑需避免寫入 repo 或使用者目錄 |
| manual-only 驗證腳本 | 未存在 | 需要 gate，避免 CI 或一般開發機誤執行 |

## 3. 建議 5E 第一批邊界

| 項目 | 建議 |
|---|---|
| 實作範圍 | 先建立 Windows Service hosting contract / options / hosted loop 的最小程式結構。 |
| 安裝範圍 | 第一批不自動安裝正式服務；只建立 manual-only runbook 或 script 草案。 |
| 權限 | 不寫正式 service account、密碼、IP、正式路徑或正式機器資訊。 |
| 啟動方式 | 保留既有 console smoke path；新增 Windows Service path 前需可測試與可回退。 |
| 測試策略 | Unit tests 驗證 options、lifecycle、停止、錯誤回報與不進 CI 的 manual-only gate。 |
| 文件 | 實作後需建立 5E 實作與驗收紀錄，列出本機測試、停止線與未完成項。 |

## 4. 明確排除

- 不在未確認前安裝 Windows Service。
- 不執行 `sc.exe create`、PowerShell service install 或任何系統服務註冊。
- 不修改 GitHub、Cloudflare、Secret、正式機器或部署權限設定。
- 不寫入正式 service account、密碼、token、正式 IP、正式路徑或正式網域。
- 不新增 DB DDL、formal Apply、WebApi auth / Swagger 程式、外部 DLL 載入或真實硬體控制。
- 不改 Adapter public contract、既有 API route 或正式資料庫連線。

## 5. 建議下一步

請先確認 [5E Windows Service 實作前確認表](phase-five-e-windows-service-preimplementation-checklist.md) 七項。確認前，5E 只能停留在文件、唯讀檢查與測試基準；確認後才可進入 Windows Service 第一批程式實作。