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

Made-with: Cursor
2026-04-22 11:46:33 +00:00 · 2026-04-16 06:25:36 +03:00
parent 1b38e888e1
commit d320d6dd59
98 changed files with 6883 additions and 1 deletions
@@ -0,0 +1,124 @@
+# Admin API
+
+## 1. High-Level Overview
+
+**Purpose**: HTTP API entry point — configures DI, middleware pipeline, authentication, authorization, CORS, Swagger, and defines all REST endpoints using ASP.NET Core Minimal API.
+
+**Architectural Pattern**: Composition root + Minimal API endpoints — top-level statements configure the application and map HTTP routes to service methods.
+
+**Upstream dependencies**: User Management (IUserService), Authentication & Security (IAuthService, Security), Resource Management (IResourcesService), Data Layer (IDbFactory, ICache, configs).
+
+**Downstream consumers**: None (top-level entry point, consumed by HTTP clients).
+
+## 2. Internal Interfaces
+
+### BusinessExceptionHandler
+
+| Method | Input | Output | Async | Error Types |
+|--------|-------|--------|-------|-------------|
+| `TryHandleAsync` | `HttpContext, Exception, CancellationToken` | `bool` | Yes | None |
+
+Converts `BusinessException` to HTTP 409 JSON response: `{ ErrorCode: int, Message: string }`.
+
+## 3. External API Specification
+
+### Authentication
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/login` | POST | Anonymous | Validates credentials, returns JWT |
+
+### User Management
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/users` | POST | ApiAdmin | Creates a new user |
+| `/users/current` | GET | Authenticated | Returns current user |
+| `/users` | GET | ApiAdmin | Lists users (optional email/role filters) |
+| `/users/hardware/set` | PUT | ApiAdmin | Sets user hardware |
+| `/users/queue-offsets/set` | PUT | Authenticated | Updates queue offsets |
+| `/users/{email}/set-role/{role}` | PUT | ApiAdmin | Changes user role |
+| `/users/{email}/enable` | PUT | ApiAdmin | Enables user |
+| `/users/{email}/disable` | PUT | ApiAdmin | Disables user |
+| `/users/{email}` | DELETE | ApiAdmin | Removes user |
+
+### Resource Management
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/resources/{dataFolder?}` | POST | Authenticated | Uploads a file (up to 200 MB) |
+| `/resources/list/{dataFolder?}` | GET | Authenticated | Lists files |
+| `/resources/clear/{dataFolder?}` | POST | ApiAdmin | Clears folder |
+| `/resources/get/{dataFolder?}` | POST | Authenticated | Downloads encrypted resource |
+| `/resources/get-installer` | GET | Authenticated | Downloads production installer |
+| `/resources/get-installer/stage` | GET | Authenticated | Downloads staging installer |
+| `/resources/check` | POST | Authenticated | Validates hardware |
+
+### Authorization Policies
+- **apiAdminPolicy**: requires `ApiAdmin` role (used on most admin endpoints)
+- **apiUploaderPolicy**: requires `ResourceUploader` or `ApiAdmin` role (**defined but never applied to any endpoint — dead code**)
+
+### CORS
+- Allowed origins: `https://admin.azaion.com`, `http://admin.azaion.com`
+- All methods/headers, credentials allowed
+
+## 4. Data Access Patterns
+
+No direct data access — delegates to service components.
+
+## 5. Implementation Details
+
+**State Management**: Stateless — ASP.NET Core request pipeline.
+
+**Key Dependencies**:
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| Swashbuckle.AspNetCore | 10.1.4 | Swagger/OpenAPI documentation |
+| FluentValidation.AspNetCore | 11.3.0 | Request validation pipeline |
+| Serilog | 4.1.0 | Structured logging |
+| Serilog.Sinks.Console | 6.0.0 | Console log output |
+| Serilog.Sinks.File | 6.0.0 | Rolling file log output |
+
+**Error Handling Strategy**:
+- `BusinessException` → `BusinessExceptionHandler` → HTTP 409 with JSON body.
+- `UnauthorizedAccessException` → thrown in resource endpoints when current user is null.
+- `FileNotFoundException` → thrown when installer not found.
+- FluentValidation errors → automatic 400 Bad Request via middleware.
+- Unhandled exceptions → default ASP.NET Core exception handling.
+
+## 6. Extensions and Helpers
+
+None.
+
+## 7. Caveats & Edge Cases
+
+**Known limitations**:
+- All endpoints are defined in a single `Program.cs` file — no route grouping or controller separation.
+- Swagger UI only available in Development environment.
+- CORS origins are hardcoded (not configurable).
+- Antiforgery disabled for resource upload endpoint.
+- Root URL (`/`) redirects to `/swagger`.
+
+**Performance bottlenecks**:
+- Kestrel max request body: 200 MB — allows large file uploads but could be a memory concern.
+
+## 8. Dependency Graph
+
+**Must be implemented after**: All other components (composition root).
+
+**Can be implemented in parallel with**: Nothing — depends on all services.
+
+**Blocks**: Nothing.
+
+## 9. Logging Strategy
+
+| Log Level | When | Example |
+|-----------|------|---------|
+| WARN | Business exception caught | `BusinessExceptionHandler` logs the exception |
+| INFO | Serilog minimum level | General application events |
+
+**Log format**: Serilog structured logging with context enrichment.
+
+**Log storage**: Console + rolling file (`logs/log.txt`, daily rotation).
+
+## Modules Covered
+- `AdminApi/Program`
+- `AdminApi/BusinessExceptionHandler`