# MySQL DB LogWriter / TraceStore manual-only xUnit 驗證入口實作紀錄

## 1. 實作目的

本次實作承接 [MySQL DB LogWriter / TraceStore manual-only 真實 DB 驗證設計](mysql-db-logwriter-tracestore-manual-verification-design.md)，新增 `MySqlLogWriter` 對真實 MySQL 5.6.2 測試 DB 的 manual-only xUnit 驗證入口。

此入口預設不連 DB、不寫入資料；只有使用者明確設定 `HS_MYSQL_LOGWRITER_ENABLED=true` 與 `HS_MYSQL_LOGWRITER_ALLOW_WRITE=true` 後，才會進入 schema precheck、寫入、查詢與 cleanup 流程。

## 2. 新增內容

| 項目 | 狀態 | 說明 |
| --- | --- | --- |
| manual-only 測試檔 | 已完成 | 新增 `tests/HS.DeviceControl.Infrastructure.MySql.Tests/Logging/MySqlLogWriterManualMySql56Tests.cs`。 |
| LogWriter 專用 gate | 已完成 | 使用 `HS_MYSQL_LOGWRITER_ENABLED` 與 `HS_MYSQL_LOGWRITER_ALLOW_WRITE`，不與 TaskStore gate 混用。 |
| schema precheck | 已完成 | 先透過 `MySqlSchemaInspector` 檢查 `task_log_traces` table、欄位、索引與 comment。 |
| 固定 manual 前綴 | 已完成 | 測試 `task_id` 與 `trace_id` 使用 `manual-logwriter-poc-` 前綴。 |
| 真實 DB 寫入入口 | 已完成 | 使用 `MySqlLogWriter.Write(LogEntry)` 寫入兩筆 trace。 |
| 查詢驗證 helper | 已完成 | 依 `task_id` 查詢 `task_log_traces`，驗證 row count 與核心欄位。 |
| sanitizer 驗證 | 已完成 | 驗證查回資料不包含 `secret` 原文，需包含遮蔽符號。 |
| cleanup | 已完成 | 僅刪除本次 manual `task_id` 的 trace rows。 |

## 3. 環境變數

後續真實 DB manual-only 驗證需由使用者本機設定：

```text
HS_MYSQL_LOGWRITER_ENABLED
HS_MYSQL_LOGWRITER_ALLOW_WRITE
HS_MYSQL_LOGWRITER_HOST
HS_MYSQL_LOGWRITER_PORT
HS_MYSQL_LOGWRITER_DATABASE
HS_MYSQL_LOGWRITER_USER
HS_MYSQL_LOGWRITER_PASSWORD
HS_MYSQL_LOGWRITER_TABLE
HS_MYSQL_LOGWRITER_TIMEOUT_SECONDS
HS_MYSQL_LOGWRITER_SSL_MODE
HS_MYSQL_LOGWRITER_CLEANUP
```

安全規則：

- `HS_MYSQL_LOGWRITER_ENABLED` 未設為 `true` 時，不連 DB。
- `HS_MYSQL_LOGWRITER_ALLOW_WRITE` 未設為 `true` 時，不寫入。
- `HS_MYSQL_LOGWRITER_PASSWORD` 不得寫入 repo、文件或測試輸出。
- `HS_MYSQL_LOGWRITER_TABLE` 預設為 `task_log_traces`。
- cleanup 只允許清除 `manual-logwriter-poc-` 前綴的本次測試資料。

## 4. 測試內容

新增測試：

| 測試 | 目的 |
| --- | --- |
| `WriteAndInspect_ShouldPersistTaskLogTracesWhenManualGateIsEnabled` | gate 開啟時執行 schema precheck、寫入兩筆 trace、查詢資料、驗證 sanitizer 與 cleanup。 |
| `ManualGate_ShouldSkipLogWriterWriteWhenDisabled` | gate 關閉或未允許寫入時，不連 DB、不寫入。 |

一般 `dotnet test` 只會走 gate 關閉路徑，因此不會對外部 MySQL 產生資料。

## 5. 驗證結果

已執行：

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

結果：

```text
已通過，總計 75，失敗 0。
```

本次測試未開啟 `HS_MYSQL_LOGWRITER_*` gate，因此沒有連線真實 DB，也沒有寫入 `task_log_traces`。

## 6. 影響範圍

本次影響範圍：

- 新增 manual-only xUnit 驗證入口。
- 不修改 `ILogWriter` public contract。
- 不新增 `TaskTraceStore` public 查詢介面。
- 不修改 `MySqlLogWriter` 正式寫入邏輯。
- 不執行 DDL。
- 不接入 ConsoleHost、ServiceHost 或 WebApi。

## 7. 下一步建議

已補 [MySQL DB LogWriter 真實 DB 驗證前確認清單](mysql-db-logwriter-tracestore-real-db-precheck.md)。建議下一步依該清單確認：

1. 測試 DB 已存在 `task_log_traces`。
2. table、columns、indexes、comments 是否符合 C# schema。
3. 使用者是否允許 INSERT / SELECT / cleanup。
4. 使用者是否要驗證 sanitizer 查回結果。
5. 是否可以保存 DB 名稱與 user，host 是否遮蔽。

確認後再由使用者設定 `HS_MYSQL_LOGWRITER_*` gate，執行真實 DB 寫入 / 查詢 / cleanup 驗證。