# SchemaDryRunPlanner ConsoleHost / Initializer 承接設計

## 1. 文件目的

本文件整理 `SchemaDryRunPlanner` 第一版完成後，後續要如何被 ConsoleHost、Schema Initializer 與未來真實 MySQL 流程承接。

本節點仍屬於設計整理：

- 不導入 `MySqlConnector`。
- 不連線 MySQL。
- 不查詢 `information_schema`。
- 不執行 DDL。
- 不改 ConsoleHost 啟動方式。
- 不改既有 public method 簽章。

## 2. 目前已完成狀態

| 元件 | 狀態 | 說明 |
|---|---|---|
| `SchemaDefinitionParser` | 已完成 | 可由 C# Class + Attribute 產生目標 schema |
| `MySqlSchemaSqlGenerator` | 已完成 | 可產生 `CREATE TABLE`、`ADD COLUMN`、`ADD INDEX` 與 Dry Run Plan |
| `ISchemaInspector` | 已完成 | 已建立抽象介面 |
| `MockSchemaInspector` | 已完成 | 可用 mock snapshot 驗證 dry run |
| `SchemaDryRunPlanner` | 已完成 | 可串接 inspector snapshot 與 dry run plan |
| 真實 MySQL Inspector | 未開始 | 需確認 MySQL 套件與連線資訊後才能導入 |
| Schema Initializer | 未開始 | 尚未定義 `DryRun` / `Apply` 模式 |
| ConsoleHost dry run 顯示 | 未開始 | 尚未將 plan 顯示到 ConsoleHost |

## 3. 承接原則

後續承接應拆成三層，避免 ConsoleHost、Initializer 與真實 DB 執行混在一起。

| 層級 | 責任 | 是否可自動實作 | 備註 |
|---|---|---|---|
| ConsoleHost 顯示層 | 顯示 dry run plan、warnings、manual review items | 可以 | 只顯示，不執行 SQL |
| Schema Initializer 協調層 | 決定 `DryRun` / `Apply` 模式，串接 inspector、planner、executor | 需先做設計與確認 | 第一版先只設計，不接真實 DB |
| Schema Executor 執行層 | 實際執行 DDL | 不可自動執行 | 必須等使用者明確確認、備份與權限確認 |

## 4. ConsoleHost 承接設計

### 4.1 第一版建議

ConsoleHost 第一版只應負責顯示 dry run 結果，不執行 DDL。

建議顯示內容：

| 顯示區塊 | 內容 |
|---|---|
| `Schema dry run:` | dry run 是否成功 |
| `Mode` | 固定顯示 `DryRun` |
| `Tables to create` | 需要建立的 table |
| `Columns to add` | 需要新增的 column |
| `Indexes to add` | 需要新增的 index |
| `Manual review` | 需要人工判斷的 schema 差異 |
| `Warnings` | inspector 與 dry run warnings |
| `SQL preview` | 預覽 SQL，但明確標示未執行 |

範例輸出：

```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
```

### 4.2 ConsoleHost 不應負責

- 不應保存 MySQL 密碼。
- 不應直接連線 MySQL。
- 不應直接執行 DDL。
- 不應把 schema 初始化流程寫死在 workflow 節點中。
- 不應讓 Adapter 或 WorkflowEngine 直接知道 schema 初始化細節。

## 5. Schema Initializer 承接設計

### 5.1 建議抽象模式

未來可建立 `SchemaInitializerMode`：

| 模式 | 說明 | 是否執行 DDL |
|---|---|---|
| `DryRun` | 只產生 plan 與 SQL preview | 否 |
| `Apply` | 依 plan 執行允許的 DDL | 是，需使用者確認 |

第一版只建議先支援 `DryRun`。

### 5.2 建議 Initializer 流程

```text
SchemaDefinitionParser
    |
    v
Target Schema
    |
    v
Schema Initializer
    |
    +--> SchemaDryRunPlanner
    |       |
    |       +--> ISchemaInspector
    |       +--> MySqlSchemaSqlGenerator
    |
    v
SchemaDryRunResult
```

未來 `Apply` 模式才會接：

```text
SchemaDryRunResult
    |
    v
Schema Executor
    |
    v
MySQL DDL
```

## 6. DryRun / Apply 分離規則

| 規則 | 說明 |
|---|---|
| `DryRun` 是預設模式 | 避免誤執行 DDL |
| `Apply` 必須明確指定 | 不可由設定缺省自動啟用 |
| `Apply` 前必須有 plan | 不允許跳過 dry run 直接執行 |
| `Apply` 只能執行 allow-list SQL | 第一版最多允許 `CREATE TABLE`、`ADD COLUMN`、`ADD INDEX` |
| destructive SQL 永遠不自動執行 | `DROP`、`MODIFY`、`CHANGE`、rename 必須人工處理 |
| manual review 存在時不得 apply | 需人工確認後才能進一步處理 |

## 7. 真實 MySQL Inspector 導入前條件

導入真實 MySQL Inspector 前，需先確認：

| 確認項目 | 說明 |
|---|---|
| MySQL 套件 | 是否採用 `MySqlConnector` |
| MySQL 版本 | 目前指定為 MySQL 5.6.2 |
| 連線資訊 | host、port、database、user、password 提供方式 |
| 權限 | 第一版只需要讀取 `information_schema` |
| Secret 管理 | 不可把密碼寫入 repo |
| 測試資料庫 | 建議先用測試 DB，不可直接打正式 DB |
| 備份策略 | 進入 `Apply` 前必須有備份與回復方式 |

## 8. 驗證節點設計

### 8.1 ConsoleHost dry run 顯示驗證

| 驗證項目 | 預期結果 |
|---|---|
| mock empty snapshot | Console 顯示 `TablesToCreate` 與 SQL preview |
| mock 缺 column / index | Console 顯示 `ColumnsToAdd` / `IndexesToAdd` |
| mock schema 差異 | Console 顯示 `ManualReview` |
| inspector 失敗 | Console 顯示標準錯誤碼與訊息 |
| warnings | Console 顯示 warning 清單 |
| SQL preview | 顯示 SQL，但標示未執行 |

### 8.2 Initializer dry run 驗證

| 驗證項目 | 預期結果 |
|---|---|
| `DryRun` 模式 | 只回傳 plan，不呼叫 executor |
| `Apply` 未確認 | 不可執行 DDL |
| manual review 存在 | 不可進入 apply |
| destructive SQL | 不可進入 apply |

## 9. 建議下一步

建議下一步先做：

> `SchemaDryRunPlanner ConsoleHost 顯示實作前確認`

該確認清單應包含：

- ConsoleHost 要顯示哪些欄位。
- 是否需要 formatter。
- 是否先用 `MockSchemaInspector.Empty()` 做示範。
- 測試是否放在 ConsoleHost 相關測試中。
- 是否維持「只顯示 SQL preview，不執行 DDL」。