# MySqlSchemaInspector 真實 DB provider 實作前確認

## 1. 文件目的

本文件整理進入 `MySqlSchemaInspector` 真實 DB provider 前的確認項目，目標是判斷是否可以從「純程式 helper」進入「導入 MySQL 套件並讀取真實 `information_schema`」。

此節點仍是實作前確認，不會導入 `MySqlConnector`、不會修改 `.csproj`、不會建立 connection string、不會連線 MySQL、不會讀取真實 `information_schema`，也不會執行任何 DDL。

## 2. 目前狀態

| 項目 | 狀態 |
|---|---|
| MySQL 版本 | 使用者指定為 MySQL 5.6.2 |
| Schema Attribute | 已完成 |
| SQL Generator | 已完成 |
| ALTER TABLE Dry Run | 已完成 |
| `ISchemaInspector` | 已完成抽象與 mock inspector |
| `SchemaDryRunPlanner` | 已完成 |
| `SchemaInitializer` DryRun | 已完成 |
| ConsoleHost DryRun 顯示 | 已完成 |
| Query Builder / Row Mapper / Snapshot Assembler | 已完成，程式 repo commit `51cb17c` |
| 測試數 | `dotnet test` 合計 329 個測試通過 |
| 真實 DB provider | 尚未開始 |
| MySQL 套件 | 尚未導入 |
| 真實 DB 連線 | 尚未執行 |
| DDL / Apply | 尚未允許 |

## 3. 本節點建議結論

建議下一步可以進入「真實 DB provider 第一版」，但必須先取得使用者確認。

第一版 provider 建議只做唯讀 inspect：

| 範圍 | 是否納入 | 說明 |
|---|---|---|
| 導入 `MySqlConnector` | 需確認後才可納入 | 需修改程式 repo `.csproj`。 |
| 建立 provider class | 可在確認後納入 | 將真實 DB metadata 轉成既有 schema snapshot。 |
| 讀取 `information_schema` | 需確認後才可納入 | 僅限指定 database。 |
| 產生 Dry Run Plan | 可納入 | 只比對，不套用。 |
| 執行 `CREATE` / `ALTER` / `DROP` | 不納入 | Apply / DDL executor 需另行設計與確認。 |
| 寫入 TaskStore | 不納入 | 等 inspect / dry run 穩定後再進入。 |

## 4. 實作位置建議

| 類型 | 建議位置 | 原因 |
|---|---|---|
| 真實 DB provider | 新增 Infrastructure 或 MySQL 專屬實作專案 | 避免 Core 直接依賴 MySQL 套件。 |
| `ISchemaInspector` | 沿用 Core 既有抽象 | 讓 mock 與真實 provider 可替換。 |
| Query Builder / Mapper / Assembler | 沿用目前 internal helper | 已有測試覆蓋，不需重寫。 |
| Connection settings | Infrastructure / ConsoleHost 設定層 | 密碼不得寫死，不污染 Core schema model。 |
| 真實驗證入口 | ConsoleHost 或獨立驗證工具 | 需明確標示只讀，不改既有代表流程。 |

若目前程式 repo 尚未建立 Infrastructure 專案，建議先停下確認「是否新增 Infrastructure 專案」，不得直接把 MySQL provider 放進 Core。

## 5. 套件導入確認

| 確認項 | 建議 |
|---|---|
| 套件 | `MySqlConnector` |
| 導入位置 | Infrastructure / MySQL provider 專案，不放 Core |
| .NET 相容性 | 需選擇支援 .NET 5.0 的版本 |
| CI 影響 | GitHub Actions 需能 restore / build / test |
| 測試策略 | 單元測試不依賴真實 DB；真實 DB 只做人工驗證節點 |
| 停止條件 | 套件導入失敗、CI restore 失敗、需要升級 .NET 時停下討論 |

## 6. 連線資訊來源

| 資訊 | 建議來源 | 是否可寫入 repo |
|---|---|---|
| Host / IP | 本機未追蹤設定檔或環境變數 | 可寫範例，不可寫正式值 |
| Port | 本機未追蹤設定檔或環境變數 | 可寫預設 `3306` |
| DatabaseName | 本機未追蹤設定檔或環境變數 | 可寫範例 |
| User | 本機未追蹤設定檔或環境變數 | 不建議寫正式帳號 |
| Password | 環境變數、Secret、本機未追蹤設定 | 不可寫入 repo |
| SSL / Timeout | 設定檔欄位 | 可寫預設值，但需可覆寫 |

