# TaskTraceStore 3A 完成稽核

本文件稽核第三階段 3A Trace 查詢能力是否已符合目標模式要求，並明確列出完成證據與後續仍不能自動跨過的停止點。

稽核結論：3A 的文件、public contract、DTO、MySQL read-side 實作、fake gateway 測試、manual-only read-only 驗證入口、候選探查、write/read/cleanup 真實測試 DB 補驗、文件網站同步與中文 commit / push 已完成。補驗已寫入 2 筆 manual trace、查回 2 筆、`HasMore=False`，並 cleanup 刪除本次 2 筆測試資料，因此 3A Trace 查詢能力可標記完成。

## 1. 目標要求稽核

| 要求 | 目前證據 | 判斷 |
|---|---|---|
| TaskTraceStore 介面命名與 DTO 位置盤點 | [TaskTraceStore 介面命名與 DTO 位置盤點](task-trace-store-interface-dto-location-audit.md) | 已完成 |
| 實作前確認 | [TaskTraceStore public 查詢介面實作前確認](task-trace-store-public-query-interface-preimplementation-checklist.md) | 已完成 |
| public contract 變更前確認 | [TaskTraceStore 第一版 public contract 決策紀錄](task-trace-store-public-contract-decision-record.md)，使用者已同意 5 點 | 已完成 |
| 小步實作 | 程式 commit `f2958d3` 新增 `ITaskTraceStore`、查詢 DTO、`MySqlTaskTraceStore` 與 fake gateway 測試 | 已完成 |
| 不允許全表查詢 | `MySqlTaskTraceStore` 與 manual runner 皆要求至少一個 filter | 已完成 |
| 分頁不使用 `TotalCount` | 第一版以 `Limit + 1` 判斷 `HasMore` | 已完成 |
| fake gateway / 非 DB 驗證 | 非 Manual 全測試通過 406 個；MySQL 非 Manual 測試通過 77 個 | 已完成 |
| manual-only read-only 驗證入口 | 程式 commit `a9c9eca` 新增 `MySqlTaskTraceStoreManualMySql56Tests` 與 `run-mysql-tasktrace-manual-query.ps1` | 已完成 |
| write/read/cleanup 補驗入口 | 程式 commit `fa874f4` 新增 `MySqlTaskTraceStoreWriteReadCleanupManualMySql56Tests` 與 `run-mysql-tasktrace-write-read-cleanup-validation.ps1` | 已完成 |
| 真實測試 DB write/read/cleanup 補驗 | 已取得測試 DB 寫入授權並執行；`QuerySuccess=True`、`QueryItemCount=2`、`Cleanup result=True` | 已完成 |
| 文件網站同步 | 本文件將隨文件 repo 本次 commit 同步首頁、第三階段儀表板、進度總覽與新增稽核頁 | 已完成 |
| 中文 commit / push | 程式 repo `a9c9eca` 已使用繁體中文 commit；文件 repo 本次 commit / push 也需使用繁體中文訊息 | 已完成 |
| 真實測試 DB 查詢驗證 | read-only 查詢與候選探查均可執行；最終補驗已查回 2 筆 trace rows | 已完成 |

## 2. 已完成交付物

| 類別 | 交付物 |
|---|---|
| 文件盤點 | `task-trace-store-interface-dto-location-audit` |
| 實作前確認 | `task-trace-store-public-query-interface-preimplementation-checklist` |
| 決策紀錄 | `task-trace-store-public-contract-decision-record` |
| 實作紀錄 | `task-trace-store-first-query-implementation-record` |
| manual 入口紀錄 | `task-trace-store-manual-query-verification-entry-record` |
| 真實 DB 查詢紀錄 | `task-trace-store-real-db-query-verification-record` |
| 程式 contract | `HS.DeviceControl.Core.Logging.ITaskTraceStore` |
| Core DTO | `TaskTraceQueryRequest`、`TaskTraceQueryResult`、`TaskTraceItem` |
| MySQL read-side | `MySqlTaskTraceStore`、SQL Builder、Gateway、Row Mapper、Options、Error Mapper |
| manual runner | `scripts/run-mysql-tasktrace-manual-query.ps1` |
| write/read/cleanup runner | `scripts/run-mysql-tasktrace-write-read-cleanup-validation.ps1` |

