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,31 @@
+# Business Logic Model — Unit 01: Core Base
+
+Dit document beschrijft de functionele workflows en dataflows binnen het Core Framework.
+
+## 1. Module Levenscyclus Model
+
+Het framework beheert modules via de volgende logische stappen:
+
+1.  **Discovery**: De API Shell identificeert potentiële modules (via referentie of DLL scan).
+2.  **Registration**: De Core valideert de `ModuleInfo`.
+    - Controleert BR-CORE-01 (Uniciteit & Metadata).
+3.  **Service Registration**: De Core roept `RegisterServices` aan.
+    - Modules voegen hun services toe aan de globale DI-container.
+4.  **Middleware Configuration**: De Core roept `ConfigureMiddleware` aan tijdens de startup van de webhost.
+
+## 2. Globale Availability Orchestratie Model
+
+Het proces van statuscontrole verloopt als volgt:
+
+- **Centrale Controle**: De Core Base definieert de `IAvailabilityService` interface. De API Shell gebruikt één centrale implementatie om de status van de gehele API te bepalen.
+- **Binaire Status**: Het resultaat is een binaire status (beschikbaar/niet beschikbaar) voor de volledige API suite, niet opgedeeld per individuele module.
+- **Reporting**: De resultaten worden gerapporteerd in een enkel `AvailabilityDetails` object.
+
+## 3. Exception-to-Response Flow
+
+Flow van een foutieve actie naar een response:
+
+1.  **Event**: Een actie in een module of de Core gooit een domein-exception.
+2.  **Capture**: Globale middleware (in de Shell, maar gedefinieerd in Core) vangt de exception op.
+3.  **Transformation**: De exception wordt gemapt naar een `ApiErrorResponse` volgens BR-CORE-03.
+4.  **Response**: De client ontvangt een gestandaardiseerde JSON body met de relevante HTTP status code (bijv. 404 voor `ModuleNotFoundException`).
@@ -0,0 +1,25 @@
+# Business Rules — Unit 01: Core Base
+
+Dit document beschrijft de validatieregels en logica voor het Core Framework.
+
+## 1. Module Registratie Regels (BR-CORE-01)
+
+- **Uniciteit**: Elke module moet een unieke `Name` hebben. Registratie van een tweede module met dezelfde naam moet resulteren in een `DuplicateModuleException`.
+- **Verplichte Metadata**: Registratie faalt als `Name`, `Version` of `Description` leeg zijn.
+- **Dependency Resolutie**:
+  - Als een module afhankelijkheden opgeeft, moet het framework controleren of deze modules ook geladen zijn.
+  - Bij ontbrekende afhankelijkheden moet een waarschuwing worden gelogd, maar mag de applicatie in de MVP fase wel doorstarten (soft dependency).
+
+## 2. Globale Availability Regels (BR-CORE-02)
+
+- **API-breed**: De beschikbaarheidscontrole is een binaire status voor de gehele API Shell.
+- **Implementatie Verplichting**: Er moet één actieve implementatie van `IAvailabilityService` geregistreerd zijn in de API Shell.
+- **Gedrag**: Indien de service niet bereikbaar is (bijv. door Master-API uitval in de toekomst), wordt de gehele API als "niet beschikbaar" beschouwd voor niet-beheerders.
+
+## 3. Error Handling Conversie (BR-CORE-03)
+
+- **Gedetailleerde Mapping**: Elke domein-specifieke exception moet worden vertaald naar een `ApiErrorResponse` met specifieke details.
+  - `ModuleNotFoundException` -> Details bevatten de gezochte `ModuleName`.
+  - `UnauthorizedAccessException` -> Details bevatten de vereiste rol en de huidige rol van de gebruiker.
+  - `ValidationException` -> Details bevatten een lijst van velden die niet voldeden aan de regels.
+- **Privacy**: In productie-omgevingen moeten stacktraces worden verwijderd uit de `Details` dictionary.
@@ -0,0 +1,49 @@
+# Domain Entities — Unit 01: Core Base
+
+Dit document beschrijft de domein-modellen en interfaces voor het Core Framework.
+
+## 1. Module Interfaces & Entiteiten
+
+### IModule
+Het basiscontract voor elke module in het systeem.
+```csharp
+public interface IModule
+{
+    ModuleInfo GetInfo();
+    void RegisterServices(IServiceCollection services);
+    void ConfigureMiddleware(IApplicationBuilder app);
+}
+```
+
+### ModuleInfo (Record)
+Metadata van een module, verplicht op te geven bij registratie.
+- `string Name`: Unieke identifier van de module.
+- `string Version`: Semantische versie (bijv. 1.0.0).
+- `string Description`: Korte omschrijving van het doel.
+- `IEnumerable<string> Dependencies`: Lijst met namen van modules waar deze module van afhankelijk is.
+
+## 2. Availability Interfaces & Entiteiten
+
+### IAvailabilityService
+Service die de status van een component bewaakt.
+```csharp
+public interface IAvailabilityService
+{
+    Task<bool> IsAvailableAsync();
+    Task<AvailabilityDetails> GetDetailsAsync();
+}
+```
+
+### AvailabilityDetails (Record)
+Gedetailleerde statusinformatie.
+- `bool IsAvailable`: Globale status van de API.
+- `DateTime LastChecked`: Tijdstip van de laatste controle.
+- `IDictionary<string, string> Metadata`: Extra statusinformatie (bijv. latency, Master-API status).
+
+## 3. Error Handling Models
+
+### ApiErrorResponse
+Basismodel voor foutmeldingen.
+- `string ErrorCode`: Functionele code (bijv. "MODULE_NOT_FOUND").
+- `string Message`: Mensvriendelijke beschrijving.
+- `IDictionary<string, object> Details`: Specifieke debug- of context-informatie per exception type.
@@ -0,0 +1,37 @@
+# Availability Service Design — Unit 01: Core Base
+
+Dit document beschrijft de technische details voor de beschikbaarheidscontrole (NFR-AVAIL-01).
+
+## 1. Configuratie
+
+De timeout wordt globaal geconfigureerd in `appsettings.json`:
+
+```json
+{
+  "AvailabilitySettings": {
+    "TimeoutSeconds": 2,
+    "DefaultStatusOnFailure": "Unknown"
+  }
+}
+```
+
+## 2. IAvailabilityService Interface
+
+Gedefinieerd in U01:
+
+```csharp
+public interface IAvailabilityService
+{
+    /// <summary>
+    /// Controleert de algemene beschikbaarheid van de API.
+    /// Gebruikt de geconfigureerde globale timeout.
+    /// </summary>
+    Task<AvailabilityStatus> IsAvailableAsync();
+}
+```
+
+## 3. Implementatie Details
+
+- **Timeout Mechanisme**: De implementatie maakt intern gebruik van `Task.WaitAsync(TimeSpan)` of een intern aangemaakte `CancellationTokenSource` met de tijd uit de configuratie.
+- **Fallback**: Bij een `TimeoutException` of een andere interne fout tijdens de check, wordt de status gerapporteerd die in de configuratie is vastgelegd (bijv. "Unknown").
+- **Logging**: Elke mislukte check of timeout moet worden gelogd met een `Warning` niveau, inclusief de verstreken tijd.
@@ -0,0 +1,38 @@
+# Exception Handling Design — Unit 01: Core Base
+
+Dit document beschrijft de technische implementatie van de globale foutafhandeling (NFR-SEC-01).
+
+## 1. IExceptionHandler Implementatie
+
+We maken gebruik van de `IExceptionHandler` interface (.NET 8+).
+
+### Component: `GlobalExceptionHandler`
+- **Verantwoordelijkheid**: Het vangen van ongehandled exceptions en het omzetten naar een gestandaardiseerd `ApiErrorResponse`.
+- **Logic**:
+    - Logt de volledige exception (inclusief stacktrace) naar `ILogger<GlobalExceptionHandler>`.
+    - Bepaalt de HTTP Status Code op basis van het type exception (bijv. `ValidationException` -> 400, `NotFoundException` -> 404, de rest -> 500).
+    - Bouwt het `ApiErrorResponse` object.
+
+## 2. ApiErrorResponse Structuur
+
+Conform NFR-SEC-01 wordt gevoelige informatie gefilterd in productie.
+
+```csharp
+public record ApiErrorResponse(
+    string Message,
+    string? Detail = null,
+    string? TraceId = null
+);
+```
+
+### Gedrag per omgeving:
+- **Development**: `Message` bevat de exception message, `Detail` bevat de stacktrace.
+- **Production**: `Message` bevat een generieke foutmelding of een veilige publieke melding, `Detail` is `null`. `TraceId` wordt altijd meegegeven voor correlatie in logs.
+
+## 3. Registratie
+
+In `Program.cs` (U04) of via een extensie-methode in de Core Base:
+```csharp
+services.AddExceptionHandler<GlobalExceptionHandler>();
+services.AddProblemDetails();
+```
@@ -0,0 +1,34 @@
+# Module Discovery Design — Unit 01: Core Base
+
+Dit document beschrijft het ontwerp van de dynamische module discovery (NFR-PERF-01).
+
+## 1. Naamconventie
+
+Het systeem scant automatisch naar assemblies die voldoen aan het volgende patroon:
+`SlpModularCms.Modules.*.dll`
+
+## 2. Discovery Logica
+
+De `ModuleOrchestrator` (onderdeel van U04, maar gebruikmakend van interfaces uit U01) voert de volgende stappen uit tijdens het opstarten:
+
+1. **Assembly Loading**: Zoekt in de applicatie-directory naar DLL's die voldoen aan de naamconventie.
+2. **Type Scanning**: In elke geladen assembly wordt gezocht naar klassen die de `IModule` interface implementeren.
+3. **Registration**: De gevonden module-entry klassen worden geïnstantieerd en hun `RegisterServices(IServiceCollection services)` methode wordt aangeroepen.
+
+### Performance Optimalisatie:
+- Om de opstarttijd te minimaliseren (NFR-PERF-01), worden alleen assemblies gescand die voldoen aan de prefix.
+- De resultaten van de discovery kunnen indien nodig worden gecached, hoewel de overhead bij een beperkt aantal modules verwaarloosbaar is (< 100ms).
+
+## 3. IModule Interface
+
+Gedefinieerd in de Core Base (U01):
+
+```csharp
+public interface IModule
+{
+    string Name { get; }
+    string Version { get; }
+    void RegisterServices(IServiceCollection services);
+    void UseModule(IApplicationBuilder app);
+}
+```
@@ -0,0 +1,37 @@
+# Testing Strategy Design — Unit 01: Core Base
+
+Dit document beschrijft de testaanpak voor de Core Base componenten (NFR-MAINT-02).
+
+## 1. Tooling
+
+- **Framework**: xUnit.
+- **Data Generatie**: AutoFixture.
+- **Mocks**: NSubstitute (optioneel, indien nodig voor interfaces).
+- **Assertions**: FluentAssertions.
+
+## 2. AutoFixture Patronen
+
+Om consistentie te waarborgen gebruiken we de volgende patronen:
+
+### Customizations
+Voor domein-specifieke types (zoals `ModuleInfo`) maken we gebruik van `ICustomization` klassen om realistische data te genereren.
+
+```csharp
+public class ModuleCustomization : ICustomization
+{
+    public void Customize(IFixture fixture)
+    {
+        fixture.Customize<ModuleInfo>(composer =>
+            composer.With(m => m.Version, "1.0.0"));
+    }
+}
+```
+
+### Base Test Class
+We overwegen een base class voor unit tests die de `IFixture` configureert met de benodigde customizations.
+
+## 3. Test Dekking Targets
+
+- **Exception Mapping**: 100% dekking van alle bekende exception types naar de juiste HTTP status codes en response formaten.
+- **Availability Fallback**: Tests die vertraging simuleren om te verifiëren dat de timeout en fallback status correct werken.
+- **Module Discovery**: Integratietesten (met in-memory assemblies) om te verifiëren dat de conventie-gebaseerde scanning correct werkt.
@@ -0,0 +1,27 @@
+# NFR Requirements — Unit 01: Core Base
+
+Dit document beschrijft de non-functional requirements voor het Core Framework.
+
+## 1. Schaalbaarheid & Performance (NFR-PERF)
+
+- **Dynamische Module Discovery**: Het systeem moet een onbekend aantal modules kunnen ondersteunen zonder significante degradatie van de opstarttijd.
+- **Middleware Overhead**: Een overhead van > 50ms voor globale exception handling en logging is acceptabel bevonden om robuustheid en detailniveau te waarborgen.
+- **Resource Management**: Interfaces in de Core Base moeten `async` zijn waar I/O verwacht wordt (bijv. `IAvailabilityService`) om threadpool starvation te voorkomen.
+
+## 2. Security & Privacy (NFR-SEC)
+
+- **Informatiebeveiliging in Responses**: De `ApiErrorResponse` mag in productieomgevingen onder geen beding de volgende informatie bevatten:
+    - Stacktraces.
+    - Interne server IP-adressen.
+    - Lokale bestandspaden van de server.
+- **Isolatie**: Hoewel modules in dezelfde procesruimte draaien, moet de Core Base interfaces bieden die een duidelijke scheiding van verantwoordelijkheden afdwingen.
+
+## 3. Availability & Reliability (NFR-AVAIL)
+
+- **Check Timeout**: De `IAvailabilityService.IsAvailableAsync()` methode moet een instelbare timeout hebben, met een standaardwaarde tussen 1 en 2 seconden.
+- **Graceful Degradation**: Bij het falen van de beschikbaarheidscontrole moet het systeem een veilige fallback status rapporteren (bijv. "Onbekend" of "Niet beschikbaar" voor reguliere gebruikers).
+
+## 4. Onderhoudbaarheid & Testbaarheid (NFR-MAINT)
+
+- **Consistentie**: Gebruik van gestandaardiseerde .NET patronen voor DI en Logging.
+- **Test Dekking**: Cruciale cross-cutting concerns (zoals exception mapping) moeten gedekt zijn met unit tests die gebruik maken van geautomatiseerde data generatie.
@@ -0,0 +1,24 @@
+# Tech Stack Decisions — Unit 01: Core Base
+
+Dit document legt de gekozen technologieën en bibliotheken vast voor de implementatie van Unit 01.
+
+## 1. Core Framework & Runtime
+
+- **Runtime**: .NET 10.
+- **Project Type**: Class Library (voor Core).
+
+## 2. Cross-Cutting Concerns
+
+- **Dependency Injection**: Standaard `Microsoft.Extensions.DependencyInjection`. Er is momenteel geen behoefte aan externe containers zoals Autofac.
+- **Logging**: Standaard `Microsoft.Extensions.Logging`. Implementaties (zoals Serilog voor file/cloud logging) kunnen later in de API Shell (U04) worden geconfigureerd.
+
+## 3. Testing Stack
+
+- **Unit Testing Framework**: `xUnit`.
+- **Assertions**: `FluentAssertions` voor leesbare en expressieve checks.
+- **Data Generation**: `AutoFixture` voor het genereren van test data en het ondersteunen van geautomatiseerde scenario's (ter vervanging/aanvulling van formele PBT met FsCheck, conform gebruikersvoorkeur).
+
+## 4. Architecturale Patronen
+
+- **Interfaces & Records**: Veelal gebruik van `record` types voor DTO's en metadata (zoals `ModuleInfo`) voor onveranderlijkheid (immutability).
+- **Middleware**: Gebruik van het standard .NET Middleware patroon voor globale exception handling.