Adds 2 units and docs for unit 3. nfr-requirements plan

2026-06-29 22:18:37 +02:00
parent 0e01ca1e1c
commit c156107cb1
126 changed files with 15204 additions and 80199 deletions
@@ -0,0 +1,142 @@
+# Component Methods — Master CMS Module
+
+> Method signatures at the interface level. Detailed business rules and implementation logic are deferred to Functional Design (CONSTRUCTION phase).
+
+---
+
+## Unit 1 — master-backend
+
+### ICmsInstanceRepository
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `GetAllAsync` | `Task<IReadOnlyList<CmsInstance>> GetAllAsync()` | Returns all registered slave CMS instances |
+| `GetActiveAsync` | `Task<IReadOnlyList<CmsInstance>> GetActiveAsync()` | Returns all non-Inactive instances (used by integrity check) |
+| `GetByIdAsync` | `Task<CmsInstance?> GetByIdAsync(Guid id)` | Returns instance by primary key; null if not found |
+| `AddAsync` | `Task AddAsync(CmsInstance instance)` | Adds new entity to the change tracker |
+| `UpdateAsync` | `Task UpdateAsync(CmsInstance instance)` | Marks entity as modified in the change tracker |
+| `SaveChangesAsync` | `Task<int> SaveChangesAsync()` | Persists pending changes via `MasterDbContext` |
+
+### ICmsInstanceService
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `GetAllAsync` | `Task<IReadOnlyList<CmsInstanceDto>> GetAllAsync()` | Returns all instances as DTOs; `ApiKey` excluded (NFR-MASTER-03) |
+| `AddAsync` | `Task<CmsInstanceDto> AddAsync(CreateCmsInstanceRequest request)` | Creates entity, persists, triggers auto-registration with slave (FR-MASTER-03); returns DTO |
+| `UpdateStatusAsync` | `Task UpdateStatusAsync(Guid id, CmsInstanceStatus status, string? disableMessage)` | Updates entity status, persists, pushes status to slave via HTTP (FR-MASTER-05); `disableMessage` required when `status = NotAvailable` (FR-MASTER-14) |
+| `VerifyIntegrityAsync` | `Task VerifyIntegrityAsync()` | Called by `IntegrityCheckBackgroundService`; checks all active slaves have correct master URL; re-registers if mismatch (FR-MASTER-04) |
+
+### ISlaveApiClient
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `RegisterMasterAsync` | `Task<bool> RegisterMasterAsync(string slaveUrl, string apiKey, string masterUrl)` | POST `/api/internal/master/register` on slave; returns `true` on success (FR-MASTER-03) |
+| `PushStatusAsync` | `Task<bool> PushStatusAsync(string slaveUrl, string apiKey, CmsInstanceStatus status, string? disableMessage)` | Pushes new status to slave's availability endpoint; returns `true` on success (FR-MASTER-05) |
+| `GetRegisteredMasterUrlAsync` | `Task<string?> GetRegisteredMasterUrlAsync(string slaveUrl, string apiKey)` | GET slave's currently registered master URL; used for integrity check (FR-MASTER-04); null if no master registered |
+
+### IntegrityCheckBackgroundService
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `ExecuteAsync` | `override Task ExecuteAsync(CancellationToken stoppingToken)` | Main background loop; uses `PeriodicTimer` with interval from `MasterModuleOptions.IntegrityCheckIntervalMinutes`; creates `IServiceScope` per tick to resolve scoped services |
+
+### CmsInstanceController
+
+| Method | HTTP | Route | Purpose |
+|--------|------|-------|---------|
+| `GetAll` | GET | `/api/v1/CmsInstances` | Returns `IReadOnlyList<CmsInstanceDto>` |
+| `Add` | POST | `/api/v1/CmsInstances` | Body: `CreateCmsInstanceRequest`; returns created `CmsInstanceDto` (201) |
+| `UpdateStatus` | PUT | `/api/v1/CmsInstances/{id}/status` | Body: `UpdateStatusRequest`; returns 200 OK or 404 if not found |
+
+---
+
+## Unit 2 — slave-availability-extension
+
+### IMasterAvailabilityService
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `GetMasterStatusAsync` | `Task<MasterGateResult> GetMasterStatusAsync()` | Checks DB for `MasterRegistration`; if no registration → returns `HasMaster = false`; if registration exists → returns cached or freshly-pulled status with fail-open fallback |
+
+### MasterGateResult
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `HasMaster` | `bool` | Whether a master URL is registered on this slave |
+| `Status` | `CmsInstanceStatus?` | Master-controlled status (null when `HasMaster = false`) |
+| `DisableMessage` | `string?` | Message to include in 503 when `Status = NotAvailable` |
+
+### AvailabilityController (new method)
+
+| Method | HTTP | Route | Purpose |
+|--------|------|-------|---------|
+| `RegisterMaster` | POST | `/api/internal/master/register` | Header: `X-Master-Api-Key`; Body: `RegisterMasterRequest`; validates key, upserts `MasterRegistration`; returns 200 OK or 401 Unauthorized |
+
+### RegisterMasterRequest
+
+| Property | Type | Notes |
+|----------|------|-------|
+| `MasterUrl` | `string` | Base URL of the Master CMS |
+
+### AvailabilityMiddleware.InvokeAsync (extended signature)
+
+```csharp
+public async Task InvokeAsync(
+    HttpContext context,
+    IAvailabilityService availabilityService,
+    IMasterAvailabilityService masterAvailabilityService)
+```
+
+---
+
+## Unit 3 — frontend-cms-page
+
+### useCmsInstances
+
+```typescript
+function useCmsInstances(): UseQueryResult<CmsInstance[], Error>
+```
+
+### useAddCmsInstance
+
+```typescript
+interface CreateCmsInstancePayload {
+    name: string;
+    url: string;
+    apiKey: string;
+}
+
+function useAddCmsInstance(): UseMutationResult<CmsInstance, Error, CreateCmsInstancePayload>
+```
+
+### useUpdateCmsInstanceStatus
+
+```typescript
+interface UpdateStatusPayload {
+    id: string;
+    status: CmsInstanceStatus;
+    disableMessage?: string;
+}
+
+function useUpdateCmsInstanceStatus(): UseMutationResult<void, Error, UpdateStatusPayload>
+```
+
+### CmsInstance (TypeScript)
+
+```typescript
+interface CmsInstance {
+    id: string;
+    name: string;
+    url: string;
+    status: CmsInstanceStatus;
+    disableMessage?: string;
+    lastContactedAt?: string;     // ISO 8601
+    lastStatusPushedAt?: string;  // ISO 8601
+}
+
+enum CmsInstanceStatus {
+    Available = 'Available',
+    NotAvailable = 'NotAvailable',
+    Inactive = 'Inactive',
+}
+```