Functional design, NFR requirements, code generation plan and summary, and build-and-test instructions with results. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
100 lines
6.6 KiB
Markdown
100 lines
6.6 KiB
Markdown
# NFR Requirements Plan — frontend-shell
|
|
|
|
Unit: **frontend-shell**. Builds on requirements NFR-01…NFR-06 and the approved functional design. NFR Design is skipped (execution plan); the patterns are small and go straight into this document and the code generation plan.
|
|
|
|
## Plan
|
|
|
|
- [x] 1. Answer the questions below
|
|
- [x] 2. Analyze answers for ambiguities (follow-up questions if needed)
|
|
- [x] 3. Generate `nfr-requirements.md` — measurable NFRs per category: performance, accessibility, SEO, security, reliability, maintainability/testing, browser support; scalability/availability marked N/A with rationale
|
|
- [x] 4. Generate `tech-stack-decisions.md` — test stack (PBT-09), linting, security headers/CSP, build plugins, dependency changes with rationale
|
|
- [x] 5. Validate against Security Baseline (SECURITY-04, -09, -10, -13, -15) and PBT-09
|
|
|
|
## Already decided (no question needed)
|
|
|
|
- **Scalability and availability**: N/A for the shell. It is a static site without a server; availability depends on the future host (Operations).
|
|
- **Test stack** (NFR-03, PBT-09): Vitest + React Testing Library + `@testing-library/user-event` + `jsdom` + fast-check. fast-check covers custom generators, shrinking and seed-based replay, and runs inside Vitest. The seed is printed on failure and can be passed back to replay a run.
|
|
- **Security headers** (NFR-04): `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` and HSTS `max-age=31536000; includeSubDomains`. Browsers ignore HSTS over plain `http://localhost`, so locally it has no effect; it matters on the production host.
|
|
- **CSP content for the production build**: `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`.
|
|
- `style-src 'unsafe-inline'` is needed because Chakra/Emotion inject `<style>` tags at runtime (justified).
|
|
- The JSON-LD block is a data block (`application/ld+json`). It is not executed and needs no CSP exception.
|
|
- **Router devtools**: only loaded in development (`import.meta.env.DEV`), so they are not in the production bundle (SECURITY-09 hardening). `@tanstack/react-router-devtools` moves to `devDependencies`.
|
|
- **Sitemap plugin**: a local plugin in the Vite config; no extra dependency. `vite.config.js` becomes `vite.config.ts`, so it can import the typed `sitePages` registry and get type checking.
|
|
|
|
---
|
|
|
|
## Questions
|
|
|
|
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe. Waar ik een voorkeur heb staat **(aanbevolen)**.
|
|
|
|
### Vraag 1: Content-Security-Policy tijdens het ontwikkelen
|
|
|
|
De strenge CSP hierboven werkt op de gebouwde site (`pnpm preview`). De dev-server (`pnpm dev`) heeft voor hot reload een inline script en een websocket nodig. Een strenge CSP breekt daar het herladen.
|
|
|
|
A) Strenge CSP op `preview` (en als voorschrift voor productie). In `dev` dezelfde CSP, maar met alleen de uitzonderingen die Vite nodig heeft (inline script voor React Refresh, websocket voor HMR). De overige headers zijn in beide gelijk. **(aanbevolen)** Je ziet CSP-problemen dan al tijdens het ontwikkelen, behalve die van Vite zelf.
|
|
B) Alleen op `preview` een CSP; `dev` zonder CSP
|
|
X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
|
|
|
[Answer]: A
|
|
|
|
### Vraag 2: `next-themes` (wisselen tussen licht en donker)
|
|
|
|
De site staat vast op licht (`defaultTheme="light"`, `enableSystem={false}`). `next-themes` doet nu dus niets nuttigs. Wel zet het een inline script in de pagina, en dat botst met een strenge CSP (`script-src 'self'`).
|
|
|
|
A) `next-themes` verwijderen en de site vast op licht zetten. Het thema houdt zijn `_dark`-waarden, zodat een donkere modus later weer kan. **(aanbevolen)** Eén afhankelijkheid minder, en geen CSP-uitzondering nodig.
|
|
B) Houden voor een mogelijke donkere modus later, en het script via een hash in de CSP toestaan
|
|
X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
|
|
|
[Answer]: A
|
|
|
|
### Vraag 3: Meetbare doelen voor kwaliteit
|
|
|
|
A) Lighthouse (mobiel) ≥ 90 voor Performance en 100 voor Accessibility, Best Practices en SEO, op de gebouwde site (`pnpm preview`). Handmatig gemeten bij Build and Test. **(aanbevolen)**
|
|
B) Hetzelfde, maar automatisch bij elke build (Lighthouse CI). Meer opzetwerk, en zonder CI-server draait het alleen lokaal.
|
|
C) Geen harde doelen, alleen de regels uit het functional design
|
|
X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
|
|
|
[Answer]: B
|
|
|
|
### Vraag 4: Automatisch testen op toegankelijkheid
|
|
|
|
A) `axe-core` in de componenttests (via `vitest-axe`): elke shell-, placeholder-, 404- en foutpagina-test controleert ook op toegankelijkheidsfouten. Contrast controleert axe in `jsdom` niet; dat dekt Lighthouse (vraag 3) af. **(aanbevolen)**
|
|
B) Geen automatische controle, alleen handmatig met Lighthouse en een schermlezer
|
|
X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
|
|
|
[Answer]: A
|
|
|
|
### Vraag 5: Linting
|
|
|
|
Er is nu alleen Prettier (opmaak), geen linter die fouten in code vindt.
|
|
|
|
A) ESLint toevoegen met de aanbevolen regels voor TypeScript, React Hooks en `jsx-a11y` (toegankelijkheid in JSX), plus een `lint`-script **(aanbevolen)** Vangt bv. vergeten `alt`-teksten en fouten met hooks al tijdens het schrijven.
|
|
B) Geen linter in deze feature
|
|
X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
|
|
|
[Answer]: A
|
|
|
|
### Vraag 6: Welke browsers ondersteunen we?
|
|
|
|
A) De laatste 2 versies van Chrome, Edge, Firefox en Safari, plus Safari op iOS 16 en nieuwer. Dat dekt vrijwel alle bezoekers; oudere browsers krijgen de site zonder garantie. **(aanbevolen)**
|
|
B) Ruimer: ook oudere browsers (bv. iOS 14), met extra fallbacks voor nieuwere CSS
|
|
X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
|
|
|
[Answer]: Begin met optie A. B zou later nog kunnen met name voor de mobiele versies.
|
|
|
|
### Vraag 7: Testdekking
|
|
|
|
A) Geen harde drempel voor de hele code, wel 100% dekking van de pure functies (`backToTopThreshold`, `visibleSocials`, `emailAddress`, `copyrightLine`, `canonicalUrl`, `sitemapXml`, `jsonLdScript`). De dekking wordt gerapporteerd bij `pnpm test`. **(aanbevolen)**
|
|
B) Een drempel voor de hele code (bv. 80% van de regels), die de tests laat falen als hij niet gehaald wordt
|
|
X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
|
|
|
[Answer]: A
|
|
|
|
### Vraag 8: Controle op kwetsbare afhankelijkheden
|
|
|
|
A) Een script `pnpm audit:deps` (`pnpm audit --audit-level high`) plus een `check`-script dat lint, tests, build en audit achter elkaar draait. Dit is de controle vóór elke release, en later de basis voor CI. **(aanbevolen)**
|
|
B) Alleen documenteren dat `pnpm audit` handmatig gedraaid moet worden
|
|
X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
|
|
|
[Answer]: A
|