# 5D auth / Swagger 程式 repo 結構檢查與實作前盤點

本文件承接 [5D auth / Swagger 邊界分析](phase-five-d-auth-swagger-boundary-analysis.md) 與 [5D auth / Swagger 實作前確認表](phase-five-d-auth-swagger-preimplementation-checklist.md)。

本文件只記錄程式 repo 唯讀檢查、候選修改位置、測試基準與停止線。本文件建立時尚未修改程式 repo；後續已依使用者七項確認完成 5D 程式實作與驗收。

## 0. 文件狀態

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

## 1. 現有 WebApi 結構

| 類型 | 現況 |
|---|---|
| WebApi project | `src/HS.DeviceControl.WebApi/HS.DeviceControl.WebApi.csproj`，目前未引用 Swagger / OpenAPI package。 |
| Startup | `Startup.ConfigureServices` 註冊 controllers、mock / in-memory Application services；`Configure` 只使用 routing 與 endpoints。 |
| Controllers | `TasksController`、`DevicesController`、`SchemaController`、`HealthController`。 |
| Models | `TaskStartApiRequest`、`TaskCancelApiRequest`、`SchemaPreviewApiRequest`、`ApiErrorResponse` 等 API DTO。 |
| Infrastructure | `ApiResultMapper` 負責成功 / 失敗結果轉 HTTP response。 |
| Tests | `tests/HS.DeviceControl.WebApi.Tests/WebApiControllerTests.cs`，目前 7 tests。 |

## 2. 唯讀掃描結果

| 掃描項目 | 結果 |
|---|---|
| `AddAuthentication` / `UseAuthentication` | 未命中。 |
| `AddAuthorization` / `UseAuthorization` / `[Authorize]` | 未命中。 |
| `Swagger` / `OpenApi` / `AddSwaggerGen` / `UseSwagger` | 未命中。 |
| ControllerBase | 現有 controller 皆為 MVC controller，適合以 attribute 或 endpoint policy 加 auth gate。 |
| WebApi tests | `dotnet test tests\HS.DeviceControl.WebApi.Tests\HS.DeviceControl.WebApi.Tests.csproj --no-restore`，7 passed。 |

## 3. 候選新增 / 修改檔案

| 類型 | 候選檔案 | 風險 |
|---|---|---|
| Auth options | `src/HS.DeviceControl.WebApi/Security/WebApiAuthOptions.cs` | 不得保存正式 secret；safe default 應為關閉或測試用。 |
| Auth handler | `src/HS.DeviceControl.WebApi/Security/ApiKeyAuthenticationHandler.cs` | 不得把正式 key 寫死；錯誤訊息不得回顯 credential。 |
| Policy constants | `src/HS.DeviceControl.WebApi/Security/WebApiPolicies.cs` | 不得混入案場角色或客製權限。 |
| Startup | `src/HS.DeviceControl.WebApi/Startup.cs` | pipeline 順序需測試；不得影響 Health 決策。 |
| Controllers | `src/HS.DeviceControl.WebApi/Controllers/*.cs` | 不得修改 route 語意；只加授權 attribute 或明確匿名。 |
| Swagger package | `src/HS.DeviceControl.WebApi/HS.DeviceControl.WebApi.csproj` | 新增套件前需確認版本與範圍；production disabled。 |
| Tests | `tests/HS.DeviceControl.WebApi.Tests/WebApiAuthTests.cs`、`SwaggerGateTests.cs` | 需覆蓋 401、403、成功、dev-only / production disabled。 |

## 4. 建議第一批測試案例

| 測試主題 | 建議測試名稱 | 預期 |
|---|---|---|
| 缺少 credential | `ProtectedEndpoint_ShouldReturnUnauthorizedWhenCredentialMissing` | protected API 回 401。 |
| 錯誤 credential | `ProtectedEndpoint_ShouldReturnUnauthorizedWhenCredentialInvalid` | 回 401，不暴露 credential。 |
| 成功呼叫 | `ProtectedEndpoint_ShouldAllowValidTestCredential` | 合法測試 credential 可呼叫既有 API。 |
| 權限不足 | `SchemaPreview_ShouldReturnForbiddenForOperatorRole` | 若採 role / policy，權限不足回 403。 |
| Health 決策 | `Health_ShouldFollowConfiguredAnonymousPolicy` | 明確測 `/health` 匿名或授權策略。 |
| Swagger development | `Swagger_ShouldBeAvailableOnlyInDevelopmentWhenEnabled` | development 可用。 |
| Swagger production | `Swagger_ShouldBeDisabledInProduction` | production 不開 UI / JSON。 |
| 停止線 | `WebApiSecurity_ShouldNotStoreProductionSecrets` | 不保存正式 secret、URL、IP、token。 |

## 5. 必跑測試命令

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

## 6. 停止線掃描

| 停止線 | 掃描方向 | 不得出現 |
|---|---|---|
| Secret | `src`、`tests`、`samples`、`docs` 的 5D 變更 | 正式 API key、token、JWT secret、client secret、正式 IP、正式 URL。 |
| Swagger production | WebApi Startup / config / tests | production 預設開放 Swagger UI / JSON。 |
| 新 route | Controllers / tests | 未確認的新 API route 或 route 語意變更。 |
| DB / Apply | 全 repo 5D 變更 | DB table、DDL、ALTER TABLE、formal Apply、真實 DB 寫入。 |
| Windows Service | ServiceHost / project files | `UseWindowsService`、service install script、sc.exe。 |
| 外部 DLL | Production code | `Assembly.Load`、`LoadFrom`、`LoadFile`、plugin folder scan。 |

## 7. 下一步

請先完成 5D 七項確認。確認後才可進入 WebApi auth / Swagger 程式實作；若確認前只需補文件，可繼續停留在文件 repo。