Schema Initializer DryRun ConsoleHost 接入設計
1. 設計目的
本文件用來設計下一步是否讓 ConsoleHost 的 schema dry run demo 改由 SchemaInitializer 取得結果。
目前 ConsoleHost 已能顯示 schema dry run，但流程仍是：
ConsoleHost -> SchemaDryRunPlanner -> SchemaDryRunResult -> FormatSchemaDryRunResult在 SchemaInitializer 第一版完成後，建議逐步改成：
ConsoleHost -> SchemaInitializer -> SchemaInitializerResult -> FormatSchemaInitializerResult目標是讓 ConsoleHost 對齊未來 ServiceHost / WebApi 也可共用的 initializer 協調層，而不是直接操作 planner。
2. 本次設計邊界
| 項目 | 本次是否包含 |
|---|---|
| 分析 ConsoleHost 接入方式 | 是 |
| 定義 formatter 承接方式 | 是 |
| 定義測試範圍 | 是 |
| 修改程式碼 | 否 |
| 修改 ConsoleHost 啟動參數 | 否 |
| 導入 MySQL 套件 | 否 |
| 連線 MySQL | 否 |
| 執行 DDL | 否 |
| 實作 Apply | 否 |
3. 現況
目前 ConsoleHost 的 schema dry run 區塊由以下責任組成：
| 區塊 | 現況 |
|---|---|
CreateSchemaDryRunDemo() | 建立 SchemaDryRunPlanner(MockSchemaInspector.Empty()) 並呼叫 GenerateDryRunPlan() |
FormatSchemaDryRunResult() | 接收 SchemaDryRunResult，輸出 mode、success、差異數量、SQL preview、manual review、warnings |
| 測試 | ConsoleHostSchemaDryRunDisplayTests 驗證 create table、add column/index、manual review、warning、failure、empty result |
此設計可運作，但 ConsoleHost 仍直接認識 planner。若後續要讓 ServiceHost 或 WebApi 也走相同流程，應逐步改由 initializer 作為統一入口。
4. 建議接入策略
建議採用「小步接入」：
- 保留既有 ConsoleHost 啟動方式。
- 保留
CreateConsoleHostDemoSchema()與 mock schema snapshot。 - 新增或調整 demo 建立流程，改為建立
SchemaInitializer。 - 使用
SchemaInitializerDryRunRequest包裝 target schema、inspect request、correlation id 與 source。 - 新增
FormatSchemaInitializerResult()，讓 ConsoleHost 可顯示 initializer result。 - 保留既有
FormatSchemaDryRunResult()，避免一次刪除舊測試與既有顯示能力。 - 新增 ConsoleHost 測試，確認 initializer result 的 mode、summary、warnings、manual review、error、correlation id、source 可被顯示。
5. 建議顯示格式
第一版建議沿用目前 schema dry run 顯示區塊，但補上 initializer 層資訊。
建議輸出：
Schema initializer dry run:
Mode=DryRun Success=True Source=ConsoleHost CorrelationId=consolehost-schema-initializer-dry-run TablesToCreate=1 ColumnsToAdd=0 IndexesToAdd=0 ManualReview=0
SQL preview:
- CREATE TABLE IF NOT EXISTS ...
Warnings:
- Dry Run only. No DDL was executed.失敗時建議輸出：
Schema initializer dry run failed:
Mode=DryRun Source=ConsoleHost CorrelationId=...
ErrorCode=SCH-0002
Message=metadata read failed
Warnings:
- ...6. 實作建議
6.1 ConsoleHost
建議新增：
CreateSchemaInitializerDryRunDemo()
FormatSchemaInitializerResult(SchemaInitializerResult result)並讓 Main() 的 schema dry run 區塊改成：
foreach (var line in FormatSchemaInitializerResult(CreateSchemaInitializerDryRunDemo()))
{
Console.WriteLine(line);
}6.2 測試
建議新增或擴充 ConsoleHostSchemaDryRunDisplayTests：
| 測試情境 | 預期 |
|---|---|
| initializer result 成功 | 顯示 Schema initializer dry run: |
| 顯示 mode | 包含 Mode=DryRun |
| 顯示 correlation id | 包含 CorrelationId=... |
| 顯示 source | 包含 Source=ConsoleHost |
| 顯示 SQL preview | 保留既有 SQL preview |
| 顯示 manual review | 保留 manual review 區塊 |
| 顯示 warnings | 保留 warnings 區塊 |
| initializer result 失敗 | 顯示 error code 與 message |
| result 為 null | 顯示 empty 訊息 |
7. 不建議本次處理的項目
下一步實作時仍不建議處理：
- 不新增
--schema-dry-run或--schema-apply啟動參數。 - 不接
appsettings.json的 DB 連線字串。 - 不新增 MySQL package。
- 不讀取真實
information_schema。 - 不執行
CREATE TABLE、ALTER TABLE或任何 DDL。 - 不刪除既有
FormatSchemaDryRunResult()，除非測試與呼叫點已完全改好。 - 不把 schema 初始化流程混入 Workflow 節點執行流程。
8. 建議驗收標準
下一步實作完成後，至少需符合：
| 驗收項目 | 標準 |
|---|---|
| ConsoleHost 測試 | ConsoleHostSchemaDryRunDisplayTests 通過 |
| 全專案測試 | dotnet test 通過 |
| ConsoleHost 實際輸出 | 可看到 Schema initializer dry run: |
| 安全邊界 | 無 MySQL 套件、無 DB 連線、無 DDL 執行 |
| 啟動方式 | 不變更既有 dotnet run --project src\HS.DeviceControl.ConsoleHost 行為 |
9. 建議下一步
建議下一步進入：
Schema Initializer DryRun ConsoleHost 接入實作前確認
先確認實作時是否採用：
- 新增
FormatSchemaInitializerResult()。 - 保留
FormatSchemaDryRunResult()。 Main()改呼叫CreateSchemaInitializerDryRunDemo()。- 新增 ConsoleHost 顯示測試。