# MySQL TaskStore node_executions 真實 DB 驗證紀錄

## 1. 驗證摘要

| 項目 | 內容 |
| --- | --- |
| 驗證節點 | MySQL TaskStore `node_executions` 真實 DB manual-only 寫入 / 查詢 / cleanup |
| 驗證日期 | 2026-06-02 |
| 程式 repo 分支 | `poc/nmodbus-tcp` |
| 驗證執行程式 commit | `0216296` |
| 驗證紀錄同步 commit | `ade8860` |
| 測試 DB | `hs_device_control_test` |
| DB host | 已遮蔽 |
| Port | `3306` |
| User | `hs_device` |
| Task table | `task_executions` |
| Node table | `node_executions` |
| Cleanup | 開啟，只刪除本次 `manual-taskstore-poc-` task id |

本紀錄只代表測試 DB manual-only 驗證通過，不代表正式 DB 初始化、Schema Apply / DDL Executor、WebApi、ServiceHost 或正式部署流程已完成。

## 2. 驗證目的

確認 `MySqlTaskStore.Save(record)` 在 manual-only gate 明確開啟後，可以：

1. 先通過 `task_executions` 與 `node_executions` schema precheck。
2. 寫入一筆任務摘要到 `task_executions`。
3. 依 `TaskExecutionRecord.NodeRecords` 寫入兩筆節點明細到 `node_executions`。
4. 可查回同一個 `task_id` 的 node rows。
5. `FindById` 與 `ListRecent` 可查到本次任務。
6. cleanup 可刪除本次測試 task id 的 `node_executions` 與 `task_executions` 資料。

## 3. 執行前狀態

第一次執行 manual-only 驗證時，測試 DB 可連線，但 `node_executions` 尚不存在。

```text
SchemaPrecheck: False
SchemaPrecheckMessage: required table is missing: node_executions
```

該次驗證停在 schema precheck，未進入 Save 寫入流程，因此沒有產生需要 cleanup 的資料。

## 4. 測試 DB 建表

使用者明確同意後，Codex 只在測試 DB `hs_device_control_test` 執行：

```sql
CREATE TABLE IF NOT EXISTS `node_executions`
```

建表 SQL 由 `MySqlTaskNodeExecutionSchema` 透過 `SchemaDefinitionParser` 與 `MySqlSchemaSqlGenerator` 產生，包含：

| 項目 | 結果 |
| --- | --- |
| 欄位數 | 18 |
| 主鍵 | `task_id`, `sequence_no` |
| 索引 | `idx_node_executions_task_id`, `idx_node_executions_status`, `idx_node_executions_device`, `idx_node_executions_node_id` |
| Table comment | `任務節點執行紀錄` |
| Charset | `utf8` |
| Engine | `InnoDB` |

本次建表屬於使用者明確授權的測試 DB DDL，不代表 Schema Apply / DDL Executor 功能已完成。

## 5. 執行指令

```powershell
$env:HS_MYSQL_TASKSTORE_ENABLED="true"
$env:HS_MYSQL_TASKSTORE_ALLOW_WRITE="true"
$env:HS_MYSQL_TASKSTORE_CLEANUP="true"
dotnet test tests\HS.DeviceControl.Infrastructure.MySql.Tests\HS.DeviceControl.Infrastructure.MySql.Tests.csproj --filter FullyQualifiedName~MySqlTaskStoreNodeExecutionsManualMySql56Tests --logger "console;verbosity=detailed"
```

密碼只使用本機環境變數，未寫入文件、commit message 或測試輸出。

## 6. 驗證結果

| 驗證項目 | 結果 |
| --- | --- |
| 測試總數 | 2 |
| 通過 | 2 |
| 失敗 | 0 |
| SchemaPrecheck | 通過 |
| Save | 成功 |
| NodeExecutionRowCount | 2 |
| FindById | `True` |
| ListRecent | 包含本次 `TaskId` |
| Cleanup | 成功 |

主要輸出：

```text
SchemaPrecheck: True
SchemaPrecheckMessage: schema ok: tables include task_executions and node_executions, nodeColumns=18, nodeIndexes=4
Save result: success
NodeExecutionRowCount: 2
FindById result: True
ListRecent contains TaskId: True
Cleanup result: True
Cleanup message: deleted current manual task id from node_executions and task_executions.
```

## 7. Node rows 驗證

| SequenceNo | NodeId | Status | DeviceId | CommandName | RetryCount | TimeTakenMs | ErrorCode | NextNodeId |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | `manual-node-1` | `Completed` | `manual-device-1` | `manual-command-1` | 0 | 25 |  | `manual-node-2` |
| 2 | `manual-node-2` | `Failed` | `manual-device-2` | `manual-command-2` | 1 | 25 | `MANUAL_NODE_FAILED` |  |

## 8. 驗證結論

`node_executions` 第一版已完成真實測試 DB manual-only 寫入 / 查詢 / cleanup 驗證。

目前可確認：

- C# schema class 可產生可用的 MySQL 5.6.2 建表 SQL。
- `MySqlTaskStore.Save(record)` 可同時寫入 task summary 與 node execution rows。
- schema precheck 可確認 table、必要欄位、主鍵、索引與 comment。
- cleanup 只針對本次 manual task id，未清除其他資料。

## 9. 仍延後的邊界

| 項目 | 狀態 | 原因 |
| --- | --- | --- |
| `command_executions` | 延後 | RawRequest / RawResponse 來源尚未固定，不宜直接擴充 public model。 |
| 詳細 log table | 延後 | 建議獨立走 DB LogWriter / TraceStore，不應塞入 `MySqlTaskStore.Save`。 |
| Schema Apply / DDL Executor | 延後 | 正式 CREATE / ALTER / DROP 流程仍需另行設計與確認。 |
| `FindById` / `ListRecent` 回填 `NodeRecords` | 延後 | 會改變查詢語意與 contract，需要另行設計。 |

## 10. 建議下一步

建議下一步將第二階段 TaskStore 多表節點標記為完成，並同步文件網站進度；後續再進入 `command_executions` 或 DB LogWriter / TraceStore 的設計，而不是把所有明細直接塞進 TaskStore。