# 真實 MySQL Inspector 前置確認

## 1. 文件目的

本文件整理進入「真實 MySQL Inspector」前需要確認的實作邊界、資料來源、連線安全、查詢欄位、測試策略與停止條件。

此節點仍屬於實作前確認，不會新增 MySQL 套件、不會連線資料庫、不會讀取真實 `information_schema`，也不會執行任何 DDL。

## 2. 目前前置狀態

| 項目 | 狀態 |
|---|---|
| MySQL 版本 | 使用者指定為 MySQL 5.6.2 |
| Schema Attribute | 已完成第一版設計與實作 |
| SQL Generator | 已完成 `CREATE TABLE IF NOT EXISTS`、`ADD COLUMN`、`ADD INDEX` |
| Schema Inspector 抽象 | 已完成 `ISchemaInspector` 與 mock inspector |
| Dry Run Planner | 已可用 mock schema 產生新增欄位、索引與人工確認項目 |
| Schema Initializer | 已完成 DryRun 第一版 |
| ConsoleHost 顯示 | 已可呈現 Schema Initializer DryRun 結果 |
| 自動測試 | `dotnet test` 通過 318 個測試 |
| 最新程式 commit | `ac52376` |
| 真實 MySQL 套件 | 尚未導入，導入前需另行確認 |
| 真實 MySQL 連線 | 尚未執行，連線前需另行確認 |
| DDL / Apply | 尚未執行，任何寫入 DB 行為需另行確認 |

## 3. 本節點建議目標

真實 MySQL Inspector 第一版建議只做「唯讀 schema snapshot」，目標是把既有資料庫現況轉成專案內部 schema model，交給 Dry Run Planner 比對。

| 目標 | 說明 |
|---|---|
| 讀取 table metadata | 從 `information_schema.TABLES` 取得 table 名稱、註解、engine、collation |
| 讀取 column metadata | 從 `information_schema.COLUMNS` 取得欄位型別、nullable、default、comment、順序 |
| 讀取 index metadata | 從 `information_schema.STATISTICS` 取得 index 名稱、欄位順序、unique 狀態 |
| 判斷 primary key | 優先由 `STATISTICS` 的 `PRIMARY` 或 `KEY_COLUMN_USAGE` 判斷 |
| 轉成 snapshot | 轉成現有 `SchemaDefinition` / `TableDefinition` / `ColumnDefinition` / `IndexDefinition` 相容結構 |
| 串接 Dry Run | 用真實 DB snapshot 與 C# 目標 schema 產生 Dry Run Plan |

## 4. 明確不做的事

| 不做項目 | 原因 |
|---|---|
| 不執行 `CREATE TABLE` | Inspector 只讀，不負責建表 |
| 不執行 `ALTER TABLE` | 避免尚未確認前修改資料庫 |
| 不執行 `DROP` / `MODIFY` / `CHANGE` | 破壞性或高風險 SQL 必須另行設計與確認 |
| 不把密碼寫進 repo | 密碼、token、連線字串不可進入文件或程式碼 |
| 不把 MySQL 套件放進 Core | 避免 Core 依賴外部 DB provider |
| 不改 ConsoleHost 啟動方式 | CLI 參數與正式啟動流程需另行確認 |
| 不自動套用 Dry Run 結果 | Dry Run 只輸出計畫，不等於 Apply |

## 5. 連線資訊與安全規則

真實 Inspector 需要 DB 連線資訊，但第一版規劃應先定義資訊來源，不直接收集密碼。

| 資訊 | 建議處理 |
|---|---|
| Host / IP | 可由本機設定檔或環境變數提供 |
| Port | 預設 `3306`，但需允許覆寫 |
| DatabaseName | 必填，只允許讀取指定 database |
| User | 建議使用唯讀帳號 |
| Password | 只允許由環境變數、Secret 或本機未納版設定提供 |
| SSL / Timeout | 第一版可先保留設定欄位，實作時再確認預設值 |
| ConnectionString | 不建議完整寫入 repo，應由安全來源組合 |

建議第一個真實測試帳號只給：

```text
SELECT 權限
information_schema 讀取能力
不得具有 CREATE / ALTER / DROP 權限
```

## 6. information_schema 查詢欄位

### 6.1 `information_schema.TABLES`

| 欄位 | 用途 |
|---|---|
| `TABLE_SCHEMA` | 限定指定 database |
| `TABLE_NAME` | 對應 table name |
| `TABLE_COMMENT` | 對應 table description |
| `ENGINE` | 確認 table engine |
| `TABLE_COLLATION` | 後續判斷 charset / collation |

### 6.2 `information_schema.COLUMNS`

