Schema Initializer DryRun ConsoleHost 接入實作前確認
1. 確認目的
本文件用來確認下一步是否可進入 Schema Initializer DryRun ConsoleHost 接入實作。
上一份設計文件已確認接入方向：ConsoleHost 的 schema dry run demo 應逐步從直接呼叫 SchemaDryRunPlanner，改為透過 SchemaInitializer 取得 SchemaInitializerResult。
本次確認重點是把實作範圍切小，確保只做 ConsoleHost 顯示層接入，不提前導入真實 MySQL、啟動參數、DDL executor 或 Apply 模式。
2. 本次建議結論
建議可以進入下一步程式實作，但範圍需限縮為「ConsoleHost 小步接入」：
- 新增
CreateSchemaInitializerDryRunDemo()。 - 新增
FormatSchemaInitializerResult(SchemaInitializerResult result)。 Main()的 schema dry run 顯示區塊改呼叫 initializer demo。- 保留既有
FormatSchemaDryRunResult()與相關測試。 - 補 ConsoleHost 顯示測試，確認 initializer result 可正常輸出。
本節點不建議修改 ConsoleHost 啟動方式，也不建議新增 --schema-dry-run 或 --schema-apply。
3. 實作範圍確認表
| 項目 | 本次是否執行 | 判斷 |
|---|---|---|
新增 CreateSchemaInitializerDryRunDemo() | 是 | 讓 ConsoleHost 以 initializer 作為 dry run demo 入口 |
新增 FormatSchemaInitializerResult() | 是 | 專責格式化 SchemaInitializerResult |
Main() 改顯示 initializer dry run | 是 | 只替換 schema dry run demo 的資料來源 |
保留 FormatSchemaDryRunResult() | 是 | 避免一次移除既有 planner result 顯示能力 |
| 擴充 ConsoleHost 測試 | 是 | 驗證成功、失敗、warning、manual review、null result |
| 執行 ConsoleHost 人工驗證 | 是 | 實作後需執行 dotnet run --project src\HS.DeviceControl.ConsoleHost |
| 修改 ConsoleHost 啟動參數 | 否 | 避免影響既有代表流程 |
| 新增 MySQL package | 否 | 本次不連真實 DB |
讀取 information_schema | 否 | 真實 inspector 另行確認 |
| 執行 DDL | 否 | DryRun 只顯示 SQL preview |
| 實作 Apply 模式 | 否 | Apply 需獨立設計與確認 |
| 修改 public method 簽章 | 否 | 避免破壞既有測試與呼叫端 |
4. 建議程式改動點
4.1 ConsoleHost
建議只修改 Program.cs 內的 schema dry run demo 區塊：
CreateSchemaInitializerDryRunDemo()
FormatSchemaInitializerResult(SchemaInitializerResult result)建議保留：
CreateSchemaDryRunDemo()
FormatSchemaDryRunResult(SchemaDryRunResult result)保留原因：
- 既有 formatter 測試可維持穩定。
- 若 initializer formatter 有問題，可快速比對 planner result 顯示。
- 未來若要刪除舊 formatter，可另立清理節點，不在本次混做。
4.2 Demo request
CreateSchemaInitializerDryRunDemo() 建議建立固定 demo request：
| 欄位 | 建議值 |
|---|---|
Source | ConsoleHost |
CorrelationId | consolehost-schema-initializer-dry-run |
TargetSchema | 沿用目前 ConsoleHost demo schema |
InspectRequest | 沿用目前 demo schema inspect request |
Inspector | MockSchemaInspector.Empty() |
4.3 Formatter 顯示內容
FormatSchemaInitializerResult() 第一版至少顯示：
| 欄位 | 顯示目的 |
|---|---|
Mode | 讓使用者知道目前是 DryRun |
Success | 讓使用者知道 initializer 是否成功 |
Source | 讓 Log / Console 輸出可追蹤來源 |
CorrelationId | 讓一次 dry run 可被追蹤 |
Plan summary | 顯示 table / column / index / manual review 數量 |
SQL preview | 顯示將來可能執行的 SQL，但不執行 |
Warnings | 明確提醒 DryRun 不會執行 DDL |
Error | 失敗時顯示 error code 與 message |
5. 測試清單
下一步程式實作建議至少新增或擴充以下測試：
| 測試情境 | 預期 |
|---|---|
| initializer result 成功 | 顯示 Schema initializer dry run: |
| 顯示 mode | 包含 Mode=DryRun |
| 顯示 source | 包含 Source=ConsoleHost |
| 顯示 correlation id | 包含 CorrelationId=consolehost-schema-initializer-dry-run |
| 顯示 SQL preview | 包含 SQL preview: 與 SQL 條目 |
| 顯示 warnings | 包含 DryRun 不執行 DDL 的警告 |
| 顯示 manual review | 有 manual review 時可列出項目 |
| initializer result 失敗 | 顯示 Schema initializer dry run failed:、error code 與 message |
| result 為 null | 顯示 Schema initializer dry run: empty. |
| 既有 dry run formatter 測試 | 仍需通過 |
6. 實作時禁止範圍
下一步實作不得：
- 不新增
MySqlConnector或其他 MySQL package。 - 不建立真實 MySQL 連線。
- 不讀取
information_schema。 - 不執行
CREATE TABLE、ALTER TABLE、DROP、MODIFY、CHANGE或任何 DDL。 - 不新增
--schema-dry-run、--schema-apply或其他 ConsoleHost 啟動參數。 - 不把 DB connection string、user、password 寫入 repo。
- 不改
SchemaInitializer既有 public method 簽章。 - 不改
SchemaDryRunPlanner既有 public method 簽章。 - 不把 schema initializer 混入 Workflow / TaskEngine 節點流程。
7. 驗證方式
下一步程式實作完成後，至少需執行：
dotnet test tests\HS.DeviceControl.ModbusPoc.Tests\HS.DeviceControl.ModbusPoc.Tests.csproj
dotnet test
dotnet run --project src\HS.DeviceControl.ConsoleHost人工驗證重點：
- ConsoleHost 可看到
Schema initializer dry run:。 - ConsoleHost 可看到
Mode=DryRun、Source=ConsoleHost、CorrelationId=...。 - ConsoleHost 可看到
SQL preview。 - ConsoleHost 有明確 warning 表示未執行 DDL。
- 既有 Workflow / Task / Recent tasks 輸出不受影響。
8. 風險與應對
| 風險 | 應對 |
|---|---|
| formatter 轉換時遺失 warning 或 manual review | 測試需覆蓋 warnings 與 manual review |
| 新 formatter 與舊 formatter 顯示格式差異過大 | 第一版保留相近格式，只補 initializer metadata |
| Main 改動影響既有 ConsoleHost 代表流程 | 實作後執行 ConsoleHost 人工驗證 |
| 過早導入真實 DB 或 Apply | 本次明確禁止 MySQL package、DB 連線與 DDL |
9. 驗收標準
| 驗收項目 | 標準 |
|---|---|
| 測試 | dotnet test 通過 |
| ConsoleHost 顯示 | 可看到 initializer dry run 區塊 |
| 安全邊界 | 無 MySQL package、無 DB 連線、無 DDL |
| 啟動方式 | dotnet run --project src\HS.DeviceControl.ConsoleHost 行為不需新增參數 |
| 文件同步 | 實作後需補實作紀錄並同步文件網站進度 |
10. 建議下一步
建議下一步進入：
Schema Initializer DryRun ConsoleHost 接入實作
實作順序建議：
- 在 ConsoleHost 新增
FormatSchemaInitializerResult()測試。 - 新增
CreateSchemaInitializerDryRunDemo()。 - 將
Main()的 schema dry run 區塊改用 initializer demo。 - 執行 ConsoleHost 測試與全專案測試。
- 執行 ConsoleHost 人工驗證。
- 補實作紀錄並同步文件網站進度。