Schema Initializer DryRun 第一版實作紀錄
1. 完成目的
本紀錄整理 Schema Initializer DryRun 第一版程式實作結果。
前一份實作前確認已決定第一版只建立 initializer 協調層，不導入真實 MySQL、不執行 DDL、不修改 ConsoleHost 啟動方式。本次程式實作依照該範圍完成。
2. 程式 repo 資訊
| 項目 | 內容 |
|---|---|
| repo | hs-device-control-template |
| branch | poc/nmodbus-tcp |
| commit | 52adfab |
| commit 訊息 | 實作 Schema Initializer DryRun 第一版 |
| 完成時間 | 2026-05-30 |
3. 新增內容
| 檔案 | 說明 |
|---|---|
src/HS.DeviceControl.Core/Schema/SchemaInitializer.cs | 新增 RunDryRun() 協調層 |
src/HS.DeviceControl.Core/Schema/SchemaInitializerDryRunRequest.cs | 定義 initializer dry run 輸入資料 |
src/HS.DeviceControl.Core/Schema/SchemaInitializerResult.cs | 定義 initializer dry run 輸出結果 |
tests/HS.DeviceControl.Core.Tests/SchemaInitializerTests.cs | 新增 10 個 Core 測試 |
4. 實作範圍
第一版已完成：
SchemaInitializer.RunDryRun()。- request 驗證。
- 目標 schema 驗證。
- inspect request 驗證。
- planner 缺失防呆。
- 呼叫既有
SchemaDryRunPlanner.GenerateDryRunPlan()。 - 保留
Warnings。 - 保留
ManualReviewItems。 - 保留
CorrelationId。 - 保留
Source。 - 保留
Mode = DryRun。 - inspector 失敗時回傳原始
SchemaInspectionFailed。
5. 明確未納入
本次仍未納入：
- 不新增 MySQL package。
- 不連線 MySQL。
- 不讀取
information_schema。 - 不執行
CREATE TABLE、ALTER TABLE或任何 DDL。 - 不建立
SchemaExecutor。 - 不實作 Apply。
- 不修改 ConsoleHost 啟動方式。
- 不建立
SchemaDefinitionProvider。
6. 驗證結果
| 驗證項目 | 結果 |
|---|---|
| Core tests | 通過 162 個測試 |
全專案 dotnet test | 通過 313 個測試 |
| GitHub Actions | 程式 repo push 後通知文件 repo workflow 成功 |
| 文件網站狀態同步 | status.json 已更新到 52adfab |
測試仍會出現 .NET 5.0 EOL warning，屬於目前指定版本的已知狀態。
7. 實際效果
完成後，Core 已具備一個比 SchemaDryRunPlanner 更上層的協調入口。
呼叫端未來可以先建立：
SchemaInitializerDryRunRequest再呼叫：
SchemaInitializer.RunDryRun(request)並取得：
- 是否成功。
- DryRun mode。
- schema migration plan。
- warnings。
- manual review items。
- error。
- time taken。
- correlation id。
- source。
這代表後續 ConsoleHost、ServiceHost 或 WebApi 若要接 schema 初始化流程，可以先依賴 initializer result，而不是直接操作 planner。
8. 風險與限制
| 項目 | 說明 |
|---|---|
| 真實 DB 尚未驗證 | 目前仍使用 MockSchemaInspector，尚未讀取真實 MySQL metadata |
| Apply 尚未設計 | 目前只能 DryRun，不會真正建立或修改 table |
| ConsoleHost 尚未接 initializer | 目前 ConsoleHost 仍直接展示既有 dry run demo |
| SchemaDefinitionProvider 尚未建立 | 目前 request 仍需由呼叫端提供 SchemaDefinition |
9. 建議下一步
建議下一步進入：
Schema Initializer DryRun ConsoleHost 接入設計
先討論 ConsoleHost 是否要從直接呼叫 SchemaDryRunPlanner 改為呼叫 SchemaInitializer，並保持既有啟動方式不變。