# Schema Initializer DryRun 第一版實作紀錄

## 1. 完成目的

本紀錄整理 `Schema Initializer DryRun` 第一版程式實作結果。

前一份實作前確認已決定第一版只建立 initializer 協調層，不導入真實 MySQL、不執行 DDL、不修改 ConsoleHost 啟動方式。本次程式實作依照該範圍完成。

## 2. 程式 repo 資訊

| 項目 | 內容 |
|---|---|
| repo | `hs-device-control-template` |
| branch | `poc/nmodbus-tcp` |
| commit | `52adfab` |
| commit 訊息 | `實作 Schema Initializer DryRun 第一版` |
| 完成時間 | 2026-05-30 |

## 3. 新增內容

| 檔案 | 說明 |
|---|---|
| `src/HS.DeviceControl.Core/Schema/SchemaInitializer.cs` | 新增 `RunDryRun()` 協調層 |
| `src/HS.DeviceControl.Core/Schema/SchemaInitializerDryRunRequest.cs` | 定義 initializer dry run 輸入資料 |
| `src/HS.DeviceControl.Core/Schema/SchemaInitializerResult.cs` | 定義 initializer dry run 輸出結果 |
| `tests/HS.DeviceControl.Core.Tests/SchemaInitializerTests.cs` | 新增 10 個 Core 測試 |

## 4. 實作範圍

第一版已完成：

- `SchemaInitializer.RunDryRun()`。
- request 驗證。
- 目標 schema 驗證。
- inspect request 驗證。
- planner 缺失防呆。
- 呼叫既有 `SchemaDryRunPlanner.GenerateDryRunPlan()`。
- 保留 `Warnings`。
- 保留 `ManualReviewItems`。
- 保留 `CorrelationId`。
- 保留 `Source`。
- 保留 `Mode = DryRun`。
- inspector 失敗時回傳原始 `SchemaInspectionFailed`。

## 5. 明確未納入

本次仍未納入：

- 不新增 MySQL package。
- 不連線 MySQL。
- 不讀取 `information_schema`。
- 不執行 `CREATE TABLE`、`ALTER TABLE` 或任何 DDL。
- 不建立 `SchemaExecutor`。
- 不實作 Apply。
- 不修改 ConsoleHost 啟動方式。
- 不建立 `SchemaDefinitionProvider`。

## 6. 驗證結果

| 驗證項目 | 結果 |
|---|---|
| Core tests | 通過 162 個測試 |
| 全專案 `dotnet test` | 通過 313 個測試 |
| GitHub Actions | 程式 repo push 後通知文件 repo workflow 成功 |
| 文件網站狀態同步 | `status.json` 已更新到 `52adfab` |

測試仍會出現 `.NET 5.0` EOL warning，屬於目前指定版本的已知狀態。

## 7. 實際效果

完成後，Core 已具備一個比 `SchemaDryRunPlanner` 更上層的協調入口。

呼叫端未來可以先建立：

```text
SchemaInitializerDryRunRequest
```

再呼叫：

```text
SchemaInitializer.RunDryRun(request)
```

並取得：

- 是否成功。
- DryRun mode。
- schema migration plan。
- warnings。
- manual review items。
- error。
- time taken。
- correlation id。
- source。

這代表後續 ConsoleHost、ServiceHost 或 WebApi 若要接 schema 初始化流程，可以先依賴 initializer result，而不是直接操作 planner。

## 8. 風險與限制

| 項目 | 說明 |
|---|---|
| 真實 DB 尚未驗證 | 目前仍使用 `MockSchemaInspector`，尚未讀取真實 MySQL metadata |
| Apply 尚未設計 | 目前只能 DryRun，不會真正建立或修改 table |
| ConsoleHost 尚未接 initializer | 目前 ConsoleHost 仍直接展示既有 dry run demo |
| SchemaDefinitionProvider 尚未建立 | 目前 request 仍需由呼叫端提供 `SchemaDefinition` |

## 9. 建議下一步

建議下一步進入：

`Schema Initializer DryRun ConsoleHost 接入設計`

先討論 ConsoleHost 是否要從直接呼叫 `SchemaDryRunPlanner` 改為呼叫 `SchemaInitializer`，並保持既有啟動方式不變。