# MySQL DB LogWriter / TraceStore 第一版實作紀錄

## 1. 實作目的

本次實作承接 [MySQL DB LogWriter / TraceStore 實作前確認](mysql-db-logwriter-tracestore-preimplementation-checklist.md)，先建立 DB LogWriter 的第一版可測試骨架，讓 `LogEntry` 可以被映射成 MySQL trace row，並具備 SQL 產生、payload 遮罩與寫入失敗 fallback 行為。

本次仍維持第二階段範圍控制：

- 不執行真實 DB DDL。
- 不自動建立或修改 MySQL table。
- 不改動 `ILogWriter.Write(LogEntry entry)` public contract。
- 不改動 `TaskExecutionRecord` / `TaskNodeExecutionRecord` public model。
- 不導入 `TaskTraceStore` public 查詢介面。
- 不將 MySqlLogWriter 自動接入 ConsoleHost 啟動流程。

## 2. 新增內容

| 項目 | 狀態 | 說明 |
| --- | --- | --- |
| `task_log_traces` schema class | 已完成 | 新增 `MySqlTaskLogTraceSchema`，可由 schema parser / SQL generator 產出 MySQL 5.6.2 相容的 table preview。 |
| `MySqlLogWriterOptions` | 已完成 | 提供 LogWriter 專用 MySQL 連線與 table 設定，預設 table 為 `task_log_traces`。 |
| options validator | 已完成 | 驗證 host、port、database、user、password、table name 與 timeout。 |
| `LogEntry` mapper | 已完成 | 將 `LogEntry` 映射成 trace record，包含 Task、Node、Device、Command、Status、Error、Raw summary 與建立時間。 |
| payload sanitizer | 已完成 | 針對 password、pwd、token、secret、authorization、connection string 類型資訊做遮罩，並限制欄位長度。 |
| MySQL insert SQL builder | 已完成 | 產生 `INSERT INTO task_log_traces` SQL 與參數，不直接串接 payload。 |
| MySQL gateway | 已完成 | 第一版同步 `ExecuteNonQuery` 寫入 gateway，可由 fake gateway 測試替代。 |
| fallback 行為 | 已完成 | MySQL 寫入失敗或 options 無效時，不拋出例外，改寫入 fallback writer。 |

## 3. 尚未導入內容

| 項目 | 原因 |
| --- | --- |
| 真實 MySQL DDL / CREATE TABLE | 需使用者確認後才可操作真實 DB。 |
| manual-only 真實 DB 寫入測試 | 需先確認 `task_log_traces` table 建立方式與測試資料 cleanup 規則。 |
| ConsoleHost 自動啟用 MySqlLogWriter | 會改變啟動行為，需另行確認。 |
| `TaskTraceStore` public query interface | 會新增查詢 contract，需先完成查詢需求與邊界確認。 |
| retention / cleanup job | 屬於維運策略，第一版先不納入。 |

## 4. 驗證結果

已執行：

```powershell
dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj
dotnet test HS.DeviceControl.sln
```

結果：

- MySQL Infrastructure 測試通過：73 passed。
- 全 solution 測試通過：
  - Core：176 passed。
  - Adapters：108 passed。
  - Infrastructure.MySql：73 passed。
  - WorkflowSimulation：11 passed。
  - ModbusPoc：37 passed。
- 僅出現既有 `.NET 5.0` EOL SDK warning，非本次變更造成。

## 5. 影響範圍

本次影響範圍集中在 `HS.DeviceControl.Infrastructure.MySql`：

- 新增 MySQL log trace 寫入能力。
- 新增 `task_log_traces` schema preview 能力。
- 新增 fake gateway 測試，未碰真實 MySQL。
- 不影響 Core、Adapter、WorkflowEngine、TaskStore 既有 public contract。
- 不改變 ConsoleHost 啟動方式。

## 6. 下一步建議

建議下一步先做「MySQL DB LogWriter manual-only 真實 DB 驗證設計」，確認：

1. `task_log_traces` table 是否由 SQL preview 手動建立。
2. 真實 DB 寫入測試的 manual-only gate 名稱。
3. 測試資料 trace_id / task_id 命名規則。
4. 測試後 cleanup 條件。
5. index 與 comment 是否需要一併驗證。

確認後再進入真實 DB 寫入 / 查詢驗證，避免未經確認就對外部 MySQL 產生資料。