建議第一版環境變數命名：

```text
HS_DB_HOST
HS_DB_PORT
HS_DB_NAME
HS_DB_USER
HS_DB_PASSWORD
HS_DB_SSL_MODE
HS_DB_TIMEOUT_SECONDS
```

## 7. 第一版 provider 流程

```mermaid
flowchart LR
    A["讀取安全來源設定"] --> B["建立 MySQL 連線"]
    B --> C["查詢 information_schema.TABLES"]
    B --> D["查詢 information_schema.COLUMNS"]
    B --> E["查詢 information_schema.STATISTICS"]
    C --> F["Metadata Rows"]
    D --> F
    E --> F
    F --> G["Snapshot Assembler"]
    G --> H["SchemaInspectResult"]
    H --> I["SchemaDryRunPlanner"]
```

## 8. 錯誤處理規則

| 情境 | 建議錯誤資訊 |
|---|---|
| 缺少 Host / Database / User | 回傳設定錯誤，不嘗試連線 |
| 缺少 Password | 回傳安全設定錯誤，不提示或寫出密碼 |
| 連線失敗 | 回傳 provider、host、database、exception type、message |
| 權限不足 | 回傳權限錯誤，標示讀取 `information_schema` 失敗 |
| database 不存在 | 回傳 schema not found 類型錯誤 |
| metadata 欄位缺失 | 回傳 mapping error 或 warning |
| 查詢逾時 | 回傳 timeout error 與 timeout 秒數 |

錯誤不得只回傳 `false`，也不得吞掉 exception。

## 9. 測試策略

| 測試類型 | 是否需要真實 DB | 說明 |
|---|---|---|
| Query Builder 單元測試 | 否 | 已有基礎，可補 provider 使用情境。 |
| Row Mapper 單元測試 | 否 | 使用 fake metadata row。 |
| Provider settings validation 測試 | 否 | 驗證缺少必要欄位會被擋下。 |
| Provider command flow 測試 | 否 | 可用 fake executor 模擬 reader。 |
| 真實 MySQL inspect 人工驗證 | 是 | 使用唯讀帳號與指定 database。 |
| CI 自動真實 DB 測試 | 第一版不做 | 避免 CI 需要密碼與外部 DB。 |

## 10. 人工驗證節點

未來真實 provider 完成後，需建立「真實 MySQL metadata inspect 人工驗證」。

回報至少包含：

| 項目 | 說明 |
|---|---|
| 驗證節點名稱 | 真實 MySQL metadata inspect 人工驗證 |
| 驗證目的 | 確認 provider 可唯讀讀取指定 database metadata |
| 驗證方式 | 使用安全來源提供 Host / Port / Database / User / Password |
| 實際結果 | table / column / index 數量 |
| 安全結果 | 是否未執行任何 DDL |
| 錯誤結果 | 若失敗，列出錯誤碼、階段、訊息與限制 |
| 下一步 | 是否串接 ConsoleHost dry run 顯示或補 mapping 規則 |

## 11. 必須停下確認

以下事項必須先取得使用者明確確認：

| 事項 | 原因 |
|---|---|
| 新增 `MySqlConnector` | 新增套件與修改 `.csproj` |
| 新增 Infrastructure 專案 | 改變 solution / project 結構 |
| 新增 connection settings 格式 | 可能影響設定檔格式 |
| 修改 public method 簽章 | 可能影響既有契約 |
| 修改 ConsoleHost 啟動方式 | 可能影響既有使用流程 |
| 連線真實 MySQL | 涉及外部服務與敏感資訊 |
| 讀取真實 `information_schema` | 進入真實 DB metadata 存取 |
| 執行任何 DDL | 會修改資料庫 |

## 12. 本次結論

目前可以進入下一個決策點：「是否允許導入 `MySqlConnector` 並新增真實 DB provider 所需專案 / 設定」。

若使用者同意，建議下一步先做程式 repo 的「provider 實作前程式結構檢查」，確認現有 `.sln`、專案分層、Core helper、測試專案與是否需要新增 Infrastructure 專案。

若使用者尚未同意，則維持在文件與規劃階段，不修改 `.csproj`、不導入套件、不連 DB。