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

## 1. 驗證節點摘要

| 項目 | 內容 |
|---|---|
| 驗證節點名稱 | Schema Inspector 抽象介面與 mock inspector 第一版 |
| 驗證日期 | 2026-05-30 |
| 程式 repo | `hs-device-control-template` |
| 實作 commit | `e8fd1b0` |
| 驗證分支 | `poc/nmodbus-tcp` |
| 自動測試結果 | `dotnet test` 通過 286 個測試 |
| 狀態 | 已完成第一版驗證 |

本節點依「Schema Inspector 抽象介面與 mock inspector 實作前確認」執行，只建立抽象介面、mock 實作與單元測試。

## 2. 已完成範圍

| 類型 | 完成內容 |
|---|---|
| 抽象介面 | 新增 `ISchemaInspector` |
| Request model | 新增 `SchemaInspectRequest` |
| Result model | 新增 `SchemaInspectResult` |
| Mock 實作 | 新增 `MockSchemaInspector` |
| Error code | 新增 `SchemaInspectionFailed` |
| 實作紀錄 | 新增程式 repo 文件 `schema-inspector-interface-mock-implementation-record.md` |
| 測試 | 新增 `SchemaInspectorTests` |

## 3. 明確未納入

| 未納入項目 | 說明 |
|---|---|
| `MySqlConnector` | 未新增任何 MySQL 套件 |
| 真實 MySQL 連線 | 未使用 host、port、user、password、dbname |
| `information_schema` 查詢 | 未建立 SQL 查詢 |
| DDL Executor | 未執行 `CREATE TABLE`、`ALTER TABLE`、`DROP` |
| ConsoleHost 啟動自動建表 | 尚未串接 |
| Schema Initializer | 尚未串接 |

## 4. 測試覆蓋

| 測試項目 | 實際驗證 |
|---|---|
| 空 schema snapshot | `MockSchemaInspector.Empty()` 可回傳空 table 清單 |
| 完整 schema snapshot | 可回傳 table、column、index |
| table 篩選 | `ExpectedTables` 可限制回傳 table |
| 隱藏 index/comment | `IncludeIndexes = false`、`IncludeComments = false` 可移除 index/comment |
| 讀取失敗 | `MockSchemaInspector.Failed()` 回傳 `SchemaInspectionFailed` |
| request 為 null | 回傳標準錯誤，不丟未處理 exception |
| Dry Run 缺 column/index | mock snapshot 可驅動 `GenerateDryRunPlan` 產生 `ADD COLUMN` / `ADD INDEX` |
| Dry Run 欄位差異 | mock snapshot 可驅動 `ManualReviewItems` |

## 5. 實際測試結果

執行指令：

```powershell
dotnet test tests\HS.DeviceControl.Core.Tests\HS.DeviceControl.Core.Tests.csproj
dotnet test
```

結果：

| 測試專案 | 通過數 |
|---|---:|
| `HS.DeviceControl.Core.Tests` | 141 |
| `HS.DeviceControl.WorkflowSimulation.Tests` | 11 |
| `HS.DeviceControl.Adapters.Tests` | 108 |
| `HS.DeviceControl.ModbusPoc.Tests` | 26 |
| 合計 | 286 |

執行時仍會出現 `.NET 5.0` 已不受支援的 `NETSDK1138` warning，這是目前專案指定版本的既有限制。

## 6. 實際效果

目前已可以在不接觸真實 MySQL 的情況下，建立目前 schema snapshot，並交給既有 `MySqlSchemaSqlGenerator.GenerateDryRunPlan` 做差異比對。

這代表下一步若要實作真實 `MySqlSchemaInspector`，可以沿用同一個介面與 result model；若要先補更多測試，也可以先用 mock inspector 完成。

## 7. 建議下一步

建議下一步進入：

> `Schema Inspector 與 Dry Run Plan 串接服務設計`

此步驟仍可不導入 MySQL 套件、不連線 DB、不執行 DDL，先整理是否需要一個 `SchemaDryRunPlanner` 類型的服務負責：

- 呼叫 `ISchemaInspector` 取得目前 schema。
- 接收目標 `SchemaDefinition`。
- 呼叫 `MySqlSchemaSqlGenerator.GenerateDryRunPlan`。
- 回傳 plan 與 warnings。