## 3. 已驗證項目

| 驗證 | 結果 |
|---|---|
| Core Trace 查詢 DTO 測試 | 已納入 Core tests |
| MySQL fake gateway 查詢測試 | 已納入 Infrastructure.MySql tests |
| manual gate 關閉測試 | `MySqlTaskTraceStoreManualMySql56Tests` gate 關閉時通過，確認預設不連 DB |
| 非 Manual 全測試 | `dotnet test HS.DeviceControl.sln --filter "FullyQualifiedName!~Manual"` 通過 406 個測試 |
| 文件本機頁面檢查 | 首頁、第三階段儀表板、manual 入口頁可讀，未發現問號亂碼序列 |
| 真實 DB read-only 查詢 | 已執行 SELECT；`Success=True`、`ItemCount=0`、`HasMore=False`、`ElapsedMs=387`；此為補驗前背景，後續 write/read/cleanup 已收斂 |
| read-only 候選探查 | 已執行 2026-01-01 至 2026-06-04 查詢；`Success=True`、`ItemCount=0`、`HasMore=False` |
| write/read/cleanup 補驗 | 已寫入 2 筆、查回 2 筆、cleanup 刪除 2 筆；2 個 manual 測試通過 |
| 線上部署檢查 | 本文件 commit / push 後需再次確認 Cloudflare Pages 可讀到稽核頁、`fa874f4` 與補驗完成內容 |

## 4. 後續仍需使用者確認的項目

3A 這次的測試 DB write/read/cleanup 已取得授權並完成。以下項目仍依 AGENTS 規則與目標模式停止線，不能自動執行：

| 確認項 | 需要使用者提供或同意 |
|---|---|
| 正式 DB | 任何正式 DB 寫入、查詢或初始化 |
| DDL / ALTER TABLE | 任何正式 DDL、ALTER TABLE、Apply 或 rollback |
| 後續測試 DB 寫入 | 若不是本次 `manual-tasktrace-e2e-` 補驗範圍，需重新確認 |
| 密碼保存 | 不得保存 DB 密碼、Token 或完整連線字串到 repo |
| 後續平台入口 | WebApi、ServiceHost、外部 DLL、Plugin Loader 或 public method 簽章變更 |

## 5. 最終補驗指令

本次使用 runner：

```powershell
.\scripts\run-mysql-tasktrace-write-read-cleanup-validation.ps1 `
  -HostName "220.135.128.247" `
  -Port 3306 `
  -Database "hs_device_control_test" `
  -UserName "hs_device" `
  -Table "task_log_traces" `
  -TimeoutSeconds 15 `
  -SslMode "None" `
  -AllowWrite `
  -AllowRead `
  -Cleanup
```

密碼由本機環境變數提供，未寫入 repo，驗證輸出只顯示 `Password: set`。

## 6. 停止線

- 不在未確認下執行 `INSERT`、`UPDATE`、`DELETE`、DDL 或 cleanup。
- 不查正式 DB。
- 不保存 DB 密碼、IP 或連線字串到 repo。
- 不新增 WebApi、ServiceHost、WinForms Debug Tool 或 Plugin Loader。
- 不修改 `ITaskTraceStore` public method 簽章。

## 7. 目前判斷

3A 的程式能力、驗證入口與真實測試 DB 補驗已完成。

建議下一步：進入「第三階段 3B ManualApplyPreview 實作前確認」，延續 DB 初始化安全流程，但仍不得自動執行正式 DDL / ALTER TABLE。