# MySQL DB LogWriter task_log_traces 真實 DB 驗證紀錄

## 1. 驗證概況

| 項目 | 內容 |
|---|---|
| 驗證節點 | MySQL DB LogWriter `task_log_traces` 真實 DB manual-only 寫入 / 查詢 / cleanup |
| 驗證狀態 | 已完成測試 DB DDL 建表與 manual-only 寫入 / 查詢 / cleanup 驗證 |
| 驗證日期 | 2026-06-03 |
| 程式 repo 分支 | `poc/nmodbus-tcp` |
| DB LogWriter 實作基準 commit | `843b593` |
| 首次缺表實測 commit | `876d97f` |
| 成功實測執行 commit | `d5fb311` |
| 驗證紀錄回填 commit | `84ec9a1` |
| 測試 DB | `hs_device_control_test` |
| DB host | 已遮蔽 |
| Port | `3306` |
| User | `hs_device` |
| Target table | `task_log_traces` |
| DDL | 已由使用者授權，只在測試 DB 執行 `CREATE TABLE IF NOT EXISTS task_log_traces` |
| Cleanup | 已刪除本次 `manual-logwriter-poc-` task id，affected=2 |

本驗證先前在 2026-06-03 以真實 DB manual-only 方式執行時，已成功進入 gate 與 schema precheck，但測試 DB 尚未建立 `task_log_traces` table，因此停在 schema precheck，不進行寫入。使用者明確授權測試 DB DDL 後，Codex 依 `MySqlTaskLogTraceSchema` 與 `MySqlSchemaSqlGenerator` 產生 SQL preview，並只在測試 DB 執行 `CREATE TABLE IF NOT EXISTS task_log_traces`，接著重新執行寫入 / 查詢 / cleanup 驗證並通過。

## 2. 驗證目的

確認 `MySqlLogWriter.Write(LogEntry)` 在真實 MySQL 5.6.2 測試 DB 與 manual-only gate 下可以：

1. 通過 `task_log_traces` schema precheck。
2. 將兩筆測試 `LogEntry` 寫入真實 DB。
3. 依本次 `task_id` 查回 trace rows。
4. 驗證 `ErrorCode`、`Level`、`TaskId` 等關鍵欄位有正確保存。
5. 驗證 `RawRequestSummary`、`RawResponseSummary`、`MetadataSummary` 已完成遮罩與摘要處理。
6. cleanup 只刪除本次 manual 測試資料。

## 3. 預設安全測試結果

2026-06-03 已先確認一般自動測試在不開啟真實 DB 寫入 gate 時仍安全：

```powershell
$env:HS_MYSQL_LOGWRITER_ENABLED='false'
$env:HS_MYSQL_LOGWRITER_ALLOW_WRITE='false'
dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj --filter "FullyQualifiedName~Logging" --logger "console;verbosity=detailed"
```

| 項目 | 結果 |
|---|---|
| 測試數 | 16 |
| 通過 | 16 |
| 失敗 | 0 |
| manual gate | 關閉 |
| 真實 DB 連線 | 未執行 |
| 真實 DB 寫入 | 未執行 |

manual-only 測試會輸出：

```text
MySQL LogWriter manual verification is disabled.
Enabled: False
AllowWrite: False
SkipReason: HS_MYSQL_LOGWRITER_ENABLED is not true.
```

## 4. 真實 DB 驗證條件

真實 DB 驗證必須同時符合以下條件：

| 項目 | 驗證條件 |
|---|---|
| 測試 DB | 必須是 `hs_device_control_test`，不得使用正式 DB。 |
| Table | 只允許 `task_log_traces`。 |
| 欄位 | 必須符合 `MySqlTaskLogTraceSchema`。 |
| 索引 | 必須包含 `idx_task_log_traces_task_id`、`idx_task_log_traces_node_id`、`idx_task_log_traces_device`、`idx_task_log_traces_command`、`idx_task_log_traces_level`、`idx_task_log_traces_error_code`、`idx_task_log_traces_created_at`。 |
| Comment | table comment 與 column comment 必須存在。 |
| 寫入 | 只允許本次 manual 測試資料 INSERT / SELECT / DELETE。 |
| Cleanup | 只允許刪除本次 `manual-logwriter-poc-` 前綴資料。 |
| 敏感資訊 | Host 與 password 不可寫入 repo、文件、commit message 或輸出摘要。 |

## 5. 真實 DB 驗證指令

使用程式 repo 的 manual-only 驗證腳本執行：

```powershell
.\scripts\run-mysql-logwriter-manual-validation.ps1 `
  -HostName "<test-db-host>" `
  -Port 3306 `
  -Database "hs_device_control_test" `
  -UserName "hs_device" `
  -Table "task_log_traces" `
  -TimeoutSeconds 15 `
  -SslMode "None" `
  -AllowWrite `
  -Cleanup
