Initial commit with inital CMS

2026-06-15 17:00:16 +02:00
commit 95d986790e
132 changed files with 7624 additions and 0 deletions
@@ -0,0 +1,30 @@
+# Business Rules — Unit 03: Availability Module
+
+Dit document beschrijft de functionele logica voor de beschikbaarheidscontrole en de remote shutdown functionaliteit.
+
+## 1. Beschikbaarheidsstatus (BR-AVAIL-01)
+
+- **Status Typen**:
+    - `Available`: Het systeem is volledig operationeel.
+    - `Maintenance`: Het systeem is in onderhoud; alleen beheerders hebben toegang.
+    - `Degraded`: Sommige functies zijn beperkt, maar het systeem is in principe bereikbaar.
+    - `NotAvailable`: Het systeem is volledig afgesloten (Remote Shutdown).
+- **Default (MVP)**: In de MVP versie retourneert de `StubAvailabilityService` altijd `Available`, tenzij handmatig anders geconfigureerd in `appsettings.json`.
+
+## 2. Remote Shutdown Handhaving (BR-AVAIL-02)
+
+- **Mechanisme**: Een globale middleware controleert bij elk inkomend request de status via de `IAvailabilityService`.
+- **Gedrag**:
+    - Als status == `NotAvailable` -> Retourneer `503 Service Unavailable`.
+    - Als status == `Maintenance` -> Blokkeer requests voor reguliere gebruikers; sta alleen toe voor gebruikers met de rol `Owner` of `Administrator`.
+- **Response**: De response moet het gestandaardiseerde `ApiErrorResponse` formaat gebruiken (U01).
+
+## 3. Publieke Status (BR-AVAIL-03)
+
+- **Endpoint**: `GET /api/availability/status` moet voor iedereen bereikbaar zijn (geen authenticatie vereist).
+- **Informatie**: Het endpoint retourneert de huidige status en een timestamp van de laatste controle.
+
+## 4. Beheerder Bypass (BR-AVAIL-04)
+
+- **Rechten**: Gebruikers met de rol `Owner` of `Administrator` kunnen de blokkades van de Availability Middleware omzeilen om onderhoudstaken uit te voeren.
+- **Identificatie**: De bypass is gebaseerd op de JWT claims (`role`).
@@ -0,0 +1,27 @@
+# Domain Entities — Unit 03: Availability Module
+
+Dit document beschrijft de data structuren voor de beschikbaarheidsmodule.
+
+## 1. AvailabilityResponse (DTO)
+
+Model voor de publieke status check.
+
+- **Status**: De huidige `AvailabilityStatus` (Enum uit U01).
+- **CheckedAt**: Tijdstip van de status check.
+- **Message**: Optionele tekstuele toelichting (bijv. "Onderhoud gepland tot 14:00").
+
+## 2. AvailabilitySettings (Configuration)
+
+Model voor de configuratie in `appsettings.json`.
+
+- **DefaultStatus**: De status die geretourneerd wordt door de stub.
+- **MaintenanceMessage**: Bericht dat getoond wordt tijdens onderhoud.
+- **AllowedRolesForMaintenance**: Lijst van rollen die toegang hebben tijdens onderhoud (default: `Owner`, `Administrator`).
+
+## 3. AvailabilityState (In-Memory)
+
+Indien we in de MVP de status dynamisch willen kunnen aanpassen zonder restart:
+
+- **CurrentStatus**: `AvailabilityStatus`.
+- **StatusChangedAt**: DateTimeOffset.
+- **Reason**: String.
@@ -0,0 +1,40 @@
+# Business Logic Model — Unit 03: Availability Module
+
+Dit document beschrijft de processen voor beschikbaarheidscontrole.
+
+## 1. Availability Middleware Flow
+
+```mermaid
+graph TD
+    A[Inkomend Request] --> B{Is Endpoint /status?}
+    B -- Ja --> C[Laat door naar Controller]
+    B -- Nee --> D{Check Status via IAvailabilityService}
+    D --> E{Status == Available?}
+    E -- Ja --> C
+    E -- Nee --> F{Status == Maintenance?}
+    F -- Ja --> G{Heeft Rol Admin/Owner?}
+    G -- Ja --> C
+    G -- Nee --> H[Retourneer 503 + ApiErrorResponse]
+    F -- Nee --> H
+```
+
+## 2. Status Check Flow
+
+1. **Client** roept `GET /api/availability/status` aan.
+2. **AvailabilityController** roept `IAvailabilityService.IsAvailableAsync()` aan.
+3. **Service** haalt status op (in MVP uit config of in-memory state).
+4. **Controller** bouwt response:
+    ```json
+    {
+      "status": "Available",
+      "checkedAt": "2026-06-12T01:15:00Z",
+      "message": "System is running normally."
+    }
+    ```
+
+## 3. Remote Shutdown Logic (Toekomst)
+
+Hoewel de MVP een stub gebruikt, is het logic model voorbereid op een externe trigger:
+- Een administratieve actie zet een vlag in de database/cache.
+- De `IAvailabilityService` detecteert deze wijziging.
+- De Middleware reageert direct op alle volgende requests.
@@ -0,0 +1,36 @@
+# Controller Design — Unit 03: Availability Module
+
+Dit document beschrijft de endpoints van de `AvailabilityController`.
+
+## 1. Publieke Status Endpoint
+
+- **Method**: `GET`
+- **Path**: `/api/availability/status`
+- **Auth**: Geen (AllowAnonymous)
+- **Response**: `AvailabilityResponse`
+- **Logic**: Roept `IAvailabilityService.IsAvailableAsync()` aan en mapt de status naar het response object.
+
+## 2. Status Update Endpoint (Beheer)
+
+- **Method**: `POST`
+- **Path**: `/api/availability/admin/status`
+- **Auth**: `OwnerOnly` Policy (Unit 02)
+- **Request Body**:
+    ```json
+    {
+      "newStatus": "Maintenance",
+      "reason": "Gepland database onderhoud"
+    }
+    ```
+- **Logic**:
+    1. Valideert de nieuwe status.
+    2. Werkt de database record bij via de `IAvailabilityService`.
+    3. Maakt een audit log aan (Unit 02).
+- **Response**: `200 OK`.
+
+## 3. Integratie met Audit Log
+
+Bij elke statuswijziging wordt de `IAuditService` aangeroepen met de volgende gegevens:
+- **ActorId**: De ID van de Owner.
+- **Action**: `SystemStatusChanged`.
+- **Details**: `OldStatus: Available, NewStatus: Maintenance, Reason: ...`
@@ -0,0 +1,35 @@
+# Middleware Design — Unit 03: Availability Module
+
+Dit document beschrijft de technische implementatie van de Availability Middleware.
+
+## 1. Middleware Registratie
+
+De middleware wordt in de `Program.cs` van de API Shell (U04) geregistreerd:
+
+```csharp
+app.UseExceptionHandler(); // Eerst de exception handler (U01)
+app.UseAvailability();     // Daarna de availability check
+// ... andere middleware (Auth, Routing, etc)
+```
+
+## 2. AvailabilityMiddleware Logica
+
+- **Bypass voor Status Endpoint**: Het pad `/api/availability/status` wordt altijd doorgelaten zonder check.
+- **Check Fase**:
+    - De middleware roept `IAvailabilityService.IsAvailableAsync()` aan.
+    - Indien status == `Available` -> `_next(context)`.
+- **Bypass voor Admins/Owners**:
+    - Indien status == `Maintenance` of `NotAvailable`:
+    - De middleware inspecteert het JWT token in de `Authorization` header handmatig (omdat de globale Authentication middleware nog niet is uitgevoerd op dit punt).
+    - Indien de claim `role` gelijk is aan `Owner` of `Administrator` -> `_next(context)`.
+    - Anders -> Retourneer `503 Service Unavailable` met `ApiErrorResponse`.
+
+## 3. PersistentAvailabilityService
+
+Implementatie van de interface uit Unit 01.
+
+- **Database Opslag**: Maakt gebruik van de `ApplicationDbContext` (Unit 02).
+- **Circuit Breaker**:
+    - Houdt in een statische variabele de `_lastErrorTime` en `_cachedStatus` bij.
+    - Indien `DateTimeOffset.UtcNow - _lastErrorTime < 30 seconden` -> Retourneer de `_cachedStatus` (default: `Available`) zonder de database te pollen.
+- **Logging**: Elke blokkade wordt gelogd met het IP-adres van de client en het gevraagde pad.
@@ -0,0 +1,30 @@
+# NFR Requirements — Unit 03: Availability Module
+
+Dit document specificeert de non-functionele vereisten voor de beschikbaarheidsmodule.
+
+## 1. Performance (AVAIL-PERF)
+
+- **AVAIL-PERF-01: Middleware Latency**:
+    - De Availability Middleware mag maximaal 5ms toevoegen aan de totale requestduur.
+    - Dit vereist een geoptimaliseerde database check (indexering op de status tabel).
+- **AVAIL-PERF-02: Real-time Check**:
+    - Er wordt GEEN caching toegepast in de middleware (conform gebruikerskeuze). Elke request voert een actuele check uit om maximale consistentie te waarborgen.
+
+## 2. Betrouwbaarheid & Persistentie (AVAIL-REL)
+
+- **AVAIL-REL-01: Persistent Status**:
+    - De beschikbaarheidsstatus moet in de database worden opgeslagen, zodat deze behouden blijft na een herstart van de applicatie.
+- **AVAIL-REL-02: Fallback**:
+    - Indien de database onbereikbaar is, moet de `IAvailabilityService` terugvallen op een "Veilige" status (bijv. `Available` of de laatst bekende status in het geheugen) om een lock-out te voorkomen.
+
+## 3. Beveiliging (AVAIL-SEC)
+
+- **AVAIL-SEC-01: Access Control**:
+    - Alleen gebruikers met de rol `Owner` kunnen de globale beschikbaarheidsstatus van de API wijzigen via een beveiligd endpoint.
+- **AVAIL-SEC-02: Maintenance Bypass**:
+    - De bypass voor beheerders (zoals gedefinieerd in Functional Design) moet strikt gecontroleerd worden op basis van JWT claims.
+
+## 4. Onderhoudbaarheid (AVAIL-MAINT)
+
+- **AVAIL-MAINT-01: Audit Trail**:
+    - Elke wijziging van de beschikbaarheidsstatus moet worden gelogd in de `AuditLogs` tabel (Unit 02), inclusief de reden en de uitvoerder.
@@ -0,0 +1,26 @@
+# Tech Stack Decisions — Unit 03: Availability Module
+
+Dit document beschrijft de definitieve technische keuzes voor Unit 03.
+
+## 1. Opslag (Persistence)
+
+- **Provider**: Microsoft SQL Server (conform NFR-01).
+- **Entiteit**: `GlobalAvailabilityState` (Single record).
+
+## 2. Middleware Implementatie
+
+- **Type**: Custom Middleware in de `SlpModularCms.Api` (Shell).
+- **Dependency**: Maakt gebruik van de `IAvailabilityService` uit Unit 01.
+
+## 3. Interfaces & DI
+
+- **Service**: `PersistentAvailabilityService` (Implementeert `IAvailabilityService`).
+- **Lifetime**: `Scoped` (voor database toegang per request).
+
+## 4. Configuratie
+
+- **Options Pattern**: Gebruik van `IOptions<AvailabilitySettings>` voor de fallback status en andere drempelwaarden.
+
+## 5. Monitoring
+
+- **Logging**: Gebruik van `ILogger` voor het loggen van statuswijzigingen en middleware blokkades (Warning niveau).