# SchemaDryRunPlanner 第一版實作紀錄

## 1. 節點狀態

| 項目 | 內容 |
|---|---|
| 節點名稱 | SchemaDryRunPlanner 第一版實作 |
| 完成時間 | 2026-05-30 |
| repo | `hs-device-control-template` |
| branch | `poc/nmodbus-tcp` |
| 狀態 | 已完成 |

本節點依文件 repo 的「Schema Inspector 與 Dry Run Plan 串接服務設計」實作第一版純流程服務。

## 2. 本次新增內容

| 類別 | 內容 |
|---|---|
| Request model | `SchemaDryRunRequest` |
| Result model | `SchemaDryRunResult` |
| Planner | `SchemaDryRunPlanner` |
| Tests | `SchemaDryRunPlannerTests` |

`SchemaDryRunPlanner` 負責：

- 呼叫 `ISchemaInspector.Inspect()` 取得目前 schema snapshot。
- 將目標 schema 與目前 schema 交給 `MySqlSchemaSqlGenerator.GenerateDryRunPlan()`。
- 合併 inspector warnings 與 plan warnings。
- 保留 inspector 或 generator 的標準錯誤資訊。
- 回傳 `SchemaDryRunResult`，避免只回傳 bool。

## 3. 明確未納入範圍

本節點沒有做以下事項：

- 未新增 `MySqlConnector` 或任何 MySQL 套件。
- 未連線 MySQL。
- 未查詢 `information_schema`。
- 未執行 `CREATE TABLE` / `ALTER TABLE` / `DROP`。
- 未修改 ConsoleHost 啟動流程。
- 未變更既有 public method 簽章。

## 4. 測試覆蓋

| 測試項目 | 驗證目的 |
|---|---|
| 空 snapshot | 應產生 create table dry run operation |
| 缺 column / index | 應產生 add column / add index operation |
| schema 差異 | 應產生 manual review item |
| inspector 失敗 | 應保留 `SchemaInspectionFailed` |
| warning 合併 | 應同時保留 inspector warning 與 dry run warning |
| request null | 應回傳標準錯誤，不丟例外 |
| target schema null | 應回傳標準錯誤 |
| inspector null | 應回傳標準錯誤 |
| generator null | 應回傳標準錯誤 |
| generator 驗證失敗 | 應保留 schema definition error |
| 非破壞性 SQL | 不產生 `DROP`、`MODIFY`、`CHANGE` |

## 5. 驗證結果

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

| 測試範圍 | 結果 |
|---|---:|
| Core tests | 152 passed |
| 全專案測試 | 297 passed |

備註：測試仍出現既有 `.NET 5.0` 已停止支援的 `NETSDK1138` warning，非本次變更造成。

## 6. 影響範圍

- 影響 Core `Schema` 區域。
- 新增純流程串接服務，不依賴 UI、Host、DB 或真實硬體。
- 後續可由 ConsoleHost 或 Schema Initializer 呼叫，但本節點尚未接入。

## 7. 建議下一步

建議下一步整理「SchemaDryRunPlanner ConsoleHost / Initializer 承接設計」。

該節點應先決定：

- ConsoleHost 是否只顯示 dry run plan，不執行 DDL。
- Schema Initializer 是否拆成 `DryRun` 與 `Apply` 兩種模式。
- 真實 MySQL Inspector 何時導入，以及導入前需要的連線資訊與權限。