本文件記錄第五階段 5D auth / Swagger 第一批程式實作、測試、停止線、提交、推送與 Actions 驗收。5D 僅完成 WebApi 邊界的最小 API key gate、protected controller policy、development-only Swagger 與測試；沒有導入 JWT / OAuth / OIDC / 外部 IdP，沒有保存正式 secret，沒有變更既有 API route，也沒有修改 DB、Windows Service、外部 DLL 或 Adapter contract。
0. 基本資訊
| 驗收日期 | 2026-06-07 |
|---|---|
| 對應節點 | 第五階段 5D auth / Swagger |
| 程式 repo / branch | hs-device-control-template / poc/nmodbus-tcp |
| 程式基準 commit | 354fecd |
| 程式 commit | c92342b |
| Commit 訊息 | 新增 5D WebApi auth 與 Swagger gate |
| GitHub Actions | 27094590136 success |
| 文件狀態 | 第一批實作與提交、推送與 Actions 驗收紀錄已建立 |
1. 程式修改範圍
| 類別 | 檔案 |
|---|---|
| Auth options / policy / handler | src/HS.DeviceControl.WebApi/Security/* |
| Startup | src/HS.DeviceControl.WebApi/Startup.cs |
| Controller protection | TasksController.cs、DevicesController.cs、SchemaController.cs |
| Health boundary | HealthController.cs |
| Swagger package | HS.DeviceControl.WebApi.csproj |
| WebApi tests | WebApiTestHost.cs、WebApiSecurityTests.cs、SwaggerGateTests.cs |
2. 實作內容
| 項目 | 結果 |
|---|---|
| API key options | 新增 WebApiAuthOptions，預設啟用驗證，正式 key 必須由外部設定注入。 |
| Authentication handler | 新增最小 API key handler，缺少或錯誤 key 回 401，不回顯 credential。 |
| Authorization policy | 新增 WebApiProtectedEndpoint，集中保護 Tasks、Devices、Schema controller。 |
| Health endpoint | HealthController 明確標記 AllowAnonymous。 |
| Swagger | 新增 Swashbuckle 5.6.3，僅在 Development pipeline 啟用 Swagger JSON / UI。 |
| Route | 未修改既有 route；授權只套在 WebApi 邊界。 |
3. 測試與驗收結果
| 驗證項目 | 結果 |
|---|---|
| WebApi.Tests | 17 passed / 0 failed / 0 skipped |
| Application.Tests | 67 passed / 0 failed / 0 skipped |
| Solution tests | 536 passed / 0 failed / 0 skipped |
| Auth gate | 未帶 API key 回 401，錯誤 API key 回 401，正確測試 key 可進入既有 Application result。 |
| Health gate | 未帶 API key 呼叫 /health 回 200。 |
| Swagger gate | Development 可取得 /swagger/v1/swagger.json，Production 回 404。 |
| 停止線掃描 | 未命中 DB DDL、Windows Service、外部 DLL loading、JWT / OAuth / OIDC / Bearer、password / secret。 |
| 污染字串掃描 | 程式 repo AGENTS.md、README.md、docs 指定文字檔範圍未命中八項污染字串。 |
| 程式 repo commit / push | c92342b 已推送至 poc/nmodbus-tcp。 |
| GitHub Actions | 27094590136 completed success。 |
備註：solution 測試仍有既有 .NET 5.0 EOL warning，與本次 5D 修改無關。
4. 停止線確認
- 不導入 JWT、OAuth、OIDC、OpenId、Bearer token 或外部 IdP。
- 不保存正式 API key、password、client secret、token、正式 IP、正式 URL 或正式帳號。
- 不變更既有 API route 或 Application result mapping。
- 不新增 DB DDL、ALTER TABLE、DROP TABLE、formal Apply 或正式 DB 寫入。
- 不新增 Windows Service package、
UseWindowsService、service installer 或安裝腳本。 - 不載入外部 DLL，不掃描 plugin folder，不修改 Adapter public contract。
5. 驗收結論
5D auth / Swagger 第一批實作已在核准範圍內完成，並通過 WebApi、Application、solution 測試與 GitHub Actions。下一步可同步文件 repo stage / commit / push，並在文件網站部署成功後進入 5E Windows Service 最小實作前確認與實作。