第四階段標準 / 文件 / 施作範圍 / 驗收條件總表
1. 文件定位
本文件定義第四階段的總標準、文件交付項目、施作範圍與驗收條件，承接第三階段總收斂與 4A 邊界分析結果。
本文件不代表已授權新增 HS.DeviceControl.WebApi、HS.DeviceControl.ServiceHost、Plugin Loader、API route、Controller、middleware、背景服務套件、認證授權套件、外部 DLL 載入、config schema 調整、public method 簽章變更、正式 DB DDL 或真實硬體控制。
2. 目前基準
| 項目 | 內容 |
| 文件整理日期 | 2026-06-06 |
| 文件 repo | hs-device-control-template-docs |
| 程式 repo | hs-device-control-template |
| 程式 branch | poc/nmodbus-tcp |
| 程式基準 commit | 6f34bb9 新增 4D 最小 Application plugin contract；已 push 並通過 Actions run 27064992270 |
| 已完成前置 | 第三階段總收斂確認表、4A 邊界分析、4A 決策確認表、4B / 4C / 4D 執行切分表、4B WebApi 第一版、4C ServiceHost 第一版與 4D 最小 Application plugin contract |
| 線上驗收 | 已建立 phase-four-final-online-acceptance-record.md，確認 Cloudflare Pages status.json、第四階段完成確認表與 4D commit / push 前確認頁均反映 6f34bb9 與 Actions success |
| 第四階段總定位 | 先完成正式入口最小標準，再以 4B WebApi、4C ServiceHost、4D 最小 Application plugin contract 分段收斂；真正動態 Loader 與外部 DLL 載入仍屬後續授權範圍 |
3. 第四階段總標準
| 標準項 | 定義 | 驗收方式 |
| 分層標準 | WebApi、ServiceHost、現場工具不得重寫 Workflow 或 Adapter 操作，應透過 HS.DeviceControl.Application contract 承接。 | 文件需明確列出可呼叫層與禁止呼叫層。 |
| 契約先行 | 任何正式入口進程式實作前，需先有 contract 草案、決策確認表與實作前確認表。 | 檢查對應文件是否存在，且列出 route / DTO / lifecycle / trust model / 停止線。 |
| 逐階段推進 | 第四階段依序切分為 4A、4B、4C、4D，不把 WebApi、ServiceHost 與 Plugin Loader 混在同一個未確認實作。 | 檢查切分表與進度文件是否一致。 |
| 安全停止線 | 未確認前不新增正式入口、不改 public method 簽章、不改 config schema、不執行 DB DDL、不載入外部 DLL。 | 每份前置文件需保留停止線。 |
| 驗收可追溯 | 每個可驗收節點需留下實作前確認、實作紀錄、完成稽核、線上驗收或測試證據。 | README、docs 索引、progress、首頁與 public 鏡像需同步。 |
| 文件 / 程式同步 | 程式 repo 若有實作，文件 repo 需同步 commit、測試數、commit SHA 與線上驗收紀錄。 | stage / commit 前確認與線上驗收紀錄需包含程式與文件 repo 狀態。 |
4. 階段施作範圍
| 階段 | 主題 | 可施作 | 不可施作 | 完成基準 |
| 4A | 正式入口前置確認 | 邊界分析、七項決策確認、4B / 4C / 4D 切分、線上驗收紀錄、第四階段總標準。 | 不新增正式入口、不新增 route、不建立 Loader、不改 public method 簽章、不改 config schema。 | 4A 文件包完整，能回答 WebApi、ServiceHost、Plugin Loader 的階段歸屬與停止線。 |
| 4B | WebApi | WebApi contract 草案、route 候選、request / response DTO、錯誤格式、權限模型、Application service mapping、測試策略、實作前確認與第一版 WebApi。 | 未確認前不新增 HS.DeviceControl.WebApi、Controller、middleware、API route 或 Web framework / auth 套件；完成後仍不代表正式外網安全模型。 | 4B WebApi 第一版已完成；WebApi tests 7 passed、solution tests 475 passed，本機 API 與 DB 非破壞性驗收通過。 |
| 4C | ServiceHost | ServiceHost contract 草案、背景生命週期、Adapter lifecycle、Health、Log / Trace、Operator / HostName / AppVersion、部署模型、實作前確認與第一版 ServiceHost。 | 未確認前不新增 HS.DeviceControl.ServiceHost、Windows Service、排程服務、外部 queue 或啟動方式變更；完成後仍不代表 Windows Service 安裝。 | 4C ServiceHost 第一版已完成；ServiceHost tests 7 passed、solution tests 482 passed，主程式 Running -> Stopped。 |
| 4D | Plugin Loader | Plugin Loader 信任模型、metadata contract、版本相容、簽章 / 來源信任、錯誤隔離、卸載與回復策略、審計紀錄、實作前確認；本階段只落地最小 Application plugin contract。 | 未確認前不掃描 plugin folder、不載入外部 DLL、不執行外部程式碼、不改 Adapter public contract；4D 最小 contract 完成後仍不代表真正 Loader 完成。 | 4D 最小 Application plugin contract 已完成 commit 6f34bb9 並 push；Application.Tests 40 passed、solution tests 492 passed，Actions run 27064992270 success，Loader / DLL 停止線掃描無命中。 |
5. 文件交付清單
| 文件 | 狀態 | 目的 |
phase-four-a-boundary-analysis.md | 已建立 | 定義 4A 正式入口前置邊界。 |
phase-four-a-decision-confirmation.md | 已建立 | 供使用者逐項確認 4A 七項決策。 |
phase-four-execution-split-plan.md | 已建立 | 明確切分 WebApi 在 4B、ServiceHost 在 4C、Plugin Loader 在 4D。 |
phase-four-4a-4b-split-online-acceptance-record.md | 已建立 | 記錄 4A / 4B 切分文件線上發布驗收。 |
phase-four-standards-scope-acceptance.md | 本次新增 | 定義第四階段總標準、施作範圍與驗收條件。 |
phase-four-goal-completion-audit.md | 本次新增 | 稽核本次目標模式是否完成文件型標準包。 |
phase-four-b-webapi-contract-preimplementation-checklist.md | 已確認 | 4B WebApi 進程式實作前的 contract 草案與確認表。 |
phase-four-b-webapi-implementation-acceptance-record.md | 已完成 | 4B WebApi 第一版實作、API 測試、solution 測試與本機 / DB 非破壞性驗收紀錄。 |
phase-four-c-servicehost-contract-preimplementation-checklist.md | 已確認 | 4C ServiceHost 進程式實作前的 contract 草案與確認表。 |
phase-four-c-servicehost-implementation-acceptance-record.md | 已完成 | 4C ServiceHost 第一版實作、lifecycle 測試、solution 測試與 Running -> Stopped 驗收紀錄。 |
phase-four-d-pluginloader-boundary-analysis.md | 已建立 | 4D PluginLoader 信任模型、metadata contract、版本相容、隔離、卸載、回復與停止線。 |
phase-four-d-pluginloader-decision-confirmation.md | 已確認 | 4D PluginLoader 七項決策確認表，使用者已同意，可進入 contract 草案 / 實作前確認表。 |
phase-four-d-pluginloader-contract-preimplementation-checklist.md | 已確認 | 4D PluginLoader metadata、verification result、state、audit、候選檔案、測試策略與停止線七項 contract 決策已確認。 |
phase-four-d-pluginloader-code-structure-preimplementation-checklist.md | 已完成 | 4D PluginLoader 程式 repo 唯讀結構檢查、Application.Plugins 承接位置、候選檔案與停止線。 |
phase-four-d-pluginloader-application-contract-preimplementation-checklist.md | 已確認 | 4D 最小 Application plugin contract 實作前最後確認表，固定候選檔案、欄位、測試策略與停止線。 |
phase-four-d-pluginloader-application-contract-implementation-record.md | 已完成 | 4D 最小 Application plugin contract 第一版實作、測試、commit / push 與 Actions 驗收紀錄。 |
phase-four-d-pluginloader-completion-audit.md | 已完成 | 判定 4D 就最小 Application plugin contract 已完成 commit / push / Actions，並保留真正 Loader 停止線。 |
phase-four-final-completion-confirmation.md | 已完成 | 收斂 4A、4B、4C、4D 完成狀態，作為第四階段最小範圍完成確認。 |
phase-four-d-pluginloader-application-contract-commit-push-precheck.md | 已完成 | 固定 4D stage 範圍、commit 訊息，並補充 commit 6f34bb9、push 與 Actions success。 |
phase-four-final-online-acceptance-record.md | 已完成 | 記錄 Cloudflare Pages、status.json、第四階段完成確認表、4D commit / push 前確認頁與 Actions 的線上驗收結果。 |
6. 驗收條件
| 驗收面向 | 通過條件 | 本文件包要求 |
| 文件完整性 | 標準、文件清單、施作範圍、驗收條件、停止線均已明確列出。 | 本文件需覆蓋 4A、4B、4C、4D。 |
| 索引同步 | README、docs 索引、首頁、開發進度總覽與 progress.json 均能找到新文件。 | 更新 source 與 public 鏡像。 |
| public 鏡像 | docs/ 與 public/docs/ 對應檔案 hash 一致。 | 每次文件完成後檢查 SHA256。 |
| JSON 可讀 | progress.json 與 public/progress.json 可解析。 | 使用 PowerShell ConvertFrom-Json 檢查。 |
| 污染掃描 | AGENTS、README、docs、txt、log、html、json 未出現既定污染字串。 | 使用既定 rg 關鍵字掃描。 |
| 程式邊界 | 本目標不修改程式 repo，不新增正式入口或 Loader。 | git status 僅應顯示文件 repo 變更。 |
| 後續實作門檻 | 4B / 4C / 4D 任一程式實作前，需有對應實作前確認與使用者確認。 | 未確認前不得自行進入程式修改。 |
7. 驗證節點標準
| 節點 | 觸發時機 | 需包含 |
| 文件驗收節點 | 第四階段標準包、contract 草案或稽核表完成後。 | 文件路徑、索引同步、public 鏡像、JSON、污染掃描、diff 檢查。 |
| 程式驗收節點 | 4B / 4C / 4D 任一程式實作完成後。 | 測試命令、通過數、失敗限制、實際輸出、影響範圍與停止線。 |
| 線上驗收節點 | 文件 repo push 後。 | Cloudflare Pages URL、HTTP 結果、內容比對、Actions 狀態與限制。 |
| 架構停止線稽核 | 任一階段要跨越 public method、config schema、外部 DLL、DB DDL 或正式硬體前。 | 風險、回復策略、需使用者確認項目與不可自動執行項目。 |
8. 本階段不授權項目
- 不新增
HS.DeviceControl.WebApi專案。 - 不新增
HS.DeviceControl.ServiceHost專案。 - 不新增 API route、Controller、endpoint 或 middleware。
- 不新增或更換 Web framework、認證授權、背景服務、佇列或 Plugin framework 套件。
- 不修改 Core / Adapters / Infrastructure / Application public method 簽章。
- 不修改
devices.json/workflows.json/appsettings.jsonschema。 - 不建立 Plugin Loader。
- 不掃描 plugin folder。
- 不載入外部 DLL。
- 不保存密碼、Token、IP、Port、完整 connection string、正式 DLL 路徑或正式環境資訊。
- 不執行 DB 寫入、DDL、ALTER TABLE 或正式 Apply。
- 不改程式啟動方式。
- 不接真實硬體或案場客製邏輯。
9. 建議下一步
第四階段最小範圍已完成程式 repo 與文件網站收斂：4D commit 6f34bb9 已 push，Actions run 27064992270 success，Cloudflare Pages 線上驗收已通過。建議下一步規劃後續授權節點，例如真正 PluginLoader / 外部 DLL 載入安全決策、WebApi 正式部署安全模型、DB audit table 或第五階段前置分析。
真正 PluginLoader、外部 DLL 載入、config schema、Adapter contract、DB audit table、WebApi auth / Swagger 與正式部署設定仍需另行確認。