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，主要會新增：
- connection / command 執行層。
- 將
DbDataReader或查詢結果轉成目前已建立的 metadata row。 - 將
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 實作前確認」，明確列出：
- 是否允許新增
MySqlConnector。 - 連線資訊來源與 Secret 規則。
- 第一版只做 read-only inspect，不做 apply。
- 真實 DB 人工驗證節點如何執行。
未確認前，不應直接新增套件、修改 .csproj、連線 DB 或讀取真實 metadata。