TaskTraceStore 第一版查詢實作紀錄
本文件承接 TaskTraceStore 第一版 public contract 決策紀錄，記錄第三階段 3A Trace 查詢能力第一版程式實作結果。
本次只完成已確認的 public contract 與 fake gateway 查詢實作，不執行真實 DB 查詢、不執行 DDL、不新增 WebApi / ServiceHost、不導入外部 DLL 或 Plugin Loader。
實作摘要
| 項目 | 內容 |
| 實作日期 | 2026-06-03 |
| 程式 repo | hs-device-control-template |
| 分支 | poc/nmodbus-tcp |
| 程式 commit | f2958d3 |
| 目前狀態 | 3A Trace 查詢第一版 fake gateway 實作完成 |
| 驗證方式 | Core / MySQL / WorkflowSimulation / Adapters / ModbusPoC 非 Manual 全測試 |
| 測試結果 | dotnet test HS.DeviceControl.sln --filter "FullyQualifiedName!~Manual" 通過 406 個測試 |
已新增 public contract
| 類型 | 位置 | 說明 |
ITaskTraceStore | HS.DeviceControl.Core.Logging | Trace read-side 查詢入口。 |
TaskTraceQueryRequest | HS.DeviceControl.Core.Logging | Trace 查詢條件與分頁設定。 |
TaskTraceQueryResult | HS.DeviceControl.Core.Logging | 查詢結果、HasMore、耗時與錯誤資訊。 |
TaskTraceItem | HS.DeviceControl.Core.Logging | 對應 task_log_traces 的查詢回傳項目。 |
TraceQueryInvalidRequest | HS.DeviceControl.Core.Common.ErrorCodes | 查詢條件不合法，例如沒有任何 filter。 |
TraceQueryDatabaseFailed | HS.DeviceControl.Core.Common.ErrorCodes | 查詢來源或資料庫存取失敗。 |
MySQL 第一版實作
| 元件 | 說明 |
MySqlTaskTraceStore | 實作 ITaskTraceStore.Query(...)。 |
MySqlTaskTraceStoreOptions | 定義 MySQL 連線與 task_log_traces table 設定。 |
MySqlTaskTraceStoreOptionsValidator | 驗證 host、port、database、user、password、table name 與 timeout。 |
MySqlTaskTraceStoreSqlBuilder | 產生參數化 SELECT SQL，依 filter 組合 WHERE。 |
IMySqlTaskTraceStoreGateway | internal gateway，方便 fake gateway 單元測試。 |
MySqlTaskTraceStoreGateway | 真實 MySQL 查詢 gateway；本次沒有執行真實 DB 測試。 |
MySqlTaskTraceDataRecordMapper | 將 IDataRecord 轉為 internal row。 |
MySqlTaskTraceStoreErrorMapper | 查詢失敗時遮蔽密碼後回傳錯誤訊息。 |
查詢規則
| 規則 | 第一版作法 |
| 查詢方法 | 同步 Query(TaskTraceQueryRequest request)，符合現有 MySQL infrastructure 慣例。 |
| 必要 filter | 至少需要一個 filter，避免無條件全表查詢。 |
| 支援 filter | TaskId、NodeId、DeviceId、CommandName、Level、Status、ErrorCode、CreatedFrom、CreatedTo。 |
| 分頁 | Limit 預設 100、上限 500；Offset 不可小於 0。 |
| 下一頁判斷 | 使用 Limit + 1 查詢並回傳 HasMore，不做 COUNT(*)。 |
| 排序 | 依 created_at 排序，預設新到舊，可設定由舊到新。 |
| SQL 安全 | 只使用參數化查詢；table name 只允許安全 identifier。 |
| 敏感資訊 | 查詢結果中的 message / raw summary / metadata 會再經 sanitizer 遮蔽 password、token、secret、authorization、connection string。 |
本次沒有納入
- 沒有執行真實 DB 查詢。
- 沒有執行 DDL、ALTER TABLE 或 cleanup。
- 沒有新增 WebApi endpoint。
- 沒有新增 ServiceHost。
- 沒有新增 WinForms Debug Tool。
- 沒有導入 Plugin Loader 或外部 DLL 載入機制。
- 沒有新增
Result<T>泛型結果型別。 - 沒有修改
ITaskStore或ILogWriterpublic method 簽章。
驗證結果
| 驗證 | 結果 |
dotnet test tests\HS.DeviceControl.Core.Tests\HS.DeviceControl.Core.Tests.csproj | 通過 180 個測試。 |
dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj --filter "FullyQualifiedName!~Manual" | 通過 77 個測試。 |
dotnet test HS.DeviceControl.sln --filter "FullyQualifiedName!~Manual" | 通過 406 個測試。 |
| GitHub Actions | 程式 repo 通知文件 repo 更新開發狀態 workflow 成功。 |
目前完成度判斷
3A Trace 查詢能力目前已完成第一版 public contract 與 fake gateway 查詢實作，可以支撐後續 Debug Tool、ServiceHost 或 WebApi 設計時引用同一個 read-side contract。
尚未代表可以由 API 查詢線上資料，也尚未代表已完成真實 DB 查詢驗證。真實 DB read-only 查詢入口已於 TaskTraceStore manual-only 查詢驗證入口紀錄 補上，但仍需使用者確認測試 DB 與 AllowRead 後才可執行。
建議下一步
建議下一步做「TaskTraceStore 真實 DB read-only 查詢驗證」，先確認測試 DB、查詢條件、ExpectedMinRows 與 AllowRead，再執行 gated manual-only 測試並回填實際驗證紀錄。