第三階段執行儀表板

本文件承接第三階段前置規劃與 TaskTraceStore public 查詢介面實作前確認，用來把第三階段拆成可執行、可驗收、可顯示在首頁專案總攬的主線。

本文件只整理第三階段執行項目與狀態，不代表已同意導入 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 `ManualApplyPreview` 實作前確認。
3B DB 初始化安全流程	讓 Host 啟動前可檢查、預覽 schema 差異，但不直接正式 Apply。	尚未開始	整理 `ManualApplyPreview` 實作前確認。
3C 正式執行入口	規劃 ServiceHost / WebApi 的任務啟動、查詢、取消與設備狀態 API。	尚未開始	先做 ServiceHost / WebApi 邊界分析，不直接建專案。
3D 平台化擴充	規劃 Plugin DLL、多設備單元、Resource Lock、Command Queue 與設定版本控管。	尚未開始	先整理需求與風險，不直接載入外部 DLL。

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` 實作前確認	preview model、風險分類、輸出格式與停止線	否，僅文件確認。
3B-2	Apply preview model 設計	plan hash、table / column / index 差異、risk level	是，會影響資料模型。
3B-3	Dry-run preview 輸出實作	不執行 DDL，只輸出 plan	是，進入程式實作前需確認。
3B-4	ConsoleHost 顯示與人工驗證	實際確認 preview 是否可讀、是否安全	是，屬驗證節點。

停止線

不得在未確認前執行正式 DDL。
不得對正式 DB 做 ALTER TABLE。
不得把 Apply 接入預設啟動流程。
不得保存 DB 密碼或連線字串到 repo。

3C 正式執行入口

目標

規劃未來正式背景服務與遠端 API 的責任邊界，讓 Server 能啟動任務、查詢任務、取消任務、查設備狀態，但不破壞 Core / Adapter 分層。

待執行

項目	目的	備註
ServiceHost 邊界分析	決定背景常駐、重啟恢復、健康檢查與 log 策略。	先分析，不建專案。
WebApi 邊界分析	決定 Task Control API、Device Status API、查詢 API 與權限。	先分析，不建 endpoint。
API / Service 驗證節點設計	定義何時需要人工驗證效果。	需等邊界確認後。
操作身分與權限模型	確認 Operator、HostName、AppVersion 與授權策略。	會影響正式使用流程。

停止線

未確認前不新增 WebApi 專案。
未確認前不新增 ServiceHost 專案或改啟動方式。
未確認前不新增 API route。
未確認前不導入認證授權套件。

3D 平台化擴充

目標

讓共用骨架未來可支援外部 DLL、真實設備模組、多設備單元共用控制主機、資源鎖與命令佇列。

待執行

項目	目的	備註
多設備單元模型	釐清 ControlUnitId / StationId / DeviceId 關係。	不限於調劑台，可包含任意設備單元。
Resource Lock / Command Queue	避免多設備或多任務同時搶同一資源。	第三階段後段。
Plugin Loader 邊界分析	決定 DLL 載入、版本、相依套件與失敗隔離。	先分析，不載入 DLL。
設定版本與回滾	讓 JSON 流程或設備設定變更可審核、追蹤、回復。	需配合 API / Service。

停止線

未確認前不載入外部 DLL。
未確認前不改 Adapter public contract。
未確認前不引入外部 plugin 框架。
未確認前不把案場客製邏輯寫入 Core。

建議首頁顯示方式

首頁只顯示第三階段四條主線：

主線	狀態	下一步
3A Trace 查詢能力	已完成真實測試 DB write/read/cleanup 補驗	已可收斂，下一步進入 3B。
3B DB 初始化安全流程	尚未開始	`ManualApplyPreview` 實作前確認。
3C Service / API 入口	尚未開始	ServiceHost / WebApi 邊界分析。
3D Plugin / 多設備單元	尚未開始	平台化擴充需求與風險整理。

完整細節放在本文件，避免首頁再次變成大量卡片。

建議下一步

建議下一步進入「第三階段 3B ManualApplyPreview 實作前確認」。

目前已完成：

本次已由使用者授權測試 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 可標記完成。

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 實作前確認。