# Schema Initializer DryRun 實作前確認

## 1. 確認目的

本文件用來確認下一步 `Schema Initializer DryRun` 第一版實作範圍。

前一份設計文件已定義 Initializer 應負責協調 `SchemaDefinition`、`ISchemaInspector`、`SchemaDryRunPlanner` 與 ConsoleHost 顯示層。本次確認的重點是把程式實作切小，避免一次導入真實 MySQL、DDL executor 或 ConsoleHost 啟動參數。

## 2. 本次建議結論

建議採用「小步第一版」：

1. 在 `HS.DeviceControl.Core` 建立 `SchemaInitializer`。
2. 第一版只支援 `RunDryRun`。
3. 第一版以 `SchemaDefinition` 作為 request 輸入，不先實作 `SchemaDefinitionProvider`。
4. 第一版仍使用 `MockSchemaInspector` 測試，不連真實 MySQL。
5. 第一版不修改 ConsoleHost 啟動方式。
6. 第一版不實作 Apply，也不建立 DDL executor。

此做法可先驗證 Initializer 協調層是否乾淨，再進入真實 MySQL Inspector 或 attribute provider。

## 3. 範圍確認表

| 項目 | 本次是否執行 | 判斷 |
|---|---|---|
| 建立 `SchemaInitializer` class | 是 | 放在 `HS.DeviceControl.Core.Schema` |
| 建立 `SchemaInitializerDryRunRequest` | 是 | 放在 `HS.DeviceControl.Core.Schema` |
| 建立 `SchemaInitializerResult` | 是 | 放在 `HS.DeviceControl.Core.Schema` |
| 新增 Core 測試 | 是 | 放在 `HS.DeviceControl.Core.Tests` |
| 使用 `MockSchemaInspector` | 是 | 第一版先驗證協調流程 |
| 使用真實 MySQL Inspector | 否 | 需等下一階段確認 |
| 讀取 `information_schema` | 否 | 不屬於本次 |
| 導入 MySQL 套件 | 否 | 不屬於本次 |
| 執行 DDL | 否 | 不屬於本次 |
| 實作 Apply | 否 | 需獨立確認 |
| 建立 `SchemaExecutor` | 否 | Apply 模式才需要 |
| 建立 `SchemaDefinitionProvider` | 否 | 先不做 attribute / reflection 擴張 |
| 修改 ConsoleHost 啟動參數 | 否 | 避免影響既有 workflow demo |

## 4. 建議 class 邊界

### 4.1 SchemaInitializer

建議職責：

- 驗證 request。
- 呼叫 `SchemaDryRunPlanner.GenerateDryRunPlan`。
- 將 planner result 包裝成 initializer result。
- 保留 warnings、manual review、error、correlation id。

不應負責：

- 組 SQL。
- 讀取 MySQL metadata。
- 執行 DDL。
- 顯示 Console 文字。
- 決定 ConsoleHost 啟動模式。

### 4.2 SchemaInitializerDryRunRequest

建議欄位：

| 欄位 | 說明 |
|---|---|
| `TargetSchema` | 目標 schema，第一版由測試或未來呼叫端提供 |
| `InspectRequest` | Schema inspector 查詢條件 |
| `CorrelationId` | 本次 dry run 追蹤代號 |
| `Source` | 呼叫來源，例如 `CoreTests` 或未來 `ConsoleHost` |

### 4.3 SchemaInitializerResult

建議欄位：

| 欄位 | 說明 |
|---|---|
| `Success` | 流程是否成功 |
| `Mode` | 第一版固定 `DryRun` |
| `Plan` | `SchemaMigrationPlan` |
| `Warnings` | 所有 warning |
| `ManualReviewItems` | 由 plan 帶出的人工審查項目 |
| `Error` | 標準 `ErrorInfo` |
| `TimeTakenMs` | 執行耗時 |
| `CorrelationId` | 追蹤代號 |
| `Source` | 呼叫來源 |

## 5. 建議流程

```mermaid
flowchart TD
    A["呼叫 RunDryRun(request)"] --> B{"request 是否有效"}
    B -- "否" --> C["回傳 SchemaDefinitionInvalid"]
    B -- "是" --> D["建立 SchemaDryRunRequest"]
    D --> E["呼叫 SchemaDryRunPlanner"]
    E --> F{"planner result 是否成功"}
    F -- "否" --> G["回傳 initializer fail result"]
    F -- "是" --> H["回傳 initializer success result"]
```

## 6. 測試清單

下一步程式實作至少要補以下測試：

| 測試情境 | 預期 |
|---|---|
| `RunDryRun` 成功 | 回傳 success，mode 為 `DryRun`，plan 不為 null |
| request 為 null | 回傳 fail，error code 為 schema definition invalid |
| target schema 為 null | 回傳 fail |
| inspect request 為 null | 回傳 fail |
| inspector 失敗 | 回傳 fail，保留 `SchemaInspectionFailed` |
| planner warning | 回傳 success，warnings 不遺失 |
| manual review | 回傳 success，manual review 不遺失 |
| correlation id | result 保留 correlation id |
| source | result 保留 source |

## 7. 禁止事項

本次程式實作不得：

- 新增 MySQL package。
- 連線 MySQL。
- 讀取 `information_schema`。
- 執行 `CREATE TABLE`、`ALTER TABLE` 或任何 DDL。
- 修改 ConsoleHost 啟動方式。
- 導入 `SchemaExecutor`。
- 實作 Apply。
- 變更既有 public method 簽章。

## 8. 驗收標準

完成下一步程式實作後，至少需符合：

| 驗收項目 | 標準 |
|---|---|
| Core tests 通過 | 必須 |
| 全專案 `dotnet test` 通過 | 必須 |
| 無 MySQL 套件變更 | 必須 |
| 無 DDL 執行 | 必須 |
| warnings 不遺失 | 必須 |
| manual review 不遺失 | 必須 |
| 文件同步 | 必須 |

## 9. 建議下一步

建議下一步進入：

`Schema Initializer DryRun 第一版實作`

實作順序建議：

1. 建立 `SchemaInitializerDryRunRequest`。
2. 建立 `SchemaInitializerResult`。
3. 建立 `SchemaInitializer`。
4. 新增 `SchemaInitializerTests`。
5. 執行 Core tests 與全專案測試。
6. 補實作紀錄並同步文件網站。