| 欄位 | 用途 |
|---|---|
| `TABLE_NAME` | 對應所屬 table |
| `COLUMN_NAME` | 對應欄位名稱 |
| `COLUMN_TYPE` | 保留完整 MySQL 型別，例如 `varchar(64)` |
| `DATA_TYPE` | 判斷基礎型別，例如 `varchar`、`int`、`datetime` |
| `CHARACTER_MAXIMUM_LENGTH` | 字串長度 |
| `NUMERIC_PRECISION` / `NUMERIC_SCALE` | 數值精度 |
| `IS_NULLABLE` | 是否允許 null |
| `COLUMN_DEFAULT` | 預設值 |
| `COLUMN_COMMENT` | 欄位描述 |
| `ORDINAL_POSITION` | 欄位順序 |

### 6.3 `information_schema.STATISTICS`

| 欄位 | 用途 |
|---|---|
| `TABLE_NAME` | 對應所屬 table |
| `INDEX_NAME` | 對應 index 名稱 |
| `COLUMN_NAME` | index 欄位 |
| `NON_UNIQUE` | 判斷 unique / non-unique |
| `SEQ_IN_INDEX` | 還原複合 index 欄位順序 |

## 7. MySQL 5.6.2 注意事項

| 項目 | 注意 |
|---|---|
| JSON 型別 | MySQL 5.6.2 不支援原生 JSON，需使用 `TEXT` |
| `datetime(3)` | 需確認 5.6.2 環境是否支援 fractional seconds；若不穩定，第一版先用 `datetime` |
| `utf8mb4` | 需確認資料庫與 table collation 是否支援，否則先採既有 DB 設定 |
| index 長度 | `varchar` 欄位建立索引時需注意編碼與長度限制 |
| default value | `TEXT` 欄位不可隨意設定 default |
| comment | table / column comment 可讀，但不同環境可能有空字串或編碼差異 |

## 8. 建議實作位置

| 類型 | 建議位置 | 原因 |
|---|---|---|
| 真實 MySQL Inspector | Infrastructure 或 schema 專屬模組 | 需要依賴 MySQL provider，不應放入 Core |
| `ISchemaInspector` | 沿用目前抽象 | 讓 mock 與真實 Inspector 可替換 |
| 連線設定 model | Infrastructure config 或 ConsoleHost 專用設定 | 避免污染 Core schema model |
| 測試替身 | Tests helper / mock inspector | 單元測試不依賴真實 DB |
| 真實 DB 驗證 | 獨立人工驗證節點 | 避免 CI 需要密碼與外部 DB |

## 9. 測試與驗證策略

第一版建議拆成三層：

| 層級 | 驗證方式 | 是否需要真實 DB |
|---|---|---|
| SQL query builder 測試 | 驗證產生的查詢包含 database filter 與必要欄位 | 否 |
| row mapping 測試 | 用假資料列轉成 schema snapshot | 否 |
| 真實 DB 人工驗證 | 使用唯讀帳號讀取指定 database 並輸出 Dry Run Plan | 是，但需另行確認 |

真實 DB 人工驗證節點需回報：

- 連線是否成功。
- 讀到幾張 table、幾個 column、幾個 index。
- 是否正確限制在指定 database。
- 是否產生符合預期的 Dry Run Plan。
- 是否完全沒有執行 DDL。
- 若失敗，錯誤碼、錯誤訊息與連線階段需清楚。

## 10. 停止條件

遇到以下情況必須停下確認：

| 情況 | 原因 |
|---|---|
| 要新增 `MySqlConnector` 或其他 DB 套件 | 屬於新增核心套件 |
| 要建立真實 connection string | 可能涉及密碼與環境資訊 |
| 要連線實際 MySQL | 會碰到外部服務與權限 |
| 要讀取 `information_schema` | 已進入真實 DB metadata 存取 |
| 要執行 `CREATE` / `ALTER` / `DROP` | 會修改資料庫 |
| 要調整 public method 簽章 | 可能影響既有契約 |
| 要改 ConsoleHost 啟動方式 | 可能影響使用流程 |

## 11. 建議實作順序

1. 整理 `MySqlSchemaInspector` 實作前確認清單。
2. 確認是否允許導入 `MySqlConnector`。
3. 建立唯讀 connection settings model，但不寫入密碼。
4. 建立 `information_schema` query builder。
5. 建立 metadata row mapping 測試。
6. 實作 `MySqlSchemaInspector`，先以測試替身驗證 mapping。
7. 經使用者確認後，再做真實 DB 人工驗證。
8. 真實驗證通過後，再討論 Apply executor。

## 12. 本次結論

可以進入「MySqlSchemaInspector 實作前確認清單」。

但下一步若要真的導入 `MySqlConnector`、建立連線資訊、讀取真實 `information_schema` 或接上 ConsoleHost 啟動參數，仍需先取得使用者確認。