Files
slp-modular-cms/docs/hero-module.md
T
SluijsensandClaude Sonnet 5.5 a71db84632
Continuous Integration / config-sls (pull_request) Successful in 8s
Continuous Integration / changes (pull_request) Successful in 13s
Continuous Integration / frontend-prepare (pull_request) Skipped
Continuous Integration / frontend-build (pull_request) Skipped
Continuous Integration / frontend-test (pull_request) Skipped
Continuous Integration / frontend-lint (pull_request) Skipped
Continuous Integration / config-asf (pull_request) Successful in 5s
Continuous Integration / compile-sites (pull_request) Successful in 1m31s
Continuous Integration / vulnerability-scan (pull_request) Successful in 1m18s
Continuous Integration / backend-build (pull_request) Successful in 3m10s
Continuous Integration / publish-sls-test (pull_request) Canceled after 0s
Continuous Integration / publish-sls-production (pull_request) Canceled after 0s
Continuous Integration / deploy-sls-test (pull_request) Canceled after 0s
Continuous Integration / deploy-sls-production (pull_request) Canceled after 0s
Continuous Integration / publish-asf-test (pull_request) Canceled after 0s
Continuous Integration / deploy-asf-test (pull_request) Canceled after 0s
Continuous Integration / backend-test (pull_request) Canceled after 1m25s
Continuous Integration / smoke-sls-test (pull_request) Canceled after 0s
Continuous Integration / smoke-asf-test (pull_request) Canceled after 0s
Media: instelling Media:AutoCleanupUnattached (standaard true) om ongebruikte uploads te bewaren
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-17 14:17:28 +01:00

68 lines
9.5 KiB
Markdown

