TaskTraceStore manual-only 查詢驗證入口紀錄

本文件承接 TaskTraceStore 第一版查詢實作紀錄，記錄第三階段 3A Trace 查詢能力的真實 DB manual-only 查詢驗證入口。

本次只完成「可由使用者明確開啟的測試入口」，尚未實際連線測試 DB 查詢。此入口預設關閉，不會進入一般 CI，不執行 DDL，不寫入資料，不刪除資料，也不保存密碼或連線資訊到 repo。

實作摘要

項目	內容
實作日期	2026-06-03
程式 repo	`hs-device-control-template`
分支	`poc/nmodbus-tcp`
程式 commit	`a9c9eca`
目前狀態	3A Trace 查詢 manual-only 驗證入口已完成，尚未執行真實 DB 查詢
驗證方式	非 Manual 全測試、manual gate 關閉測試

新增內容

類型	位置	說明
xUnit manual-only 測試	`tests/HS.DeviceControl.Infrastructure.MySql.Tests/Logging/MySqlTaskTraceStoreManualMySql56Tests.cs`	以 `MySqlTaskTraceStore.Query(...)` 查詢真實 MySQL 5.6.2 測試 DB。
PowerShell runner	`scripts/run-mysql-tasktrace-manual-query.ps1`	從任意位置啟動 manual-only 查詢測試，並只在 process 環境變數中帶入連線資訊。

Gate 與安全規則

規則	作法
預設不連 DB	`HS_MYSQL_TASKTRACE_ENABLED` 未設為 `true` 時，測試只輸出 skip 訊息。
需二次確認讀取	`HS_MYSQL_TASKTRACE_ALLOW_READ=true` 才會真的查詢。
不允許全表查詢	runner 與 xUnit 入口都要求至少一個 filter。
限定測試 DB	runner 強制 `Database=hs_device_control_test`。
限定 trace table	runner 強制 `Table=task_log_traces`。
不保存敏感資訊	密碼只由互動輸入或環境變數提供，不寫入 repo。
不寫入 / 不刪除	本入口只查詢，不執行 `INSERT`、`UPDATE`、`DELETE`、DDL 或 cleanup。

支援查詢條件

至少需提供一個查詢條件：

條件	環境變數 / 參數
TaskId	`HS_MYSQL_TASKTRACE_TASK_ID` / `-TaskId`
NodeId	`HS_MYSQL_TASKTRACE_NODE_ID` / `-NodeId`
DeviceId	`HS_MYSQL_TASKTRACE_DEVICE_ID` / `-DeviceId`
CommandName	`HS_MYSQL_TASKTRACE_COMMAND_NAME` / `-CommandName`
Level	`HS_MYSQL_TASKTRACE_LEVEL` / `-Level`
Status	`HS_MYSQL_TASKTRACE_STATUS` / `-Status`
ErrorCode	`HS_MYSQL_TASKTRACE_ERROR_CODE` / `-ErrorCode`
CreatedFrom	`HS_MYSQL_TASKTRACE_CREATED_FROM` / `-CreatedFrom`
CreatedTo	`HS_MYSQL_TASKTRACE_CREATED_TO` / `-CreatedTo`

建議執行方式

若要只確認入口預設不連 DB：

dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj --filter FullyQualifiedName~MySqlTaskTraceStoreManualMySql56Tests --logger "console;verbosity=detailed"

若使用者確認要查測試 DB，建議使用 runner：

.\scripts\run-mysql-tasktrace-manual-query.ps1 `
  -HostName "測試 DB Host 或 IP" `
  -Port 3306 `
  -Database "hs_device_control_test" `
  -UserName "hs_device" `
  -Table "task_log_traces" `
  -TaskId "要查詢的 TaskId" `
  -Limit 20 `
  -ExpectedMinRows 1 `
  -AllowRead

若要查最近一段時間，也可改用 -CreatedFrom / -CreatedTo，但仍需確認查詢範圍足夠小，避免查詢過大。

驗證結果

驗證	結果
`dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj --filter "FullyQualifiedName!~Manual"`	通過 77 個測試。
`dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj --filter FullyQualifiedName~MySqlTaskTraceStoreManualMySql56Tests --logger "console;verbosity=detailed"`	gate 關閉時通過 2 個測試，確認預設不連 DB。
`dotnet test HS.DeviceControl.sln --filter "FullyQualifiedName!~Manual"`	通過 406 個測試。

本次沒有納入

沒有實際查詢真實測試 DB。
沒有建立、修改或刪除 task_log_traces。
沒有把測試 DB 帳密、IP 或連線字串寫入 repo。
沒有新增 WebApi、ServiceHost、WinForms Debug Tool 或 Plugin Loader。
沒有修改 ITaskTraceStore public method 簽章。

目前完成度判斷

3A Trace 查詢能力目前已完成：

public 查詢 contract。
Core 查詢 DTO。
MySQL fake gateway 查詢實作。
真實 DB 查詢的 manual-only 驗證入口。
runner 與安全停止線。

尚未完成的是「使用者授權後，對測試 DB 執行一次 read-only 查詢並回填驗證紀錄」。

建議下一步

建議下一步在使用者確認測試 DB、查詢條件與 AllowRead 後，執行「TaskTraceStore 真實 DB read-only 查詢驗證」，並整理實際輸出、查詢筆數、遮罩結果與限制。