# Schema Initializer DryRun ConsoleHost 接入實作前確認

## 1. 確認目的

本文件用來確認下一步是否可進入 `Schema Initializer DryRun ConsoleHost 接入實作`。

上一份設計文件已確認接入方向：ConsoleHost 的 schema dry run demo 應逐步從直接呼叫 `SchemaDryRunPlanner`，改為透過 `SchemaInitializer` 取得 `SchemaInitializerResult`。

本次確認重點是把實作範圍切小，確保只做 ConsoleHost 顯示層接入，不提前導入真實 MySQL、啟動參數、DDL executor 或 Apply 模式。

## 2. 本次建議結論

建議可以進入下一步程式實作，但範圍需限縮為「ConsoleHost 小步接入」：

1. 新增 `CreateSchemaInitializerDryRunDemo()`。
2. 新增 `FormatSchemaInitializerResult(SchemaInitializerResult result)`。
3. `Main()` 的 schema dry run 顯示區塊改呼叫 initializer demo。
4. 保留既有 `FormatSchemaDryRunResult()` 與相關測試。
5. 補 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 區塊：

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

建議保留：

```text
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. 驗證方式

下一步程式實作完成後，至少需執行：

```powershell
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 接入實作`

實作順序建議：

1. 在 ConsoleHost 新增 `FormatSchemaInitializerResult()` 測試。
2. 新增 `CreateSchemaInitializerDryRunDemo()`。
3. 將 `Main()` 的 schema dry run 區塊改用 initializer demo。
4. 執行 ConsoleHost 測試與全專案測試。
5. 執行 ConsoleHost 人工驗證。
6. 補實作紀錄並同步文件網站進度。