Adds the prerendering requirements, design and baseline

Records the requirements, execution plan, application design, the first unit's
functional design and code generation plan, and the baseline on master.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-31 17:41:12 +01:00
co-authored by Claude Opus 5.5
parent c4c2f83d6c
commit 65c850e949
22 changed files with 2569 additions and 0 deletions
@@ -0,0 +1,42 @@
# Verduidelijkingsvragen: prerendering
Twee van je antwoorden hebben nog een keuze nodig voordat ik de requirements kan schrijven. Je overige antwoorden zijn verwerkt.
## Tegenstrijdigheid 1: TanStack Start en de CSP
Je koos TanStack Start (vraag 2, B). Een vast uitgangspunt was dat de CSP ongewijzigd blijft. Die twee botsen, zoals een kleine proef-app laat zien: TanStack Start 1.169.4 met Chakra, getest in Chrome met onze `script-src`.
**Wat de proef liet zien:**
- **Statische HTML werkt:** Start maakt per pagina een HTML-bestand met de inhoud en de Chakra-stijlen, zonder Node-server. De bestanden komen in `dist/client` te staan, dus CI en deployment moeten mee veranderen.
- **Inline scripts:** elke pagina krijgt twee inline scripts. Het eerste bevat paginagegevens, waardoor de hash per pagina verschilt.
- **Met onze huidige CSP breekt de site:** de browser blokkeert de scripts, de app crasht en de inhoud verdwijnt van het scherm.
- **Scripts in eigen bestanden werken:** als een stap na de build die scripts naar eigen bestanden in `/assets` verplaatst, blijft de CSP gelijk. De knop en de link werkten dan, zonder CSP-meldingen.
- **Meer JavaScript:** de hoofdbundel van de proef is 165 kB gzip, bijna zonder eigen code. De huidige site, inclusief al zijn code, is ongeveer 149–153 kB. Dit is een grove vergelijking, maar Start lijkt de bundel groter te maken, en dat werkt tegen het Lighthouse-doel van vraag 7.
### Verduidelijkingsvraag 1
Hoe lossen we dit op?
- A) Start gebruiken, met een stap na de build die de inline scripts naar eigen bestanden verplaatst. De CSP blijft gelijk. Nadeel: we leunen op hoe Start zijn scripts schrijft, dus een test moet dit bij elke upgrade bewaken, en elke pagina krijgt twee kleine extra verzoeken. Aanbevolen als je bij Start wilt blijven; dit is ook in de proef bewezen.
- B) Start gebruiken en de hashes van alle pagina's in de CSP zetten. Geen extra verzoeken, maar de CSP verandert bij elke inhoudswijziging, en de nginx-config op de Pi moet nu met de hand worden bijgewerkt. Dat is dus niet praktisch zonder ook die config te automatiseren.
- C) Toch de eigen Vite-build-stap (vraag 2, A). Geen inline scripts en waarschijnlijk minder JavaScript, maar geen standaardframework. Dit is ook de beste optie als de score het zwaarst weegt.
- D) `'unsafe-inline'` toestaan in `script-src`. Het is het eenvoudigst, maar verzwakt de bescherming tegen XSS en vraagt een gedocumenteerde uitzondering op SECURITY-04. Niet aanbevolen.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Onduidelijkheid 1: wat doet de build-trigger?
Je koos ervoor nu al een manier in te bouwen om de build van buitenaf te starten (vraag 8, B). De CI-workflow heeft al een handmatige start (`workflow_dispatch`) met de keuzes `deploy_test` en `deploy_production`. Productie kan daarmee alleen vanaf een `release/*`-branch. Nog niet duidelijk is hoe ver een trigger mag gaan.
### Verduidelijkingsvraag 2
Wat moet een trigger van buitenaf kunnen?
- A) De bestaande `workflow_dispatch` hergebruiken en documenteren: een aanroep met een token met zo min mogelijk rechten bouwt en zet het resultaat op test. Productie blijft een handmatige stap. Aanbevolen: er komt niets nieuws bij om te beveiligen, en er gaat niets ongezien live. Of onze Gitea-versie deze aanroep ondersteunt, controleer ik nog.
- B) Zoals A, maar de trigger mag ook naar productie deployen, na de bestaande controles en Lighthouse. Een wijziging in het CMS staat dan automatisch live, maar het token wordt gevoeliger en de `release/*`-regel moet worden aangepast.
- C) Een eigen webhook-endpoint dat de build start. Dit vraagt een server die openbaar bereikbaar is, en die hebben we nu niet.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: x, moet er van buiten getriggert worden? Front-end triggeren is voor nu prima want pagina-teksten worden grotendeels vast. de CMS zal alleen gallerijen, pakketten etc doen, maar de belangrijkste teksten worden mogelijk niet aanpasbaar in het CMS. Als dat wel zo is kunnen we tegen die tijd kijken hoe we dat gaan doen