# MySQL TaskStore node_executions 真實 DB 驗證前確認清單

## 1. 文件目的

本文件用於執行 `node_executions` 真實 MySQL 5.6.2 manual-only 寫入 / 查詢驗證前，先確認測試 DB、schema、gate、cleanup 與停止線是否已準備完成。

本文件不保存密碼、不連線資料庫、不執行 DDL、不寫入資料，只作為執行前確認清單。若任一必要條件未確認，Codex 不得自行執行真實 DB 寫入測試。

後續已於 2026-06-02 在使用者明確同意下完成測試 DB 建表與 `node_executions` 真實 DB manual-only 寫入 / 查詢 / cleanup 驗證，結果見 [MySQL TaskStore node_executions 真實 DB 驗證紀錄](mysql-taskstore-node-executions-real-db-verification-record.md)。

## 2. 驗證目標

| 項目 | 內容 |
| --- | --- |
| 驗證節點 | MySQL TaskStore `node_executions` 真實 DB manual-only 驗證 |
| 主要目的 | 確認 `MySqlTaskStore.Save(record)` 可同時寫入 `task_executions` 與 `node_executions` |
| 查詢確認 | 透過測試內部 helper 查回同一個 `task_id` 的 node rows |
| cleanup | 只清除本次 `manual-taskstore-poc-` 前綴的測試資料 |
| 不驗證項目 | `command_executions`、詳細 log table、Schema Apply / DDL Executor |

## 3. 執行前必須確認

| 確認項目 | 必要狀態 | 備註 |
| --- | --- | --- |
| 是否為測試 DB | 必須是 | 不得使用正式 DB。 |
| MySQL 版本 | `5.6.2` | 目前第二階段目標版本。 |
| Database | `hs_device_control_test` 或使用者明確指定的測試 DB | DB 名稱可寫入文件；密碼不可寫入。 |
| User | 僅限測試 DB 權限 | 建議具備 `SELECT`、`INSERT`、`UPDATE`、`DELETE`。 |
| Password | 僅能透過本機環境變數提供 | 不得 commit 到 repo。 |
| `task_executions` | 已存在 | 需具備既有 TaskStore PoC schema。 |
| `node_executions` | 已存在 | 本驗證不自動建表。 |
| table comment | 已存在 | `node_executions` 需有 table comment。 |
| column comment | 已存在 | 必要欄位需有 comment。 |
| index | 已存在 | 必要 index 需可由 `information_schema` 讀取。 |
| cleanup | 預設開啟 | 只刪除本次測試 task id。 |

## 4. 必要 schema 停止線

執行寫入前，manual-only 測試會先用 `MySqlSchemaInspector` 與 `MySqlTaskStoreNodeExecutionSchemaPrecheck` 檢查：

| 類別 | 必要內容 |
| --- | --- |
| 必要資料表 | `task_executions`、`node_executions` |
| `node_executions` 主鍵 | `task_id`、`sequence_no` |
| 必要欄位 | `task_id`、`sequence_no`、`node_id`、`status`、`retry_count`、`started_at`、`time_taken_ms`、`created_at` |
| 必要索引 | `idx_node_executions_task_id`、`idx_node_executions_status`、`idx_node_executions_device`、`idx_node_executions_node_id` |
| 必要描述 | `node_executions` table comment 與必要 column comment |

若缺少 table、欄位、主鍵、index 或 comment，測試必須停止並回報，不得自動建立或修改資料表。

## 5. 必要環境變數

```powershell
$env:HS_MYSQL_TASKSTORE_ENABLED="true"
$env:HS_MYSQL_TASKSTORE_ALLOW_WRITE="true"
$env:HS_MYSQL_TASKSTORE_HOST="<test-db-host>"
$env:HS_MYSQL_TASKSTORE_PORT="3306"
$env:HS_MYSQL_TASKSTORE_DATABASE="hs_device_control_test"
$env:HS_MYSQL_TASKSTORE_USER="hs_device"
$env:HS_MYSQL_TASKSTORE_PASSWORD="<password>"
$env:HS_MYSQL_TASKSTORE_TABLE="task_executions"
$env:HS_MYSQL_TASKSTORE_TIMEOUT_SECONDS="15"
$env:HS_MYSQL_TASKSTORE_SSL_MODE="None"
$env:HS_MYSQL_TASKSTORE_CLEANUP="true"
```

安全規則：

- `HS_MYSQL_TASKSTORE_ENABLED=true` 只表示允許連線測試 DB。
- `HS_MYSQL_TASKSTORE_ALLOW_WRITE=true` 只表示允許 manual-only 測試寫入測試資料。
- 密碼不得寫入文件、README、commit message、issue、log 或截圖。
- 若 `HS_MYSQL_TASKSTORE_CLEANUP=false`，必須先確認測試資料可以暫留。

## 6. 執行指令

確認完成後，才可在程式 repo 根目錄執行：

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

## 7. 通過條件

| 項目 | 預期結果 |
| --- | --- |
| Gate | `Enabled: true`、`AllowWrite: true` |
| SchemaPrecheck | `True` |
| Save | `Save result: success` |
| Node rows | `NodeExecutionRowCount: 2` |
| 第一筆 node | `manual-node-1`、`Completed`、`manual-device-1`、`manual-command-1` |
| 第二筆 node | `manual-node-2`、`Failed`、`MANUAL_NODE_FAILED` |
| FindById | `True` |
| ListRecent | 包含本次 `TaskId` |
| Cleanup | 成功刪除本次 task id 的 `node_executions` 與 `task_executions` |

## 8. 必須停止並回報的情境

| 情境 | 處理方式 |
| --- | --- |
| 使用者未明確確認為測試 DB | 停止，不執行。 |
| 密碼或連線資訊缺少 | 停止，請使用者在本機設定環境變數。 |
| `node_executions` 不存在 | 停止，不自動建表。 |
| 缺少欄位、主鍵、index 或 comment | 停止，不執行寫入。 |
| 測試 DB 連線失敗 | 停止，回報錯誤類型與已遮蔽訊息。 |
| Save 失敗 | 停止，回報錯誤碼、例外型別與是否 cleanup。 |
| Cleanup 失敗 | 停止，回報殘留 task id，由使用者決定是否手動清除。 |

## 9. 延後邊界

| 項目 | 狀態 | 原因 |
| --- | --- | --- |
| `command_executions` | 延後 | RawRequest / RawResponse 來源尚未固定。 |
| 詳細 log table | 延後 | 建議獨立走 DB LogWriter / TraceStore，不塞入 TaskStore PoC。 |
| Schema Apply / DDL Executor | 延後 | 任何 `CREATE TABLE`、`ALTER TABLE`、`DROP` 都需要另行確認。 |
| `FindById` / `ListRecent` 回填 NodeRecords | 延後 | 會改變查詢語意與 contract，需要另行設計。 |

## 10. 執行後需回填的紀錄

若真實 DB manual-only 驗證完成，需新增或更新驗證紀錄，至少包含：

- 驗證日期與程式 commit。
- 是否為測試 DB。
- schema precheck 結果。
- `NodeExecutionRowCount`。
- 兩筆 node row 摘要。
- `FindById` / `ListRecent` 結果。
- cleanup 結果。
- 失敗時的錯誤類型、錯誤訊息與是否有殘留資料。

## 11. 下一步建議

確認本清單所有必要項目後，再由使用者明確授權執行 `node_executions` 真實 DB manual-only 驗證。若任何 schema 條件不符合，先停下討論是手動建表、修正測試 DB，或延後到 Schema Apply / DDL Executor 階段。