TaskTraceStore 第一版 public contract 決策紀錄
本文件承接 TaskTraceStore 介面命名與 DTO 位置盤點 與 TaskTraceStore public 查詢介面實作前確認，整理第三階段 3A Trace 查詢能力在進入程式實作前必須由使用者確認的 public contract 決策。
本文件只做決策紀錄，不代表已同意新增 public interface、DTO、錯誤碼、MySQL 查詢實作、真實 DB 查詢、WebApi、ServiceHost 或啟動流程變更。
決策狀態
| 項目 | 狀態 |
| 決策日期 | 2026-06-03 |
| 目前狀態 | 待使用者確認 |
| 是否已可改程式 repo public contract | 否 |
是否可新增 ITaskTraceStore | 尚未確認 |
| 是否可新增 DTO | 尚未確認 |
| 是否可執行真實 DB 查詢 | 否 |
需使用者確認的 5 點
| 順序 | 決策項 | 建議 | 確認狀態 |
| 1 | 新增 public interface | 允許新增 ITaskTraceStore | 待確認 |
| 2 | DTO namespace | 允許在 HS.DeviceControl.Core.Logging 新增 TaskTraceQueryRequest、TaskTraceQueryResult、TaskTraceItem | 待確認 |
| 3 | 方法型態 | 第一版採同步 Query(TaskTraceQueryRequest request) | 待確認 |
| 4 | 分頁策略 | 第一版不做 TotalCount，改用 HasMore | 待確認 |
| 5 | 查詢安全 | 第一版不允許無條件全表查詢 | 待確認 |
使用者未明確同意前，Codex 不得新增上述 public interface、DTO 或 method 簽章。
同意後的程式實作範圍
| 區域 | 預計新增 / 修改 | 說明 |
| Core Logging | ITaskTraceStore | Trace read-side 查詢入口。 |
| Core Logging | TaskTraceQueryRequest | 查詢條件 DTO。 |
| Core Logging | TaskTraceQueryResult | 專用查詢結果，內含 Success、Items、Limit、Offset、HasMore、Error、TimeTakenMs。 |
| Core Logging | TaskTraceItem | 查詢回傳 item，對應 task_log_traces 已摘要與遮罩後欄位。 |
| Core Common | 視需要新增 Trace 查詢錯誤碼 | 例如 query 條件不合法或資料庫查詢失敗；若新增 constant，仍需清楚說明。 |
| Infrastructure.MySql.Logging | MySqlTaskTraceStore | MySQL read-side store。 |
| Infrastructure.MySql.Logging | MySqlTaskTraceStoreOptions / validator | 查詢連線、table name、limit 上限等設定。 |
| Infrastructure.MySql.Logging | SQL builder / gateway / row mapper | 參數化查詢、fake gateway 測試與資料列映射。 |
| Tests | Core / MySQL fake gateway 測試 | 不連真實 DB 驗證 public DTO、validator、SQL builder、row mapper 與 HasMore。 |
不納入第一批實作
| 不納入項目 | 原因 |
| WebApi endpoint | 屬第三階段 3C，需另行確認 API route 與權限。 |
| ServiceHost | 會改正式執行入口與啟動方式，需另行確認。 |
| WinForms Debug Tool | 屬後續現場工具，不納入 3A 第一批。 |
| 真實 DB manual-only 查詢 | 需等 fake gateway 與單元測試完成後，再由使用者授權 DB 資訊與 gate。 |
| 正式 DB DDL / ALTER TABLE | task_log_traces schema 已存在；3A 查詢不應執行 DDL。 |
| 外部 DLL / Plugin Loader | 屬第三階段 3D，不屬 Trace 查詢第一版。 |
Result<T> 泛型結果型別 | 會新增額外 public contract；3A 第一版採專用 result 即可。 |
建議第一批測試清單
| 測試 | 目的 |
TaskTraceQueryRequest 空條件驗證 | 確認不允許無條件全表查詢。 |
Limit 預設與上限驗證 | 確認預設 100、最大 500，超過上限會失敗。 |
Offset 驗證 | 確認不可小於 0。 |
CreatedFrom / CreatedTo 驗證 | 確認結束時間不可早於開始時間。 |
| SQL builder 條件組合測試 | 確認 TaskId、NodeId、DeviceId、CommandName、Level、Status、ErrorCode、時間範圍都用參數化 SQL。 |
HasMore 測試 | 使用 Limit + 1 查詢策略，不做 COUNT(*)。 |
| Row mapper 測試 | 確認 DB row 可映射成 TaskTraceItem。 |
| fake gateway query 測試 | 不連 DB 驗證 MySqlTaskTraceStore.Query(...) 流程。 |
| 錯誤遮罩測試 | 查詢結果或錯誤訊息不得洩漏 password、token、secret、authorization、connection string。 |
驗收標準
dotnet test通過，且包含 Core / MySQL Trace 查詢相關測試。- 不新增 WebApi、ServiceHost、WinForms Debug Tool 或 Plugin Loader。
- 不修改
ITaskStore、ILogWriter、既有 public method 簽章或專案啟動方式。 - 不執行真實 DB 查詢、DDL、cleanup。
- 文件網站同步 3A 狀態與下一步。
建議下一步
請使用者確認是否同意本文件的 5 點 public contract 決策。
同意後，Codex 可開始「ITaskTraceStore 第一版 fake gateway 查詢實作」；未同意前只能繼續整理文件，不得新增 public contract。