# 第二階段規劃總覽

## 1. 文件目的

本文件用於第一階段驗收完成後，整理第二階段的規劃架構、優先順序、待確認決策與驗收節點。

第二階段不應一次把所有長期平台功能全部導入，而是把第一階段已完成的控制骨架，逐步推進到可保存、可查詢、可服務化、可接真實設備、可被現場人員驗證的狀態。

## 2. 第二階段定位

第一階段已完成「可驗收的共用控制骨架」。

第二階段建議定位為：

> 讓控制骨架具備正式化前的持久化、服務入口、真實設備驗證與維運可觀測能力。

第二階段仍不建議直接擴張成完整中央平台；多案場管理、報表、權限系統、完整 Web UI 可列為第三階段或長期平台。

## 3. 建議優先順序

| 優先序 | 主題 | 建議原因 | 是否需先討論 |
|---:|---|---|---|
| 1 | MySQL 任務持久化 | 第一階段目前使用 InMemoryTaskStore，重啟後資料消失；若要進入正式化，需要保存任務與節點歷程 | 是 |
| 2 | ServiceHost / WebApi 邊界 | 需要決定正式背景執行入口，以及是否提供遠端啟動、查詢、取消 API | 是 |
| 3 | 真實設備 Adapter 驗證 | Modbus TCP 第一版已完成模擬器驗證，下一步需接近現場通訊條件 | 是 |
| 4 | .NET 升級評估 | `.NET 5.0` 已 EOL，正式化前應評估升級到受支援版本 | 是 |
| 5 | 維運與 Log 查詢 | 第一階段 Log 可追蹤，但第二階段需要更容易查詢任務歷程、錯誤原因與設備狀態 | 是 |

## 4. 建議分成五條工作線

### 4.1 資料持久化線

目標：讓任務、節點歷程、設備命令結果與錯誤資訊可保存、可查詢。

目前資料庫版本限制：MySQL 5.6.2。第二階段若優先做 MySQL 任務持久化，SQL 語法、欄位型態、套件選型與測試環境都需以 MySQL 5.6.2 相容性為前提。

建議先討論：

- MySQL schema 是否只保存 Task / Node / Command / Error。
- MySQL 5.6.2 是否為 PoC 與正式環境共同版本。
- 是否保留 RawRequest / RawResponse。
- 是否需要保存 Adapter metadata。
- 是否需要 migration 工具。
- 是否先做 Repository 介面，再做 MySQL 實作。

第一版建議只做：

- Task execution record
- Node execution record
- Command execution record
- ErrorInfo snapshot

暫不做：

- 報表
- 多案場查詢
- 權限
- 長期資料歸檔

### 4.2 服務入口線

目標：從 ConsoleHost 驗證入口，逐步過渡到正式背景執行入口。

建議拆分：

| 模組 | 第二階段定位 |
|---|---|
| ConsoleHost | 保留為 Debug / 人工驗證入口 |
| ServiceHost | 正式背景執行入口候選 |
| WebApi | 遠端啟動、查詢、取消任務入口候選 |

需先確認：

- 第二階段是否先做 ServiceHost，還是先做 WebApi。
- WebApi 是否只提供內部使用，不對外公開。
- 任務取消、暫停、恢復是否列入第二階段。
- API 回傳格式是否沿用 Result / ErrorInfo。

### 4.3 真實設備 Adapter 線

目標：把第一階段已完成的 Adapter 抽象與 Modbus TCP 第一版，推進到可接近現場驗證。

建議優先處理：

- 第一個真實設備 Adapter 驗證對象。
- TCP / UDP / Serial / Modbus TCP 的設定格式是否共用。
- 連線失敗、逾時、斷線復原策略是否需要標準化。
- 現場測試時如何保護設備，避免誤動作。

第二階段第一個驗證節點可設定為：

> 使用可控的測試設備或模擬器環境，驗證 Modbus TCP Read / Write、連線失敗、逾時、錯誤碼、Log 與任務結果。

### 4.4 技術升級線

目標：評估 `.NET 5.0` 升級路線，降低正式化風險。

需分析：

- 是否升級到 `.NET 8 LTS`。
- NModbus 與測試專案相容性。
- ConsoleHost、Adapters、Core 是否需要調整。
- 是否先建立升級分支做驗證。

建議不要與 MySQL / WebApi 同時大改，避免問題來源混在一起。

### 4.5 維運與觀測線

