SchemaDryRunPlanner ConsoleHost 顯示第一版實作紀錄

基本資訊

• 日期：2026-05-30
• repo：hs-device-control-template
• branch：poc/nmodbus-tcp
• 程式 commit：c09da28
• 類型：第二階段資料庫 Schema 自動化前導實作
• 範圍：ConsoleHost 顯示層、mock dry run 預覽、格式化測試

實作目標

本次目標是讓 ConsoleHost 可以顯示 SchemaDryRunPlanner 的 dry run 結果，讓後續進入 Schema Initializer 前，可以先用人工方式確認：

• 預計建立的 table 數量。
• 預計補上的 column 數量。
• 預計補上的 index 數量。
• 需要人工審查的 schema 差異。
• SQL preview 是否只停留在預覽，不直接執行。
• warning 與失敗訊息是否能被使用者看懂。

實作內容

ConsoleHost 顯示

新增 Program.FormatSchemaDryRunResult，統一將 dry run result 轉成 ConsoleHost 可輸出的文字列。

顯示內容包含：

• Schema dry run: 或 Schema dry run failed:
• Mode
• Success
• TablesToCreate
• ColumnsToAdd
• IndexesToAdd
• ManualReview
• SQL preview
• Manual review
• Warnings
• 錯誤時的 ErrorCode 與 Message

Mock 預覽資料

ConsoleHost 第一版只使用 MockSchemaInspector.Empty() 產生預覽結果。

此設計刻意保留在安全邊界內：

• 不連線 MySQL。
• 不讀取 information_schema。
• 不執行 DDL（包含 CREATE TABLE、ALTER TABLE 或其他資料庫結構變更）。
• 不新增 MySQL 套件。
• 不改變 ConsoleHost 啟動參數。

測試補強

新增 ConsoleHostSchemaDryRunDisplayTests，覆蓋以下顯示情境：

• 空資料庫 snapshot 產生 CREATE TABLE preview。
• 已有 table 但缺 column / index 時顯示 ADD COLUMN 與 ADD INDEX preview。
• 欄位型別不一致時顯示 manual review。
• inspector warning 會被保留並輸出。
• inspector 失敗時顯示標準錯誤碼與訊息。
• null result 會輸出空結果提示。

驗證結果

已執行：

dotnet test tests\HS.DeviceControl.ModbusPoc.Tests\HS.DeviceControl.ModbusPoc.Tests.csproj
dotnet test
dotnet run --project src\HS.DeviceControl.ConsoleHost

結果：

• ConsoleHost / ModbusPoc 測試通過：32
• 全專案測試通過：303
• 失敗：0
• 略過：0
• ConsoleHost 實際輸出可看到 Schema dry run:、SQL preview:、CREATE TABLE IF NOT EXISTS task_executions 與 Dry Run warning。

備註：

• 仍會出現既有 .NET 5.0 EOL 警告。
• 本次 ConsoleHost 實跑沒有連線 MySQL，也沒有執行 DDL。

影響範圍

本次影響：

• HS.DeviceControl.ConsoleHost
• HS.DeviceControl.ModbusPoc.Tests
• 文件紀錄

未影響：

• Core schema 計算規則。
• MySQL 連線。
• 套件選型。
• public method 簽章。
• 專案啟動方式。
• 真實資料庫初始化流程。

限制與後續

目前仍屬於顯示第一版，尚未連接正式 Schema Initializer。

建議下一步：

1. 補一份 ConsoleHost Schema Dry Run 顯示人工驗證紀錄。
2. 進入 Schema Initializer DryRun 流程設計。
3. 設計 DB 連線資訊檢查與權限不足時的錯誤呈現方式。