TaskTraceStore public 查詢介面實作前確認
本文件承接 MySQL TaskTraceStore 查詢邊界設計 與 第三階段前置規劃，用來整理 TaskTraceStore public 查詢介面進入程式 repo 前必須先確認的範圍、命名、資料模型與驗證方式。
本文件只做實作前確認，不代表已同意新增 public interface、DTO、WebApi、ServiceHost、正式 DB 查詢、DDL、啟動流程或外部服務設定。
目前可用基礎
| 項目 | 狀態 | 說明 |
task_log_traces schema class | 已完成 | 欄位、索引與 comment 已可由 C# class 維護。 |
MySqlLogWriter 第一版 | 已完成 | 可將 LogEntry 映射到 task_log_traces。 |
| payload sanitizer | 已完成 | 可遮罩 password、token、secret、authorization 與 connection string 類資訊。 |
| fake gateway 測試 | 已完成 | 已驗證寫入映射、fallback 與錯誤處理。 |
| manual-only xUnit 入口 | 已完成 | 預設不連 DB、不寫入，需明確 gate 才會執行。 |
| 真實測試 DB 驗證 | 已完成 | 已完成 task_log_traces 寫入 / 查詢 / cleanup 驗證。 |
| 查詢邊界設計 | 已完成 | 已先固定 read-side 角色、查詢條件、SQL 安全與停止線。 |
是否建議進入 public 查詢介面
建議可以進入「實作前確認」，但不建議直接進入程式實作。
原因是 TaskTraceStore 會成為後續 WebApi、ServiceHost、Debug Tool 與資料庫儀表板共用的 read-side contract；如果命名、DTO、分頁、排序、遮罩規則或錯誤格式沒有先固定，後續 API 與 UI 很容易被第一版臨時模型綁住。
建議 public contract 邊界
| 項目 | 建議 | 備註 |
| 介面名稱 | 優先評估 ITaskTraceStore | 延續 TaskStore 命名語意；進程式 repo 前仍需檢查既有命名慣例。 |
| 職責 | 只讀 task_log_traces | 不改 Workflow 狀態、不寫入任務主檔、不執行 cleanup。 |
| 回傳格式 | 使用專用 TaskTraceQueryResult + ErrorInfo | 目前 Core Result 不是泛型；不建議為 3A 第一版新增 Result<T>。 |
| 查詢型態 | 第一版建議採同步 Query(...) | 程式 repo 既有 MySQL TaskStore / LogWriter 為同步介面；後續 WebApi / ServiceHost 再另行評估 async。 |
| DB 執行方式 | 參數化 SQL | 不接受使用者輸入直接組 table、column、order by。 |
| 使用範圍 | Infrastructure read-side | WebApi / ServiceHost / UI 只能在後續階段引用，不在本次導入。 |
候選 method 形狀
以下只作為討論草案，不是最終 public method 簽章：
TaskTraceQueryResult Query(TaskTraceQueryRequest request);這個草案依 TaskTraceStore 介面命名與 DTO 位置盤點 調整而來。
不建議第一版使用 Result<TaskTraceQueryResult>，因為目前 Core 只有非泛型 Result。若要新增泛型 Result，會變成另一個 public contract 決策，應另案討論。
Request model 候選欄位
| 欄位 | 必填 | 建議規則 |
TaskId | 否 | 若未提供，必須至少提供時間範圍或其他主要條件，避免全表查詢。 |
NodeId | 否 | 篩選特定節點 trace。 |
DeviceId | 否 | 篩選特定設備 trace。 |
CommandName | 否 | 篩選特定設備命令。 |
Level | 否 | 篩選 info / warning / error 類級別。 |
Status | 否 | 篩選 success / failed / timeout 類狀態。 |
ErrorCode | 否 | 篩選特定錯誤代碼。 |
CreatedFrom | 否 | 時間範圍起點。 |
CreatedTo | 否 | 時間範圍終點，不可早於 CreatedFrom。 |
Limit | 否 | 預設 100，第一版最大建議 500。 |
Offset | 否 | 預設 0，不可小於 0。 |
SortDescending | 否 | 預設依 created_at 由新到舊。 |
Result model 候選欄位
| 欄位 | 用途 |
Success | 是否查詢成功。 |
Items | 查回的 trace 清單。 |
Limit | 本次查詢限制筆數。 |
Offset | 本次查詢位移。 |
HasMore | 是否仍有下一頁資料。 |
Error | 失敗時使用 ErrorInfo。 |
TimeTakenMs | 查詢耗時。 |
TotalCount | 第一版建議不做，避免大量資料查詢成本過高。 |
Items 建議至少包含：
TraceIdTaskIdNodeIdNodeNameDeviceIdCommandNameLevelStatusRetryCountTimeTakenMsAdapterTimeTakenMsErrorCodeMessageDataSummaryRawRequestSummaryRawResponseSummaryMetadataSummaryCreatedAt
驗證規則
| 規則 | 建議處理 |
| 沒有任何查詢條件 | 回傳 validation error，不執行全表查詢。 |
Limit 未填 | 使用預設 100。 |
Limit 超過上限 | 回傳 validation error 或壓到最大值；建議第一版回傳錯誤。 |
Offset 小於 0 | 回傳 validation error。 |
CreatedTo 早於 CreatedFrom | 回傳 validation error。 |
| 字串條件過長 | 回傳 validation error，避免異常查詢與 log 污染。 |
| 排序欄位 | 第一版只允許 created_at，不開放任意欄位。 |
遮罩與安全規則
- read-side 不得還原已遮罩資料。
RawRequestSummary、RawResponseSummary、MetadataSummary若包含敏感字串，仍需經 sanitizer。- 測試需覆蓋 password、token、secret、authorization、connection string 類字串。
- 不得將 DB password、Token、連線字串、IP 白名單或外部服務 Secret 寫入 repo。
SQL 與資料庫查詢規則
- 必須使用參數化 SQL。
- table / column / order by 必須由程式白名單決定。
- 第一版不接受任意 SQL filter。
- 預設排序為
created_at DESC。 - 查詢 timeout 應可設定，但不得把敏感連線資訊寫入文件或 Log。
- 查詢失敗需回標準
ErrorInfo，保留可判斷原因的錯誤碼與訊息。
錯誤碼建議
| 錯誤情境 | 建議錯誤語意 |
| 查詢條件不合法 | TraceQueryInvalidRequest |
| 未提供必要篩選條件 | TraceQueryFilterRequired |
| DB 查詢失敗 | TraceQueryDatabaseFailed |
| DB timeout | TraceQueryTimeout |
| schema 不符合預期 | TraceQuerySchemaMismatch |
| 連線不可用 | TraceQueryConnectionUnavailable |
實際錯誤碼名稱需進程式 repo 後比對既有 ErrorCode 命名風格再決定。
測試計畫
| 測試類型 | 目的 |
| Request validator unit test | 驗證必要條件、分頁、時間範圍、字串長度。 |
| SQL builder fake test | 驗證 SQL 使用參數化、排序白名單與條件組合。 |
| Row mapper test | 驗證 DB row 可轉為 TaskTraceItem。 |
| sanitizer output test | 驗證 read-side 回傳仍不洩漏敏感資訊。 |
| fake gateway query test | 不連 DB 驗證查詢流程與錯誤處理。 |
| manual-only 真實 DB 查詢測試 | 使用者授權後，對測試 DB 執行查詢驗證；預設關閉。 |
停止線
以下項目不得在未確認前直接執行：
- 新增
ITaskTraceStorepublic interface。 - 新增或固定 public DTO / model。
- 改動
ITaskStore、ILogWriter或既有 public method 簽章。 - 導入 WebApi、ServiceHost、WinForms Debug Tool 或 UI。
- 連真實 DB 執行查詢、寫入、DDL、cleanup。
- 修改設定檔格式、啟動流程、Secret、GitHub / Cloudflare 設定。
決策表
| 決策項 | 建議 | 是否已定案 |
| 介面名稱 | 建議採 ITaskTraceStore | 待使用者確認 |
| DTO 位置 | 建議放在 HS.DeviceControl.Core.Logging | 待使用者確認 |
| sync / async | 第一版建議同步 Query(TaskTraceQueryRequest request) | 待使用者確認 |
TaskTraceQueryResult | 建議採專用 result，內含 Success、Items、Error、TimeTakenMs | 待使用者確認 |
TotalCount | 第一版不做，改用 HasMore | 待使用者確認 |
| 查詢上限 | 預設 100，最大 500 | 待使用者確認 |
| 無條件查詢 | 不允許 | 建議定案 |
| 排序欄位 | 第一版只允許 created_at DESC | 建議定案 |
| manual-only 真實 DB 查詢 | 只在使用者授權與 gate 開啟後執行 | 建議定案 |
建議下一步
程式 repo 命名與 DTO 位置盤點已完成，建議下一步由使用者確認以下 5 點：
- 允許新增
ITaskTraceStore。 - 允許在
HS.DeviceControl.Core.Logging新增TaskTraceQueryRequest、TaskTraceQueryResult、TaskTraceItem。 - 第一版採同步
Query(TaskTraceQueryRequest request)。 - 第一版不做
TotalCount，改用HasMore。 - 第一版不允許無條件全表查詢。
確認後再進入程式 repo fake gateway 查詢實作；未確認前不新增 public contract。