目標：讓現場或工程人員能快速知道任務為什麼成功、失敗或卡住。

建議補強：

- 錯誤碼分級。
- 任務查詢格式。
- Recent tasks 顯示規格。
- Log 查詢欄位。
- 驗證節點回報格式。

## 5. 第二階段不建議一次做的項目

| 項目 | 不建議原因 |
|---|---|
| 完整 Web UI | 會拉大前端、權限、部署與使用者流程範圍 |
| 多案場管理 | 需定義租戶、案場、設備群組與權限，超出第二階段核心 |
| 報表統計 | 需先有穩定資料模型與持久化資料 |
| 完整權限系統 | 需先確認 WebApi / ServiceHost 是否正式導入 |
| 自動更新與安裝包 | 需等執行模式與部署方式確定 |

## 6. 建議驗收節點

| 驗收節點 | 驗收目的 | 預期成果 |
|---|---|---|
| P2-01 MySQL TaskStore PoC | 確認任務與節點歷程可保存 | 重啟後仍能查詢任務紀錄 |
| P2-02 MySQL schema review | 確認資料表不過度耦合案場邏輯 | schema 文件與測試資料 |
| P2-03 MySQL 行前連線資訊確認 | 確認測試 database、Host、Port、User、Password 提供方式與權限 | 可進行最小連線測試與 Dry Run 建表測試 |
| P2-04 ServiceHost 啟動 PoC | 確認背景入口可載入設定並啟動流程 | 可啟動、停止、記錄錯誤 |
| P2-05 WebApi 邊界設計 | 確認 API 不把核心流程邏輯寫入 Controller | API contract 文件 |
| P2-06 真實設備 Adapter 驗證 | 確認 Adapter 行為接近現場需求 | 實際讀寫、錯誤碼、Log 紀錄 |
| P2-07 .NET 升級 PoC | 確認升級後測試仍通過 | 升級評估報告 |

## 7. 需要使用者先確認的決策

1. 第二階段是否優先做 MySQL 持久化。
2. MySQL 5.6.2 是否為 PoC 與正式環境共同版本。
3. MySQL 是否只保存任務歷程，還是也保存設備狀態與原始通訊資料。
4. MySQL 測試 database 是否已建立，並由使用者提供 Host / Port / Database / User / Password。
5. MySQL PoC 帳號是否具備 `SELECT / INSERT / UPDATE / CREATE / ALTER / INDEX` 權限。
6. ServiceHost 與 WebApi 哪一個先做。
7. 第一個真實設備驗證對象是 Modbus TCP、UDP，還是其他設備。
8. `.NET 5.0` 是否在第二階段先升級。
9. 第二階段是否仍維持 ConsoleHost 作為主要人工驗證入口。

## 8. 建議下一步

建議先做「第二階段工作拆解與優先順序確認」，不要立即開資料庫或 WebApi 實作。

第二階段第一個主軸選型比較請參考：[第二階段第一個主軸選型比較](./phase-two-first-track-selection.md)。

若同意第一主軸先走 MySQL，實作前確認請參考：[MySQL TaskStore PoC 實作前確認清單](./mysql-taskstore-poc-checklist.md)。

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

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

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

MySQL 行前連線資訊確認請參考：[MySQL 行前連線資訊確認](./mysql-preflight-connection-checklist.md)。

建議討論順序：

1. 先確認第二階段第一個主軸：MySQL、ServiceHost / WebApi、真實設備 Adapter、或 .NET 升級。
2. 針對選定主軸建立實作前確認清單。
3. 確認不改動第一階段既有 public method、設定格式與啟動方式，除非使用者明確同意。
4. 建立第二階段進度儀表欄位與驗收節點。

## 9. 第二階段進度條規則

文件首頁需顯示第二階段獨立進度條，避免只看到第一階段 100% 或長期總進度。

第二階段進度由 `progress.json` 人工維護，只有完成可驗收節點、文件決策正式確認或程式功能完成並通過測試後才更新。

目前第二階段進度為 22%，代表已完成第二階段規劃總覽、第一主軸選型、MySQL TaskStore PoC 實作前確認清單、MySQL 5.6.2 相容性限制整理、MySQL 套件選型分析、MySQL Schema 自動建表設計、MySQL schema Class 初稿與 MySQL 行前連線資訊確認文件；尚未取得實際連線資訊，也尚未進入 Schema Attribute 程式實作。