MySqlSchemaInspector 實作前確認清單
1. 文件目的
本文件整理進入 MySqlSchemaInspector 第一版實作前需要確認的工程邊界、實作位置、套件導入條件、query builder、row mapping、測試案例與人工驗證節點。
此節點仍然是「實作前確認」，不會導入 MySqlConnector、不會建立真實連線字串、不會連線 MySQL、不會讀取真實 information_schema，也不會執行任何 DDL。
2. 前置條件
| 項目 | 狀態 |
|---|---|
| MySQL 版本 | 使用者指定為 MySQL 5.6.2 |
| Schema Attribute / SQL Generator | 已完成第一版 |
ISchemaInspector | 已完成抽象與 mock inspector |
SchemaDryRunPlanner | 已完成 mock snapshot 比對 |
SchemaInitializer DryRun | 已完成第一版 |
| ConsoleHost 顯示 | 已可顯示 Schema Initializer DryRun 結果 |
| 真實 MySQL Inspector 前置確認 | 已完成 |
| 自動測試 | dotnet test 通過 318 個測試 |
| 最新程式 commit | ac52376 |
3. 本節點建議結論
可以準備進入 MySqlSchemaInspector 第一版實作，但第一版建議拆成兩段：
| 段落 | 內容 | 是否需要真實 DB |
|---|---|---|
| A. 純程式準備 | 建立 query builder、row mapping、result mapping 與單元測試 | 否 |
| B. 真實 DB 驗證 | 導入套件、連線唯讀 MySQL、讀取 information_schema | 是，需另行確認 |
本次建議先做 A 段，等 A 段完成後，再由使用者確認是否進入 B 段。
4. 實作位置建議
| 類型 | 建議位置 | 說明 |
|---|---|---|
MySqlSchemaInspector | Infrastructure 或 schema 專屬 infrastructure 區 | 需依賴 MySQL provider，不應放在 Core |
| query builder | 與 MySqlSchemaInspector 同區或內部 helper | 負責產生 information_schema 查詢，不持有密碼 |
| row mapper | 與 inspector 同區 | 將 table / column / index rows 轉成 schema snapshot |
| connection settings | Infrastructure config model | 不放密碼預設值，不寫進 repo |
| tests | 對應測試專案 | 用假資料列測 mapping，不需真實 DB |
Core 仍只保留 schema model 與抽象契約，不直接引用 MySQL 套件。
5. 套件導入條件
導入 MySqlConnector 前需再次確認：
| 確認項 | 原因 |
|---|---|
| 是否允許新增 NuGet package | AGENTS 規則要求新增核心套件前需確認 |
| 套件版本 | 需相容 .NET 5.0 |
| 放置專案 | 建議只放在 Infrastructure / MySQL 實作專案，不放 Core |
| CI 還原 | 確認 GitHub Actions 能還原套件 |
| 連線字串來源 | 不得寫死在 repo |
| 測試策略 | 單元測試不依賴真實 DB，真實 DB 驗證另列人工節點 |
若使用者尚未確認，下一步只能做文件與設計，不可直接修改 .csproj。
6. Query Builder 範圍
第一版 query builder 建議只產生三類查詢：
| 查詢 | 來源 | 目的 |
|---|---|---|
| Table query | information_schema.TABLES | 取得指定 database 內的 table |
| Column query | information_schema.COLUMNS | 取得指定 database 內的欄位 |
| Index query | information_schema.STATISTICS | 取得指定 database 內的 index 與 primary key |
6.1 共用條件
每個查詢都必須包含：
TABLE_SCHEMA = @DatabaseName- 可選 table filter，但不得直接串接使用者輸入。
- 明確排序，例如 table name、ordinal position、index name、sequence。
- 參數化查詢，不拼接 database name。
6.2 Table query 欄位
| 欄位 | 目的 |
|---|---|
TABLE_NAME | table 名稱 |
TABLE_COMMENT | table 描述 |
ENGINE | engine |
TABLE_COLLATION | collation |
6.3 Column query 欄位
| 欄位 | 目的 |
|---|---|
TABLE_NAME | table 名稱 |
COLUMN_NAME | 欄位名稱 |
COLUMN_TYPE | 完整 MySQL 型別 |
DATA_TYPE | 基礎型別 |
IS_NULLABLE | nullable |
COLUMN_DEFAULT | default value |
COLUMN_COMMENT | 欄位描述 |
ORDINAL_POSITION | 欄位順序 |
CHARACTER_MAXIMUM_LENGTH | 字串長度 |
NUMERIC_PRECISION / NUMERIC_SCALE | 數值精度 |
6.4 Index query 欄位
| 欄位 | 目的 |
|---|---|
TABLE_NAME | table 名稱 |
INDEX_NAME | index 名稱 |
COLUMN_NAME | 欄位名稱 |
NON_UNIQUE | 判斷 unique |
SEQ_IN_INDEX | 複合 index 欄位順序 |
7. Row Mapping 規則
Row mapping 第一版需處理：
| 情境 | 規則 |
|---|---|
| table 無 comment | 保留空字串，不視為錯誤 |
| column default 為 null | 區分「沒有 default」與「default null」的表示方式 |
IS_NULLABLE | YES 對應 nullable，其他視為 not nullable |
NON_UNIQUE | 0 對應 unique，1 對應 non-unique |
INDEX_NAME = PRIMARY | 轉成 primary key metadata |
| 複合 index | 依 SEQ_IN_INDEX 排序 |
| 未預期型別 | 不直接失敗，轉成 manual review warning |
| 資料列缺少必要欄位 | 回傳標準錯誤，不吞 exception |
8. Error / Result 規則
MySqlSchemaInspector 不應只回傳 bool，也不應讓未處理 exception 直接外拋到 Host。
建議錯誤至少包含：
ErrorCodeErrorMessageExceptionTypeDatabaseNameSourceCorrelationIdTimeTakenMs
建議先沿用既有 SchemaInspectResult / ErrorInfo 風格；若需新增公開欄位或改 public method 簽章，必須先停下確認。
9. 測試案例
不連真實 DB 的第一批測試建議包含：
| 測試 | 預期 |
|---|---|
| Table query 包含 database filter | 查詢必須使用 @DatabaseName |
| Column query 包含排序 | 欄位需依 table / ordinal position 排序 |
| Index query 可還原複合 index | 多欄位 index 依 SEQ_IN_INDEX 排序 |
| nullable mapping | YES / NO 正確轉換 |
| unique mapping | NON_UNIQUE = 0 轉 unique |
| primary key mapping | INDEX_NAME = PRIMARY 可辨識 |
| table / column comment 空值 | 不失敗 |
| metadata row 缺少必要欄位 | 回傳標準錯誤 |
| 未知型別 | 產生 warning 或 manual review，不直接套用 |
10. 人工驗證節點規劃
等使用者確認可以連真實 MySQL 後，需建立人工驗證節點。
人工驗證回報至少包含：
| 項目 | 說明 |
|---|---|
| 驗證節點名稱 | 真實 MySQL Inspector metadata 讀取驗證 |
| 驗證目的 | 確認唯讀帳號可讀指定 database metadata |
| 驗證方式 | 使用指定 Host / Port / Database / User，Password 由安全來源提供 |
| 實際結果 | 讀到 table / column / index 數量 |
| 是否符合預期 | 是否只讀指定 database，是否未執行 DDL |
| 發現問題 | 權限、連線、型別、comment、collation 差異 |
| 下一步 | 是否串接 Dry Run Plan 或補 mapping 規則 |
11. 必須停下確認的事項
以下事項不得在本節點自動執行：
| 事項 | 原因 |
|---|---|
新增 MySqlConnector | 新增套件需確認 |
修改 .csproj | 會影響程式 repo build / restore |
| 新增真實 connection settings | 可能涉及密碼與環境資訊 |
| 連線 MySQL | 外部服務操作需確認 |
讀取真實 information_schema | 進入真實 DB metadata |
| 修改 public method 簽章 | 可能影響既有契約 |
| 修改 ConsoleHost 啟動方式 | 影響使用流程 |
| 執行任何 DDL | 會修改資料庫 |
12. 建議下一步
建議下一步先向使用者確認是否允許導入 MySqlConnector。
若尚未允許導入套件，可先做更細的「Query Builder / Row Mapper 設計」，仍不碰 .csproj。