# SchemaDryRunPlanner ConsoleHost 顯示實作前確認

## 1. 文件目的

本文件確認 `SchemaDryRunPlanner` 要接到 ConsoleHost 顯示層之前，實作範圍、輸出格式、測試方式與不可碰觸範圍。

本節點是實作前確認，不直接修改程式碼。

## 2. 本次確認結論

| 項目 | 結論 |
|---|---|
| 是否接真實 MySQL | 否 |
| 是否導入 MySQL 套件 | 否 |
| 是否查詢 `information_schema` | 否 |
| 是否執行 DDL | 否 |
| 是否改 ConsoleHost 啟動方式 | 否 |
| 是否修改既有 public method 簽章 | 否 |
| 是否可進入下一步實作 | 可以，限 ConsoleHost 顯示與 formatter |

## 3. 建議實作範圍

第一版只做 ConsoleHost 的 dry run 顯示，不做真實資料庫初始化。

| 類別 | 建議內容 |
|---|---|
| Demo schema | 使用現有或新增的測試 schema class 產生 target schema |
| Current schema | 使用 `MockSchemaInspector.Empty()` 或 mock snapshot |
| Planner | 呼叫 `SchemaDryRunPlanner.GenerateDryRunPlan(...)` |
| Console output | 顯示 plan summary、warnings、manual review、SQL preview |
| Formatter | 建議抽出 internal formatter，方便單元測試 |
| 測試 | 放在 ConsoleHost 相關測試或現有 ConsoleHost 驗證測試區 |
| 文件 | 實作後補 `schema-dry-run-planner-consolehost-display-record.md` |

## 4. 建議 ConsoleHost 顯示格式

ConsoleHost 顯示應清楚告訴使用者這只是 Dry Run。

```text
Schema dry run:
Mode=DryRun Success=True
TablesToCreate=1 ColumnsToAdd=0 IndexesToAdd=0 ManualReview=0

SQL preview:
- CREATE TABLE IF NOT EXISTS `task_executions` (...)

Warnings:
- Dry Run 不會執行任何 MySQL DDL
```

若沒有任何變更：

```text
Schema dry run:
Mode=DryRun Success=True
TablesToCreate=0 ColumnsToAdd=0 IndexesToAdd=0 ManualReview=0
SQL preview: empty.
Warnings: empty.
```

若 inspector 或 planner 失敗：

```text
Schema dry run failed:
ErrorCode=SCH-0002
Message=metadata read failed
```

## 5. Formatter 建議

建議新增或擴充 ConsoleHost formatter：

```csharp
internal static IEnumerable<string> FormatSchemaDryRunResult(SchemaDryRunResult result)
```

格式化規則：

| 情境 | 輸出 |
|---|---|
| `result == null` | `Schema dry run: empty.` |
| `Success == false` | 顯示 `Schema dry run failed:`、`ErrorCode`、`Message` |
| 無 SQL | 顯示 `SQL preview: empty.` |
| 無 warnings | 顯示 `Warnings: empty.` |
| 有 manual review | 顯示 `Manual review:` 與每筆 table / object / message |
| 有 SQL | 每筆 SQL 前加 `- ` |

## 6. 測試清單

| 測試名稱建議 | 驗證內容 |
|---|---|
| `ConsoleHost_ShouldFormatSchemaDryRunCreateTablePreview` | empty snapshot 時顯示 create table preview |
| `ConsoleHost_ShouldFormatSchemaDryRunAddColumnAndIndexPreview` | 缺欄位與索引時顯示 add column / add index |
| `ConsoleHost_ShouldFormatSchemaDryRunManualReview` | schema 差異時顯示 manual review |
| `ConsoleHost_ShouldFormatSchemaDryRunWarnings` | 顯示 warning 清單 |
| `ConsoleHost_ShouldFormatSchemaDryRunFailure` | inspector 失敗時顯示錯誤碼與訊息 |
| `ConsoleHost_ShouldFormatEmptySchemaDryRunResult` | null result 時顯示 empty |

## 7. 實作時禁止範圍

本次後續實作不得做以下事項：

- 不新增 `MySqlConnector`。
- 不建立真實 MySQL 連線。
- 不讀取 `information_schema`。
- 不執行 `CREATE TABLE`、`ALTER TABLE`、`DROP`。
- 不把密碼或連線字串寫入 repo。
- 不改 ConsoleHost 啟動參數或啟動方式。
- 不改 `SchemaDryRunPlanner` 既有 public method 簽章。
- 不改 `TaskEngine`、`WorkflowEngine` 或 Adapter 行為。

## 8. 驗證方式

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

```powershell
dotnet test tests\HS.DeviceControl.Core.Tests\HS.DeviceControl.Core.Tests.csproj
dotnet test
```

若實作有修改 ConsoleHost，建議再執行：

```powershell
dotnet run --project src\HS.DeviceControl.ConsoleHost
```

人工驗證重點：

- Console 有明確顯示 `Schema dry run`。
- Console 有明確顯示 `SQL preview`。
- Console 有明確標示未執行 DDL。
- 失敗時看得到標準錯誤碼與訊息。

## 9. 建議下一步

建議下一步進入：

> `SchemaDryRunPlanner ConsoleHost 顯示第一版實作`

實作範圍限：

- 新增或擴充 ConsoleHost formatter。
- 使用 mock inspector 產生 dry run demo。
- 補 ConsoleHost formatter 測試。
- 補實作紀錄。