# 4B WebApi 第一版實作與 API / DB 驗收紀錄

本文件承接 [4B WebApi contract 草案 / 實作前確認表](phase-four-b-webapi-contract-preimplementation-checklist.md) 與 [4B WebApi 決策確認紀錄](phase-four-b-webapi-decision-confirmation.md)，記錄 4B 最小 WebApi 第一版的實作範圍、API 測試、DB 非破壞性驗收與仍需停止的項目。

本次驗收不代表同意建立 `ServiceHost`、Plugin Loader、外部 DLL 載入、認證授權套件、Swagger、正式部署設定、正式 DB DDL、正式 Apply 或真實硬體控制。

## 0. 驗收狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 已完成 |
| 整理日期 | 2026-06-06 |
| 對應階段 | 第四階段 4B WebApi |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式 commit | `9527773 新增 4B WebApi 第一版與驗收測試` |
| GitHub Actions | `Notify docs repo status` run `27055408505`，completed / success |
| 本次定位 | 最小 WebApi 第一版，負責 HTTP 邊界與 Application contract mapping |
| 本次驗收結論 | 通過；4B WebApi 第一版可作為後續 4C ServiceHost contract 前的 WebApi 基準 |

## 1. 程式實作範圍

| 類型 | 檔案 / 內容 | 說明 |
|---|---|---|
| Solution | `HS.DeviceControl.sln` | 掛入 WebApi 與 WebApi.Tests。 |
| WebApi 專案 | `src/HS.DeviceControl.WebApi/HS.DeviceControl.WebApi.csproj` | `net5.0`，引用 Application / Core / Adapters 作為 host composition root。 |
| 啟動入口 | `Program.cs`、`Startup.cs` | 不加 Swagger / auth / 部署設定；預設使用 in-memory task store、mock device adapter 與 mock schema inspector。 |
| Controllers | `HealthController`、`TasksController`、`DevicesController`、`SchemaController` | 僅處理 HTTP request / response 與 Application service mapping。 |
| API DTO | `TaskStartApiRequest`、`TaskCancelApiRequest`、`SchemaPreviewApiRequest`、`ApiErrorResponse` | 錯誤回應不暴露 exception stack trace 或敏感資訊。 |
| API 測試 | `tests/HS.DeviceControl.WebApi.Tests/WebApiControllerTests.cs` | 使用 fake Application service 驗證 route mapping、HTTP status 與停止線。 |

## 2. 第一版 route 驗收

| Method | Route | 驗收結果 | 備註 |
|---|---|---|---|
| `GET` | `/health` | HTTP `200` | 回傳 Application health 摘要，不含 secret。 |
| `POST` | `/api/tasks` | HTTP `202` | 建立 in-memory task request，回傳 `TaskId` 與 `Queued`。 |
| `GET` | `/api/tasks/{taskId}` | HTTP `200` | 可查回剛建立的 task 狀態。 |
| `GET` | `/api/devices/{deviceId}/status` | HTTP `200` | 使用 mock adapter read-only status，不呼叫 `Execute()`。 |
| `POST` | `/api/schema/preview` | HTTP `200` | 使用 mock inspector 產生 ManualApplyPreview；`canApply=false`、`ddlExecutionAllowed=false`、`ddlExecuted=false`。 |

## 3. 驗證紀錄

| 驗證項目 | 指令 / 方法 | 結果 |
|---|---|---|
| WebApi tests | `dotnet test tests/HS.DeviceControl.WebApi.Tests/HS.DeviceControl.WebApi.Tests.csproj` | Passed：7 passed / 0 failed / 0 skipped。 |
| Solution tests | `dotnet test HS.DeviceControl.sln --no-restore` | Passed：475 passed / 0 failed / 0 skipped。 |
| DB 非破壞性測試 | Solution tests 中 `HS.DeviceControl.Infrastructure.MySql.Tests` | Passed：89 passed；未啟用真實 DB manual gate，未執行 DDL / ALTER / Apply。 |
| 本機 API 啟動 | `dotnet run --no-build --project src/HS.DeviceControl.WebApi -- --urls http://127.0.0.1:5097` | WebApi 可啟動，驗收後已停止背景程序。 |
| Schema preview 安全旗標 | 本機 `POST /api/schema/preview` | 回傳 `canApply=false`、`ddlExecutionAllowed=false`、`ddlExecuted=false`，只產生 SQL preview 字串。 |
| 污染掃描 | `rg` 掃描 source/docs/json/html/txt/log，排除 `bin/obj` | 原始碼與文件範圍未找到污染字串。 |
| diff check | `git diff --check` | 無 whitespace error；僅有 LF/CRLF 提醒。 |
| Push 後 Actions | `gh run list --repo Hongsen-tw/hs-device-control-template --branch poc/nmodbus-tcp` | run `27055408505` completed / success。 |

## 4. DB 驗收邊界

| 分類 | 本次結果 |
|---|---|
| 自動化 DB 相關測試 | 已透過 solution tests 跑過 Infrastructure.MySql 測試 89 筆。 |
| 真實 DB 連線 | 未執行；未要求密碼、Token、IP、Port 或 connection string。 |
| DDL / ALTER / Apply | 未執行；WebApi 只提供 preview endpoint。 |
| Schema preview | 使用 mock inspector；只產生 dry-run / manual preview，不修改資料庫。 |
| 後續真實 DB read-only preview | 仍需另行確認測試 DB、連線資訊、AllowRead 與操作窗口。 |

## 5. 完成判定

| 判定項 | 結果 |
|---|---|
| 4B WebApi 專案建立 | 通過 |
| Route / DTO / error response 第一版 | 通過 |
| API 測試 | 通過 |
| 本機 API 啟動驗收 | 通過 |
| DB 非破壞性驗收 | 通過 |
| ServiceHost 停止線 | 維持，未建立 |
| Plugin Loader 停止線 | 維持，未建立 |
| 正式 DB DDL / Apply 停止線 | 維持，未執行 |

## 6. 剩餘風險與限制

- WebApi 第一版尚未導入 auth、rate limit、Swagger、正式部署設定或正式外網安全模型。
- 任務啟動目前是 in-memory request 建立，不代表背景 workflow runtime 或正式 queue 已完成。
- Device status 使用 mock adapter，不代表已接真實硬體。
- Schema preview 使用 mock inspector；真實 DB read-only preview 仍需另行確認。
- ServiceHost 留到 4C，Plugin Loader 留到 4D；不得因 4B 完成而直接載入外部 DLL 或新增背景服務。

## 7. 建議下一步

建議將本文件 repo stage / commit / push，查 Cloudflare Pages 部署後，再進入 4C ServiceHost contract 草案 / 實作前確認。4C 開始前仍需先確認 ServiceHost lifecycle、啟停方式、Adapter 生命週期、Log / Health / Trace 與部署停止線。