[AZ-189] [AZ-190] [AZ-191] [AZ-192] [AZ-193] [AZ-194] [AZ-195] Add e2e blackbox test suite

Made-with: Cursor

_docs/02_document/modules/admin_api_program.md

@@ -0,0 +1,93 @@
+# Module: Azaion.AdminApi.Program
+
+## Purpose
+Application entry point: configures DI, middleware, authentication, authorization, CORS, Swagger, logging, and defines all HTTP endpoints using ASP.NET Core Minimal API.
+
+## Public Interface (HTTP Endpoints)
+
+| Method | Path | Auth | Summary |
+|--------|------|------|---------|
+| POST | `/login` | Anonymous | Validates credentials, returns JWT token |
+| POST | `/users` | ApiAdmin | Creates a new user |
+| GET | `/users/current` | Any authenticated | Returns current user from JWT claims |
+| GET | `/users` | ApiAdmin | Lists users with optional email/role filters |
+| PUT | `/users/hardware/set` | ApiAdmin | Sets a user's hardware fingerprint |
+| PUT | `/users/queue-offsets/set` | Any authenticated | Updates user's queue offsets |
+| PUT | `/users/{email}/set-role/{role}` | ApiAdmin | Changes a user's role |
+| PUT | `/users/{email}/enable` | ApiAdmin | Enables a user account |
+| PUT | `/users/{email}/disable` | ApiAdmin | Disables a user account |
+| DELETE | `/users/{email}` | ApiAdmin | Removes a user |
+| POST | `/resources/{dataFolder?}` | Any authenticated | Uploads a resource file |
+| GET | `/resources/list/{dataFolder?}` | Any authenticated | Lists files in a resource folder |
+| POST | `/resources/clear/{dataFolder?}` | ApiAdmin | Clears a resource folder |
+| POST | `/resources/get/{dataFolder?}` | Any authenticated | Downloads an encrypted resource |
+| GET | `/resources/get-installer` | Any authenticated | Downloads latest production installer |
+| GET | `/resources/get-installer/stage` | Any authenticated | Downloads latest staging installer |
+| POST | `/resources/check` | Any authenticated | Validates hardware fingerprint |
+
+## Internal Logic
+
+### DI Registration
+- `IUserService` → `UserService` (Scoped)
+- `IAuthService` → `AuthService` (Scoped)
+- `IResourcesService` → `ResourcesService` (Scoped)
+- `IDbFactory` → `DbFactory` (Singleton)
+- `ICache` → `MemoryCache` (Scoped)
+- `LazyCache` via `AddLazyCache()`
+- FluentValidation validators auto-discovered from `RegisterUserValidator` assembly
+- `BusinessExceptionHandler` registered as exception handler
+
+### Middleware Pipeline
+1. Swagger (dev only)
+2. CORS (`AdminCorsPolicy`)
+3. Authentication (JWT Bearer)
+4. Authorization
+5. URL rewrite: root `/` → `/swagger`
+6. Exception handler
+
+### Authorization Policies
+- `apiAdminPolicy`: requires `RoleEnum.ApiAdmin` role
+- `apiUploaderPolicy`: requires `RoleEnum.ResourceUploader` OR `RoleEnum.ApiAdmin` role
+
+### Configuration Sections
+- `JwtConfig` — JWT signing/validation
+- `ConnectionStrings` — DB connections
+- `ResourcesConfig` — file storage paths
+
+### Kestrel
+- Max request body size: 200 MB (for file uploads)
+
+### Logging
+- Serilog: console + rolling file (`logs/log.txt`)
+
+### CORS
+- Allowed origins: `https://admin.azaion.com`, `http://admin.azaion.com`
+- All methods and headers allowed
+- Credentials allowed
+
+## Dependencies
+All services, configs, entities, and request types from Azaion.Common and Azaion.Services.
+
+## Consumers
+None — this is the application entry point.
+
+## Data Models
+None defined here.
+
+## Configuration
+Reads `JwtConfig`, `ConnectionStrings`, `ResourcesConfig` from `IConfiguration`.
+
+## External Integrations
+- PostgreSQL (via DI-registered `DbFactory`)
+- Local filesystem (via `ResourcesService`)
+
+## Security
+- JWT Bearer authentication with full validation (issuer, audience, lifetime, signing key)
+- Role-based authorization policies
+- CORS restricted to `admin.azaion.com`
+- Request body limit of 200 MB
+- Antiforgery disabled for resource upload endpoint
+- Password sent via POST body (not URL)
+
+## Tests
+None directly; tested indirectly through integration tests.