# 5D auth / Swagger 實作測試案例與停止線稽核表

本文件承接 [5D auth / Swagger 邊界分析](phase-five-d-auth-swagger-boundary-analysis.md)、[5D auth / Swagger 實作前確認表](phase-five-d-auth-swagger-preimplementation-checklist.md) 與 [5D auth / Swagger 程式 repo 結構檢查與實作前盤點](phase-five-d-auth-swagger-code-structure-preimplementation-checklist.md)。

此表只整理 5D 第一批程式實作後應驗證的測試案例、掃描項目與驗收證據。本文件建立時尚未修改程式 repo；後續已依使用者七項確認完成 5D 程式實作與驗收。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 歷史前置文件；5D 已於 `c92342b` 完成實作與驗收 |
| 建立日期 | 2026-06-07 |
| 對應節點 | 第五階段 5D auth / Swagger |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式基準 | 本文件建立時為 `354fecd`；後續實作完成基準為 `c92342b` |
| 是否授權程式修改 | 已取得 5D 七項確認並完成實作；本文件本身不再授權新修改 |

## 1. 5D 第一批建議實作範圍

| 類型 | 預計檔案 | 驗收重點 |
|---|---|---|
| Auth options | `src/HS.DeviceControl.WebApi/Security/WebApiAuthOptions.cs` | safe default、不保存正式 secret。 |
| Auth handler / gate | `src/HS.DeviceControl.WebApi/Security/` | 缺少或錯誤 credential 回 401，不暴露 credential。 |
| Policy | `src/HS.DeviceControl.WebApi/Security/WebApiPolicies.cs` | role / policy 名稱集中，避免案場客製。 |
| Startup | `src/HS.DeviceControl.WebApi/Startup.cs` | pipeline 順序正確，Swagger dev-only。 |
| Controller attributes | `src/HS.DeviceControl.WebApi/Controllers/*.cs` | protected / anonymous 邊界清楚，不改 route。 |
| Tests | `tests/HS.DeviceControl.WebApi.Tests` | 401、403、success、health、Swagger gate、停止線。 |

本批不保存正式 secret、不改正式部署設定、不新增 DB / Service / DLL 邊界。

## 2. 必要測試案例

| # | 測試主題 | 建議測試名稱 | 預期結果 |
|---:|---|---|---|
| 1 | protected API 缺 credential | `ProtectedApi_ShouldReturnUnauthorizedWhenCredentialMissing` | 401，無 stack trace / secret。 |
| 2 | protected API 錯 credential | `ProtectedApi_ShouldReturnUnauthorizedWhenCredentialInvalid` | 401，不回顯 credential。 |
| 3 | protected API 合法 credential | `ProtectedApi_ShouldAllowValidTestCredential` | 成功呼叫既有 controller，Application result 不變。 |
| 4 | 權限不足 | `SchemaPreview_ShouldReturnForbiddenWhenPolicyMissing` | 403，錯誤格式可追蹤。 |
| 5 | Health 策略 | `Health_ShouldFollowAnonymousOrProtectedDecision` | 與 5D 決策一致，且不暴露敏感資料。 |
| 6 | Swagger development | `Swagger_ShouldBeAvailableInDevelopmentOnlyWhenEnabled` | development / local gate 可用。 |
| 7 | Swagger production | `Swagger_ShouldBeDisabledInProduction` | production 不提供 Swagger UI / JSON。 |
| 8 | Swagger auth | `Swagger_ShouldNotBypassApiAuthGate` | Swagger 不應讓 protected API 免授權。 |
| 9 | Secret stop-line | `WebApiSecurity_ShouldNotPersistProductionSecrets` | 無正式 secret、token、正式 IP / URL。 |
| 10 | route 不變 | `WebApiSecurity_ShouldNotChangeExistingRoutes` | 既有 route 語意不變。 |

## 3. 必跑測試命令

| 驗證項目 | 命令 | 預期 |
|---|---|---|
| WebApi tests | `dotnet test tests\HS.DeviceControl.WebApi.Tests\HS.DeviceControl.WebApi.Tests.csproj --no-restore` | 全部通過，需包含 5D tests。 |
| Application tests | `dotnet test tests\HS.DeviceControl.Application.Tests\HS.DeviceControl.Application.Tests.csproj --no-restore` | 全部通過。 |
| Solution tests | `dotnet test HS.DeviceControl.sln --no-restore` | 全 solution 通過。 |
| Commit 前檢查 | `git diff --check` 與 `git diff --cached --check` | 無 whitespace / patch 格式問題。 |

## 4. 停止線掃描

| 停止線 | 掃描方向 | 不得出現 |
|---|---|---|
| Secret / credential | 5D 新增 / 修改檔案 | 正式 API key、JWT secret、OAuth secret、token、正式 IP、正式 URL、正式帳號。 |
| Production Swagger | `Startup.cs`、config、tests | production 預設啟用 Swagger UI / JSON。 |
| Auth bypass | controller / tests | protected API 無授權即可改變或查詢敏感狀態。 |
| DB / schema | 5D 變更 | DB DDL、ALTER TABLE、formal Apply、真實 DB 寫入。 |
| Windows Service | 5D 變更 | Service installer、`UseWindowsService`、`sc.exe`。 |
| External DLL | 5D 變更 | `Assembly.Load`、`LoadFrom`、`LoadFile`、plugin folder scan。 |

## 5. 驗收證據

5D 第一批實作完成後，至少需在驗收紀錄中保留：

- 修改檔案清單。
- WebApi tests、Application tests 與 solution tests 結果。
- auth / Swagger 停止線掃描結果。
- 污染字串掃描結果。
- 程式 repo `git status`、commit、push 與 Actions run。
- 文件 repo 實作與驗收紀錄、commit、push 與線上查驗。

## 6. 建議確認格式

若要進入 5D 第一批程式實作，請先回覆：

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

確認後可開始 WebApi auth / Swagger 第一批實作；正式部署設定、真實 secret、外部 IdP、DB DDL、Windows Service 與外部 DLL 仍需後續獨立確認。