# ManualApplyPreview 第一版實作紀錄

## 1. 文件定位

本文件記錄第三階段 3B `ManualApplyPreview` 第一版實作結果，用於同步文件 repo 與程式 repo 目前進度。

此節點只完成「人工 Apply 前安全預覽」，不代表已開放正式 DB Apply，也不代表允許自動執行 DDL。

## 2. 對應程式 commit

| 項目 | 內容 |
|---|---|
| 程式 repo | `hs-device-control-template` |
| 分支 | `poc/nmodbus-tcp` |
| commit | `13c14ca` |
| commit 訊息 | `新增 ManualApplyPreview 安全預覽` |
| 日期 | 2026-06-04 |

## 3. 已完成內容

| 類別 | 完成項目 |
|---|---|
| Core model | 新增 `SchemaManualApplyPreviewRequest`、`SchemaManualApplyPreviewResult`、`SchemaManualApplyPreviewItem`、`SchemaManualApplyPreviewRiskLevel`。 |
| Preview builder | 新增 `SchemaManualApplyPreviewBuilder`，將 migration plan 轉成安全預覽結果。 |
| 安全欄位 | 預覽結果包含 `PlanHash`、`CanApply`、`Blocked`、`RiskLevel`、`Summary`、`GeneratedAtUtc`。 |
| 風險分級 | 支援 `Low`、`Medium`、`High`、`Critical`，未知或危險 SQL 會升級風險。 |
| Apply 限制 | 第一版固定 `CanApply = false`，只允許人工檢視，不提供正式 Apply。 |
| ConsoleHost | `schema-dry-run` 輸出新增 ManualApplyPreview 摘要、風險、阻擋狀態與 SQL preview。 |
| Manual runner | 新增 manual-only read-only 驗證腳本，需明確設定環境變數才會讀取真實 MySQL，不會執行 DDL。 |

## 4. 驗證結果

| 驗證項目 | 結果 |
|---|---|
| Core `SchemaManualApplyPreviewBuilderTests` | 9 passed |
| ConsoleHost `ConsoleHostSchemaDryRunDisplayTests` | 15 passed |
| MySQL manual-only gate 測試 | 1 passed |
| ConsoleHost `dotnet run` | 成功輸出 `PlanHash`、`CanApply=False`、`Risk=Low`、`Blocked=False` 與 SQL preview |
| 污染字串掃描 | 未找到污染字串 |
| 舊命名掃描 | 未找到 `SafeCreate`、`SafeAddColumn`、`MediumAddIndex`、`ManualReviewRequired`、`CanExecuteAutomatically`、`AutoExecute` |

## 5. 本次未執行事項

- 未連線正式 DB。
- 未執行 DDL。
- 未建立 schema history table。
- 未開放 `CanApply = true`。
- 未新增自動 Apply、rollback、WebApi、UI 或 ServiceHost。

## 6. 停止線

後續若要進入真實 DB read-only preview 驗證，需另行確認：

- MySQL 連線資訊與密碼環境變數。
- `AllowRead` 類型開關。
- 驗證目標只允許讀取 schema，不得執行 DDL。

後續若要進入正式 Apply，需另行確認新的 3B/3C 決策，不得由本次實作直接延伸。

## 7. 建議下一步

建議先整理「3B 完成稽核表」，確認第一版 ManualApplyPreview 是否滿足 3B 驗收條件；若要進一步驗證真實 DB，也應另行建立 read-only 驗證節點。