# TaskTraceStore 第一版 public contract 決策紀錄

本文件承接 [TaskTraceStore 介面命名與 DTO 位置盤點](task-trace-store-interface-dto-location-audit.md) 與 [TaskTraceStore public 查詢介面實作前確認](task-trace-store-public-query-interface-preimplementation-checklist.md)，整理第三階段 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 簽章。

## 同意後的程式實作範圍

若使用者同意 5 點，第一批程式實作建議只包含以下內容：

| 區域 | 預計新增 / 修改 | 說明 |
|---|---|---|
| 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。