MySQL TaskStore node_executions manual-only 真實 DB 驗證設計
1. 文件目的
本文件設計 MySqlTaskStore 將 TaskExecutionRecord.NodeRecords 寫入真實 MySQL 5.6.2 測試資料庫的 manual-only 驗證方式。
本文件只整理驗證節點、前置資料、環境 gate、測試資料、通過條件與停止線，不直接連線資料庫、不執行 DDL、不寫入正式 DB。
2. 驗證節點名稱
MySQL TaskStore node_executions manual-only Save / Inspect
3. 驗證目的
確認 HS.DeviceControl.Infrastructure.MySql 目前的 node_executions 第一版實作，在使用者明確開啟 manual-only gate 後，可以：
- 對
task_executions寫入任務摘要。 - 對
node_executions先刪除同 task id 的舊節點紀錄，再依NodeRecords順序寫入新節點紀錄。 - 確認
node_executions的主鍵、欄位、索引與 comment 符合目前 C# schema class。 - 確認節點欄位可保留
NodeId、NodeName、DeviceId、CommandName、Status、RetryCount、TimeTakenMs、ErrorCode、NextNodeId與 summary 欄位。 - 驗證 cleanup 只清除本次測試 task id 的
task_executions與node_executions資料。 - 驗證輸出不暴露 password 或完整 connection string。
4. 本節點不做的事
| 項目 | 原因 |
|---|---|
| 建立 database | 目前只驗證 TaskStore，不做 DB provisioning。 |
自動建立 node_executions | Schema Apply / DDL Executor 尚未確認。 |
執行 CREATE TABLE / ALTER TABLE / DROP | 避免影響真實 DB 結構。 |
| 寫入正式 DB | 第一版只允許測試 DB。 |
修改 ITaskStore public contract | 驗證資料可用 internal / test helper 讀取，不把查詢節點明細升成正式契約。 |
讓 FindById / ListRecent 回填 NodeRecords | 這是後續正式查詢設計，不塞進 manual-only 驗證。 |
驗證 command_executions 或詳細 log table | 兩者資料來源與邊界尚未確認。 |
5. 驗證前需要使用者確認
| 欄位 | 建議值 | 是否可寫入 repo | 備註 |
|---|---|---|---|
| MySQL 版本 | 5.6.2 | 可寫入 | 已知目標版本。 |
| Host / IP | <masked> | 不寫完整值 | 不在文件保留完整 IP。 |
| Port | 3306 | 可寫入 | 非敏感資訊。 |
| Database name | hs_device_control_test | 可寫入 | 必須是測試 DB。 |
| User name | hs_device | 可寫入或遮蔽 | 建議只給測試 DB 權限。 |
| Password | 不提供範例 | 不可寫入 | 只能由本機環境變數提供。 |
| Required tables | task_executions, node_executions | 可寫入 | 兩張表都必須已存在。 |
| 是否驗證 index | true | 可寫入 | 使用 information_schema.STATISTICS 驗證。 |
| 是否驗證 comment | true | 可寫入 | 使用 table / column comment 驗證。 |
| 是否允許 INSERT / UPDATE / DELETE | true | 可寫入 | 必須由使用者明確確認。 |
6. 前置 schema 檢查
在執行寫入前，驗證流程必須先確認真實測試 DB 已具備必要 schema。
必要資料表：
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 |
| comment | table comment 與主要 column comment 需存在 |
若缺少 node_executions、欄位、主鍵、索引或 comment，驗證節點應停止並回報缺口，不得自動建立或修改資料表。
7. 建議環境變數
沿用既有 MySQL TaskStore manual-only gate：
HS_MYSQL_TASKSTORE_ENABLED
HS_MYSQL_TASKSTORE_ALLOW_WRITE
HS_MYSQL_TASKSTORE_HOST
HS_MYSQL_TASKSTORE_PORT
HS_MYSQL_TASKSTORE_DATABASE
HS_MYSQL_TASKSTORE_USER
HS_MYSQL_TASKSTORE_PASSWORD
HS_MYSQL_TASKSTORE_TABLE
HS_MYSQL_TASKSTORE_TIMEOUT_SECONDS
HS_MYSQL_TASKSTORE_SSL_MODE
HS_MYSQL_TASKSTORE_CLEANUP
補充規則：
HS_MYSQL_TASKSTORE_ENABLED=true才可連 DB。HS_MYSQL_TASKSTORE_ALLOW_WRITE=true才可寫入。HS_MYSQL_TASKSTORE_TABLE仍只代表task_executions。node_executions第一版固定使用同名資料表，不新增 table name 設定，避免測試與 schema class 脫節。HS_MYSQL_TASKSTORE_PASSWORD不得寫入 repo、文件或測試輸出。
若要同時跑 schema metadata 檢查，可搭配既有 Inspector 環境變數：
HS_MYSQL_INSPECT_ENABLED=true
HS_MYSQL_INSPECT_EXPECTED_TABLES=task_executions,node_executions
HS_MYSQL_INSPECT_INCLUDE_INDEXES=true
HS_MYSQL_INSPECT_INCLUDE_COMMENTS=true
8. 測試資料設計
測試 task id 必須使用固定前綴：
manual-taskstore-poc-{yyyyMMddHHmmss}-{短隨機碼}
建議建立一筆 TaskExecutionRecord，至少包含兩筆節點紀錄：
| sequence_no | node_id | status | 用途 |
|---|---|---|---|
| 1 | manual-node-1 | Success | 驗證成功節點、設備與命令欄位。 |
| 2 | manual-node-2 | Failed 或 Success | 驗證錯誤欄位或下一節點欄位。 |
建議欄位值：
| 欄位 | 建議值 |
|---|---|
workflow_id | manual-mysql-taskstore-poc |
device_id | manual-device-1 |
command_name | manual-command-1 |
data_summary | manual data summary |
metadata_summary | manual metadata summary |
transition_summary | manual transition summary |
9. 建議驗證流程
1. 使用者確認目標是測試 DB，且可接受寫入與 cleanup。
2. 設定 TaskStore manual-only 環境變數。
3. 先執行 schema inspect，確認 task_executions 與 node_executions 存在。
4. 若 schema inspect 缺表或缺欄位，停止並回報，不執行寫入。
5. 建立含兩筆以上 NodeRecords 的 TaskExecutionRecord。
6. 呼叫 MySqlTaskStore.Save(record)。
7. 使用 test-only / internal helper 查詢 node_executions，確認同一 task_id 的資料列數、順序與欄位值。
8. 呼叫 FindById / ListRecent 確認任務摘要仍可查。
9. 若 cleanup 開啟，先刪除 node_executions 同 task id 資料，再刪除 task_executions 同 task id 資料。
10. 輸出驗證摘要，後續回填人工驗證紀錄。
10. 建議 xUnit 範圍
後續若進入實作，建議新增或擴充 manual-only 測試：
tests/HS.DeviceControl.Infrastructure.MySql.Tests/Tasks/MySqlTaskStoreNodeExecutionsManualMySql56Tests.cs
建議測試：
| 測試 | 目的 |
|---|---|
SaveAndInspectNodes_ShouldPersistNodeExecutionsWhenManualGateIsEnabled | 寫入含節點紀錄的 task，並查詢 node_executions 驗證資料列。 |
ManualGate_ShouldSkipNodeExecutionWriteWhenDisabled | gate 未開時不連 DB、不寫入。 |
SchemaPrecheck_ShouldReportMissingNodeExecutionsWithoutWrite | 缺少 node_executions 時停止，不自動 DDL。 |
此測試仍歸類為 manual-only，不放入一般 CI 必跑路徑。
11. 通過條件
| 條件 | 判斷 |
|---|---|
| gate 正常 | 未開 ENABLED 或 ALLOW_WRITE 時不連 DB、不寫入。 |
| schema 前置檢查正常 | task_executions 與 node_executions 存在，必要欄位、索引與 comment 可讀。 |
| Save 成功 | MySqlTaskStore.Save 未回傳錯誤。 |
| 節點資料列正確 | node_executions 同 task id 的筆數等於 NodeRecords.Count。 |
| 順序正確 | sequence_no 從 1 開始並符合 NodeRecords 順序。 |
| 核心欄位正確 | node_id、status、retry_count、time_taken_ms、device_id、command_name 可對回。 |
| 任務摘要仍可查 | FindById 與 ListRecent 仍能查回 task summary。 |
| cleanup 安全 | 僅刪除本次 task_id 的 node_executions 與 task_executions。 |
| 無敏感資訊 | 輸出不包含 password 或完整 connection string。 |
12. 失敗時需記錄
失敗紀錄至少包含：
- 驗證時間。
- 程式 commit。
- MySQL 版本。
- 遮蔽後的 host / database / user。
- schema precheck 是否通過。
Save是否成功。node_executions查詢是否成功。- row count 與 expected count。
- cleanup 是否成功。
- error code。
- error message。
- exception type。
- 是否疑似缺表、缺欄位、權限不足或資料型別不符。
不得記錄：
- password。
- 完整 connection string。
- 非本次測試 task id 的資料內容。
- 正式 DB 資料列內容。
13. 停止線
遇到以下狀況必須停止並請使用者確認：
1. 需要建立或修改 node_executions table。
2. 需要調整欄位型別、索引或 comment。
3. 需要新增或變更 ITaskStore public method。
4. 需要讓 FindById / ListRecent 回填節點明細。
5. 需要連接正式 DB 或保存正式資料。
6. 需要調整 DB 帳號權限。
14. 目前結論
node_executions 第一版已完成 fake gateway 寫入實作與單元測試，但尚未對真實測試 DB 執行 manual-only 寫入 / 查詢驗證。
已完成 MySQL TaskStore node_executions manual-only xUnit 驗證入口實作紀錄。
建議下一步在使用者確認測試 DB 已具備 node_executions table、index、comment，且明確開啟 manual-only gate 後，執行真實 DB 寫入 / 查詢驗證並整理驗證紀錄。