```

也可以用環境變數方式執行，密碼只存在目前 PowerShell session，不寫入 repo：

```powershell
$env:HS_MYSQL_LOGWRITER_ENABLED="true"
$env:HS_MYSQL_LOGWRITER_ALLOW_WRITE="true"
$env:HS_MYSQL_LOGWRITER_HOST="<test-db-host>"
$env:HS_MYSQL_LOGWRITER_PORT="3306"
$env:HS_MYSQL_LOGWRITER_DATABASE="hs_device_control_test"
$env:HS_MYSQL_LOGWRITER_USER="hs_device"
$env:HS_MYSQL_LOGWRITER_PASSWORD="<password>"
$env:HS_MYSQL_LOGWRITER_TABLE="task_log_traces"
$env:HS_MYSQL_LOGWRITER_TIMEOUT_SECONDS="15"
$env:HS_MYSQL_LOGWRITER_SSL_MODE="None"
$env:HS_MYSQL_LOGWRITER_CLEANUP="true"

dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj --filter FullyQualifiedName~MySqlLogWriterManualMySql56Tests --logger "console;verbosity=detailed"
```

## 6. 測試 DB DDL 執行結果

| 項目 | 結果 |
|---|---|
| 授權 | 使用者明確授權執行測試 DB DDL |
| 執行範圍 | 僅限 `hs_device_control_test.task_log_traces` |
| SQL 來源 | `MySqlTaskLogTraceSchema` + `MySqlSchemaSqlGenerator` |
| 執行 SQL | `CREATE TABLE IF NOT EXISTS task_log_traces` |
| DROP / ALTER | 未執行 |
| 正式 DB | 未接觸 |
| TableExists | `True` |
| TableCommentPresent | `True` |
| ColumnCount | 18 |
| IndexCount | 8，包含 PRIMARY 與 7 個非唯一索引 |
| ColumnCommentPresentCount | 18 |

## 7. 驗證結果

| 驗證項目 | 結果 |
|---|---|
| 測試總數 | 2 |
| 通過 | 2 |
| 失敗 | 0 |
| SchemaPrecheck | `True` |
| SchemaPrecheckMessage | `task_log_traces schema precheck passed.` |
| Write result | success |
| TraceRowCount | 2 |
| Sanitizer 驗證 | 通過，敏感資訊未直接保存為原文 |
| Cleanup requested | `True` |
| Cleanup result | `True` |
| Cleanup message | `deleted current manual task id only. affected=2` |

## 8. trace rows

| TraceId | Level | TaskId | NodeId | DeviceId | CommandName | ErrorCode | Sanitized |
|---|---|---|---|---|---|---|---|
| `manual-logwriter-poc-20260603104930-81c86aa4-err` | Error | `manual-logwriter-poc-20260603104930-81c86aa4` | `manual-log-node-2` | `manual-log-device-1` | `ManualFailedLogCommand` | `MANUAL_LOG_FAILED` | 通過 |
| `manual-logwriter-poc-20260603104930-81c86aa4-ok` | Info | `manual-logwriter-poc-20260603104930-81c86aa4` | `manual-log-node-1` | `manual-log-device-1` | `ManualLogCommand` | 空值 | 通過 |

## 9. 驗證結論

`task_log_traces` 真實 DB manual-only 寫入 / 查詢 / cleanup 驗證已完成。

本次驗證證明 manual-only gate、測試 DB 限定、schema precheck、`MySqlLogWriter.Write(LogEntry)` 寫入、依本次 task id 查詢、payload sanitizer 與 cleanup 都可以在真實 MySQL 5.6.2 測試 DB 中正常運作。

本次測試 DB DDL 只代表在使用者授權下完成測試 table 建立，不代表 Schema Apply / DDL Executor、ConsoleHost DB 初始化、WebApi、ServiceHost 或正式 DB apply 已完成。

## 10. 風險邊界

此節點完成後，仍需保留以下邊界：

- 欄位、索引與 comment 仍由 C# schema 維護。
- 測試 DB 不等於正式 DB。
- cleanup 不可刪除非本次測試資料。
- 不可自行套用其他 table。
- 不可自行執行 ALTER / DROP。
- 不可接觸正式 DB。
- 不可將密碼、Token 或未遮蔽連線資訊寫入文件。

## 11. 下一步建議

第二階段 B 收斂稽核已完成，DB LogWriter / TraceStore 第一版可列為第二階段可驗收能力。

建議下一步進入第三階段前置規劃，確認 `TaskTraceStore` public 查詢介面、`ManualApplyPreview` 程式實作與 Host DB 初始化的先後順序。