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

本文件承接 [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 auth / Swagger 實作前文件線上驗收紀錄](phase-five-d-auth-swagger-preimplementation-online-acceptance-record.md)。

5D 是 WebApi 安全邊界節點，會影響 API 存取、Swagger 暴露面、測試憑證、production 預設行為與部署安全。因此本文件是進入程式 repo 修改前的最後確認 gate；未完成七項確認前，不得修改 WebApi 程式。

## 0. 文件狀態

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

## 1. 最小實作範圍

| 範圍 | 最小版本決策 |
|---|---|
| Auth gate | 只建立可測試的最小 WebApi auth gate，不接外部 IdP。 |
| Credential | 只使用測試 / local 用非正式設定，不把正式 key、password、client secret 或 production secret 寫入 repo。 |
| Protected API | Tasks、Devices、Schema 等既有操作 / 查詢 API 需受保護，route 語意不得改變。 |
| Health | `/health` 是否匿名需明確測試與文件化。 |
| Swagger | 若導入 Swagger，只允許 development / local gate；production 預設 disabled。 |
| Tests | 需新增 WebApi auth / Swagger tests，並保留既有 WebApi controller tests。 |
| 文件 | 完成後需補實作紀錄、驗收紀錄、README / status / progress / public mirror 與線上驗收。 |

## 2. 最後七項確認

| 編號 | 確認項 | 同意內容 |
|---|---|---|
| 1 | 最小 auth gate | 同意 5D 第一批只建立可測試的最小 WebApi auth gate，不導入 JWT / OAuth / OIDC / 外部 IdP。 |
| 2 | Credential 安全 | 同意 repo 不保存正式 API key、password、client secret、production secret、正式 IP、正式網域或正式帳號。 |
| 3 | Controller 保護 | 同意既有 tasks、devices、schema API 以最小方式加上保護，不修改既有 route 與 Application result mapping。 |
| 4 | Health 決策 | 同意 `/health` 的匿名或授權策略必須在測試與文件中明確固定。 |
| 5 | Swagger gate | 同意 Swagger 只能 development / local 可用，production 預設 disabled 並有測試證據。 |
| 6 | 測試與停止線 | 同意實作後執行 WebApi tests、Application tests、solution tests、停止線掃描、污染掃描與 commit 前檢查。 |
| 7 | 排除項目 | 同意本批不做 DB DDL、正式 DB 寫入、Windows Service、外部 DLL 載入、plugin folder 掃描、Adapter public contract、正式部署設定或 GitHub / Cloudflare secret 設定。 |

## 3. 程式候選檔案

| 類型 | 候選檔案 |
|---|---|
| Auth options / constants | `src/HS.DeviceControl.WebApi/Security/` |
| Auth handler / gate | `src/HS.DeviceControl.WebApi/Security/` |
| Startup pipeline | `src/HS.DeviceControl.WebApi/Startup.cs` |
| Controller attributes | `src/HS.DeviceControl.WebApi/Controllers/*.cs` |
| Swagger setup | `src/HS.DeviceControl.WebApi/HS.DeviceControl.WebApi.csproj`、`Startup.cs` |
| WebApi tests | `tests/HS.DeviceControl.WebApi.Tests` |

若實作時需要新增核心套件、改 route、改 public contract、接外部 IdP、保存正式 secret、修改部署設定或調整 GitHub / Cloudflare 設定，需停下重新確認。

## 4. 必要驗收

| 驗收項目 | 預期 |
|---|---|
| Missing credential | Protected API 回 401。 |
| Invalid credential | Protected API 回 401，且不回顯 credential。 |
| Valid test credential | 既有 API 可成功呼叫，既有 result mapping 不變形。 |
| Health policy | `/health` 匿名或授權策略有明確測試。 |
| Swagger development | Development / local gate 可測。 |
| Swagger production | Production 預設 disabled。 |
| Stop-line scan | 未保存正式 secret，未新增 DB DDL、Windows Service install、外部 DLL loading 或 plugin folder scan。 |

## 5. 建議回覆格式

若同意進入 5D 最小 WebApi auth / Swagger 程式實作，請回覆：

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

## 6. 未確認前停止線

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