# Query Builder / Row Mapper 實作前確認

## 1. 文件目的

本文件整理進入 `MySqlSchemaInspector` Query Builder / Row Mapper 第一版實作前的確認項目，目標是把可實作範圍、預計新增類別、方法、測試檔、影響範圍與停止線先列清楚。

本節點仍不導入 `MySqlConnector`、不修改 `.csproj`、不連線 MySQL、不讀取真實 `information_schema`、不執行 DDL，也不調整 ConsoleHost 啟動方式。

## 2. 實作目標

本批建議只做「不依賴真實 DB 的純程式元件」。

| 目標 | 說明 |
|---|---|
| Query Builder | 產生 table / column / index metadata 查詢字串與參數名稱 |
| Metadata Row Model | 表示 `information_schema` 查詢結果的 table / column / index row |
| Row Mapper | 將 metadata row 轉成 schema model 可使用的中間結構 |
| Snapshot Assembler | 將 table / column / index metadata 組成 schema snapshot |
| 單元測試 | 驗證 SQL 條件、參數化、nullable / unique / primary key / composite index mapping |

## 3. 明確不做

| 不做項目 | 原因 |
|---|---|
| 不新增 `MySqlConnector` | 新增 NuGet package 需使用者確認 |
| 不修改 `.csproj` | 避免影響 restore / build |
| 不建立真實 connection string | 避免密碼與環境資訊進入 repo |
| 不連線 MySQL | 外部服務操作需另行確認 |
| 不讀取真實 `information_schema` | 真實 DB metadata 存取需另行確認 |
| 不執行 DDL | 會修改資料庫 |
| 不改 ConsoleHost 啟動方式 | 會影響使用流程 |
| 不改 public method 簽章 | 避免破壞既有契約 |

## 4. 建議新增類別

以下命名為建議，實作時仍需依程式 repo 現有 namespace 與資料夾調整。

| 類別 | 建議用途 | 是否 public |
|---|---|---|
| `MySqlSchemaInspectorQueryBuilder` | 產生 metadata 查詢 | internal 優先 |
| `MySqlSchemaQuery` | 包裝 SQL text 與 parameter names | internal 優先 |
| `MySqlTableMetadataRow` | table metadata row | internal 或測試可見 |
| `MySqlColumnMetadataRow` | column metadata row | internal 或測試可見 |
| `MySqlIndexMetadataRow` | index metadata row | internal 或測試可見 |
| `MySqlSchemaMetadataMapper` | row mapping | internal 優先 |
| `MySqlSchemaSnapshotAssembler` | 組合 schema snapshot | internal 優先 |

若現有專案沒有啟用 `InternalsVisibleTo`，第一版可以先將測試需要的 helper 設成 public，但需避免進入正式對外契約；若需新增 `InternalsVisibleTo`，要先確認是否符合專案規則。

## 5. 建議方法

### 5.1 Query Builder

```csharp
BuildTableQuery(SchemaInspectRequest request)
BuildColumnQuery(SchemaInspectRequest request)
BuildIndexQuery(SchemaInspectRequest request)
```

預期：

- 回傳 SQL text 與參數名稱。
- 必含 `TABLE_SCHEMA = @DatabaseName`。
- table filter 必須使用參數，例如 `@TableName0`、`@TableName1`。
- 不產生 DDL。

### 5.2 Row Mapper

```csharp
MapTable(MySqlTableMetadataRow row)
MapColumn(MySqlColumnMetadataRow row)
MapIndex(MySqlIndexMetadataRow row)
```

預期：

- 缺少必要欄位時回傳標準錯誤。
- null comment 轉空字串。
- `IS_NULLABLE = YES` 轉 nullable。
- `NON_UNIQUE = 0` 轉 unique。
- `INDEX_NAME = PRIMARY` 標記為 primary key。

### 5.3 Snapshot Assembler

```csharp
Assemble(
    IEnumerable<MySqlTableMetadataRow> tables,
    IEnumerable<MySqlColumnMetadataRow> columns,
    IEnumerable<MySqlIndexMetadataRow> indexes)
```

預期：

- 依 table name 組合 schema snapshot。
- column 依 `ORDINAL_POSITION` 排序。
- index 欄位依 `SEQ_IN_INDEX` 排序。
- column / index 指到不存在 table 時產生 warning。
- 不直接呼叫 DB。

## 6. 建議測試檔

| 測試檔 | 測試重點 |
|---|---|
| `MySqlSchemaInspectorQueryBuilderTests` | table / column / index query 條件、排序、參數化 |
| `MySqlSchemaMetadataMapperTests` | nullable、unique、primary key、comment、缺欄位錯誤 |
| `MySqlSchemaSnapshotAssemblerTests` | table / column / index 組合、複合 index、warning |

測試專案應優先放在既有 schema / infrastructure 相關測試區。若現有測試專案命名不明確，實作前需先檢查程式 repo 結構再決定。

## 7. 測試案例清單

| 測試 | 預期 |
|---|---|
| Table query 包含 `TABLE_SCHEMA = @DatabaseName` | 只能讀指定 database |
| Column query 排序穩定 | `ORDER BY TABLE_NAME, ORDINAL_POSITION` |
| Index query 排序穩定 | `ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX` |
| Table filter 參數化 | 不直接拼接 table name |
| 空 table filter | 不產生 `IN ()` |
| Nullable mapping | `YES` / `NO` 正確轉換 |
| Unique mapping | `NON_UNIQUE = 0` 為 unique |
| Primary key mapping | `PRIMARY` 不放入一般 index |
| Composite index assembly | 欄位順序正確 |
| Null comment | 轉空字串 |
| 缺少 table name | 回傳標準錯誤 |
| column 指向不存在 table | 產生 warning |
| index 指向不存在 column | 產生 warning |

## 8. 影響範圍

預期影響：

- 只新增 schema inspector 周邊純程式 helper。
- 只新增不連 DB 的單元測試。
- 不影響 ConsoleHost。
- 不影響現有 Workflow / Adapter / TaskEngine。
- 不改既有 public method 簽章。
- 不新增外部套件。

## 9. 實作前檢查

真正進入程式 repo 實作前，需要先檢查：

1. 現有 schema model 的 namespace 與資料夾位置。
2. `ISchemaInspector` / `SchemaInspectResult` 現有簽章。
3. 既有測試專案位置與命名。
4. 是否已有 internal helper 測試慣例。
5. 是否已有 Result / ErrorInfo 標準工廠可沿用。

## 10. 停止線

實作中若遇到以下情況需停下確認：

| 情況 | 原因 |
|---|---|
| 需要新增 NuGet package | 超出本批不導入套件範圍 |
| 需要修改 `.csproj` | 可能影響 build |
| 需要修改 public method 簽章 | 可能影響既有契約 |
| 需要改 schema model 欄位 | 可能影響既有 SQL Generator / Dry Run |
| 需要新增 ConsoleHost CLI 參數 | 影響啟動方式 |
| 需要連真實 DB | 外部服務操作 |
| 需要執行 DDL | 修改資料庫 |

## 11. 建議下一步

可以進入「Query Builder / Row Mapper 第一版實作」，但第一步應先讀取程式 repo 結構與現有 schema inspector 程式碼，再提出實作範圍。

若實作前發現需要新增套件、修改 public contract 或改 `.csproj`，必須先停下確認。