# TaskTraceStore 真實 DB 查詢補驗紀錄

本文件記錄第三階段 3A Trace 查詢能力的真實測試 DB 查詢驗證與 write/read/cleanup 最終補驗結果。

結論：第一次 read-only 查詢與候選探查已證明測試 DB 當時沒有可命中的 trace rows；使用者授權測試 DB write/read/cleanup 後，已由 `run-mysql-tasktrace-write-read-cleanup-validation.ps1` 寫入 2 筆 `manual-tasktrace-e2e-` 測試 trace，`MySqlTaskTraceStore.Query(...)` 查回 2 筆，`HasMore=False`，並 cleanup 刪除本次 2 筆測試資料。3A Trace 查詢能力可標記完成。

## 最終補驗資訊

| 項目 | 內容 |
|---|---|
| 驗證日期 | 2026-06-04 |
| 來源 | Codex 執行 `run-mysql-tasktrace-write-read-cleanup-validation.ps1` 輸出 |
| DB | `hs_device_control_test` |
| Table | `task_log_traces` |
| User | `hs_device` |
| Port | `3306` |
| SslMode | `None` |
| TimeoutSeconds | `15` |
| AllowWrite | `true` |
| AllowRead | `true` |
| Cleanup | `true` |
| 測試資料前綴 | `manual-tasktrace-e2e-` |

## 最終補驗結果

| 項目 | 結果 |
|---|---|
| TaskId | `manual-tasktrace-e2e-20260604022217-b35df369` |
| 寫入結果 | `success` |
| QuerySuccess | `True` |
| QueryItemCount | `2` |
| QueryHasMore | `False` |
| QueryElapsedMs | `53` |
| Cleanup requested | `true` |
| Cleanup result | `True` |
| Cleanup message | `deleted current manual task id only. affected=2` |
| xUnit 結果 | 2 個 manual 測試通過 |

## 查回資料摘要

| TraceId | NodeId | CommandName | Level | Status | ErrorCode |
|---|---|---|---|---|---|
| `manual-tasktrace-e2e-20260604022217-b35df369-err` | `manual-tasktrace-node-2` | `ManualTaskTraceFailedCommand` | `Error` | `Failed` | `MANUAL_TASKTRACE_FAILED` |
| `manual-tasktrace-e2e-20260604022217-b35df369-ok` | `manual-tasktrace-node-1` | `ManualTaskTraceCommand` | `Info` | `Completed` | `<empty>` |

## 前一次 read-only 查詢結果

| 項目 | 結果 |
|---|---|
| Query Success | `True` |
| ItemCount | `0` |
| HasMore | `False` |
| ElapsedMs | `387` |
| xUnit 結果 | 2 個測試中 1 個通過、1 個失敗 |
| 失敗原因 | `Expected at least 1 trace rows but got 0.` |

## 判讀

- 已證明 manual-only gate、測試 DB 連線、`MySqlLogWriter` 寫入、`TaskTraceStore` 查詢與 cleanup 流程可執行。
- 已在有資料時驗證 trace item mapping 可回傳 `TraceId`、`TaskId`、`NodeId`、`DeviceId`、`CommandName`、`Level`、`Status`、`ErrorCode` 與 `CreatedAt`。
- cleanup 僅刪除本次 manual `TaskId`，不跨任務清除資料。
- 本次未執行 DDL、正式 DB 寫入或正式 Apply。
- 密碼未寫入 repo，輸出中只顯示 `Password: set`。

## 候選探查結果

使用者於 2026-06-04 執行 `scripts/run-mysql-tasktrace-candidate-probe.ps1`，查詢範圍如下：

| 項目 | 結果 |
|---|---|
| CreatedFrom | `2026-01-01 00:00:00` |
| CreatedTo | `2026-06-04 23:59:59` |
| ExpectedMinRows | `0` |
| Limit | `20` |
| AllowRead | `true` |
| Success | `True` |
| ItemCount | `0` |
| HasMore | `False` |
| ElapsedMs | `1364` |
| 測試結果 | 2 個 manual 測試通過 |

候選探查結論：即使擴大查詢時間範圍，測試 DB 仍沒有可用 `TaskId` 或 trace rows。後續已改由使用者授權測試 DB write/read/cleanup 補驗，並已完成。

## 目前狀態

3A 目前可標記為完成。

完成證據包含：

- `ITaskTraceStore` public contract 與 DTO 已完成。
- `MySqlTaskTraceStore` fake gateway 查詢與參數化 SQL 已完成。
- read-only manual 查詢入口已完成。
- read-only 候選探查已證明測試 DB 無既有 trace rows。
- write/read/cleanup 補驗已寫入 2 筆、查回 2 筆、cleanup 刪除 2 筆。

## 建議下一步

建議下一步進入「第三階段 3B ManualApplyPreview 實作前確認」。3B 仍只做 DB 初始化安全流程與 preview 設計，不自動執行正式 DDL / ALTER TABLE。

## 補驗指令範本

以下指令均需在程式 repo 根目錄執行：

```powershell
cd "C:\Users\Evan\OneDrive - 鴻森智能科技有限公司\重要資料\hs-device-control-template"
```

程式 repo 已於 commit `fa874f4` 新增 write/read/cleanup 補驗 runner：`scripts/run-mysql-tasktrace-write-read-cleanup-validation.ps1`。

若後續需要重新驗證，必須明確限制在測試 DB、`task_log_traces` 與 cleanup 本次 manual task id：

```powershell
.\scripts\run-mysql-tasktrace-write-read-cleanup-validation.ps1 `
  -HostName "220.135.128.247" `
  -Port 3306 `
  -Database "hs_device_control_test" `
  -UserName "hs_device" `
  -Table "task_log_traces" `
  -TimeoutSeconds 15 `
  -SslMode "None" `
  -AllowWrite `
  -AllowRead
  -Cleanup
```

後續若要對正式 DB、DDL、ALTER TABLE 或正式 Apply 進行操作，仍需另行確認，不可沿用本次 3A 授權。