Adds the AI-DLC documents of the CMS and API foundation feature
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
+148
@@ -0,0 +1,148 @@
|
||||
# Vragen bij de requirements: cms-api-foundation
|
||||
|
||||
Vul achter elke `[Answer]:` de letter van je keuze in. Past geen enkele optie, kies dan de laatste (Anders) en licht je keuze toe. Bij elke vraag staat welke optie ik aanbeveel en waarom.
|
||||
|
||||
**Wat deze feature is:** de basis waarop Andrea's site straks op de SlpModularCms draait. Dus: een eigen client-project voor Andrea (zoals `Api.SlpSoftware`), een vast thema per site, een instelbare set modules per site, en de CMS-host die zowel de admin als de geprerenderde site serveert. Pakketten, contactformulier, testimonials en shoot-pagina's zijn aparte, latere features.
|
||||
|
||||
**Vaste uitgangspunten, hierover hoef je niets te beslissen** (uit je antwoorden):
|
||||
|
||||
- Meerdere sites = één deployment en één database per site; de modules per site bepaal je met de DLL-referenties van de client (aangepast in het ontwerp).
|
||||
- Het thema staat vast per site en wordt niet in de admin aangepast.
|
||||
- De CMS-host serveert admin (`/admin`), API (`/api/v1`) en de site (`/`); er is maar ruimte voor één website op de host.
|
||||
- Dit werk raakt de bestanden van de Testimonials-sessie niet.
|
||||
|
||||
## Vraag 1
|
||||
|
||||
Wat hoort er in deze feature bij het "de CMS serveert de site" deel aan de kant van deze (web)repo?
|
||||
|
||||
- A) Alleen de CMS-kant: een brief en bewaking van het resultaat. De omschakeling van de huidige hosting (nginx test, IIS productie) en de CI van de site volgt in een eigen feature.
|
||||
- B) CMS-kant én de web-kant: de site-build wordt bij de deploy in `wwwroot/web/` van de CMS-host gezet, de CI van de web-repo wordt daarop aangepast en op test is de omschakeling bewezen. Aanbevolen: de feature is pas af als de keten werkt, en de web-kant is klein.
|
||||
- C) CMS-kant plus web-kant tot en met productie.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Vraag 2
|
||||
|
||||
Hoe moet de CMS-host de geprerenderde pagina's serveren? Nu is er een SPA-fallback: een pad zonder extensie (`/over-mij`) krijgt `index.html`. Onze build maakt per pagina een eigen HTML-bestand, en een onbekend pad moet de echte 404-pagina met status 404 krijgen.
|
||||
|
||||
- A) De host krijgt een "geprerenderde site"-modus: eerst `{pad}.html` of `{pad}/index.html`, anders de 404-pagina met status 404. Aanbevolen: dit geeft de bezoeker de snelle HTML en de SEO-winst van de prerendering echt.
|
||||
- B) De bestaande SPA-fallback blijft: elke pagina laadt `index.html` en React rendert daarna. Dan verdwijnt het voordeel van de prerendering.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A (prerender-modus nu). User note: wants SSR eventually to be independent of the build pipeline; asked whether Node runs on mijnhostingpartner.nl (unknown, to be checked by the user). Decision: prerender-modus now, SSR vs hybrid decided before the first content feature.
|
||||
|
||||
## Vraag 3
|
||||
|
||||
De site heeft nu strenge beveiligingsheaders (CSP uit `web/config/securityHeaders.ts`). De CMS geeft de site standaard het mildere `Relaxed`-beleid.
|
||||
|
||||
- A) De CMS-host krijgt een instelling waarmee het client-project de CSP voor `/` zelf kan bepalen, en Andrea's client gebruikt dezelfde strenge CSP als nu. Aanbevolen: geen beveiligingsachteruitgang bij de omschakeling.
|
||||
- B) We accepteren het `Relaxed`-beleid voor de site.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 4
|
||||
|
||||
Hoe wordt het thema per site vastgelegd?
|
||||
|
||||
- A) In het client-project (configuratie of een vast bestand), dat de API aanbiedt; de admin leest het bij het opstarten en zet het als CSS-variabelen. Eén admin-build voor alle sites. Aanbevolen.
|
||||
- B) Een aparte admin-build per site met het thema ingebakken.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: X: admin build per site where only a theme file is specified (user proposal; styling does not belong in the API). Theme files live in the CMS repo, selected at build time, no theme API.
|
||||
|
||||
## Vraag 5
|
||||
|
||||
Wat moet het thema per site kunnen bepalen?
|
||||
|
||||
- A) Kleuren (de bestaande tokens), hoekafronding, lettertype, logo/app-naam en favicon. Aanbevolen: genoeg om aan te sluiten op Andrea's site, zonder overbodige vrijheid.
|
||||
- B) Alleen kleuren en logo/app-naam.
|
||||
- C) Alles uit A plus eigen CSS per site.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 6
|
||||
|
||||
Welke modules staan voor Andrea aan in deze feature? (Master is voor het beheren van andere CMS-instanties; Availability hoort bij de master-status.)
|
||||
|
||||
- A) Alleen wat voor een werkende admin nodig is (Identity en wat de CMS-host verplicht stelt); `Offerings` staat uit. Zo bewijst het verschil met SlpSoftware dat de schakelaar werkt. Aanbevolen.
|
||||
- B) Identity plus `Offerings` aan, zodat de pakketten-feature er direct op kan aansluiten.
|
||||
- C) Alles aan, net als de bestaande Api-host.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A (this feature = step 0; Offerings is switched on in the packages feature)
|
||||
|
||||
## Vraag 7
|
||||
|
||||
Wie zijn de gebruikers van Andrea's CMS in deze feature?
|
||||
|
||||
- A) Zoals nu: een eerste beheerder via de setup-flow en daarna uitnodigingen. Geen nieuwe rollen. Aanbevolen: auth bestaat al en hoeft hier niet opnieuw ontworpen.
|
||||
- B) Er komen rollen bij (bijvoorbeeld beheerder en alleen-lezen).
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 8
|
||||
|
||||
Welke taal heeft de admin standaard voor Andrea? De admin kent NL en EN.
|
||||
|
||||
- A) Nederlands standaard, Engels blijft kiesbaar; de standaardtaal wordt per site vastgelegd. Aanbevolen.
|
||||
- B) Engels standaard, zoals nu.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 9
|
||||
|
||||
Op welke omgevingen komt Andrea's CMS-instantie in deze feature?
|
||||
|
||||
- A) Eerst alleen test (de Pi, via de bestaande Gitea-deploy van de CMS-repo); productie volgt als de keten bewezen is. Aanbevolen.
|
||||
- B) Test en productie.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 10
|
||||
|
||||
Hoe werk ik met de CMS-sessie (`AndreaSlopFotografie`) samen?
|
||||
|
||||
- A) Hybride: web-vragen beantwoord ik zelf uit de repo en het design. Beslissingen over CMS-interne zaken, security en datamodel leg ik aan jou voor. Jij keurt de requirements en het ontwerp van de CMS-kant goed. Aanbevolen.
|
||||
- B) Ik beantwoord alles wat ik uit de context kan afleiden, houd een besluitenlijst bij en jij keurt alleen het eindresultaat goed.
|
||||
- C) Alle vragen van de CMS-sessie gaan naar jou.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 11: Beveiligingsextensies
|
||||
|
||||
Moeten de beveiligingsregels als harde vereisten worden afgedwongen voor dit project?
|
||||
|
||||
- A) Ja: dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten (aanbevolen voor productietoepassingen)
|
||||
- B) Nee: sla alle BEVEILIGINGSREGELS over (geschikt voor PoC's, prototypes en experimentele projecten)
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 12: Property-Based Testing Extensie
|
||||
|
||||
Moeten de property-based testing (PBT) regels worden afgedwongen voor dit project?
|
||||
|
||||
- A) Ja: dwing alle PBT-regels af als blokkerende vereisten (aanbevolen voor projecten met bedrijfslogica, datatransformaties, serialisatie of stateful componenten)
|
||||
- B) Gedeeltelijk: dwing PBT-regels alleen af voor pure functies en serialisatie round-trips (geschikt voor projecten met beperkte algoritmische complexiteit)
|
||||
- C) Nee: sla alle PBT-regels over (geschikt voor eenvoudige CRUD-applicaties, UI-only projecten of dunne integratielagen zonder significante bedrijfslogica)
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Vraag 13: Operations-fase
|
||||
|
||||
Moet deze feature na de Construction-fase door de Operations-fase (deployment en monitoring inrichten)?
|
||||
|
||||
- A) Ja: voer de Operations-fase uit na Construction (deployment en monitoring)
|
||||
- B) Nee: stop na Build and Test (deployment en monitoring vallen buiten deze feature)
|
||||
- C) Nog niet zeker: vraag het me opnieuw na de Construction-fase
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
@@ -0,0 +1,97 @@
|
||||
# Requirements: cms-api-foundation ("step 0")
|
||||
|
||||
## Intent analysis
|
||||
|
||||
- **User request**: Start the API and CMS for the Andrea Slop Fotografie website on top of the owner's existing modular CMS (`SlpModularCms`, separate repo), feature by feature. This feature is **step 0**: a working CMS plus API host for the site, with per-site theming and a per-site module set (chosen by the DLLs the client references), serving both the admin and the prerendered website from one host. Packages, contact form, testimonials and shoot pages are later features.
|
||||
- **Request type**: New feature (cross-repo): extension of an existing system.
|
||||
- **Scope estimate**: Cross-system. CMS repo (new client host, shared host composition, admin frontend theming, CI) and this web repo (deploy pipeline, site build output).
|
||||
- **Complexity estimate**: Complex. Hosting model change, security headers, shared-host change that must not regress the existing SlpSoftware client.
|
||||
- **Requirements depth**: Comprehensive. Security-relevant (CSP, auth host), two repos, two AIDLC workspaces.
|
||||
- **Clarity**: Clear after the 13 clarification questions (answers in `requirement-verification-questions.md`).
|
||||
|
||||
## Context (verified by reading the CMS repo, read-only)
|
||||
|
||||
- SlpModularCms is a .NET 10 modular monolith on MariaDB. Modules: `Identity` (login, refresh, revoke, invitations, setup, users), `Master`, `Availability`, `Offerings`. Admin: Vite + React 19 + TypeScript + Tailwind v4 (primary `#ac0000`) + shadcn-style components, NL/EN.
|
||||
- Multi-site pattern today: one deployable client project per site (`Api.SlpSoftware`), a thin `Program.cs` over the shared `CmsHost` composition in `SlpModularCms.Core`, with its own database.
|
||||
- Single-host serving: one process serves `/` (site from `wwwroot/web/`), `/admin`, `/api/v1`. Reserved paths: `/admin`, `/api/v1`, `/health`. Extensionless paths currently fall back to `wwwroot/web/index.html`. The site gets the `Relaxed` CSP, the reserved paths `Strict`.
|
||||
- No theming exists; only CSS variables in the admin `index.css`.
|
||||
- This web repo: a prerendered React SPA (one HTML file per page), currently deployed as static files behind nginx (test) and IIS (production), with a strict CSP from `web/config/securityHeaders.ts`.
|
||||
|
||||
## Decisions taken in clarification
|
||||
|
||||
| # | Decision |
|
||||
|---|---|
|
||||
| Q1 | Scope covers the CMS side and the web side, proven on **test**. |
|
||||
| Q2 | The host gets a prerendered-site mode now. SSR (the owner wants it eventually, to be independent of the build pipeline) versus a hybrid (CMS blocks loaded at runtime) is decided before the first content feature. The owner checks whether the hosting partner allows a Node process. |
|
||||
| Q3 | The client project determines the CSP for `/`; Andrea's client uses the same strict CSP as the site has today. |
|
||||
| Q4 | Admin is built per site; a per-site theme file is selected at build time. No theme in the API. |
|
||||
| Q5 | The theme covers colours (existing tokens), radius, font, logo/app name and favicon. |
|
||||
| Q6 | `Offerings` is **off** for Andrea in step 0; it is switched on in the packages feature. |
|
||||
| Q7 | Users as today: first admin through the setup flow, then invitations; no new roles. |
|
||||
| Q8 | Admin default language per site; Dutch for Andrea, English remains selectable. |
|
||||
| Q9 | Only the test environment in step 0. |
|
||||
| Q10 | Hybrid collaboration with the CMS session (see Process requirements). |
|
||||
| Q11 | Security Baseline extension enforced. |
|
||||
| Q12 | Property-based testing: partial (PBT-02, 03, 07, 08, 09). |
|
||||
| Q13 | Operations phase included. |
|
||||
|
||||
## Functional requirements
|
||||
|
||||
### Client host (CMS repo)
|
||||
|
||||
- **FR-1** A new client project `SlpModularCms.Api.AndreaSlopFotografie` exists in the CMS repo, following the `Api.SlpSoftware` pattern: a thin `Program.cs` on the shared `CmsHost`, its own database, its own local dev port, the three-file appsettings pattern, and solution placement per the CMS repo's `AGENTS.md`.
|
||||
- **FR-2** The active module set of a site is the set of module projects its client host references (the existing mechanism: a module DLL that ships with the host is a module that is on). Andrea's client references only the modules the admin needs and not `Offerings`; a module that is not referenced registers nothing (no controllers or routes, no database context or migrations, no admin navigation entry) and `/api/v1/System/capabilities` lists only the referenced modules. Switching a module on later means adding its reference to the client project. No configuration filter is added to the shared host (owner decision, design stage, 2026-11-06, which supersedes the earlier "configuration switch per module" assumption).
|
||||
- **FR-3** Existing hosts (`Api`, `Api.SlpSoftware`) keep their current behaviour: same modules, same endpoints, same look, same tests passing.
|
||||
|
||||
### Theming (CMS repo, admin frontend)
|
||||
|
||||
- **FR-4** A theme is a per-site theme file (CSS tokens: colours, radius, font) plus logo, app name and favicon, stored in the CMS repo and selected when the admin is built. Without a selection, the admin keeps today's look.
|
||||
- **FR-5** The CI builds the admin once per deployable client with that client's theme. The API exposes no theme.
|
||||
- **FR-6** Andrea's theme matches the site's visual identity (source: this repo's design reference `design/andreaslop-static/` and the web theme).
|
||||
- **FR-7** The default admin language is configurable per site; Andrea's default is Dutch.
|
||||
|
||||
### Serving the site (CMS repo, shared host)
|
||||
|
||||
- **FR-8** The host has a prerendered-site mode: for a request path without a file extension it serves `{path}.html`, else `{path}/index.html`; for an unknown path it serves the site's 404 page with HTTP status 404. URLs have no trailing slash, query strings are preserved, and the reserved paths `/admin`, `/api/v1` and `/health` always win.
|
||||
- **FR-9** Existing behaviour (SPA fallback) remains available for sites that do not use the prerendered mode, so SlpSoftware is unaffected.
|
||||
- **FR-10** The CSP (and the other security headers) for `/` is set per client project. Andrea's client reproduces the strict policy of `web/config/securityHeaders.ts`. A mechanism keeps the two from drifting apart (decided in design).
|
||||
|
||||
### Authentication
|
||||
|
||||
- **FR-11** Authentication is the existing Identity module, unchanged: first administrator via the setup flow, then invitations, no new roles. For Andrea's instance the setup flow must not be reachable by anyone else once the first administrator exists.
|
||||
|
||||
### Web repo (this repo)
|
||||
|
||||
- **FR-12** The site build output (prerendered pages, assets, 404 page) can be delivered to `wwwroot/web/` of Andrea's CMS host on test as part of the deploy, without a manual step.
|
||||
- **FR-13** The web CI is adapted for that delivery. Removing the static nginx deployment of the test site is part of the switch, but only after the new route works.
|
||||
- **FR-14** Proof on test: the home page and at least one sub page are served prerendered, an unknown path returns the 404 page with status 404, `/admin` shows Andrea's theme and allows login, `/health` and `/api/v1/System/capabilities` respond and show `Offerings` off.
|
||||
|
||||
### Process
|
||||
|
||||
- **FR-15** The CMS work is handed to the CMS session (`AndreaSlopFotografie`, `dbb9e4`) as a feature brief per feature; the CMS session runs its own AIDLC. This session answers web-side questions; CMS-internal, security and data-model decisions go to the owner, who approves the CMS requirements and design. The result is handed back as an artifact (changed contract and changelog) which this session verifies by integrating it.
|
||||
|
||||
## Non-functional requirements
|
||||
|
||||
- **NFR-1 Security (Security Baseline enforced).** Applicable rules for step 0: SECURITY-03 (structured logging, no secrets in logs), SECURITY-04 (security headers on all HTML endpoints; no `unsafe-inline` or `unsafe-eval` without documented justification), SECURITY-05 (input validation, existing endpoints), SECURITY-08 (deny by default, CORS only for allowed origins, server-side token validation), SECURITY-09 (no default credentials, generic production errors, no directory listing, no sample content), SECURITY-10 (lock files, vulnerability scan step, pinned CI versions), SECURITY-11 (rate limiting on login, misuse case for the setup flow), SECURITY-12 (credential and session handling as existing; no committed secrets), SECURITY-13 (build integrity), SECURITY-15 (global error handler, fail closed). SECURITY-01, 02, 06, 07 and 14 are assessed per stage (database TLS and encryption at rest, access logging on the reverse proxy, least privilege of the deploy identity, network exposure of the Pi, alerting). Non-compliance is a blocking finding.
|
||||
- **NFR-2 No security regression.** Moving the site behind the CMS host must not weaken the headers the site has today (see FR-10).
|
||||
- **NFR-3 Performance.** Prerendered pages are served as static files with compression and long-lived caching for hashed assets, and the site's Lighthouse targets (see the open follow-ups) must not drop compared to the nginx deployment.
|
||||
- **NFR-4 Compatibility.** Existing hosts and tests keep working (FR-3); the shared `CmsHost` change is backward compatible by default.
|
||||
- **NFR-5 Deployability.** Runs on the test Pi (ARM64, MariaDB) through the existing Gitea CI/CD with its atomic release switch. `wwwroot/web/` stays outside the swapped release directory so a CMS deploy does not remove the site.
|
||||
- **NFR-6 Testing.** Unit and integration tests for module composition (a client without a module exposes none of its routes), prerendered-site serving (including 404 status and reserved paths) and header configuration. Property-based tests (partial mode, PBT-02, 03, 07, 08, 09) for pure functions and round-trips, for example path-to-file resolution and configuration parsing.
|
||||
- **NFR-7 Maintainability.** Per-site differences live in the client project and the theme file; the shared host contains no site names.
|
||||
- **NFR-8 Documentation.** CMS repo docs (`WEBSITE_WORKSPACE.md`, README) are updated for the prerendered mode, module composition per client and themes.
|
||||
|
||||
## Out of scope for step 0
|
||||
|
||||
Offerings/packages, contact form, testimonials, shoot pages and media upload; SSR or the hybrid runtime content loading (decided before the first content feature); production cutover and the IIS hosting; the `Master` module for Andrea; roles; a theme editor in the admin; changes to files owned by the Testimonials session.
|
||||
|
||||
## Open items and risks
|
||||
|
||||
- **Hosting partner**: whether a Node process (SSR) is possible on `mijnhostingpartner.nl`, and whether the production host runs .NET, is unknown. The owner checks this; it does not block step 0.
|
||||
- **CSP source of truth**: the site's policy lives in `web/config/securityHeaders.ts`. How the CMS client project gets the same values without drifting (generated artifact, shared file, or test that compares) is a design decision.
|
||||
- **Parallel work**: the Testimonials session edits `aidlc-docs/active-features.md` (row-level merge conflict expected) and web components. This feature touches `web/` only for the deploy pipeline, and only after the Testimonials feature has merged or confirmed no overlap.
|
||||
- **Dev ports and databases**: Andrea's client needs its own dev port and local database, as `Api.SlpSoftware` has.
|
||||
|
||||
## Direction note (owner, 2026-11-06, tracked by the website session)
|
||||
|
||||
More and more of the website will become dynamic (CMS-driven), so the share of purely prerendered, static serving is expected to shrink over time. This is not a change to step 0: the prerendered-site mode stays as designed. It is an input to the decision on SSR versus a hybrid (CMS blocks loaded at runtime), which must be taken before the first content feature (packages), together with the answer to whether the hosting partner allows a Node process. Design consequence to keep in mind: the host's prerendered mode and its nginx-parity rules must stay usable next to dynamic content (for example as the fallback for pages that are not CMS-driven).
|
||||
Reference in New Issue
Block a user