4B WebApi 第一版實作與 API / DB 驗收紀錄
本文件承接 4B WebApi contract 草案 / 實作前確認表 與 4B WebApi 決策確認紀錄，記錄 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 與部署停止線。