CMS: één bannerlijst met Locatie, SLP-thema, thema-schakelaar, documentatie

- Banner-admin: één lijst met Locatie-badge (Boven/Onder), Locatie-keuzeveld in het formulier, "Live" en "Wordt niet getoond" per locatie, aan/uit per rij
- Thema slpsoftware: Archivo, bordeaux #7A1414 (WCAG AA licht en donker), <SLP/>-logo, favicon, mail-logo; VITE_THEME in de SLP-builds (test en productie-config)
- Thema-schakelaar: eerste klik wisselt altijd het getoonde thema (klasse op <html> als bron van waarheid, gedeelde status, startscript valideert opslag) + tests
- Docs: README, docs/cms-themas.md, docs/deploy-en-testomgevingen.md, docs/privacy-gegevens-contactformulier.md, aidlc-docs (offering-banners, bug theme-toggle-first-click)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 00:14:10 +01:00
co-authored by Claude Sonnet 5.5
parent 4b09089ffb
commit 321234dfa6
28 changed files with 1081 additions and 242 deletions
+35 -4
View File
@@ -5,8 +5,8 @@ Een modulaire monolith CMS gebouwd met .NET 10.
## Projectstructuur
- `src/SlpModularCms.Api`: De host applicatie en API shell (lokale ontwikkeling / dev-host).
- `src/SlpModularCms.Api.SlpSoftware`: Tweede Client-project, de daadwerkelijk gedeployde API voor `test.slpsoftware.nl`/`slpsoftware.nl` (CI/CD-cutover vanaf `SlpModularCms.Api`). Host dezelfde modules als `SlpModularCms.Api` via dezelfde gedeelde `CmsHost`-compositie (zie hieronder), plus de `Offerings`-module. Heeft een eigen, geïsoleerde lokale ontwikkeldatabase — zie `appsettings.Development.json` in dat project.
- `src/SlpModularCms.Api.AndreaSlopFotografie`: Derde Client-project voor Andrea Slop Fotografie (testomgeving `test.andreaslop.nl`). Host alleen de modules `Identity` en `Availability` (geen `Master`, geen `Offerings`) en serveert de voorgerenderde website uit `wwwroot/web/` (`WebsiteMode.PrerenderedPages`) plus de admin met het thema `asf` op `/admin`. Lokaal op poort `5200`, eigen database (`appsettings.Development.json`). Bijbehorende tests: `SlpModularCms.Api.AndreaSlopFotografie.Tests` (de pipelinetests daarin hebben net als `Api.Tests` een bereikbare MariaDB nodig).
- `src/SlpModularCms.Api.SlpSoftware`: Tweede Client-project, de daadwerkelijk gedeployde API voor `test.slpsoftware.nl`/`slpsoftware.nl` (CI/CD-cutover vanaf `SlpModularCms.Api`). Host dezelfde modules als `SlpModularCms.Api` via dezelfde gedeelde `CmsHost`-compositie (zie hieronder), plus de `Offerings`- en `Contact`-module. Heeft een eigen, geïsoleerde lokale ontwikkeldatabase — zie `appsettings.Development.json` in dat project.
- `src/SlpModularCms.Api.AndreaSlopFotografie`: Derde Client-project voor Andrea Slop Fotografie (testomgeving `test.andreaslop.nl`). Host de modules `Identity`, `Availability`, `Offerings` en `Contact` (geen `Master`) en serveert de voorgerenderde website uit `wwwroot/web/` (`WebsiteMode.PrerenderedPages`) plus de admin met het thema `asf` op `/admin`. Lokaal op poort `5200`, eigen database (`appsettings.Development.json`). Bijbehorende tests: `SlpModularCms.Api.AndreaSlopFotografie.Tests` (de pipelinetests daarin hebben net als `Api.Tests` een bereikbare MariaDB nodig).
- `src/SlpModularCms.Core`: Kern functionaliteiten, data modellen en interfaces. Bevat ook `Core/Hosting/CmsHost.cs` — de gedeelde service- en pipeline-compositie die elk Client-project (`Api`, `Api.SlpSoftware`) vanuit zijn eigen dunne `Program.cs` aanroept, zodat beide projecten niet uit elkaar kunnen groeien.
- `src/SlpModularCms.Modules.*`: Onafhankelijke functionele modules.
- `frontend/`: De CMS admin web-UI (Vite + React + TypeScript). Bewust buiten `src/` gehouden om de .NET solution schoon te houden.
@@ -105,7 +105,7 @@ De frontend leest de API-basis-URL uit een environment-variabele (zie `frontend/
```
VITE_API_BASE_URL=http://localhost:5000
```
Per site kan de admin bij het bouwen een thema en standaardtaal krijgen: `VITE_THEME=asf` kiest `frontend/themes/asf/theme.css` (alleen CSS-variabelen, zelf gehoste lettertypen via `@fontsource`, plus een eigen favicon; een onbekende themanaam laat de build falen, leeg of afwezig = het standaardthema) en `VITE_DEFAULT_LANGUAGE=nl` (of `en`) bepaalt de taal zolang de gebruiker nog niets koos; een opgeslagen keuze wint altijd.
Per site kan de admin bij het bouwen een thema en standaardtaal krijgen (beschikbare thema's: `asf` en `slpsoftware`, zie [docs/cms-themas.md](docs/cms-themas.md)): `VITE_THEME=asf` kiest `frontend/themes/asf/theme.css` (alleen CSS-variabelen, zelf gehoste lettertypen via `@fontsource`, plus een eigen favicon; een onbekende themanaam laat de build falen, leeg of afwezig = het standaardthema) en `VITE_DEFAULT_LANGUAGE=nl` (of `en`) bepaalt de taal zolang de gebruiker nog niets koos; een opgeslagen keuze wint altijd.
Kopieer `.env.example` naar `.env.local` en pas de waarde aan indien nodig. Optioneel kan met `VITE_ENABLE_MSW=true` de MSW-mockbackend in de browser worden ingeschakeld voor frontend-ontwikkeling zonder draaiende API.
@@ -250,6 +250,37 @@ Zolang de master-gate een slave op `NotAvailable` heeft gezet (via push of pull)
- Een lokale poging om de status alsnog te wijzigen (bijv. via een directe API-call) wordt door de backend geweigerd met `409 Conflict` (`MasterControlledAvailabilityException` in `PersistentAvailabilityService.UpdateStatusAsync`) — de master-gate kan dus niet per ongeluk of expres lokaal worden omzeild.
- `GET /api/v1/Availability/status` geeft dit door via het veld `isMasterControlled`.
## Offerings: aanbiedingen en banner
De module `SlpModularCms.Modules.Offerings` (gehost door `Api.SlpSoftware` en `Api.AndreaSlopFotografie`) beheert de aanbiedingen (pakketten, met categorieën) en de banner van de website. Hieronder alleen de banner; details en beslissingen staan in `aidlc-docs/features/offering-banners/overview.md`.
Een banner heeft een **positie**: `top` (smalle balk boven de pagina, één regel) of `bottom` (grote banner; bestaande banners zijn via migratie `20261114100000_AddOfferingBannerPosition` `bottom` geworden).
**Publiek:** `GET /api/v1/offerings/banner?position=top|bottom`
- Zonder `position` geldt `bottom`; een andere waarde geeft `400`.
- `204` zonder actieve banner; anders `200` met `title`, `text`, `linkLabel`, `linkUrl`, `position` (geen planning).
- Anoniem, rate limit `offerings-public` (standaard 120 per 60 s per clientadres, `RateLimiting:OfferingsPublic`), antwoord met `Cache-Control: public, max-age=60`.
**Beheer:** `/api/v1/offerings/banners` (`GET`, `POST`, `PUT {id}`, `DELETE {id}`), alleen voor beheerders (`AdminOnly`).
**Velden en validatie:** `top`: tekst max 120 tekens, titel optioneel. `bottom`: titel verplicht (max 100), tekst max 300. Knoptekst (max 50) en link (max 500) alleen samen; een link is `https://…` of een pad dat met één `/` begint. `endsAt` moet na `startsAt` liggen. `isActive` en de planning (`startsAt`/`endsAt`) bepalen of een banner meetelt.
**"Maximaal één per positie"** geldt bij het uitlezen: je kunt meer banners opslaan en aanzetten; per positie wint de laatst gewijzigde actieve banner die binnen zijn van/tot valt. Een boven- en een onderbanner kunnen dus tegelijk getoond worden.
**Admin** (tabblad Banner bij Aanbiedingen): één lijst met een badge Locatie (Boven/Onder), de status (Actief, Gepland, Verlopen, Uit), de markeringen "Live" (wordt getoond) en "Wordt niet getoond" (actief, maar een nieuwere banner op dezelfde locatie wint), en een aan/uit-knop per rij. Het formulier heeft een keuzeveld Locatie dat de tekstlimiet en de titelplicht aanpast.
## Contactformulier-module
De module `SlpModularCms.Modules.Contact` (gehost door `Api.SlpSoftware` en `Api.AndreaSlopFotografie`; tests in `SlpModularCms.Modules.Contact.Tests`) ontvangt berichten van het contactformulier van een website, slaat ze op, mailt een melding naar de eigenaar en laat beheerders ze in de admin (Berichten) beheren. Plan en beslissingen: `aidlc-docs/features/contact-forms-module/`. Welke gegevens worden bewaard, hoe lang en wat in logs en Sentry terechtkomt: [`docs/privacy-gegevens-contactformulier.md`](docs/privacy-gegevens-contactformulier.md).
- **Uit tenzij beide schakelaars aan staan:** de hostschakelaar `Contact:Enabled` (standaard `false` in beide `appsettings.json`) én de CMS-schakelaar bij Berichten. Is het formulier niet open, dan bestaan de publieke routes niet (404). De migraties van de module worden pas bij het opstarten toegepast als `Contact:Enabled` aan staat.
- **Publiek:** `GET /api/v1/contact-messages/token` (tijdtoken, plus eventuele captcha-gegevens) en `POST /api/v1/contact-messages` (JSON, header `Idempotency-Key` met een GUID; antwoord `202`; fouten `400` in `ProblemDetails`-vorm met veldcodes `required`, `tooLong`, `invalid`, `expired`).
- **Beheer** (`AdminOnly`): `GET /api/v1/contact-messages`, `GET`/`PATCH`/`DELETE …/{id}`, `POST …/{id}/resend`, en `GET`/`PUT /api/v1/contact-settings` (schakelaar) met `PUT …/contact-settings/recipient` (ontvangstadres).
- **Anti-spam:** honeypot, minimumtijd tussen token en verzenden, optioneel Friendly Captcha, rate limiting per clientadres (`RateLimiting:ContactForm`, `ContactToken`, `ContactResend`). Achter een reverse proxy moet `ForwardedHeaders__KnownProxies__0` gezet zijn, anders delen alle bezoekers één limiet.
- **Configuratie (sectie `Contact`):** `Enabled`, `SiteId`, `MinSeconds` (3), `TokenLifetimeMinutes` (120), `RetentionMonths` (12), `SpamRetentionDays` (30), `MaxSpamRowsPerDay` (200), `MaxBodyBytes` (16384), `ProblemTypeBase`, `RecipientEmail` (alleen via omgevingsvariabele `Contact__RecipientEmail`), `Mail:SweepSeconds`/`MaxAttempts`/`BackoffMinutes`/`ClaimMinutes`/`BatchSize`, en `Captcha:Enabled`/`Provider` (`friendlycaptcha`)/`SiteKey`/`Secret` (alleen via `Contact__Captcha__Secret`)/`Region` (`global` of `eu`)/`VerifyUrl`/`TimeoutSeconds`. Een aangezet captcha met ontbrekende of ongeldige instellingen laat de host bij opstarten falen.
- **Opschonen:** een dagelijkse achtergrondtaak verwijdert berichten na hun bewaartermijn en idempotentie-gegevens na 24 uur.
- **Mail:** vereist werkende e-mailconfiguratie (zie "E-mail" hierboven) en een ontvangstadres; anders blijft het bericht bewaard met de reden bij het bericht.
## Lokaal Master + Slave Draaien (Dev)
Om de master↔slave-connectie (zie "Master CMS Module" hierboven) lokaal te kunnen testen, kun je twee backend-instanties tegelijk draaien: een volledige "master" (met de `SlpModularCms.Modules.Master`-module) en een "slave"-instantie zonder die module. Dit is puur een lokale ontwikkel-/testopstelling — er is geen nieuwe functionaliteit aan de master/slave-protocol zelf toegevoegd.
@@ -324,7 +355,7 @@ Ontbreekt `wwwroot/web/` nog (een verse deployment vóórdat een website-workspa
Voor lokale ontwikkeling verandert er niets: `pnpm dev` blijft op `http://localhost:5173` draaien zonder `/admin`-prefix.
### 1. Build & Publish
Publiceren gebeurt via de Gitea Actions-pipeline (`.gitea/workflows/continuous_integration.yaml` → `deploy-scp.yaml`), niet met een losse handmatige `dotnet publish`-stap: elke push naar `master` deployt automatisch naar test, productie alleen via een expliciete `workflow_dispatch` met de `deploy_production`-vlag aan. De pipeline publiceert framework-dependent voor `linux-arm64` en bouwt daarbij automatisch ook de admin-frontend mee naar `wwwroot/admin/`.
Publiceren gebeurt via de Gitea Actions-pipeline (`.gitea/workflows/continuous_integration.yaml` → `deploy-scp.yaml`), niet met een losse handmatige `dotnet publish`-stap: elke push naar `master` deployt automatisch naar de SlpSoftware-testomgeving (en naar de ASF-testomgeving als de Gitea-variabele `ASF_TEST_DEPLOY_ENABLED` op `true` staat), productie alleen via een expliciete `workflow_dispatch` met de `deploy_production`-vlag aan. Een branch naar test deployen kan met een handmatige run (`deploy_test` en/of `deploy_asf_test`). Zie [`docs/deploy-en-testomgevingen.md`](docs/deploy-en-testomgevingen.md) voor invoer, testhosts, vereiste variabelen en secrets (alleen namen) en rollback. De pipeline publiceert framework-dependent voor `linux-arm64` en bouwt daarbij automatisch ook de admin-frontend mee naar `wwwroot/admin/`.
Elke deploy plaatst de nieuwe release in een verse map en wisselt pas daarna atomisch over naar `current` — er is dus nooit een moment waarop de applicatie een halfklare release serveert, en `wwwroot/web/` (de klantsite) staat structureel buiten die verwisselde map, zodat een deploy hem nooit kan raken. Volledige host-setup, rollback-procedure en de exacte deploy-stappen staan in de Operations-documentatie van deze feature, niet hier — dit README beschrijft alleen wat er gebouwd is, niet hoe je het voor het eerst inricht.