Schema Inspector 抽象介面與 mock inspector 實作前確認

1. 文件目的

本文件整理進入 Schema Inspector 第一版程式實作前的確認項目。

此節點只處理抽象介面、mock inspector、schema snapshot 回傳模型與測試案例，不導入 MySQL 套件、不連線 MySQL、不讀取 information_schema，也不執行 DDL。

這樣做的目的，是先把「Inspector 讀出目前 schema」與「Dry Run Plan 比對目標 schema」的程式接縫驗證起來，避免一開始就被真實資料庫、密碼、網路與權限問題卡住。

項目	是否納入	說明
`ISchemaInspector` 抽象介面	納入	定義讀取目前 schema snapshot 的契約
`MockSchemaInspector` / `FakeSchemaInspector`	納入	測試與 ConsoleHost 前置驗證可使用
schema snapshot model	納入	優先沿用既有 `SchemaDefinition` / `TableDefinition` / `ColumnDefinition` / `IndexDefinition`
Inspector result	納入	需能表達成功、失敗、錯誤與警告
Dry Run Plan 串接測試	納入	用 mock snapshot 驗證與目標 schema 比對
MySQL 套件	不納入	不新增 `MySqlConnector`
真實 MySQL 連線	不納入	不需要 host / port / user / password
`information_schema` 查詢	不納入	留到真實 MySQL Inspector 節點
DDL 執行	不納入	不建立、不修改、不刪除資料表

建議先建立抽象介面，讓後續可替換 mock inspector 與真實 MySQL inspector。

public interface ISchemaInspector
{
    SchemaInspectResult Inspect(SchemaInspectRequest request);
}

建議不要讓介面直接依賴 MySQL 連線物件，也不要把 connection string 放進 Core 介面。

SchemaInspectRequest 建議包含：

欄位	說明
`DatabaseName`	目標 database 名稱；mock inspector 可用來標示測試情境
`ExpectedTables`	可選，限制只讀取或回傳指定 table
`IncludeIndexes`	是否包含 index snapshot
`IncludeComments`	是否包含 table / column comment
`CorrelationId`	方便 log 與測試追蹤

第一版也可以先不建立複雜 options，只保留必要欄位，避免過早設計。

SchemaInspectResult 建議包含：

欄位	說明
`Success`	是否讀取成功
`Schema`	成功時回傳目前 schema snapshot
`Warnings`	可繼續執行但需提醒的項目
`Error`	失敗時回傳標準錯誤資訊
`TimeTakenMs`	執行耗時
`Source`	例如 `Mock`、`MySQL information_schema`

錯誤格式需盡量沿用既有 Result / ErrorInfo 風格，不要只回傳 bool 或丟出未處理 exception。

建議第一版 mock inspector 支援下列情境：

情境	行為
回傳空 database	`SchemaDefinition` 中無 table
回傳既有完整 schema	模擬 DB 已符合目標 schema
回傳缺少 column	讓 Dry Run Plan 產生 `ColumnsToAdd`
回傳缺少 index	讓 Dry Run Plan 產生 `IndexesToAdd`
回傳欄位型別不同	讓 Dry Run Plan 產生 `ManualReviewItems`
模擬讀取失敗	回傳標準 `ErrorInfo`，不吞 exception

Mock inspector 不應該假裝連線 MySQL，也不應該藏入任何真實連線資訊。

類型	建議位置
抽象介面	若只使用 schema model，可放在 Core schema 區；若會牽涉外部連線，需放 Infrastructure
Mock inspector	優先放測試專案或測試 helper；若 ConsoleHost 需要展示，可放 Infrastructure / Mock 實作區
真實 MySQL inspector	後續放 Infrastructure 或 MySQL schema 實作區，不放 Core

若現有程式 repo 已經有 Schema 資料夾與 SQL Generator，第一版可以先把純抽象與 mock 放在同一個低風險區域，但需避免讓 Core 依賴 MySQL 套件。

測試案例	驗證目的
mock inspector 可回傳空 schema	確認空 DB snapshot 可表示
mock inspector 可回傳既有 table / column / index	確認 snapshot model 可承載資料
mock snapshot 與目標 schema 相同	Dry Run Plan 不應產生 SQL
mock snapshot 缺少 column	Dry Run Plan 應產生 `ADD COLUMN`
mock snapshot 缺少 index	Dry Run Plan 應產生 `ADD INDEX`
mock snapshot 欄位型別不同	Dry Run Plan 應進 `ManualReviewItems`
mock inspector 失敗	result 應包含標準錯誤資訊
inspector 不產生 DDL	確認 inspector 只讀 snapshot，不產生 SQL、不執行 SQL

確認項目	建議
是否先做 mock inspector	建議先做
是否新增 MySQL 套件	本節點不新增
是否改 public method 簽章	避免改既有 public 簽章，新增介面與 model 即可
是否改啟動方式	不改
是否需要 ConsoleHost 展示	本節點先不接 ConsoleHost，避免擴大範圍
是否需要文件同步	需要，完成後同步開發進度

建議採用：

先建立 ISchemaInspector + mock inspector + 單元測試，不碰真實 MySQL。

原因：

若確認本文件方向，下一步可進入：

Schema Inspector 抽象介面與 mock inspector 第一版實作

實作時建議只包含：

仍不做：