# MySQL Schema Inspector 純程式 helper 實作紀錄

## 1. 文件目的

本文件記錄程式 repo commit `51cb17c` 的實作結果，說明本次完成的 Query Builder、metadata row mapper、snapshot assembler 與測試覆蓋範圍。

本次仍未導入 `MySqlConnector`、未修改 `.csproj`、未連線 MySQL、未讀取真實 `information_schema`，也未執行任何 DDL。

## 2. 實作基準

| 項目 | 內容 |
|---|---|
| 程式 repo | `hs-device-control-template` |
| 分支 | `poc/nmodbus-tcp` |
| commit | `51cb17c` |
| commit 訊息 | 實作 MySQL Schema Inspector 純程式 helper |
| 測試結果 | `dotnet test` 合計 329 個測試通過 |
| 文件同步狀態 | 本文件同步後待發布 |

## 3. 本次新增內容

| 類別 / 檔案 | 類型 | 說明 |
|---|---|---|
| `AssemblyInfo.cs` | assembly metadata | 透過 `InternalsVisibleTo("HS.DeviceControl.Core.Tests")` 讓測試可驗證 internal helper |
| `MySqlSchemaInspectorQueryBuilder` | internal helper | 產生 table / column / index metadata 查詢 |
| `MySqlSchemaQuery` | internal model | 保存 SQL 字串與參數名稱 |
| `MySqlTableMetadataRow` | internal row model | 承接 table metadata |
| `MySqlColumnMetadataRow` | internal row model | 承接 column metadata |
| `MySqlIndexMetadataRow` | internal row model | 承接 index metadata |
| `MySqlSchemaMetadataMapper` | internal mapper | 將 metadata row 轉成 `ColumnDefinition` |
| `MySqlSchemaSnapshotAssembler` | internal assembler | 將 table / column / index row 組成 `SchemaDefinition` |
| `MySqlSchemaSnapshotAssemblyResult` | internal result | 回傳 schema snapshot 與 warning |

## 4. Query Builder 實作重點

目前 query builder 只產生 SQL 字串與參數名稱，不負責開 connection 或執行 SQL。

| Query | 來源 | 重點 |
|---|---|---|
| Table query | `information_schema.TABLES` | 限制 `TABLE_SCHEMA = @DatabaseName`，並排除非 base table |
| Column query | `information_schema.COLUMNS` | 讀取欄位名稱、型別、nullable、primary key、comment 與排序 |
| Index query | `information_schema.STATISTICS` | 讀取 index 名稱、欄位、唯一性與欄位順序 |

table filter 會使用 `@TableName0`、`@TableName1` 這類參數名稱，不直接把 table name 拼進 SQL。

## 5. Metadata Mapper / Assembler 實作重點

| 項目 | 行為 |
|---|---|
| 欄位型別 | 轉為小寫，例如 `VARCHAR(64)` 轉成 `varchar(64)` |
| property name | 由 `snake_case` 轉成 PascalCase，例如 `task_id` 轉成 `TaskId` |
| primary key | 同時支援 column metadata `COLUMN_KEY = PRI` 與 index metadata `PRIMARY` |
| required | `IS_NULLABLE = NO` 或 primary key 會視為 required |
| comment | 可依 `includeComments` 開關保留或隱藏 |
| index | 排除 `PRIMARY` index，一般 index 依 `SEQ_IN_INDEX` 排序 |
| warning | column / index 指到不存在 table 或 column 時，回傳 warning，不直接執行破壞性動作 |

## 6. 測試覆蓋

| 測試檔 | 覆蓋重點 |
|---|---|
| `MySqlSchemaInspectorQueryBuilderTests` | database 參數、table filter 參數化、穩定排序、不產生 DDL |
| `MySqlSchemaMetadataMapperTests` | 欄位名稱、型別、required、primary key、comment mapping |
| `MySqlSchemaSnapshotAssemblerTests` | schema snapshot 組裝、index 排序、missing table warning、missing column warning、include switches |

## 7. 實際效果

本次完成後，程式 repo 已具備「不連 DB」的真實 MySQL metadata 解析前置能力。

也就是說，下一步若導入 `MySqlConnector`，主要會新增：

1. connection / command 執行層。
2. 將 `DbDataReader` 或查詢結果轉成目前已建立的 metadata row。
3. 將 `MySqlSchemaSnapshotAssembler` 輸出接回 `SchemaInspectResult`。

既有 `ISchemaInspector` contract 暫時不需要改。

## 8. 仍未完成

| 項目 | 狀態 |
|---|---|
| `MySqlConnector` 套件導入 | 尚未開始，需另行確認 |
| 真實 DB connection string | 尚未建立，需另行確認 |
| 實際讀取 MySQL 5.6.2 `information_schema` | 尚未執行 |
| ConsoleHost 真實 schema inspect 入口 | 尚未建立 |
| Apply / DDL executor | 尚未設計與實作 |

## 9. 建議下一步

建議下一步先做「MySqlSchemaInspector 真實 DB provider 實作前確認」，明確列出：

1. 是否允許新增 `MySqlConnector`。
2. 連線資訊來源與 Secret 規則。
3. 第一版只做 read-only inspect，不做 apply。
4. 真實 DB 人工驗證節點如何執行。

未確認前，不應直接新增套件、修改 `.csproj`、連線 DB 或讀取真實 metadata。