# 第三階段執行儀表板

本文件承接 [第三階段前置規劃](phase-three-preplanning.md)、[TaskTraceStore public 查詢介面實作前確認](task-trace-store-public-query-interface-preimplementation-checklist.md) 與 [ManualApplyPreview 實作前確認](manual-apply-preview-preimplementation-checklist.md)，用來把第三階段拆成可執行、可驗收、可顯示在首頁專案總攬的主線。

本文件只整理第三階段執行項目與狀態，不代表已同意導入 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 邊界分析。 |
| 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` 實作前確認 | 已完成 [ManualApplyPreview 實作前確認](manual-apply-preview-preimplementation-checklist.md)，整理 preview model、風險分類、輸出格式與停止線 | 已完成。 |
| 3B-2 | 決策確認 | 使用者已依 [3B ManualApplyPreview 決策確認表](manual-apply-preview-decision-confirmation.md) 同意七項決策 | 已完成。 |
| 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 完成稽核表](manual-apply-preview-3b-completion-audit.md)，判定第一版可驗收完成 | 已完成。 |
| 3B-8 | 線上驗收紀錄 | 已完成 [ManualApplyPreview 3B 線上驗收紀錄](manual-apply-preview-3b-online-acceptance-record.md)，確認 Cloudflare Pages 首頁、稽核頁與 `status.json` 已反映 3B 狀態 | 已完成。 |

### 停止線

- 不得在未確認前執行正式 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 初始化安全流程 | 第一版完成稽核與線上驗收已完成 | 真實 DB read-only preview 驗證或 3C 邊界分析。 |
| 3C Service / API 入口 | 尚未開始 | ServiceHost / WebApi 邊界分析。 |
| 3D Plugin / 多設備單元 | 尚未開始 | 平台化擴充需求與風險整理。 |

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

## 建議下一步

3B 第一版完成稽核與線上驗收已整理完成，判定 `ManualApplyPreview` 安全預覽可驗收完成，且文件網站已反映最新 3B 狀態。建議下一步由使用者選擇：真實 DB read-only preview 驗證，或 3C Service / API 邊界分析。

目前已完成：

- [TaskTraceStore 第一版 public contract 決策紀錄](task-trace-store-public-contract-decision-record.md)
- [TaskTraceStore 第一版查詢實作紀錄](task-trace-store-first-query-implementation-record.md)
- [TaskTraceStore manual-only 查詢驗證入口紀錄](task-trace-store-manual-query-verification-entry-record.md)
- [TaskTraceStore 3A 完成稽核](task-trace-store-3a-completion-audit.md)
- [TaskTraceStore 真實 DB read-only 查詢驗證紀錄](task-trace-store-real-db-query-verification-record.md)
- [ManualApplyPreview 實作前確認](manual-apply-preview-preimplementation-checklist.md)
- [3B ManualApplyPreview 決策確認表](manual-apply-preview-decision-confirmation.md)
- [ManualApplyPreview 第一版實作紀錄](manual-apply-preview-implementation-record.md)
- [ManualApplyPreview 3B 完成稽核表](manual-apply-preview-3b-completion-audit.md)
- [ManualApplyPreview 3B 線上驗收紀錄](manual-apply-preview-3b-online-acceptance-record.md)

本次已由使用者授權測試 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` 第一版安全預覽、完成稽核與線上驗收已完成，下一步可選真實 DB read-only preview 驗證或 3C 邊界分析。