# SchemaDryRunPlanner ConsoleHost 顯示第一版實作紀錄

## 基本資訊

- 日期：2026-05-30
- repo：`hs-device-control-template`
- branch：`poc/nmodbus-tcp`
- 程式 commit：`c09da28`
- 類型：第二階段資料庫 Schema 自動化前導實作
- 範圍：ConsoleHost 顯示層、mock dry run 預覽、格式化測試

## 實作目標

本次目標是讓 ConsoleHost 可以顯示 `SchemaDryRunPlanner` 的 dry run 結果，讓後續進入 Schema Initializer 前，可以先用人工方式確認：

- 預計建立的 table 數量。
- 預計補上的 column 數量。
- 預計補上的 index 數量。
- 需要人工審查的 schema 差異。
- SQL preview 是否只停留在預覽，不直接執行。
- warning 與失敗訊息是否能被使用者看懂。

## 實作內容

### ConsoleHost 顯示

新增 `Program.FormatSchemaDryRunResult`，統一將 dry run result 轉成 ConsoleHost 可輸出的文字列。

顯示內容包含：

- `Schema dry run:` 或 `Schema dry run failed:`
- `Mode`
- `Success`
- `TablesToCreate`
- `ColumnsToAdd`
- `IndexesToAdd`
- `ManualReview`
- `SQL preview`
- `Manual review`
- `Warnings`
- 錯誤時的 `ErrorCode` 與 `Message`

### Mock 預覽資料

ConsoleHost 第一版只使用 `MockSchemaInspector.Empty()` 產生預覽結果。

此設計刻意保留在安全邊界內：

- 不連線 MySQL。
- 不讀取 `information_schema`。
- 不執行 DDL（包含 `CREATE TABLE`、`ALTER TABLE` 或其他資料庫結構變更）。
- 不新增 MySQL 套件。
- 不改變 ConsoleHost 啟動參數。

### 測試補強

新增 `ConsoleHostSchemaDryRunDisplayTests`，覆蓋以下顯示情境：

- 空資料庫 snapshot 產生 `CREATE TABLE` preview。
- 已有 table 但缺 column / index 時顯示 `ADD COLUMN` 與 `ADD INDEX` preview。
- 欄位型別不一致時顯示 manual review。
- inspector warning 會被保留並輸出。
- inspector 失敗時顯示標準錯誤碼與訊息。
- null result 會輸出空結果提示。

## 驗證結果

已執行：

```powershell
dotnet test tests\HS.DeviceControl.ModbusPoc.Tests\HS.DeviceControl.ModbusPoc.Tests.csproj
dotnet test
dotnet run --project src\HS.DeviceControl.ConsoleHost
```

結果：

- ConsoleHost / ModbusPoc 測試通過：32
- 全專案測試通過：303
- 失敗：0
- 略過：0
- ConsoleHost 實際輸出可看到 `Schema dry run:`、`SQL preview:`、`CREATE TABLE IF NOT EXISTS task_executions` 與 Dry Run warning。

備註：

- 仍會出現既有 `.NET 5.0` EOL 警告。
- 本次 ConsoleHost 實跑沒有連線 MySQL，也沒有執行 DDL。

## 影響範圍

本次影響：

- `HS.DeviceControl.ConsoleHost`
- `HS.DeviceControl.ModbusPoc.Tests`
- 文件紀錄

未影響：

- Core schema 計算規則。
- MySQL 連線。
- 套件選型。
- public method 簽章。
- 專案啟動方式。
- 真實資料庫初始化流程。

## 限制與後續

目前仍屬於顯示第一版，尚未連接正式 Schema Initializer。

建議下一步：

1. 補一份 ConsoleHost Schema Dry Run 顯示人工驗證紀錄。
2. 進入 Schema Initializer DryRun 流程設計。
3. 設計 DB 連線資訊檢查與權限不足時的錯誤呈現方式。