# 5D auth / Swagger 實作與驗收紀錄

本文件記錄第五階段 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 | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式基準 commit | `354fecd` |
| 程式 commit | `c92342b` |
| Commit 訊息 | 新增 5D WebApi auth 與 Swagger gate |
| GitHub Actions | `27094590136` success |
| 文件狀態 | 第一批實作、提交、推送與 Actions 驗收紀錄已建立 |

## 1. 程式修改範圍

| 類別 | 檔案 |
|---|---|
| Auth options | `src/HS.DeviceControl.WebApi/Security/WebApiAuthOptions.cs` |
| Auth policy | `src/HS.DeviceControl.WebApi/Security/WebApiPolicies.cs` |
| Auth handler | `src/HS.DeviceControl.WebApi/Security/ApiKeyAuthenticationHandler.cs` |
| Startup | `src/HS.DeviceControl.WebApi/Startup.cs` |
| Controller protection | `src/HS.DeviceControl.WebApi/Controllers/TasksController.cs` |
| Controller protection | `src/HS.DeviceControl.WebApi/Controllers/DevicesController.cs` |
| Controller protection | `src/HS.DeviceControl.WebApi/Controllers/SchemaController.cs` |
| Health boundary | `src/HS.DeviceControl.WebApi/Controllers/HealthController.cs` |
| Swagger package | `src/HS.DeviceControl.WebApi/HS.DeviceControl.WebApi.csproj` |
| WebApi tests | `tests/HS.DeviceControl.WebApi.Tests/WebApiTestHost.cs` |
| WebApi tests | `tests/HS.DeviceControl.WebApi.Tests/WebApiSecurityTests.cs` |
| WebApi tests | `tests/HS.DeviceControl.WebApi.Tests/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 邊界。 |
| Test host | 新增本機 loopback WebApi test host，驗證實際 HTTP pipeline。 |

## 3. 測試與驗收結果

| 驗證項目 | 結果 |
|---|---|
| `dotnet restore tests\HS.DeviceControl.WebApi.Tests\HS.DeviceControl.WebApi.Tests.csproj --disable-parallel` | 通過；首次 sandbox 內受 NuGet scratch lock 擋住，改 sandbox 外執行成功。 |
| `dotnet test tests\HS.DeviceControl.WebApi.Tests\HS.DeviceControl.WebApi.Tests.csproj --no-restore -m:1 /p:BuildInParallel=false /p:UseSharedCompilation=false` | 17 passed / 0 failed / 0 skipped。 |
| `dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj --no-restore -m:1 /p:BuildInParallel=false /p:UseSharedCompilation=false` | 67 passed / 0 failed / 0 skipped。 |
| `dotnet test HS.DeviceControl.sln --no-restore -m:1 /p:BuildInParallel=false /p:UseSharedCompilation=false` | 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. 停止線確認

本次 5D 實作沒有做下列事項：

- 不導入 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、不使用 `Assembly.Load` / `LoadFrom` / `LoadFile`。
- 不修改 Adapter public contract。

## 5. 驗收結論

5D auth / Swagger 第一批實作已在核准範圍內完成，並通過 WebApi、Application、solution 測試與 GitHub Actions。下一步可同步文件 repo stage / commit / push，並在文件網站部署成功後進入 5E Windows Service 最小實作前確認與實作。