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>`

判讀

已證明 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 查詢、read-only manual 查詢入口、read-only 候選探查、write/read/cleanup 補驗寫入 2 筆、查回 2 筆、cleanup 刪除 2 筆。

建議下一步

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

補驗指令範本

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

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：

.\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 授權。