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 驗證紀錄。

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. 必要環境變數


$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 根目錄執行：


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 階段。