第三階段執行儀表板
本文件承接 第三階段前置規劃、TaskTraceStore public 查詢介面實作前確認 與 ManualApplyPreview 實作前確認，用來把第三階段拆成可執行、可驗收、可顯示在首頁專案總攬的主線。
本文件只整理第三階段執行項目與狀態，不代表已同意導入 WebApi、ServiceHost、Plugin Loader、正式 DB Apply、外部 DLL 載入、真實硬體控制或修改 public method 簽章。
第三階段定位
第三階段的核心目標不是一次完成完整平台，而是把第一階段控制核心與第二階段 MySQL / Trace / Schema Automation 基礎，逐步接到正式平台入口前的必要能力。
第三階段應遵守以下原則：
- 先完成 read-side 查詢與 DB 初始化安全流程，再討論 WebApi / ServiceHost。
- 先固定 public contract 與資料邊界，再讓 UI 或 API 依賴。
- 不直接把正式 DB DDL、外部 DLL、背景服務或遠端 API 混在同一批變更。
- 每個主線完成後都要更新首頁、進度文件與驗證紀錄。
第三階段總覽
| 主線 | 目標 | 目前狀態 | 下一個可執行項目 |
| 3A Trace 查詢能力 | 讓未來 Debug Tool、ServiceHost 或 WebApi 可查任務 trace。 | 已完成真實測試 DB write/read/cleanup 補驗 | 已收斂，作為 3B 前置基礎。 |
| 3B DB 初始化安全流程 | 讓 Host 啟動前可檢查、預覽 schema 差異，但不直接正式 Apply。 | 第一版完成稽核與線上驗收已完成 | 可另行確認真實 DB read-only preview 驗證。 |
| 3C 正式執行入口 | 規劃 ServiceHost / WebApi 的任務啟動、查詢、取消與設備狀態 API。 | Application contract 線上驗收已完成 | commit aee6ab6 已推送，文件網站已完成 3C 線上內容比對。 |
| 3D 平台化擴充 | 規劃 Plugin DLL、多設備單元、Resource Lock、Command Queue 與設定版本控管。 | Application contract 第一版已完成 | 已完成 3D Plugin / 多設備單元邊界分析、3D Plugin / 多設備單元決策確認表、3D contract 草案 / 實作前確認表、3D contract 決策確認表、3D 程式 repo 結構檢查、3D 程式 repo 結構檢查線上驗收紀錄、3D Application contract 草案 / 實作前確認表、3D Application contract 決策確認表、3D Application contract 第一版實作紀錄、3D Application contract commit / push 前確認 與 3D 完成稽核表。 |
3A Trace 查詢能力
目標
讓系統能用標準 read-side contract 查詢 task_log_traces，作為未來 Debug Tool、ServiceHost、WebApi 與資料庫儀表板的共同基礎。
已完成
| 項目 | 狀態 | 說明 |
task_log_traces schema | 已完成 | 第二階段 B 已完成 schema class、測試 DB DDL 與 comment / index 驗證。 |
MySqlLogWriter | 已完成 | 已可寫入 trace，並具備 sanitizer 與 fallback。 |
| 真實測試 DB 寫入 / 查詢 / cleanup | 已完成 | manual-only 驗證已完成。 |
| 查詢邊界設計 | 已完成 | 已定義 read-side 角色、查詢條件、SQL 安全與停止線。 |
| public 查詢介面實作前確認 | 已完成 | 已整理 request / result model 候選、驗證規則、錯誤碼與測試策略。 |
| 程式 repo 命名與 DTO 位置盤點 | 已完成 | 已確認 Core Result 非泛型、MySQL infrastructure 採同步 Store / Gateway / SQL Builder 慣例，建議 ITaskTraceStore 與 DTO 放在 Core.Logging。 |
ITaskTraceStore public contract | 已完成 | 使用者已同意 5 點，程式 commit f2958d3 已新增 contract 與 DTO。 |
| fake gateway 查詢實作 | 已完成 | 已完成 MySqlTaskTraceStore、參數化 SQL、HasMore 分頁、遮罩與錯誤測試。 |
| manual-only 查詢驗證入口 | 已完成 | 程式 commit a9c9eca 已新增 gated xUnit 與 runner，預設不連 DB。 |
| read-only 候選探查腳本 | 已完成 | 程式 commit 2c817ec 已新增 run-mysql-tasktrace-candidate-probe.ps1，固定 ExpectedMinRows=0 供正式補驗前找出可用 TaskId。 |
| read-only 候選探查結果 | 已執行未命中 | 使用者於 2026-06-04 執行 2026-01-01 至 2026-06-04 查詢，Success=True、ItemCount=0、HasMore=False、2 個 manual 測試通過。 |
| write/read/cleanup 補驗入口 | 已完成 | 程式 commit fa874f4 已新增 run-mysql-tasktrace-write-read-cleanup-validation.ps1，需同時確認 AllowWrite、AllowRead 與 Cleanup。 |
| write/read/cleanup 補驗結果 | 已完成 | 已在測試 DB 寫入 2 筆 manual-tasktrace-e2e- trace、TaskTraceStore 查回 2 筆、HasMore=False、cleanup 刪除 2 筆。 |
驗證結果
| 順序 | 項目 | 產出 | 是否需先確認 |
| 3A-1 | 真實測試 DB read-only 查詢驗證 | 已執行 SELECT 且 Success=True，但原測試 DB ItemCount=0；此為補驗前背景，後續 write/read/cleanup 已收斂 | 已回填限制。 |
| 3A-2 | read-only 候選探查 | 2026-01-01 至 2026-06-04 查詢 Success=True、ItemCount=0 | 已確認測試 DB 無既有 trace rows。 |
| 3A-3 | write/read/cleanup 補驗 | 寫入 2 筆 manual trace、查回 2 筆、cleanup 刪除 2 筆 | 已完成。 |
| 3A-4 | 驗證結果回填 | 已同步首頁、進度總覽、第三階段儀表板與驗證紀錄 | 已完成。 |
停止線
- 未確認前不得導入 WebApi endpoint。
- 未確認前不得連真實 DB 執行查詢或寫入。
- 後續若再次執行測試 DB write/read/cleanup，仍需限制在測試 DB、
task_log_traces與manual-tasktrace-e2e-測試資料範圍。 - 不得執行 DDL、正式 DB 寫入或跨本次測試資料的 cleanup。
- 不得把查詢能力混入
ITaskStore.Save或ILogWriter。
3B DB 初始化安全流程
目標
讓 ConsoleHost / 未來 ServiceHost 在啟動前可以檢查 schema 狀態、產生 preview 與風險摘要，但不直接正式執行 DDL。
已完成 / 待驗證
| 順序 | 項目 | 產出 | 是否需先確認 |
| 3B-1 | ManualApplyPreview 實作前確認 | 已完成 ManualApplyPreview 實作前確認，整理 preview model、風險分類、輸出格式與停止線 | 已完成。 |
| 3B-2 | 決策確認 | 使用者已依 3B ManualApplyPreview 決策確認表 同意七項決策 | 已完成。 |
| 3B-3 | Apply preview model 實作 | 程式 commit 13c14ca 已新增 preview model、PlanHash、CanApply=False、Blocked、Low/Medium/High/Critical 風險分級 | 已完成。 |
| 3B-4 | Dry-run preview 輸出實作 | 已輸出 SQL preview 與風險摘要，不執行 DDL，不開放正式 Apply | 已完成。 |
| 3B-5 | ConsoleHost 顯示與人工驗證 | dotnet run 已確認輸出 PlanHash、CanApply=False、Risk=Low、Blocked=False 與 SQL preview | 已完成。 |
| 3B-6 | 真實 DB read-only preview 驗證 | 尚未執行；需另行確認連線資訊、密碼環境變數與 read-only gate，不得執行 DDL | 需要先確認。 |
| 3B-7 | 完成稽核表 | 已完成 ManualApplyPreview 3B 完成稽核表，判定第一版可驗收完成 | 已完成。 |
| 3B-8 | 線上驗收紀錄 | 已完成 ManualApplyPreview 3B 線上驗收紀錄，確認 Cloudflare Pages 首頁、稽核頁與 status.json 已反映 3B 狀態 | 已完成。 |
停止線
- 不得在未確認前執行正式 DDL。
- 不得對正式 DB 做 ALTER TABLE。
- 不得把 Apply 接入預設啟動流程。
- 不得保存 DB 密碼或連線字串到 repo。
3C 正式執行入口
目標
規劃未來正式背景服務與遠端 API 的責任邊界，讓 Server 能啟動任務、查詢任務、取消任務、查設備狀態，但不破壞 Core / Adapter 分層。
已完成 / 待確認
| 項目 | 目的 | 備註 |
| ServiceHost 邊界分析 | 決定背景常駐、重啟恢復、健康檢查與 log 策略。 | 已完成 3C Service / API 邊界分析，先分析，不建專案。 |
| WebApi 邊界分析 | 決定 Task Control API、Device Status API、查詢 API 與權限。 | 已完成候選 API 類型與停止線整理，先分析，不建 endpoint。 |
| Application Service 邊界分析 | 釐清 ServiceHost 與 WebApi 共用的任務控制、Trace 查詢、設備狀態與 schema preview 協調層。 | 已完成候選服務整理，但是否新增 contract 需另行決策。 |
| 3C 決策確認表 | 將 Application Service、ServiceHost、WebApi、Task Control、Device Status、Schema Preview 與停止線整理成七項確認。 | 使用者已同意七項決策，程式 repo 結構檢查與實作前確認已完成。 |
| 程式 repo 結構檢查與實作前確認 | 唯讀盤點 Solution、既有 Core / Adapter / Infrastructure 能力、尚未存在的 Application / ServiceHost / WebApi 邊界與候選檔案。 | 已完成 3C 程式 repo 結構檢查與實作前確認，不改程式、不新增專案。 |
| Application Service contract 草案 / 實作前確認表 | 將新增 Application 專案、引用方向、Task Control、Device Status、Schema Preview、Health 與停止線整理成七項確認。 | 已完成 3C Application Service contract 草案 / 實作前確認表，且已整理 3C Application contract 決策確認紀錄。 |
| Application contract 第一版實作 | 新增 Application 專案、測試專案、Task / Device / Schema / Health contract 與薄 service。 | 已完成 3C Application contract 第一版實作紀錄，Application tests 15 passed，solution tests 453 passed。 |
| 3C 完成稽核 | 確認 3C 是否符合已確認範圍、測試與停止線。 | 已完成 3C Application contract 完成稽核表。 |
| 3C commit / push 前確認 | 確認程式 repo 與文件 repo 的變更範圍、測試證據、停止線與建議 commit 訊息。 | 已完成 3C Application contract commit / push 前確認。 |
| 3C 線上驗收紀錄 | 確認文件 repo push 後，Cloudflare Pages 首頁、第三階段儀表板、3C 提交前確認頁與 status.json 已反映 3C 狀態。 | 已完成 3C Application contract 線上驗收紀錄。 |
| API / Service 驗證節點設計 | 定義何時需要人工驗證效果。 | 已透過 3C Application contract 第一版驗證節點完成程式測試與停止線確認；WebApi / ServiceHost 驗證仍需另行確認後才可建立。 |
| 操作身分與權限模型 | 確認 Operator、HostName、AppVersion 與授權策略。 | 已列為尚待決策，會影響正式使用流程。 |
停止線
- 未確認前不新增 WebApi 專案。
- 未確認前不新增 ServiceHost 專案或改啟動方式。
- 未確認前不新增 API route。
- 未確認前不導入認證授權套件。
3D 平台化擴充
目標
讓共用骨架未來可支援外部 DLL、真實設備模組、多設備單元共用控制主機、資源鎖與命令佇列。
已完成 / 待執行
| 項目 | 目的 | 備註 |
| 3D 邊界分析 | 釐清外部 DLL、多設備單元、Resource Lock、Command Queue、設定版本與停止線。 | 已完成 3D Plugin / 多設備單元邊界分析，不載入 DLL、不改程式。 |
| 3D 決策確認表 | 將多設備單元命名、Resource Lock、Command Queue、Plugin metadata、Adapter contract 與停止線整理成七項確認。 | 使用者已同意七項決策；已回填 3D Plugin / 多設備單元決策確認表。 |
| 3D contract 草案 / 實作前確認表 | 將多設備單元 DTO、Resource Lock、Command Queue、Plugin metadata、Adapter contract 穩定性、測試策略與停止線整理成七項確認。 | 已確認 3D contract 草案 / 實作前確認表。 |
| 3D contract 決策確認表 | 將 3D contract 七項決策整理成可逐項回覆的確認表。 | 使用者已同意七項決策；已回填 3D contract 決策確認表。 |
| 3D 完成稽核表 | 對照目標模式要求，列出已完成文件、停止線與後續 stage / commit / push / 部署查驗。 | 已完成 3D Plugin / 多設備單元完成稽核表，判定 3D contract 前置節點可驗收。 |
| 3D 線上驗收紀錄 | 記錄文件 repo push 後 Cloudflare Pages 首頁、第三階段儀表板、3D 稽核頁、3D contract 決策頁與 status.json 的線上比對。 | 已完成 3D Plugin / 多設備單元線上驗收紀錄。 |
| 3D 程式 repo 結構檢查 | 唯讀盤點 HS.DeviceControl.Application、Adapter dispatcher、config schema 與 plugin loader 停止線。 | 已完成 3D 程式 repo 結構檢查與實作前確認，判定可進入 Application contract 實作前確認。 |
| 3D 程式 repo 結構檢查線上驗收 | 記錄 commit 8ce2717 push 後，Cloudflare Pages 首頁、新結構檢查頁、第三階段儀表板與 status.json 的線上比對。 | 已完成 3D 程式 repo 結構檢查線上驗收紀錄。 |
| 3D Application contract 草案 | 將 ControlUnits、Resources、Commands、Plugins、Application error code 與測試策略整理成七項確認。 | 已完成 3D Application contract 草案 / 實作前確認表，使用者已確認七項決策。 |
| 3D Application contract 決策確認表 | 將使用者 1 至 7 全部同意的結果整理成獨立確認紀錄。 | 已完成 3D Application contract 決策確認表，仍保留不新增 ServiceHost / WebApi、不建立 Plugin Loader、不載入 DLL、不改 Adapter public contract、不改 config schema 的停止線。 |
| 3D Application contract 第一版實作 | 在 Application 層新增 ControlUnits、Resources、Commands、Plugins、APP-03xx 與 xUnit 測試。 | 已完成 3D Application contract 第一版實作紀錄，程式 repo commit a158551 已 push，Application tests 30 passed，solution tests 468 passed。 |
| 3D Application contract commit / push 前確認 | 確認 staged 範圍、測試、污染掃描、commit 訊息、push 與 Actions。 | 已完成 3D Application contract commit / push 前確認，Notify docs repo status run 27029042871 success。 |
| 3D Application contract 完成稽核 | 對照 3D 目標模式，確認程式、文件、測試、Actions 與停止線。 | 已更新 3D Plugin / 多設備單元完成稽核表，判定可進入文件 repo push 與線上驗收。 |
| 第三階段總收斂確認 | 集中確認 3A、3B、3C、3D 是否都已在核准範圍內完成。 | 已建立 第三階段總收斂確認表，判定第三階段可正式標記完成，停止線保留到第四階段。 |
| 4A 邊界分析 | 釐清 WebApi、ServiceHost、Plugin Loader、Application 共用協調層、部署維運與停止線。 | 已建立 4A WebApi / ServiceHost / Plugin Loader 邊界分析，不代表新增正式入口或載入外部 DLL。 |
| 4A 決策確認表 | 逐項確認 WebApi、ServiceHost、Plugin Loader、Application 共用協調層、部署維運與停止線。 | 已建立 4A WebApi / ServiceHost / Plugin Loader 決策確認表，等待使用者回覆七項決策。 |
| 4B / 4C / 4D 執行切分 | 排定 WebApi、ServiceHost、Plugin Loader 的後續階段。 | 已建立 第四階段 4B / 4C / 4D 執行切分表，暫定 WebApi 在 4B、ServiceHost 在 4C、Plugin Loader 在 4D。 |
| 多設備單元模型 | 釐清 ControlUnitId / StationId / DeviceId 關係。 | 已納入 3D 決策確認表。 |
| Resource Lock / Command Queue | 避免多設備或多任務同時搶同一資源。 | 先確認 contract 與 fake / in-memory 邊界，不導入 queue 套件。 |
| Plugin Loader 邊界分析 | 決定 DLL 載入、版本、相依套件與失敗隔離。 | 本次只分析，不載入 DLL；後續需另行確認。 |
| 設定版本與回滾 | 讓 JSON 流程或設備設定變更可審核、追蹤、回復。 | 先分析，不改 config schema。 |
停止線
- 未確認前不載入外部 DLL。
- 未確認前不改 Adapter public contract。
- 未確認前不引入外部 plugin 框架。
- 未確認前不把案場客製邏輯寫入 Core。
建議首頁顯示方式
首頁只顯示第三階段四條主線：
| 主線 | 狀態 | 下一步 |
| 3A Trace 查詢能力 | 已完成真實測試 DB write/read/cleanup 補驗 | 已可收斂，下一步進入 3B。 |
| 3B DB 初始化安全流程 | 第一版完成稽核與線上驗收已完成 | 可另行確認真實 DB read-only preview 驗證。 |
| 3C Service / API 入口 | Application contract 線上驗收已完成 | commit aee6ab6 已推送，文件網站已完成 3C 線上內容比對。 |
| 3D Plugin / 多設備單元 | Application contract 第一版已完成 | 程式 repo commit a158551 已 push，Application tests 30 passed，solution tests 468 passed；可交棒到 4A 邊界分析。 |
完整細節放在本文件，避免首頁再次變成大量卡片。
建議下一步
3A、3B、3C 與 3D 皆已完成第三階段主要收斂項目。第三階段總收斂確認表 已建立，判定第三階段可正式標記完成。停止線仍明確保留不載入外部 DLL、不新增 Plugin Loader、不改 Adapter public contract、不新增 ServiceHost / WebApi 專案、不新增 route、不導入套件、不改 config schema。4A WebApi / ServiceHost / Plugin Loader 邊界分析、4A WebApi / ServiceHost / Plugin Loader 決策確認表 與 第四階段 4B / 4C / 4D 執行切分表 已建立；下一步等待使用者回覆 4A 七項決策確認。
目前已完成：
- TaskTraceStore 第一版 public contract 決策紀錄
- TaskTraceStore 第一版查詢實作紀錄
- TaskTraceStore manual-only 查詢驗證入口紀錄
- TaskTraceStore 3A 完成稽核
- TaskTraceStore 真實 DB read-only 查詢驗證紀錄
- ManualApplyPreview 實作前確認
- 3B ManualApplyPreview 決策確認表
- ManualApplyPreview 第一版實作紀錄
- ManualApplyPreview 3B 完成稽核表
- ManualApplyPreview 3B 線上驗收紀錄
- 3C Service / API 邊界分析
- 3C Service / API 決策確認表
- 3C 程式 repo 結構檢查與實作前確認
- 3C Application Service contract 草案 / 實作前確認表
- 3C Application contract 決策確認紀錄
- 3C Application contract 第一版實作紀錄
- 3C Application contract 完成稽核表
- 3C Application contract commit / push 前確認
- 3C Application contract 線上驗收紀錄
- 3D Plugin / 多設備單元邊界分析
- 3D Plugin / 多設備單元決策確認表
- 3D contract 草案 / 實作前確認表
- 3D contract 決策確認表
- 3D 程式 repo 結構檢查與實作前確認
- 3D 程式 repo 結構檢查線上驗收紀錄
- 3D Application contract 草案 / 實作前確認表
- 3D Application contract 決策確認表
- 第三階段總收斂確認表
- 4A WebApi / ServiceHost / Plugin Loader 邊界分析
- 4A WebApi / ServiceHost / Plugin Loader 決策確認表
- 第四階段 4B / 4C / 4D 執行切分表
本次已由使用者授權測試 DB write/read/cleanup 補驗，並執行 run-mysql-tasktrace-write-read-cleanup-validation.ps1。結果為 QuerySuccess=True、QueryItemCount=2、QueryHasMore=False、Cleanup result=True，cleanup 刪除本次 2 筆 manual-tasktrace-e2e- 測試資料。這代表 TaskTraceStore 查詢鏈路在有資料時可查回 trace rows，3A 可標記完成。
3B 最新實作狀態（2026-06-04）
| 項目 | 狀態 |
| 程式 commit | 13c14ca，新增 ManualApplyPreview 安全預覽 |
| Core model | 已完成 SchemaManualApplyPreviewRequest、SchemaManualApplyPreviewResult、SchemaManualApplyPreviewItem、SchemaManualApplyPreviewRiskLevel |
| Preview builder | 已完成 SchemaManualApplyPreviewBuilder |
| 安全欄位 | 已完成 PlanHash、CanApply、Blocked、RiskLevel、Summary、GeneratedAtUtc |
| Apply 限制 | 第一版固定 CanApply=False，不提供正式 Apply |
| ConsoleHost | 已顯示 ManualApplyPreview 摘要、風險、阻擋狀態與 SQL preview |
| 目標測試 | Core 9 passed、ConsoleHost formatter 15 passed、MySQL manual-only gate 1 passed |
| 實際輸出驗證 | dotnet run 成功輸出 PlanHash、CanApply=False、Risk=Low、Blocked=False |
| 真實 DB read-only preview | 尚未執行，需另行確認 read-only gate 與連線資訊 |
| 3B 完成稽核 | 已完成，判定第一版 ManualApplyPreview 可驗收完成 |
| 3B 線上驗收 | 已完成，Cloudflare Pages 首頁、稽核頁與 status.json 已反映 13c14ca 與 3B 完成狀態 |
| 停止線 | 未執行 DDL、未建立 schema history table、未開放自動 Apply、未導入 WebApi / ServiceHost |
3A 最新實作狀態（2026-06-04）
| 項目 | 狀態 |
ITaskTraceStore public contract | 已完成 |
| Core 查詢 DTO | 已完成，位於 HS.DeviceControl.Core.Logging |
MySqlTaskTraceStore fake gateway 查詢 | 已完成 |
| 無條件全表查詢防護 | 已完成，沒有 filter 會回傳 TraceQueryInvalidRequest |
| 分頁策略 | 已完成，使用 Limit + 1 與 HasMore，不做 TotalCount |
| 敏感資訊遮罩 | 已完成，查詢結果會遮蔽 password / token / secret / authorization / connection string |
| 非 Manual 全測試 | 通過 406 個測試 |
| 真實 DB 查詢 | 已完成 write/read/cleanup 補驗，QueryItemCount=2 |
| manual-only runner | 已完成，scripts/run-mysql-tasktrace-manual-query.ps1 |
| 候選探查 runner | 已完成，scripts/run-mysql-tasktrace-candidate-probe.ps1，commit 2c817ec |
| 候選探查結果 | 已執行，ExpectedMinRows=0、ItemCount=0、2 個 manual 測試通過 |
| write/read/cleanup runner | 已完成，scripts/run-mysql-tasktrace-write-read-cleanup-validation.ps1，commit fa874f4 |
| write/read/cleanup 補驗結果 | 已執行，寫入 2 筆、查回 2 筆、cleanup 刪除 2 筆，2 個 manual 測試通過 |
目前 3A 已完成第一版程式契約、fake gateway 實作、read-only manual 驗證入口、候選探查與 write/read/cleanup 真實測試 DB 補驗。3B ManualApplyPreview 第一版安全預覽、完成稽核與線上驗收已完成；3C Application contract 第一版實作、完成稽核、commit / push 前確認、程式 repo push、文件 repo push 與線上驗收已完成，Application tests 15 passed，solution tests 453 passed。3D Plugin / 多設備單元邊界分析、決策確認表、contract 草案 / 實作前確認表、contract 決策確認表、完成稽核表、線上驗收、程式 repo 唯讀結構檢查、Application contract 草案、Application contract 決策確認表、Application contract 第一版實作與 commit / push 前確認已完成；4A 邊界分析與 4A 決策確認表已建立，下一步等待使用者回覆七項確認，或另行確認真實 DB read-only ManualApplyPreview 驗證。