# 第三階段前置規劃

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

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

目前第三階段執行項目已由 [第三階段執行儀表板](phase-three-dashboard.md) 承接，首頁專案總攬也會以 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 查詢介面實作前確認

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

原因：

- 第二階段 B 已完成 `task_log_traces` 寫入與查詢邊界設計。
- 查詢介面會直接影響未來 WebApi、ServiceHost、WinForms Debug Tool。
- 先整理 contract，比直接做 WebApi 或 ServiceHost 更小、風險更低。
- 可以先定義資料遮罩、分頁上限、查詢條件與錯誤格式，避免後續 API 反覆變更。

## `TaskTraceStore` 前置確認清單

| 確認項 | 建議 |
|---|---|
| 查詢主鍵 | 至少支援 `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。 |

## `ManualApplyPreview` 前置確認清單

| 確認項 | 建議 |
|---|---|
| 模式 | 只做 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。 |

## Host DB 初始化前置確認清單

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

## 不納入本次前置整理的事項

- 不導入 WebApi。
- 不導入 ServiceHost。
- 不導入 WinForms Debug Tool。
- 不導入 Plugin Loader。
- 不做多設備單元 Resource Lock / Command Queue。
- 不執行正式 DB DDL。
- 不修改資料模型、API 路由、public method 簽章或專案啟動方式。

## 驗證節點建議

| 驗證節點 | 驗證目的 | 建議時機 |
|---|---|---|
| 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 初始化設計完成並經確認後。 |

## 建議下一步

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

- [TaskTraceStore public 查詢介面實作前確認](task-trace-store-public-query-interface-preimplementation-checklist.md)
- [第三階段執行儀表板](phase-three-dashboard.md)

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

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