# Schema Initializer DryRun ConsoleHost 接入設計

## 1. 設計目的

本文件用來設計下一步是否讓 ConsoleHost 的 schema dry run demo 改由 `SchemaInitializer` 取得結果。

目前 ConsoleHost 已能顯示 schema dry run，但流程仍是：

```text
ConsoleHost -> SchemaDryRunPlanner -> SchemaDryRunResult -> FormatSchemaDryRunResult
```

在 `SchemaInitializer` 第一版完成後，建議逐步改成：

```text
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. 建議接入策略

建議採用「小步接入」：

1. 保留既有 ConsoleHost 啟動方式。
2. 保留 `CreateConsoleHostDemoSchema()` 與 mock schema snapshot。
3. 新增或調整 demo 建立流程，改為建立 `SchemaInitializer`。
4. 使用 `SchemaInitializerDryRunRequest` 包裝 target schema、inspect request、correlation id 與 source。
5. 新增 `FormatSchemaInitializerResult()`，讓 ConsoleHost 可顯示 initializer result。
6. 保留既有 `FormatSchemaDryRunResult()`，避免一次刪除舊測試與既有顯示能力。
7. 新增 ConsoleHost 測試，確認 initializer result 的 mode、summary、warnings、manual review、error、correlation id、source 可被顯示。

## 5. 建議顯示格式

第一版建議沿用目前 schema dry run 顯示區塊，但補上 initializer 層資訊。

建議輸出：

```text
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.
```

失敗時建議輸出：

```text
Schema initializer dry run failed:
Mode=DryRun Source=ConsoleHost CorrelationId=...
ErrorCode=SCH-0002
Message=metadata read failed
Warnings:
- ...
```

## 6. 實作建議

### 6.1 ConsoleHost

建議新增：

```text
CreateSchemaInitializerDryRunDemo()
FormatSchemaInitializerResult(SchemaInitializerResult result)
```

並讓 `Main()` 的 schema dry run 區塊改成：

```text
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 接入實作前確認`

先確認實作時是否採用：

1. 新增 `FormatSchemaInitializerResult()`。
2. 保留 `FormatSchemaDryRunResult()`。
3. `Main()` 改呼叫 `CreateSchemaInitializerDryRunDemo()`。
4. 新增 ConsoleHost 顯示測試。