本文件承接 5D auth / Swagger 邊界分析、實作前確認表、程式 repo 結構檢查、測試矩陣、最後確認表與最後確認表線上驗收紀錄。此工作包只整理確認後的施作順序與驗收證據，不代表已授權修改程式；在使用者回覆 5D 最後七項確認前，不得新增 WebApi auth / Swagger 程式碼。
0. 基本資訊
| 文件日期 | 2026-06-07 |
|---|---|
| 對應節點 | 第五階段 5D auth / Swagger |
| 程式 repo | hs-device-control-template |
| 程式 branch | poc/nmodbus-tcp |
| 程式基準 commit | 354fecd |
| 本文件是否授權程式修改 | 否；仍需使用者回覆 5D 最後七項確認 |
| 本輪 gate 前測試 | WebApi.Tests 7 passed / 0 failed / 0 skipped |
1. 施作前置條件
| 前置條件 | 目前狀態 |
|---|---|
| 5D 最後確認表 | 已建立 |
| 5D 最後確認表線上驗收 | 已完成 |
| 第五階段剩餘 gate 稽核 | 已建立 |
| WebApi 現況測試 | dotnet test tests\HS.DeviceControl.WebApi.Tests\HS.DeviceControl.WebApi.Tests.csproj --no-restore 通過 |
| 程式 repo 狀態 | 目前乾淨，仍停在 354fecd |
2. 確認後預計修改檔案
| 類型 | 檔案 | 目的 |
|---|---|---|
| 新增 | src/HS.DeviceControl.WebApi/Security/WebApiAuthOptions.cs | 定義最小 auth gate 設定，預設關閉，不保存正式 secret |
| 新增 | src/HS.DeviceControl.WebApi/Security/WebApiPolicies.cs | 固定 protected API policy 與 health / swagger gate 命名 |
| 新增 | src/HS.DeviceControl.WebApi/Security/ApiKeyAuthenticationHandler.cs | 提供測試用 credential gate，回傳 401，不接外部 IdP |
| 修改 | src/HS.DeviceControl.WebApi/Startup.cs | 註冊 authentication / authorization，並固定 middleware 順序 |
| 修改 | src/HS.DeviceControl.WebApi/Controllers/TasksController.cs | 標記 protected API，不變更 route |
| 修改 | src/HS.DeviceControl.WebApi/Controllers/DevicesController.cs | 標記 protected API，不變更 route |
| 修改 | src/HS.DeviceControl.WebApi/Controllers/SchemaController.cs | 標記 protected API，不變更 route |
| 修改 | src/HS.DeviceControl.WebApi/Controllers/HealthController.cs | 保留 health gate 決策，不偷渡正式監控設定 |
| 視套件確認後修改 | src/HS.DeviceControl.WebApi/HS.DeviceControl.WebApi.csproj | 只在確認後新增 Swagger package；不得新增其他核心套件 |
| 新增 | tests/HS.DeviceControl.WebApi.Tests/WebApiSecurityTests.cs | 驗證 missing / invalid / valid credential、policy、health 與 route 不變 |
| 新增 | tests/HS.DeviceControl.WebApi.Tests/SwaggerGateTests.cs | 驗證 development 可開、production disabled |
3. 建議實作順序
- 先新增 options / policy constants，測試預設值與不含正式 secret。
- 新增最小 authentication handler，只接受測試設定，不連外部 IdP。
- 在
Startup.cs註冊 auth / authorization，確認 middleware 在 routing 與 endpoints 之間。 - 對 Tasks、Devices、Schema controller 加 protected policy；health 依最後確認表決策處理。
- 在 development / local gate 下新增 Swagger setup；production 預設 disabled。
- 補 WebApi security tests 與 Swagger gate tests。
- 跑 WebApi.Tests、Application.Tests、solution tests 與停止線掃描。
- 建立 5D 實作與驗收紀錄，更新文件 repo 與 public mirror。
4. 必跑測試與驗證
| 驗證項目 | 指令或方式 | 通過條件 |
|---|---|---|
| WebApi tests | dotnet test tests\HS.DeviceControl.WebApi.Tests\HS.DeviceControl.WebApi.Tests.csproj --no-restore | auth / Swagger 新舊測試全部通過 |
| Application tests | dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj --no-restore | Application contract 不受影響 |
| Solution tests | dotnet test HS.DeviceControl.sln --no-restore | 全 solution 測試通過 |
| Route 不變 | 比對既有 controller route 與 tests | 不新增或改名既有 public route |
| Production Swagger disabled | 測試 production 環境 | Swagger UI / JSON 不可開啟 |
| Secret 掃描 | 掃描 src、tests、samples、docs | 不得出現正式 API key、password、token、IP、正式 URL |
| 停止線掃描 | 掃描 DB DDL、Windows Service、external DLL loading、plugin folder scan | 均不得命中新增實作 |
5. 不可包含項目
- 不接 JWT / OAuth / OIDC / 外部 IdP。
- 不保存正式 API key、password、client secret、token、正式 IP、正式 URL。
- 不變更既有 API route。
- 不新增 DB DDL、ALTER TABLE、formal Apply 或正式 DB 初始化。
- 不新增 Windows Service package、
UseWindowsService、service installer 或安裝腳本。 - 不載入外部 DLL、不掃描 plugin folder、不使用
Assembly.Load/LoadFrom/LoadFile。 - 不修改 Adapter public contract。
- 不修改 GitHub / Cloudflare secret 或部署權限設定。
6. 5D 實作完成後應建立的文件
| 文件 | 目的 |
|---|---|
phase-five-d-auth-swagger-implementation-acceptance-record.md | 記錄 5D 實作內容、測試結果、停止線掃描與 commit |
phase-five-d-auth-swagger-online-acceptance-record.md | 記錄文件網站線上驗收、首頁入口、status.json 與 progress.json |
phase-five-remaining-gate-completion-audit.md 更新版 | 將 5D 從待實作改為已完成，並更新 5E / 5F 進入條件 |
7. 下一步確認格式
5D auth / Swagger 最小實作前最後確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意