第三階段前置規劃

本文件承接第二階段 B 收斂稽核，用來整理第三階段開始前應先確認的工作順序、邊界與驗證節點。

本文件只做規劃，不代表已同意修改 public method 簽章、導入 WebApi / ServiceHost、執行正式 DB DDL、保存密碼或改變專案啟動方式。

目前第三階段執行項目已由第三階段執行儀表板承接，首頁專案總攬也會以 3A / 3B / 3C / 3D 四條主線顯示目前狀態。

目前狀態

項目	狀態	說明
第一階段控制核心	已完成	Workflow、StateMachine、TaskEngine、Adapter、Log、Config 與 ConsoleHost 驗證節點已完成。
第二階段 MySQL 持久化	已完成	`task_executions`、`node_executions` 與 `task_log_traces` 已完成 manual-only 真實測試 DB 驗證。
DB LogWriter / TraceStore	已完成第一版	已完成寫入、sanitizer、fallback、manual-only gate 與查詢邊界設計。
Schema Apply	已完成安全策略	已有停止線、gate、備份、rollback、plan hash 與高風險分類；尚未實作正式 DDL executor。
第三階段正式平台能力	尚未開始	WebApi、ServiceHost、Plugin Loader、多設備單元控制與正式 DB Apply 尚未導入。

第三階段前置不直接做完整平台，而是先把會影響架構邊界的項目拆清楚。

目標	目的
決定 `TaskTraceStore` public 查詢介面	讓未來 WebApi、ServiceHost 或 Debug Tool 可查任務 trace，但避免查詢 contract 草率成形。
決定 `ManualApplyPreview` 是否先實作	讓 schema apply 先有可審核的 preview / plan，不直接執行 DDL。
決定 Host DB 初始化邊界	釐清 ConsoleHost、ServiceHost 未來啟動時是否只檢查 DB、是否允許 preview、是否允許 apply。
決定 WebApi / ServiceHost 先後順序	避免同時導入遠端 API、背景服務、DB 初始化與正式部署，造成範圍過大。
決定多設備單元與 Plugin Loader 是否納入第三階段	這兩項會影響正式平台能力，但需要先有穩定服務入口與資源隔離策略。

順序	工作項	建議原因	本階段是否可直接實作
1	`TaskTraceStore` public 查詢介面實作前確認	已有 `task_log_traces` 寫入與查詢邊界，下一步最自然是整理查詢 contract。	否，需先確認 request / result model。
2	`ManualApplyPreview` 程式實作前確認	能延續 Schema Apply 安全策略，只做 preview，不碰正式 DDL。	否，需先確認 apply plan 欄位與高風險分類。
3	Host DB 初始化流程設計	會影響啟動方式，需等查詢與 preview 邊界較清楚後再決定。	否，需先做設計。
4	ServiceHost / WebApi 邊界分析	需要穩定查詢與持久化資料基礎，建議排在前面三項後。	否，會擴大系統邊界。
5	Plugin Loader / 多設備單元控制	會牽動 DLL 載入安全、資源鎖、命令佇列與設備隔離。	否，需另開主題。

候選工作	可以先整理什麼	需要避免什麼
`TaskTraceStore` public 查詢介面實作前確認	查詢條件、分頁、排序、回傳 DTO、遮罩規則、錯誤碼、測試案例。	不直接新增 interface、DTO 或改 public method。
`ManualApplyPreview` 程式實作前確認	apply plan model、危險操作分類、人工確認欄位、輸出格式、preview 驗證方式。	不執行 DDL、不連正式 DB、不改啟動方式。
Host DB 初始化流程設計	ConsoleHost / ServiceHost 啟動時的 dry-run、inspect、preview、停止線與 log。	不把初始化接入正式啟動流程、不自動 apply schema。

建議第三階段第一個整理項先做 TaskTraceStore public 查詢介面實作前確認。

原因：

確認項	建議
查詢主鍵	至少支援 `TaskId`，可選 `NodeId`、`DeviceId`、`CommandName`、`Level`、`Status`、時間區間。
分頁	必須有 `Limit` 與 `Offset` 或 cursor，並設定最大筆數。
排序	預設依 `OccurredAt` 或 `CreatedAt` 由新到舊。
回傳資料	不直接回傳 DB row，應回傳查詢 DTO。
敏感資訊	沿用 sanitizer，不回傳 password、token、authorization、connection string。
錯誤格式	使用標準 `Result` / `ErrorInfo`，不得只回傳 `bool`。
測試方式	先 fake gateway 單元測試，再 manual-only 真實 DB 查詢測試。
停止線	未確認前不得新增 public interface 或 WebApi endpoint。

確認項	建議
模式	只做 preview，不執行 DDL。
輸入	Expected schema、current schema、target database、operator、reason。
輸出	Apply plan、SQL preview、risk level、plan hash、warnings。
高風險操作	`DROP`、`MODIFY`、`CHANGE`、縮短欄位長度、移除 index 必須列為高風險。
審核資訊	記錄產生時間、操作者、來源 commit、DB 版本與是否允許 apply。
停止線	不保存密碼、不自動 apply、不接正式 DB。

確認項	建議
ConsoleHost	可先顯示 DB 檢查結果，但不得自動 apply。
ServiceHost	需另行設計啟動模式、失敗策略與重試策略。
設定來源	密碼與連線字串不得寫入 repo，需使用環境變數或本機未追蹤設定。
失敗策略	DB 不可用時應明確回報，不得吞掉 exception。
Log	需記錄 host、app version、schema version、result、error code。
停止線	未確認前不得改變專案啟動方式。

驗證節點	驗證目的	建議時機
Trace 查詢 fake gateway 測試	確認查詢條件、分頁、排序與 SQL 參數。	`TaskTraceStore` 第一版實作後。
Trace 查詢 manual-only 真實 DB 測試	確認可從 `task_log_traces` 查回測試資料。	使用者授權測試 DB 查詢後。
Apply preview 輸出測試	確認 preview 不執行 DDL，只輸出 plan 與 risk。	`ManualApplyPreview` 第一版實作後。
Host DB 初始化 dry-run 人工驗證	確認啟動檢查結果、錯誤輸出與停止線。	Host DB 初始化設計完成並經確認後。

本文件的下一步已由兩份文件承接：

目前已完成「程式 repo TaskTraceStore 介面命名與 DTO 位置盤點」，下一步建議確認 ITaskTraceStore 第一版 public contract、DTO 位置、同步 Query 方法與查詢限制。

完成確認後，才能決定是否進入程式 repo 實作。