MySQL TaskTraceStore 查詢邊界設計

返回

MySQL TaskTraceStore 查詢邊界設計

1. 文件目的

本文件承接 MySQL DB LogWriter / TraceStore 邊界設計、MySQL DB LogWriter / TraceStore 第一版實作紀錄 與 MySQL DB LogWriter 真實 DB 驗證前確認清單，整理 TaskTraceStore 的查詢邊界。

本文件只做設計分析與後續實作前依據，不新增 TaskTraceStore public interface、不修改 ITaskStore、不修改 ILogWriter、不連真實 DB、不執行 DDL，也不導入 WebApi / ServiceHost。

2. 目前狀態

項目 狀態 說明
task_log_traces schema class 已完成 已可由 C# class 維護欄位、索引與描述。
MySqlLogWriter 已完成第一版 可將 LogEntry 映射為 trace row，並具備 fake gateway 測試與 fallback。
Payload sanitizer 已完成第一版 可遮罩 password、token、secret、authorization 與 connection string 類資訊。
manual-only xUnit 入口 已完成 HS_MYSQL_LOGWRITER_* gate 預設關閉，不連 DB、不寫入。
真實 DB 驗證前確認清單 已完成 已固定 task_log_traces 寫入 / 查詢 / cleanup 前置條件。
真實 DB 寫入 / 查詢 / cleanup 驗證 尚未完成 需使用者確認測試 DB 與 gate 後才能執行。
TaskTraceStore 查詢介面 尚未實作 本文件先定義查詢邊界，不新增 public contract。

3. 為什麼需要獨立 TaskTraceStore

task_log_traces 是診斷 trace table，資料量與查詢目的不同於 task_executions、node_executions。

資料來源 定位 不適合承擔的事
ITaskStore 任務主檔與節點摘要 不應保存大量 Raw / Metadata 診斷資料。
ILogWriter 寫入 log / trace 不應承擔查詢 API 或任務狀態回復。
TaskTraceStore trace read-side 查詢 不應改變 Workflow 狀態、不應寫入任務主檔。

因此建議後續採用獨立 read-side 邊界：

LogEntry -> MySqlLogWriter -> task_log_traces
                                      ↓
                              TaskTraceStore
                                      ↓
              Query by TaskId / NodeId / DeviceId / ErrorCode / TimeRange

4. 第一版查詢目標

第一版只建議支援診斷查詢，不支援報表、統計、即時監控或跨案場查詢。

查詢目標 必要性 說明
依 TaskId 查完整 trace 必要 驗證單一任務發生了哪些節點、設備命令與錯誤。
依 NodeId 查 trace 建議 協助定位特定 Workflow 節點問題。
依 DeviceId 查 trace 建議 協助定位特定設備或 Adapter 問題。
依 CommandName 查 trace 建議 協助定位特定命令問題。
依 ErrorCode 查 trace 建議 協助統一錯誤碼排查。
依 CreatedAt 時間區間查詢 必要 避免一次查出過多 trace。
分頁 / 上限 必要 避免大量資料造成 API 或工具卡住。

5. 建議查詢條件

後續若進入實作，查詢 request 建議具備以下欄位，但是否建立 public DTO 需另行確認：

欄位 型別草案 規則
TaskId string 可選；若有值，查指定任務。
NodeId string 可選；查指定節點。
DeviceId string 可選；查指定設備。
CommandName string 可選；查指定命令。
Level string 可選；例如 Info、Warning、Error。
ErrorCode string 可選；查特定錯誤。
CreatedFrom DateTime? 可選；若未提供，需搭配安全預設區間。
CreatedTo DateTime? 可選；不得早於 CreatedFrom。
Limit int 必填或預設；建議預設 100，最大 500。
Offset int 可選；第一版可先用 offset paging。
SortDescending bool 預設 true，先看最新 trace。

6. 回傳資料邊界

查詢回傳應是已摘要化與已遮罩的 trace row，不還原原始 object，也不回傳密碼、token 或完整 connection string。

欄位 是否建議回傳 說明
TraceId 是 trace row 識別碼。
TaskId 是 任務識別碼。
NodeId / NodeName 是 節點資訊。
DeviceId / CommandName 是 設備命令資訊。
Level / Status 是 診斷與狀態判讀。
RetryCount 是 可判斷重試行為。
TimeTakenMs / AdapterTimeTakenMs 是 可判斷耗時。
ErrorCode 是 可快速篩選錯誤。
Message 是 可讀摘要。
DataSummary 是 已摘要化資料。
RawRequestSummary 是 必須已遮罩與截斷。
RawResponseSummary 是 必須已遮罩與截斷。
MetadataSummary 是 必須已遮罩與截斷。
原始未處理 Raw object 否 不應由 TraceStore 還原或輸出。

7. SQL 查詢邊界

第一版查詢需遵守：

8. 不納入第一版的項目

項目 原因
WebApi trace endpoint 屬第三階段正式平台邊界。
ServiceHost trace 查詢 屬第三階段正式背景服務。
WinForms Debug Tool 屬現場工具，不屬第二階段 B 必要收斂。
跨 database / 多案場查詢 會擴大平台邊界。
報表統計 需要另一套聚合需求，不應塞進 trace store 第一版。
retention / purge job 屬維運策略，需另行設計。
public query interface 會新增 public contract，需使用者確認後才可實作。

9. 後續實作前確認項目

若要從設計進入實作，需先確認：

  1. 是否允許新增 TaskTraceStore public interface。
  2. 查詢介面要放在 Infrastructure.MySql 內部，還是先以 internal helper 驗證。
  3. 是否要建立獨立 query request / result model。
  4. 是否要支援 TaskId 必填，還是允許時間區間查詢。
  5. 最大 Limit 要採 100、500 或其他值。
  6. 是否需要回傳總筆數。
  7. 查詢結果是否要保留 Raw summary，或只回傳 message / error / metadata summary。
  8. 是否需要與未來 WebApi 的 contract 對齊。

10. 建議測試策略

測試 目的
Query builder 測試 確認不同 filter 會產生參數化 SQL。
Limit 上限測試 確認過大 limit 會被拒絕或縮到最大值。
Identifier 安全測試 確認 table name 不允許 SQL injection。
Row mapper 測試 確認 trace row 能轉成查詢結果。
Sanitized output 測試 確認查詢結果不含敏感原文。
Fake gateway 查詢測試 不連 DB 驗證 command 與參數。
manual-only 真實 DB 查詢 使用者確認後，搭配 task_log_traces 真實 DB 驗證紀錄執行。

11. 建議結論

TaskTraceStore 應作為 task_log_traces 的 read-side 邊界，不應與 ITaskStore 或 ILogWriter 混在一起。

目前第二階段 B 已具備 DB LogWriter 第一版與 manual-only xUnit 入口；下一步在未確認 public contract 前，建議先維持本文件作為設計邊界。若使用者同意新增查詢 contract，再進入 TaskTraceStore 實作前確認清單。