# Hero-module
Levend document (2026-11-16). De hero van een website (titel, tagline, lead, knoppen, afbeeldingen) staat in het CMS. Het CMS levert alleen **inhoud**; elke site houdt zijn eigen opmaak. Ontwerp en besluiten: `aidlc-docs/features/hero-module/`. Contract met de websites: `aidlc-docs/features/hero-module/inception/requirements/site-contract-agreed-with-asf.md`.
## Wat beheer je
Admin > **Hero** (Owner en Administrator, module `Hero`):
- Titel (een nieuwe regel is een regelafbreking, maximaal 5 regels), tagline, lead, weergave (`single` of `slideshow`).
- Maximaal twee knoppen met tekst en doel. Een doel is een `#anker`, een `/pad` of een `https://`-adres; andere waarden worden geweigerd.
- Geen planning en geen aan/uit voor de hero zelf (Bryan, 2026-11-17): de hero is onderdeel van het design en altijd aan. Hij is live zodra er een titel is; zonder hero-gegevens schrijft de host niets en toont de website zijn eigen ingebakken hero. Planning (later eventueel per slide) en een hero-brede aan/uit kunnen later terugkomen. Per slide blijft aan/uit bestaan.
- Slides: een afbeelding met verplichte beschrijving (alt-tekst) of de markering decoratief, volgorde, aan of uit per slide. Er is geen grens op het aantal slides; technisch publiceert de host er hoogstens `Hero:MaxPublishedSlides` (50).
- Focus: per afbeelding een algemeen punt en zoom, en optioneel een eigen punt voor de liggende (`wide`, 3:2) en de staande (`tall`, 4:5) weergave. De host snijdt de varianten daaromheen uit. **Een wijziging van het focuspunt geldt pas als je de hero opslaat** (Bryan, 2026-11-16): het focus-venster houdt de wijziging lokaal in de admin (knop Toepassen, een markering bij de slide); bij Opslaan gaat ze mee in dezelfde aanvraag (`imageFocus`); de host bewaart hero en focus direct (onder een seconde) en snijdt de varianten daarna op de achtergrond in nieuwe bestanden. De afbeelding schakelt over naar de nieuwe set zodra die compleet is; tot die tijd blijft de oude set in beeld. Verlaat je de pagina zonder op te slaan, dan vervalt de wijziging en is er niets aan de server veranderd. Mislukt een opslag nadat nieuwe bestanden zijn geschreven, dan verwijst niets ernaar en ruimt de opschoning ze na 7 dagen op; de oude bestanden blijven ook 7 dagen staan voor sites die nog oude data hebben.
De admin toont alleen een badge Live of Niet live.
## Wat de website krijgt
- `GET /api/v1/hero`: anoniem, `Cache-Control: public, max-age=60`, `204` als er niets te tonen is (dan blijft de ingebakken hero staan). Dezelfde JSON staat onder `hero` in het datablok `#cms-data`.
- Markers in de pagina: `<!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML-->` (titel, tagline, knoppen, eerste slide als `<picture>`) en `<!--CMS:HERO-PRELOAD-->…<!--/CMS:HERO-PRELOAD-->` in de head (een of twee preload-links). Alleen WebP komt in de eerste afbeelding en de preload. Zonder bruikbare hero, bij een fout of als de bestanden van de eerste slide ontbreken blijft de pagina zoals gebouwd.
- Afbeeldingen: `/media/hero/<set>/<ratio>-<breedte>.<webp|avif>`, onder het eigen adres van de site (de CSP verandert niet), `immutable` gecachet; een andere focus geeft een nieuw adres.
- De golden files van ASF (commit 13f78c4) leggen de HTML byte voor byte vast: `src/SlpModularCms.Modules.Hero.Tests/Golden`.
## Instellen op een host
| Instelling | Betekenis |
|---|---|
| `Media__Directory` | De map voor de afbeeldingen, **buiten de release** en buiten de webroot. Zonder deze instelling (of als de map niet beschrijfbaar is) staan uploads uit; bestaande bestanden en de publieke hero blijven werken. Niet in een committed appsettings-bestand. |
| `Media__MaxUploadBytes` (10 MB), `Media__MaxPixels` (64 miljoen), `Media__MaxParallelJobs` (2), `Media__DecodeTimeoutSeconds` (20), `Media__MaxTotalBytes` (2 GB), `Media__RetentionDays` (7), `Media__AutoCleanupUnattached` (standaard `true`; `false` bewaart ongebruikte uploads tot iemand ze verwijdert, voor de mediabibliotheek) | Grenzen en bewaartijd; standaardwaarden zijn bedoeld om te blijven. |
| `Hero__TextOnlyRegion` | `true` voor een site waarvan de hero geen afbeeldingen heeft (SLP Software; staat in de committed instellingen van die site): een hero zonder slides wordt dan als tekst (titelregels, lead, knoppen) in de eerste HTML geschreven. Uit (standaard, ook voor ASF): een hero zonder slides laat de pagina ongemoeid. |
| `Hero__TitlePrefix` | Merktekst die in de tekst-only-regio als eerste, visueel te verbergen deel van de h1 wordt geschreven (`<span class="cms-hero-title-prefix">`), zodat crawlers en schermlezers de volledige titel lezen. SLP Software: `"SLP Software: "` (committed instelling); leeg (standaard, ook ASF) schrijft niets. De site verbergt de klasse zelf visueel. |
| `Media__RenderSetTimeoutSeconds` (600), `Media__StripTimeoutSeconds` (60) | De tijd die het knippen van alle varianten van één foto in de achtergrond mag duren, en het verwijderen van metadata bij een upload. Ruim gekozen: een grote foto op een Raspberry Pi kost minuten. |
| `Hero__MaxPublishedSlides` | Technische bovengrens op het aantal gepubliceerde slides (standaard 50). |
| `RateLimiting__HeroPublic`, `__MediaPublic`, `__HeroUpload` | Snelheidsbeleid (standaard 120 per 60 s, 600 per 60 s, 100 uploads per uur per gebruiker: een reeks van 8-10 foto's mag de limiet niet opmaken). |
### Pi (test en later productie van SLP)
1. Eenmalig, als het service-account: `mkdir -p ~/apps/slpsoftware/<omgeving>/shared/media && chmod 700 ~/apps/slpsoftware/<omgeving>/shared/media` (voor ASF-test hetzelfde in zijn eigen map).
2. In `shared/env`: `Media__Directory=%h/apps/slpsoftware/<omgeving>/shared/media` (let op: systemd verwacht een volledig pad; vervang `%h` door het thuispad als de EnvironmentFile dat niet uitbreidt).
3. De map hoort bij de back-up van de site (het back-upscript van de database neemt hem niet mee).
4. Na de eerste deploy: kijk in het log naar `Image library Magick.NET self-test passed` (met de lijst formaten). Staat daar een fout, dan zijn uploads uitgezet en is de bibliotheek op deze machine niet bruikbaar (linux-arm64 is niet vooraf getest).
5. Het deployartefact is ongeveer 35 MB groter door de beeldbibliotheek; meet de grootte bij de eerste deploy tegen de uploadlimiet van de proxy.
### IIS (ASF-productie, later)
Een gegevensmap naast de site, buiten de webroot, waarin het account van de application pool mag schrijven. **Of dat op MijnHostingPartner kan, is nog niet getest** (Bryan test het met ASF). Faalt het, dan komt er een opslag in de database achter dezelfde koppeling (`IMediaStore`). De self-contained win-x64-publish bevat alleen `Magick.Native-Q8-x64.dll`.
## Startinhoud (alleen test)
```powershell
./scripts/Seed-Hero.ps1 -BaseUrl https://test.andreaslop.nl -ImagesDirectory <web/src/assets van de ASF-repository>
./scripts/Seed-Hero.ps1 -BaseUrl https://test.slpsoftware.nl -SeedFile ./scripts/hero-sls.json
```
`hero-asf.json` bevat de 8 huidige foto's met alt-teksten en een eerste schatting van de focuspunten (door de ASF-sessie); Bryan past ze aan in de admin. `hero-sls.json` is de huidige SLP-hero (alleen tekst, twee knoppen). Het script uploadt eerst alle foto's (de varianten worden daarna op de achtergrond gemaakt; het script wacht tot alles klaar is) (dezelfde foto is dezelfde afbeelding, dus een tweede run dupliceert niets) en slaat dan de hero in een keer op, met de focuspunten in dezelfde aanvraag (`imageFocus`): een focuspunt geldt pas bij het opslaan van de hero. Het slaat een CMS over dat al een hero heeft (`-Force` vervangt), vraagt het wachtwoord interactief (alleen voor een lokale host of testrun leest het `SEED_HERO_PASSWORD`) en gebruikt voor productie niets zonder Bryans go. Getest op PowerShell 7 en Windows PowerShell 5.1 tegen een lokale host, met de ASF-seed en `hero-sls.json`.
## Wat er achter de schermen gebeurt
- Verwerking op de achtergrond: een upload bewaart het origineel en geeft direct antwoord (`processing: true`, nog geen varianten, de afbeelding wordt niet gepubliceerd); `HeroRenderService` knipt de varianten, een afbeelding per keer (op een Raspberry Pi 4 ongeveer 25-30 s per foto), en pikt bij het opstarten en elke minuut werk op dat nog openstaat. Daardoor kapt de proxy-time-out (60 s) nooit een upload of een opslag af, en laat een afgebroken verzoek niets half bewaard achter (bestanden eerst, rij als laatste; een herhaling doet het gewoon opnieuw). De admin ververst zelf zolang er afbeeldingen worden verwerkt.
- Upload: echt bestandstype aan de inhoud (geen SVG), grenzen op bytes, pixels, tijd en gelijktijdigheid; metadata (GPS) uit het opgeslagen origineel en alle varianten; varianten per verhouding rond het focuspunt, nooit groter dan de bron, in WebP (en AVIF waar het platform dat kan). Dezelfde foto nog een keer is hetzelfde plaatje (en herstelt verloren bestanden).
- Oude bestanden (nieuwe focus, vervangen of ongebruikte foto) blijven 7 dagen en worden dan opgeschoond; een bestand dat nog gebruikt wordt, verdwijnt nooit.
- Ondersteunde invoer: JPEG, PNG, WebP, GIF, BMP, TIFF en AVIF; HEIC alleen als aangegeven mogelijkheid van de bibliotheek (nog niet met een echt bestand getest).
## Controleren na een deploy
- `scripts/smoke-site.sh` (in de CI na elke test-deploy): module `Hero` geladen, `GET /api/v1/hero` is 200 of 204, het beheer is beschermd, een niet-bestaand mediaadres is een gewone 404.
- LCP: Lighthouse (mobiel profiel) op de testsite vóór en na het plaatsen van de markers in de website; de LCP van de gerenderde pagina mag niet slechter zijn dan die van de ingebakken pagina en de hero veroorzaakt geen layoutverschuiving (`width` en `height` staan op de afbeelding). Zie `release-checklist-productie.md`.