# 5D auth / Swagger 實作前確認表

本文件承接 [5D auth / Swagger 邊界分析](phase-five-d-auth-swagger-boundary-analysis.md)。5D 涉及 API 權限、Swagger 暴露面、secret 管理與正式部署風險，因此本確認表必須在任何程式 repo 修改前完成。

## 0. 文件狀態

| 項目 | 內容 |
|---|---|
| 文件狀態 | 待確認 |
| 建立日期 | 2026-06-07 |
| 對應節點 | 第五階段 5D auth / Swagger |
| 程式 repo | `hs-device-control-template` |
| 程式 branch | `poc/nmodbus-tcp` |
| 程式基準 | `354fecd` |
| 本文件是否授權程式修改 | 尚未；需等待使用者回覆七項皆同意 |

## 1. 實作前七項確認

| 編號 | 確認項 | 建議決策 |
|---|---|---|
| 1 | 實作範圍 | 同意 5D 第一批只處理 WebApi auth / Swagger 的最小安全邊界、測試與文件，不修改正式部署設定。 |
| 2 | Auth 模型 | 同意先採可測試的最小 API gate；JWT / OAuth / OIDC / 外部 IdP 延後到另行確認。 |
| 3 | Secret 停止線 | 同意 repo 不保存正式 API key、token、JWT secret、client secret、正式 IP、正式網域或正式帳號。 |
| 4 | API 保護範圍 | 同意 tasks、devices、schema 等操作 / 查詢 API 需授權；`/health` 是否匿名需在實作時明確測試。 |
| 5 | Swagger 停止線 | 同意 Swagger 若導入，只允許 development / local gate；production 預設 disabled，不作正式外網入口。 |
| 6 | 測試與驗收 | 同意實作後至少執行 WebApi tests、Application tests、solution tests、auth / Swagger 停止線掃描、污染字串掃描與 commit 前檢查。 |
| 7 | 排除項目 | 同意 5D 不做 DB DDL / formal Apply、Windows Service、外部 DLL 載入、plugin folder 掃描、Adapter public contract 或正式部署權限設定。 |

## 2. 候選變更檔案

| 類型 | 候選檔案 |
|---|---|
| Auth options / constants | `src/HS.DeviceControl.WebApi/Security/` |
| Auth middleware / handler | `src/HS.DeviceControl.WebApi/Security/` |
| Startup pipeline | `src/HS.DeviceControl.WebApi/Startup.cs` |
| Controller attributes | `src/HS.DeviceControl.WebApi/Controllers/*.cs` |
| Swagger package / setup | `src/HS.DeviceControl.WebApi/HS.DeviceControl.WebApi.csproj`、`Startup.cs`，需確認後才可新增套件 |
| WebApi tests | `tests/HS.DeviceControl.WebApi.Tests` |

若實作時發現必須新增正式 secret、修改 API route、導入外部 IdP、新增 Swagger 正式部署入口、修改 GitHub / Cloudflare 設定或新增高風險套件，需停下重新確認。

## 3. 驗收條件

| 項目 | 驗收方式 |
|---|---|
| 未授權 | 測試缺少 credential 時 protected API 回 401。 |
| 錯誤 credential | 測試錯誤 credential 不得通過，且不暴露 secret。 |
| 權限不足 | 若有 policy / role，測試權限不足回 403。 |
| 成功流程 | 合法測試 credential 可呼叫既有 API，既有 Application result 不變形。 |
| Health | 明確測試 `/health` 的匿名或授權策略。 |
| Swagger | Development / local gate 可測；production disabled 可測。 |
| 停止線 | 掃描確認未保存 secret、未開 production Swagger、未新增 DB / Service / DLL 邊界。 |

## 4. 建議回覆格式

若同意進入 5D 第一批 WebApi auth / Swagger 程式實作，建議回覆：

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

## 5. 未確認前停止線

在使用者完成七項確認前，不得修改程式 repo，不得新增 auth middleware、Swagger 套件、controller `[Authorize]`、production Swagger 設定、正式 secret、正式部署設定，也不得新增 WebApi route 或改既有 route 語意。