MySQL TaskStore PoC 實作前確認清單
本文件用於進入第二階段「MySQL 任務持久化 PoC」前，先確認實作範圍、資料保存邊界、驗收方式與風險控制。
此清單不是程式實作文件，也不代表已同意修改既有架構、資料模型、public method 簽章或專案啟動方式。若後續需要調整程式結構，必須再經使用者確認。
PoC 目標
- 任務執行完成後，Task / Node / Command / ErrorInfo 可保存到 MySQL。
- 程式重啟後，仍可查詢已完成任務的歷程資料。
- 錯誤、重試、逾時與 Adapter 回傳資訊可被追蹤。
- 第一版只驗證任務持久化能力，不建立完整報表、權限或多案場管理。
第一版建議範圍
| 項目 | 建議 |
|---|---|
| 儲存對象 | Task、Node、Command、ErrorInfo |
| 儲存時機 | 任務開始、節點開始、節點完成、設備命令完成、任務完成 |
| 查詢能力 | 依 TaskId 查詢任務與節點歷程 |
| Host | 先維持 ConsoleHost 作為驗證入口 |
| DB | MySQL 5.6.2 |
| ORM | 先分析後決定，不在未確認前導入 |
| Migration | 先以 schema 文件與手動 SQL 初稿為主 |
MySQL 版本限制
目前使用者提供的資料庫版本為：
MySQL 5.6.2
此版本需視為第二階段 MySQL PoC 的既定環境限制。後續套件選型、SQL 語法、欄位型態與測試環境都必須以 MySQL 5.6.2 相容性為前提。
- 避免使用 MySQL 5.7 / 8.0 才支援的語法或功能。
- 第一版 schema 不使用
JSON欄位型態，RawRequest、RawResponse、AdapterData建議先使用TEXT或LONGTEXT。 - 日期時間欄位需確認
DATETIME/TIMESTAMP在 MySQL 5.6.2 的行為。 - 套件選型需確認同時支援
.NET 5.0與 MySQL 5.6.2。 - MySQL 5.6 系列已屬舊版支援風險版本，正式化前建議另做升級或版本風險評估。
第一版不做事項
| 不做項目 | 原因 |
|---|---|
| Web UI | 會擴大前端與使用流程範圍 |
| WebApi | 需等資料邊界穩定後再設計 API contract |
| ServiceHost | 會牽動啟動方式，先不作為本 PoC 必要項 |
| 多案場管理 | 需要租戶、案場、權限與資料隔離設計 |
| 報表統計 | 需等任務歷程資料穩定後再設計 |
| 設備即時狀態保存 | 與任務歷程不同，建議另開主題 |
| 自動 migration | 會牽涉套件與部署策略，先不納入第一版 |
資料保存邊界
Task
建議保存 TaskId、WorkflowId、WorkflowName、Status、StartTime、EndTime、TimeTakenMs、CurrentNodeId、FinalCode、FinalMessage。
Node
建議保存 TaskId、NodeId、NodeName、Status、StartTime、EndTime、TimeTakenMs、RetryCount、DeviceId、CommandName、SuccessNextNodeId、FailNextNodeId。
Command
建議保存 TaskId、NodeId、DeviceId、DeviceName、CommandName、Success、Code、Message、TimeTakenMs、RawRequest、RawResponse、AdapterData。
ErrorInfo
建議保存 TaskId、NodeId、DeviceId、CommandName、ErrorCode、ErrorMessage、ExceptionType、StackTrace、Source、CreatedAt。
Schema 初稿方向
| 表名 | 責任 |
|---|---|
| task_executions | 保存任務層級狀態與最終結果 |
| node_executions | 保存節點執行歷程 |
| command_executions | 保存設備命令結果與 Adapter 回傳資料 |
| task_errors | 保存錯誤快照 |
欄位命名建議使用 snake_case，程式 model 可維持 C# PascalCase，避免資料庫命名與 C# 命名互相牽制。
程式設計需先確認
| 確認項 | 建議 |
|---|---|
| 是否新增 Infrastructure 專案 | 建議先分析現有結構後再決定 |
| 是否新增 ITaskStore 實作 | 建議沿用現有 TaskStore 概念，不直接改 Core 行為 |
| 是否修改 public method | 第一版應避免，若必要需先確認 |
| 是否引入 MySQL 套件 | 需先做套件選型與確認 |
| 是否引入 ORM | 建議先比較 Dapper、EF Core、原生 MySqlConnector |
| 是否改 ConsoleHost 啟動方式 | 不建議，第一版應維持既有啟動方式 |
| 是否支援 MySQL 5.6.2 | 必須列為套件選型與 SQL 設計的必要條件 |
PoC 驗收標準
| 驗收項 | 預期結果 |
|---|---|
| 成功流程寫入 | 三節點成功流程完成後，DB 可查到 Task / Node / Command |
| 失敗流程寫入 | 設備離線或節點失敗時，DB 可查到 ErrorInfo |
| 重試紀錄 | 重試後成功或失敗時，RetryCount 與節點結果可查 |
| 重啟查詢 | ConsoleHost 重啟後，仍可查詢前一次任務紀錄 |
| Log 對照 | FileLog / ConsoleLog 與 DB 紀錄的 TaskId 可對應 |
| 不影響既有測試 | Core / Adapter / WorkflowSimulation 測試仍通過 |
| MySQL 5.6.2 相容性 | PoC SQL 與套件可在 MySQL 5.6.2 環境執行 |
人工驗證節點建議
P2-01 MySQL TaskStore PoC 人工驗證
驗證回報需包含驗證環境、MySQL 連線設定來源、MySQL 版本確認結果、sample workflow、執行指令、DB 查詢結果摘要、Log 與 DB TaskId 是否一致、發現問題或限制與下一步建議。
風險與控制方式
| 風險 | 控制方式 |
|---|---|
| 過早設計完整正式資料庫 | 第一版只做 PoC schema，不承諾正式 schema |
| 案場邏輯進入資料表 | 只保存共用任務與設備命令欄位 |
| 改動 Core public API | 優先用介面或 Infrastructure 實作承接，必要時先討論 |
| DB 連線失敗影響流程 | 需定義 DB 寫入失敗時是否讓任務失敗 |
| RawRequest / RawResponse 過大 | 第一版需限制欄位型態與保存策略 |
| MySQL 5.6.2 已屬舊版環境 | PoC 先求相容；正式化前另做升級或版本風險評估 |
| 新版 SQL 功能不可用 | SQL 語法與欄位型態需採保守設計 |
需要使用者確認
- 是否同意第二階段第一個 PoC 以 MySQL TaskStore 為主。
- 第一版是否只保存任務歷程，不保存設備即時狀態。
- 是否保存 RawRequest / RawResponse。
- 是否保存 AdapterData。
- DB 寫入失敗時，任務是否應失敗，還是只記錄警告。
- 是否確認 PoC 目標資料庫版本固定為 MySQL 5.6.2。
- 是否先做「MySQL 套件選型分析」，再進入程式實作。
建議下一步
MySQL 套件選型分析請參考：MySQL 套件選型分析。
目前建議第一版 PoC 採用 MySqlConnector，暫不導入 Dapper、EF Core、Pomelo 或 migration。
MySQL Schema 自動建表設計請參考：MySQL Schema 自動建表設計。
MySQL schema Class 初稿請參考：MySQL schema Class 初稿。
完成套件選型、自動建表設計與 Class 初稿後，再進入：
- Schema Attribute 實作前確認。
- TaskStore 介面承接設計。
- MySQL TaskStore PoC 實作前確認。