第四階段標準 / 文件 / 施作範圍 / 驗收條件總表

回到 docs

第四階段標準 / 文件 / 施作範圍 / 驗收條件總表

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
文件 repohs-device-control-template-docs
程式 repohs-device-control-template
程式 branchpoc/nmodbus-tcp
程式基準 commita158551 新增 3D Application contract 第一版
已完成前置第三階段總收斂確認表、4A 邊界分析、4A 決策確認表、4B / 4C / 4D 執行切分表、4A / 4B 切分線上驗收紀錄
第四階段總定位先建立正式入口標準與驗收條件，再依序進入 4B WebApi、4C ServiceHost、4D Plugin Loader 的 contract 草案與實作前確認

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 的階段歸屬與停止線。
4BWebApiWebApi contract 草案、route 候選、request / response DTO、錯誤格式、權限模型、Application service mapping、測試策略、實作前確認。未確認前不新增 HS.DeviceControl.WebApi、Controller、middleware、API route 或 Web framework / auth 套件。4B contract 草案與決策確認完成；若進程式實作，需有 WebApi 測試、啟動驗證與線上 / 本機驗收紀錄。
4CServiceHostServiceHost contract 草案、背景生命週期、Adapter lifecycle、Health、Log / Trace、Operator / HostName / AppVersion、部署模型、實作前確認。未確認前不新增 HS.DeviceControl.ServiceHost、Windows Service、排程服務、外部 queue 或啟動方式變更。4C contract 草案與決策確認完成；若進程式實作，需有 lifecycle 測試、Health 驗證與停止 / 重啟情境紀錄。
4DPlugin LoaderPlugin Loader 信任模型、metadata contract、版本相容、簽章 / 來源信任、錯誤隔離、卸載與回復策略、審計紀錄、實作前確認。未確認前不掃描 plugin folder、不載入外部 DLL、不執行外部程式碼、不改 Adapter public contract。4D 信任模型與 metadata contract 完成；若進 Loader 實作，需有測試 plugin、失敗隔離、版本不符與禁載驗證。

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-c-servicehost-contract-preimplementation-checklist.md待建立4C ServiceHost 進程式實作前的 contract 草案與確認表。
phase-four-d-plugin-loader-contract-preimplementation-checklist.md待建立4D Plugin Loader 信任模型與 metadata contract 草案。

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. 本階段不授權項目

9. 建議下一步

第四階段標準包完成後，建議先做 stage / commit 前確認，將 4A / 4B 線上驗收紀錄、本文件與目標模式完成稽核表一起提交。

提交後若要繼續第四階段，建議優先建立 4B WebApi contract 草案 / 實作前確認表，先固定 route、DTO、權限、錯誤格式、測試策略與停止線，再決定是否進入 WebApi 第一版程式實作。