# MySQL TaskStore PoC 實作前確認清單

## 1. 文件目的

本文件用於進入第二階段「MySQL 任務持久化 PoC」前，先確認實作範圍、資料保存邊界、驗收方式與風險控制。

此清單不是程式實作文件，也不代表已同意修改既有架構、資料模型、public method 簽章或專案啟動方式。若後續需要調整程式結構，必須再經使用者確認。

## 2. PoC 目標

MySQL TaskStore PoC 的目標是驗證：

- 任務執行完成後，Task / Node / Command / ErrorInfo 可保存到 MySQL。
- 程式重啟後，仍可查詢已完成任務的歷程資料。
- 錯誤、重試、逾時與 Adapter 回傳資訊可被追蹤。
- 第一版只驗證任務持久化能力，不建立完整報表、權限或多案場管理。

## 3. 第一版建議範圍

| 項目 | 建議 |
|---|---|
| 儲存對象 | Task、Node、Command、ErrorInfo |
| 儲存時機 | 任務開始、節點開始、節點完成、設備命令完成、任務完成 |
| 查詢能力 | 依 TaskId 查詢任務與節點歷程 |
| Host | 先維持 ConsoleHost 作為驗證入口 |
| DB | MySQL 5.6.2 |
| ORM | 先分析後決定，不在未確認前導入 |
| Migration | 先以 schema 文件與手動 SQL 初稿為主 |

## 4. 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 系列已屬舊版支援風險版本，正式化前建議另做升級或版本風險評估。

## 5. 第一版不做事項

| 不做項目 | 原因 |
|---|---|
| Web UI | 會擴大前端與使用流程範圍 |
| WebApi | 需等資料邊界穩定後再設計 API contract |
| ServiceHost | 會牽動啟動方式，先不作為本 PoC 必要項 |
| 多案場管理 | 需要租戶、案場、權限與資料隔離設計 |
| 報表統計 | 需等任務歷程資料穩定後再設計 |
| 設備即時狀態保存 | 與任務歷程不同，建議另開主題 |
| 自動 migration | 會牽涉套件與部署策略，先不納入第一版 |

## 6. 資料保存邊界

### 5.1 Task

建議保存：

- TaskId
- WorkflowId
- WorkflowName
- Status
- StartTime
- EndTime
- TimeTakenMs
- CurrentNodeId
- FinalCode
- FinalMessage

### 5.2 Node

建議保存：

- TaskId
- NodeId
- NodeName
- Status
- StartTime
- EndTime
- TimeTakenMs
- RetryCount
- DeviceId
- CommandName
- SuccessNextNodeId
- FailNextNodeId

### 5.3 Command

建議保存：

- TaskId
- NodeId
- DeviceId
- DeviceName
- CommandName
- Success
- Code
- Message
- TimeTakenMs
- RawRequest
- RawResponse
- AdapterData

### 5.4 ErrorInfo

建議保存：

- TaskId
- NodeId
- DeviceId
- CommandName
- ErrorCode
- ErrorMessage
- ExceptionType
- StackTrace
- Source
- CreatedAt

## 7. Schema 初稿方向

建議先用四張表驗證，不急著正規化到完整正式模型：

| 表名 | 責任 |
|---|---|
| task_executions | 保存任務層級狀態與最終結果 |
| node_executions | 保存節點執行歷程 |
| command_executions | 保存設備命令結果與 Adapter 回傳資料 |
| task_errors | 保存錯誤快照 |

欄位命名建議使用 snake_case，程式 model 可維持 C# PascalCase，避免資料庫命名與 C# 命名互相牽制。

## 8. 程式設計需先確認

| 確認項 | 建議 |
|---|---|
| 是否新增 Infrastructure 專案 | 建議先分析現有結構後再決定 |
| 是否新增 ITaskStore 實作 | 建議沿用現有 TaskStore 概念，不直接改 Core 行為 |
| 是否修改 public method | 第一版應避免，若必要需先確認 |
| 是否引入 MySQL 套件 | 需先做套件選型與確認 |
| 是否引入 ORM | 建議先比較 Dapper、EF Core、原生 MySqlConnector |
| 是否改 ConsoleHost 啟動方式 | 不建議，第一版應維持既有啟動方式 |
| 是否支援 MySQL 5.6.2 | 必須列為套件選型與 SQL 設計的必要條件 |

## 9. 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 環境執行 |

## 10. 人工驗證節點建議

建議建立驗證節點：

> P2-01 MySQL TaskStore PoC 人工驗證

驗證回報需包含：

- 驗證環境
- MySQL 連線設定來源
- MySQL 版本確認結果
- 使用的 sample workflow
- 執行指令
- DB 查詢結果摘要
- Log 與 DB TaskId 是否一致
- 發現問題或限制
- 下一步建議

## 11. 風險與控制方式

| 風險 | 控制方式 |
|---|---|
| 過早設計完整正式資料庫 | 第一版只做 PoC schema，不承諾正式 schema |
| 案場邏輯進入資料表 | 只保存共用任務與設備命令欄位 |
| 改動 Core public API | 優先用介面或 Infrastructure 實作承接，必要時先討論 |
| DB 連線失敗影響流程 | 需定義 DB 寫入失敗時是否讓任務失敗 |
| RawRequest / RawResponse 過大 | 第一版需限制欄位型態與保存策略 |
| MySQL 5.6.2 已屬舊版環境 | PoC 先求相容；正式化前另做升級或版本風險評估 |
| 新版 SQL 功能不可用 | SQL 語法與欄位型態需採保守設計 |

## 12. 需要使用者確認

1. 是否同意第二階段第一個 PoC 以 MySQL TaskStore 為主。
2. 第一版是否只保存任務歷程，不保存設備即時狀態。
3. 是否保存 RawRequest / RawResponse。
4. 是否保存 AdapterData。
5. DB 寫入失敗時，任務是否應失敗，還是只記錄警告。
6. 是否確認 PoC 目標資料庫版本固定為 MySQL 5.6.2。
7. 是否先做「MySQL 套件選型分析」，再進入程式實作。

## 13. 建議下一步

MySQL 套件選型分析請參考：[MySQL 套件選型分析](./mysql-package-selection-analysis.md)。

目前建議第一版 PoC 採用 `MySqlConnector`，暫不導入 Dapper、EF Core、Pomelo 或 migration。

MySQL Schema 自動建表設計請參考：[MySQL Schema 自動建表設計](./mysql-schema-auto-create-design.md)。

MySQL schema Class 初稿請參考：[MySQL schema Class 初稿](./mysql-schema-class-draft.md)。

完成套件選型、自動建表設計與 Class 初稿後，再進入：

1. Schema Attribute 實作前確認。
2. TaskStore 介面承接設計。
3. MySQL TaskStore PoC 實作前確認。