# 5D auth / Swagger 實作工作包

本文件承接 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. 建議實作順序

1. 先新增 options / policy constants，測試預設值與不含正式 secret。
2. 新增最小 authentication handler，只接受測試設定，不連外部 IdP。
3. 在 `Startup.cs` 註冊 auth / authorization，確認 middleware 在 routing 與 endpoints 之間。
4. 對 Tasks、Devices、Schema controller 加 protected policy；health 依最後確認表決策處理。
5. 在 development / local gate 下新增 Swagger setup；production 預設 disabled。
6. 補 WebApi security tests 與 Swagger gate tests。
7. 跑 WebApi.Tests、Application.Tests、solution tests 與停止線掃描。
8. 建立 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. 下一步確認格式

```text
5D auth / Swagger 最小實作前最後確認：
1. 同意
2. 同意
3. 同意
4. 同意
5. 同意
6. 同意
7. 同意
```