Completes master-cms-module: Build & Test, docs, and appsettings
Finishes the master-cms-module feature (Units 1-4): runs Build and Test across master-backend, slave-availability-extension and frontend-cms-page, fixes a missing Availability EF migration for MasterRegistration and a TanStack Query v5 mutation-callback type break, adds the missing MasterModule appsettings section, and documents the module in README.md. Also seeds a tech-debt-backlog feature to track dead config and pre-existing/introduced frontend lint findings for later cleanup.
This commit is contained in:
@@ -118,6 +118,14 @@ Om de migraties toe te passen op de database:
|
||||
dotnet ef database update --project src\SlpModularCms.Core --startup-project src\SlpModularCms.Api
|
||||
```
|
||||
|
||||
### Per-module migraties
|
||||
Sommige modules (`SlpModularCms.Modules.Master`, `SlpModularCms.Modules.Availability`) hebben een **eigen** `DbContext` met eigen migraties, los van `SlpModularCms.Core`. Deze worden automatisch toegepast bij het opstarten van de applicatie (via `Database.Migrate()` in de module's `UseModule`-methode), maar een nieuwe migratie genereren doe je expliciet per project:
|
||||
```powershell
|
||||
dotnet ef migrations add <NaamVanDeMigratie> --project src\SlpModularCms.Modules.Master --startup-project src\SlpModularCms.Api
|
||||
dotnet ef migrations add <NaamVanDeMigratie> --project src\SlpModularCms.Modules.Availability --startup-project src\SlpModularCms.Api --context AvailabilityDbContext
|
||||
```
|
||||
> Let op: voor `SlpModularCms.Modules.Availability` is `--context AvailabilityDbContext` verplicht, omdat de API-startup-project meerdere `DbContext`-typen samenvoegt en de EF CLI anders niet kan bepalen welke bedoeld wordt.
|
||||
|
||||
## Nieuwe Module Toevoegen
|
||||
|
||||
Het systeem is ontworpen om eenvoudig uitgebreid te worden met nieuwe functionele modules. Volg deze stappen om een nieuwe module toe te voegen:
|
||||
@@ -169,6 +177,32 @@ dotnet add src\SlpModularCms.Api reference src\SlpModularCms.Modules.MijnNieuweM
|
||||
|
||||
De `ModuleOrchestrator` zal de module nu automatisch ontdekken en laden bij het opstarten.
|
||||
|
||||
## Master CMS Module
|
||||
|
||||
De `SlpModularCms.Modules.Master` module laat een Owner op één "Master"-CMS de beschikbaarheid van andere ("slave") CMS-instanties centraal beheren. Elke slave die de `SlpModularCms.Modules.Availability`-module draait, respecteert een master-gecontroleerde aan/uit-status naast zijn eigen lokale beschikbaarheidsschakelaar.
|
||||
|
||||
### Architectuur
|
||||
- **Master** (`SlpModularCms.Modules.Master`): eigen `MasterDbContext` met de `CmsInstance`-entiteit (URL, versleutelde API key, status). Bevat `CmsInstanceController` (`/CmsInstances`, Owner-only), `SlaveApiClient` (uitgaande HTTP-calls naar slaves) en `IntegrityCheckBackgroundService` (periodieke reconciliatie, standaard elk uur).
|
||||
- **Slave-extensie** (`SlpModularCms.Modules.Availability`): eigen `MasterRegistration`-entiteit, `MasterController` (interne endpoints onder `/api/v1/master/*`, buiten de beschikbaarheids-gate om) en een uitgebreide `AvailabilityMiddleware` die zowel de lokale als de master-gate evalueert.
|
||||
|
||||
### Registratie- en statusflow
|
||||
1. Owner voegt op de Master `/cms`-pagina een slave toe met diens URL.
|
||||
2. De Master genereert een API key, versleutelt deze (Data Protection) en slaat hem op bij de `CmsInstance`.
|
||||
3. De Master pusht de registratie naar de slave: `POST /api/v1/master/register` met header `X-Master-Api-Key`.
|
||||
4. Zet de Owner de status van een slave om (Available / NotAvailable / Inactive), dan pusht de Master dit synchroon door naar de slave.
|
||||
5. **Fail-open**: lukt de push niet, dan wordt de statuswijziging op de Master **niet** teruggedraaid — `IntegrityCheckBackgroundService` haalt de reconciliatie in tijdens de volgende cyclus (`MasterModuleOptions.IntegrityCheckIntervalMinutes`). Een slave die herstart voordat de Master opnieuw pusht, staat standaard weer open (`_masterIsAvailable = true` bij opstarten) — er is bewust geen TTL op de laatst bekende status.
|
||||
|
||||
### Configuratie
|
||||
Nieuwe sectie `MasterModule` in `appsettings.json` (zie ook `appsettings.Development.json`):
|
||||
```json
|
||||
"MasterModule": {
|
||||
"IntegrityCheckIntervalMinutes": 60,
|
||||
"HttpTimeoutSeconds": 10,
|
||||
"MasterUrl": "https://jouw-master-domein"
|
||||
}
|
||||
```
|
||||
- `MasterUrl` is de publieke URL van déze master-instantie, gebruikt door `IntegrityCheckBackgroundService` (buiten een HTTP-requestcontext heeft de background service geen `HttpContext` om dit uit af te leiden).
|
||||
|
||||
## Productie Setup
|
||||
|
||||
### 1. Build & Publish
|
||||
@@ -183,6 +217,10 @@ In productie moeten gevoelige instellingen worden doorgegeven via Environment Va
|
||||
- `JwtSettings__Secret`
|
||||
- `JwtSettings__Issuer`
|
||||
- `JwtSettings__Audience`
|
||||
- `MasterModule__MasterUrl` — publieke URL van deze master-instantie (alleen relevant als de Master CMS Module actief is)
|
||||
|
||||
### 2a. Data Protection key ring (Master CMS Module)
|
||||
De API keys van geregistreerde slaves worden versleuteld opgeslagen met ASP.NET Core Data Protection, standaard met een bestandssysteem-key-store. Voor gecontaineriseerde of multi-instance deployments **moet** een persistente key ring geconfigureerd worden (bijv. `PersistKeysToDbContext` of `PersistKeysToAzureBlobStorage`). Zonder dit worden alle opgeslagen API keys onleesbaar zodra de container herstart, waardoor master↔slave-communicatie stopt totdat instanties opnieuw worden toegevoegd.
|
||||
|
||||
### 3. Database
|
||||
Zorg dat de doeltabel bestaat en de migraties zijn uitgevoerd. In productie kan dit via een CI/CD pipeline worden afgehandeld met `dotnet ef migrations script` of door de applicatie bij startup migraties te laten draaien (indien geconfigureerd).
|
||||
|
||||
Reference in New Issue
Block a user