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

本文件承接 [TaskTraceStore 第一版查詢實作紀錄](task-trace-store-first-query-implementation-record.md)，記錄第三階段 3A Trace 查詢能力的真實 DB manual-only 查詢驗證入口。

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

## 實作摘要

| 項目 | 內容 |
|---|---|
| 實作日期 | 2026-06-03 |
| 程式 repo | `hs-device-control-template` |
| 分支 | `poc/nmodbus-tcp` |
| 程式 commit | [`a9c9eca`](https://github.com/Hongsen-tw/hs-device-control-template/commit/a9c9eca59fc9e9fefbecd7f707990f600918ec74) |
| 目前狀態 | 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：

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

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

```powershell
.\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 查詢驗證」，並整理實際輸出、查詢筆數、遮罩結果與限制。