AI-DLC: inception en ontwerp voor redesign B/E met contactformulier
Requirements, application design (incl. concept-API-contract voor het contactformulier), units en functional design voor U1. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
+41
@@ -0,0 +1,41 @@
|
||||
# Application Design — redesign-modern-timetravel (consolidated)
|
||||
|
||||
Details: [components.md](components.md) · [component-methods.md](component-methods.md) · [services.md](services.md) · [component-dependency.md](component-dependency.md) · [contact-api-contract.md](contact-api-contract.md)
|
||||
|
||||
## Decisions (user, 2026-11-09)
|
||||
| # | Decision | Source |
|
||||
|---|---|---|
|
||||
| D1 | Shared layer (content, data hooks, form logic) + separate presentation for B and E; E lazy-loaded | Design Q1-A |
|
||||
| D2 | Variant is app state only, not in the URL, not persisted; every visit starts in B | Design Q2-A, Req Q3-A |
|
||||
| D3 | Headless form logic is written first in this repo in a movable folder `src/cms-client/`, then handed over to SlpModularCms | Design Q3-B |
|
||||
| D4 | One frontend package `cms-client` with separately importable parts (subpaths); offerings moves in later | Follow-up decision |
|
||||
| D5 | API module Contact/Forms in SlpModularCms built by `SLS Software - CMS` | Req Q10-A/Q11-B |
|
||||
| D6 | Mode (light/dark) follows system preference, overridable and persisted | Req Q5-B |
|
||||
|
||||
## Architecture overview
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph FE[slp-software-frontend]
|
||||
TP[ThemeProvider variant x mode] --> VR[VariantRenderer]
|
||||
VR --> B[Variant B eager]
|
||||
VR -.lazy.-> E[Variant E chunk]
|
||||
B --> S[shared logic]
|
||||
E --> S
|
||||
B --> CC[src/cms-client movable]
|
||||
E --> CC
|
||||
end
|
||||
CC --> API[SlpModularCms API: Contact/Forms module and Offerings category]
|
||||
S --> API
|
||||
classDef fe fill:#63b3ed,stroke:#2b6cb0,color:#000;
|
||||
classDef pkg fill:#f6e05e,stroke:#c05621,color:#000;
|
||||
classDef ext fill:#9ae6b4,stroke:#2f855a,color:#000;
|
||||
class TP,VR,B,E,S fe;
|
||||
class CC pkg;
|
||||
class API ext;
|
||||
```
|
||||
Text alternative: the theme provider drives a variant renderer that shows eager B or lazy E; both use shared logic and the movable cms-client folder, which talks to the CMS API.
|
||||
|
||||
## Design validation
|
||||
- Requirements coverage: FR-1..FR-6 (theme, variants, nav buttons, mode rules) → ThemeProvider, ModeToggle, VariantToggle, VariantRenderer, LandingB/E. FR-7..FR-12 (packages) → usePackagesQuery/usePackageFilter/useSwipeRow + PackagesB/E. FR-13..FR-19 (form) → cms-client/contact, form skins, contract. NFR-1..8 → usePrefersReducedMotion, code split, boundary lint rule, scrubbing, tests.
|
||||
- Consistency: all component names in methods/dependency docs exist in components.md; contract field names equal the hook payload.
|
||||
- Open items are listed in contact-api-contract.md § 9 and are owned by the CMS sessions.
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
# Component Dependencies
|
||||
|
||||
## Dependency matrix (frontend)
|
||||
|
||||
| Component | Depends on |
|
||||
|---|---|
|
||||
| RootLayout | ThemeProvider, VariantRenderer, UmamiAnalytics |
|
||||
| VariantRenderer | ThemeProvider, LandingB, LandingE (lazy) |
|
||||
| LandingB / LandingE | shared/content, usePackagesQuery, usePackageFilter, useSwipeRow, ContactPreselectContext, cms-client/contact, ModeToggle, VariantToggle |
|
||||
| PackagesB / PackagesE | usePackageFilter, useSwipeRow, ContactPreselectContext |
|
||||
| ContactFormView / ContactFormTerminal | cms-client/contact only (props) |
|
||||
| cms-client | nothing outside `cms-client` (enforced by ESLint `no-restricted-imports`) |
|
||||
| ThemeProvider | tokens, localStorage (guarded) |
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Root[RootLayout] --> TP[ThemeProvider]
|
||||
Root --> VR[VariantRenderer]
|
||||
VR --> LB[LandingB eager]
|
||||
VR -.lazy.-> LE[LandingE chunk]
|
||||
LB --> PB[PackagesB]
|
||||
LB --> CB[ContactB with ContactFormView]
|
||||
LE --> PE[PackagesE]
|
||||
LE --> CE[ContactE with ContactFormTerminal]
|
||||
PB --> Shared[shared: filter, swipe, content, preselect]
|
||||
PE --> Shared
|
||||
CB --> CC[cms-client/contact headless]
|
||||
CE --> CC
|
||||
CC --> HTTP[cms-client/http]
|
||||
Shared --> Q[usePackagesQuery]
|
||||
Q --> API[(CMS API offerings)]
|
||||
HTTP --> API2[(CMS API contact-messages)]
|
||||
classDef ui fill:#63b3ed,stroke:#2b6cb0,color:#000;
|
||||
classDef shared fill:#9ae6b4,stroke:#2f855a,color:#000;
|
||||
classDef pkg fill:#f6e05e,stroke:#c05621,color:#000;
|
||||
classDef ext fill:#e2e8f0,stroke:#4a5568,color:#000;
|
||||
class Root,TP,VR,LB,LE,PB,PE,CB,CE ui;
|
||||
class Shared,Q shared;
|
||||
class CC,HTTP pkg;
|
||||
class API,API2 ext;
|
||||
```
|
||||
|
||||
Text alternative: the root layout renders the variant renderer, which shows the eager B landing or the lazy E landing; both use shared logic and the headless cms-client contact part, which talks to the CMS API through the http helpers.
|
||||
|
||||
## Communication patterns
|
||||
- Theme/variant: React context (no URL, no persistence of variant).
|
||||
- Data: TanStack Query for offerings; imperative fetch with state reducer for the form.
|
||||
- Package → form: `ContactPreselectContext.select(subject)` then hash scroll to `#contact`; the form hook applies it when `key` changes.
|
||||
- Cross-repo: HTTP only (`/api/v1/...`, same origin through nginx); source-level sharing via the movable `cms-client` folder.
|
||||
|
||||
## Data flow: form submission
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(99,179,237,0.4) Browser
|
||||
participant V as Visitor
|
||||
participant H as useContactForm
|
||||
end
|
||||
box rgba(154,230,180,0.4) CMS API
|
||||
participant A as contact-messages
|
||||
participant M as IEmailSender
|
||||
end
|
||||
V->>H: focus form
|
||||
H->>A: GET token
|
||||
A-->>H: signed token and captcha info
|
||||
V->>H: submit valid values
|
||||
H->>A: POST with Idempotency-Key
|
||||
A->>A: spam checks, store message
|
||||
A-->>H: 202 received
|
||||
A->>M: send mail (best effort)
|
||||
H-->>V: success message
|
||||
```
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
# Component Methods
|
||||
|
||||
Signatures are high-level. Business rules are detailed in Functional Design (U1, U3, U4).
|
||||
|
||||
## Theme
|
||||
```ts
|
||||
type Variant = 'b' | 'e';
|
||||
type Mode = 'light' | 'dark';
|
||||
resolveInitialMode(stored: string | null, systemPrefersDark: boolean): Mode;
|
||||
useTheme(): { variant: Variant; mode: Mode; toggleMode(): void; setVariant(v: Variant): void; toggleVariant(): void };
|
||||
```
|
||||
|
||||
## Packages (shared)
|
||||
```ts
|
||||
type PackageCardData = { id; slug; title; description; price; priceNote; features: string[]; ctaLabel; featured?: boolean; category?: string | null };
|
||||
usePackagesQuery(): UseQueryResult<PackageCardData[]>;
|
||||
usePackageFilter(packages: PackageCardData[]): { categories: { id: string; label: string; count: number }[]; active: string; setActive(id: string): void; visible: PackageCardData[]; showChips: boolean };
|
||||
useSwipeRow(itemCount: number, initialIndex: number): { ref: RefObject<HTMLElement>; activeIndex: number; scrollToIndex(i: number): void };
|
||||
```
|
||||
|
||||
## Contact preselect
|
||||
```ts
|
||||
useContactPreselect(): { subject: string | null; key: number; select(subject: string): void };
|
||||
```
|
||||
|
||||
## cms-client / contact (headless)
|
||||
```ts
|
||||
type ContactFields = { name: string; email: string; subject: string; message: string };
|
||||
type ContactErrorCode = 'required' | 'tooLong' | 'invalid';
|
||||
type ContactStatus = 'editing' | 'sending' | 'sent' | 'failed';
|
||||
|
||||
validateContact(values: ContactFields): Partial<Record<keyof ContactFields, ContactErrorCode>>;
|
||||
contactFormReducer(state: ContactState, event: ContactEvent): ContactState; // pure
|
||||
|
||||
createContactClient(opts?: { baseUrl?: string; fetch?: typeof fetch }): {
|
||||
getToken(): Promise<{ token: string; minSeconds: number; captcha: { provider: string; siteKey: string } | null }>;
|
||||
submit(payload: ContactPayload, ctx: { token: string; captchaToken?: string; idempotencyKey: string }): Promise<void>; // throws ContactApiError
|
||||
};
|
||||
|
||||
useContactForm(options: {
|
||||
idPrefix: string;
|
||||
subjectOptions: { value: string; label: string }[];
|
||||
preselect?: { subject: string | null; key: number }; // unknown value ignored
|
||||
submit?: ContactClient['submit']; // injectable
|
||||
messages?: Partial<ContactMessages>; // default nl
|
||||
now?: () => number;
|
||||
}): {
|
||||
status: ContactStatus; values: ContactFields; errors: Partial<Record<keyof ContactFields, string>>;
|
||||
getFieldProps(name: keyof ContactFields): { id; name; value; onChange; onBlur; 'aria-invalid'; 'aria-describedby' };
|
||||
honeypot: { name: string; ref; tabIndex: -1; autoComplete: 'off' };
|
||||
formProps: { onSubmit; noValidate: true };
|
||||
focusFirstError(): void;
|
||||
retry(): void;
|
||||
};
|
||||
```
|
||||
|
||||
## http
|
||||
```ts
|
||||
apiUrl(path: string): string; // VITE_API_BASE_URL ?? '' + path
|
||||
parseProblemDetails(res: Response): Promise<{ status: number; errors?: Record<string, string[]>; retryAfter?: number }>;
|
||||
```
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
# Components
|
||||
|
||||
Source layout (target):
|
||||
|
||||
```text
|
||||
src/
|
||||
cms-client/ # self-contained, movable to SlpModularCms (no imports from outside)
|
||||
index.ts # barrel, but sites import subpaths
|
||||
http/ # apiUrl, fetch helpers, ProblemDetails parsing
|
||||
contact/ # headless contact form
|
||||
offerings/ # (later) typed offerings client; types from OpenAPI
|
||||
theme/ # variant x mode state (replaces red/purple)
|
||||
shared/ # a11y/motion hooks, packages logic (filter, swipe), content
|
||||
variants/
|
||||
b/ # Modern (default, eager)
|
||||
e/ # Time-travel (lazy chunk)
|
||||
components/ # RootLayout shell, ErrorBoundary, analytics
|
||||
routes/ , router.tsx # unchanged (hash history)
|
||||
```
|
||||
|
||||
## Theme and switching
|
||||
### ThemeProvider (changed)
|
||||
- **Purpose**: owns `variant` ('b' | 'e') and `mode` ('light' | 'dark').
|
||||
- **Responsibilities**: initial mode from stored value else `prefers-color-scheme`; persist only mode; write `data-variant` and `data-mode` on `<html>`; variant always starts as 'b' and is never persisted.
|
||||
- **Interface**: `useTheme(): { variant, mode, toggleMode(), setVariant(v), toggleVariant() }`.
|
||||
|
||||
### ModeToggle (replaces ThemeToggle)
|
||||
- **Purpose**: light/dark switch in the nav of both variants. Accessible name "Wissel tussen licht en donker", `aria-pressed` for dark.
|
||||
|
||||
### VariantToggle (new)
|
||||
- **Purpose**: icon-only button next to ModeToggle; tooltip and accessible label ("Tijdreis" in B, "Terug naar nu" in E). Uses `toggleVariant`.
|
||||
|
||||
### VariantRenderer (new)
|
||||
- **Purpose**: renders `LandingB` or the lazy `LandingE` depending on `variant`; `Suspense` fallback (small neutral loader); focus and scroll position reset when the variant changes; announces the change to screen readers (`aria-live`).
|
||||
|
||||
### tokens (changed)
|
||||
- **Purpose**: CSS variable sets per `[data-variant][data-mode]` (B light/dark, E light/dark), semantic Tailwind color names kept (`bg`, `surface`, `text`, `muted`, `accent`, ...), plus variant-only tokens for E eras.
|
||||
|
||||
## Variant B (eager)
|
||||
- **LandingB**: composition of NavB, HeroB, AboutB, PackagesB, ProcessB, ContactB, FooterB.
|
||||
- **NavB**: wordmark, anchor links (no years), CTA, ModeToggle, VariantToggle, mobile menu.
|
||||
- **HeroB / AboutB / ProcessB / FooterB**: presentational ports of the canvas design B using shared content.
|
||||
- **PackagesB**: B styling of the packages block (square filter chips, cards, black "Past er niets bij?" banner), uses shared packages logic.
|
||||
- **ContactB**: red contact block with white (light) / dark form panel; uses `ContactFormView` from the B skin.
|
||||
|
||||
## Variant E (lazy chunk)
|
||||
- **LandingE**: eras in order 2026 → 2013 → 2006 → 1998 → 1989 with year badges; own nav bar style including ModeToggle and VariantToggle.
|
||||
- **Era sections** (EHero2026, EAbout2013, EPackages2006, EProcess1998, EContact1989): presentational ports of design E; the 1998 Werkwijze uses the step-card layout; the 1989 terminal looks the same in both modes.
|
||||
- **EffectsLayer**: marquee, scanlines, dither transitions, caret; all disabled via `usePrefersReducedMotion`.
|
||||
|
||||
## Shared (variant-independent)
|
||||
- **content.ts** (kept): nav links (without years), hero, about, process, contact copy, package seed; E-only era captions live in `variants/e`.
|
||||
- **usePackagesQuery** (kept): TanStack Query against `/api/v1/offerings`; type gains `category`.
|
||||
- **usePackageFilter**: derives categories (order of first appearance), counts, current filter, filtered list; `showChips` when `packages.length >= 4`.
|
||||
- **useSwipeRow**: scroll-snap helper for the mobile row (active index for dots, `scrollToIndex`, initial index = featured package); no JS needed for scrolling itself.
|
||||
- **usePrefersReducedMotion**, **usePrefersDark** (media query helpers).
|
||||
- **ContactPreselectContext**: `{ subject, key }`; the "Kies …" button of a package sets it (key increments on each click) and scrolls to the contact section.
|
||||
|
||||
## cms-client (movable package, headless)
|
||||
- **contact/ContactFormState**: pure reducer + types (`editing | sending | sent | failed`).
|
||||
- **contact/validateContact**: pure validation with limits (name 100, email 254, message 2000) and error codes (`required`, `tooLong`, `invalid`).
|
||||
- **contact/useContactForm**: React hook tying state, validation, preselect (initial value + change key), `idPrefix`, honeypot, token handling and submit; returns prop getters and slots data. No markup, no styles.
|
||||
- **contact/createContactClient**: fetch implementation of the API contract (`getToken`, `submit`) incl. ProblemDetails parsing, `Idempotency-Key`, 429 handling; submit function is injectable.
|
||||
- **contact/messages.nl**: default Dutch messages (injectable/overridable).
|
||||
- **http/**: `apiUrl()` honoring `VITE_API_BASE_URL`, shared error types.
|
||||
|
||||
## Form skins
|
||||
- **ContactFormView (B)** and **ContactFormTerminal (E 1989)**: presentational components consuming `useContactForm` output; render honeypot slot (visually hidden, `aria-hidden`, `tabIndex=-1`), privacy line, status regions (`role=alert` on error, `role=status` + focus on success).
|
||||
- **ContactGate** (optional): feature flag / env switch `VITE_CONTACT_FORM_ENABLED`; when off, shows the existing mailto fallback (address assembled client-side after mount, not in static HTML).
|
||||
|
||||
## Backend components (SlpModularCms, for hand-off; not built here)
|
||||
- **Contact/Forms module**: endpoints, validation, storage, mail via `IEmailSender`, spam checks, rate-limit policy, retention job, per-site config.
|
||||
- **Offerings module**: new optional `category` field.
|
||||
+226
@@ -0,0 +1,226 @@
|
||||
# Contact Form & Offerings — Draft API Contract
|
||||
|
||||
**Version**: 0.3.1-draft (2026-11-09) — incorporates the reviews of `SLS Software - CMS` (API side), `CMS & API` (ASF website) and `AndreaSlopFotografie` (ASF CMS/hosting) and the product decisions of Bryan (admin view in scope, spam stored as `spam`, captcha fail-open).
|
||||
**Status**: DRAFT for confirmation by the builders. Product decisions still open are marked **[Bryan]** (see § 10).
|
||||
**Source of truth** once agreed: the OpenAPI document generated by the CMS (`AddOpenApi`/`MapOpenApi`), exported as a **committed artifact** in SlpModularCms so `cms-client` can generate types from it. This file carries the behaviour agreements and the intended shape.
|
||||
**Compatibility**: breaking changes → `/api/v2`; additive changes allowed within `/api/v1`. The frontend package `cms-client` follows semver.
|
||||
|
||||
## 1. Scope
|
||||
1. New `Contact/Forms` module (own DbContext + additive migration per host, own Module class, like `Modules.Offerings`): token endpoint, submit endpoint, admin endpoints, background jobs.
|
||||
2. `GET /api/v1/offerings` gains the optional field `category`.
|
||||
3. Per-site configuration (host-based: Api.SlpSoftware, Api.AndreaSlopFotografie, ...).
|
||||
|
||||
All paths are **same-origin** (`/api/v1/...`) through "the reverse proxy of the host" (nginx for SLP; ASF production will be IIS — do not hard-code nginx). No CORS. The site id is derived from the host/config, **never** from the request body.
|
||||
|
||||
**Availability gate — decided (Bryan, 2026-11-09)**: the statuses (CMS disabled / maintenance, set by the master) block **only the CMS**, i.e. changing data and settings through the admin. **Public content is always available.** The gate therefore applies to admin/CMS routes only; the public routes `GET /api/v1/offerings`, `GET /api/v1/contact-messages/token` and `POST /api/v1/contact-messages` must stay reachable (a visitor's contact request is public site functionality, not a CMS change). Today `AvailabilityMiddleware` returns `503` for everything under `/api/` (bypass list limited); the CMS must align this with the decision (public routes on the bypass list or gate limited to admin routes), and the bypass must never cover admin routes. The frontend still treats `503`/network errors as a failure with the **mailto fallback** as a safety net.
|
||||
|
||||
## 2. Public endpoints
|
||||
|
||||
### 2.1 `GET /api/v1/contact-messages/token`
|
||||
Issues a server-signed token used for the minimum-time check, bound to the site. Tokens use **ASP.NET DataProtection** (key ring in the DB survives deploys), not a custom HMAC secret. The key ring must be **persistent per host** (DB or shared directory; on IIS it must survive app-pool recycles) and use a **per-site purpose string**, so an SLP token is invalid on ASF. (Already covered by the host-level `AddCmsDataProtection`, keys in the database; Contact only uses an `IDataProtector` with purpose `SlpModularCms.Contact.Token.{siteId}`; no own key ring or table.)
|
||||
|
||||
`200 application/json`
|
||||
```json
|
||||
{ "token": "<opaque signed string>", "minSeconds": 3, "captcha": null }
|
||||
```
|
||||
- `captcha` is `null` when disabled, else `{ "provider": "friendlycaptcha", "siteKey": "..." }`.
|
||||
- Token carries issue time + site id; valid for e.g. 120 minutes. Not stored.
|
||||
- Rate-limited; `429` with `Retry-After`.
|
||||
- The client fetches the token **lazily after hydration, on first focus/interaction**, not on page load (prerender contains no token; crawlers do not use up the limit).
|
||||
|
||||
### 2.2 `POST /api/v1/contact-messages`
|
||||
Headers: `Content-Type: application/json`, `Idempotency-Key: <uuid>` (required).
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"name": "Jan Jansen",
|
||||
"email": "jan@example.nl",
|
||||
"subject": "website",
|
||||
"message": "Ik wil graag een offerte voor …",
|
||||
"hpCheck": "",
|
||||
"token": "<from 2.1>",
|
||||
"captchaToken": null
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Rules |
|
||||
|---|---|---|---|
|
||||
| `name` | string | yes | trimmed, 1–100 chars; control characters rejected |
|
||||
| `email` | string | yes | trimmed, 1–254 chars, regex `^[^\s@]+@[^\s@]+\.[^\s@]{2,}$`, no control characters |
|
||||
| `subject` | string | yes | trimmed, 1–100 chars; **opaque value** chosen by the site (a package id, slug, or `other`); no slug regex; stored as given, never validated against offerings. The label of `other` is per site (ASF: "Overig"). |
|
||||
| `message` | string | yes | trimmed, 1–2000 chars |
|
||||
| `hpCheck` | string | yes (key present) | **honeypot**; must be empty. Deliberately implausible name (not `website`/`url`) to avoid password-manager autofill; field is configurable per site; render with `autocomplete="off"`, `tabindex="-1"`, `aria-hidden`, off-screen |
|
||||
| `token` | string | yes | from 2.1 |
|
||||
| `captchaToken` | string \| null | when `captcha` enabled | verified server-side |
|
||||
|
||||
Responses:
|
||||
- `202 Accepted` — `{ "status": "received" }`. **Identical body and status for genuine and spam submissions** (honeypot filled, token too young, captcha failed) so bots learn nothing. Replays with the same `Idempotency-Key` (24 h) return the same 202 without storing twice.
|
||||
- `400 application/problem+json` — validation errors (§ 3): field validation; **expired, forged or other-site token** (all answered as `errors.token: ["expired"]`, so the endpoint is no oracle; the client fetches a fresh token and retries once automatically); missing or non-UUID `Idempotency-Key` (`errors.idempotencyKey: ["required" | "invalid"]`).
|
||||
- `413 application/problem+json` — body too large (`MaxRequestBodySize` per endpoint, e.g. 16 KB, with our own ProblemDetails shape).
|
||||
- `429 application/problem+json` — rate limit; header `Retry-After: <seconds>` (the existing `OnRejected` sets neither body nor `Retry-After` yet). This is a **separate, first-executed CMS unit**: it changes the behaviour of existing policies (login/refresh/sentry-tunnel), the admin frontend must cope with it and `PipelineTests` need adjusting. `Retry-After` comes from `MetadataName.RetryAfter` (available for fixed/sliding window limiters).
|
||||
- `503` — should not occur for the public routes (see § 1); if it does (e.g. host down behind the proxy), the client shows the mailto fallback.
|
||||
- `5xx application/problem+json` — generic; no internal detail.
|
||||
|
||||
## 3. Error shape (ProblemDetails)
|
||||
```json
|
||||
{
|
||||
"type": "about:blank",
|
||||
"title": "Validation failed",
|
||||
"status": 400,
|
||||
"errors": { "name": ["required"], "email": ["invalid"], "message": ["tooLong"] }
|
||||
}
|
||||
```
|
||||
The `type` URI is configurable per host (`Contact:ProblemTypeBase`), default `about:blank`, so no site domain is hard-coded in a module used by two sites; clients map on `errors`, never on `type`. Codes: `required`, `tooLong`, `invalid`, `expired` (token only; also for forged/other-site tokens). The `errors` mapping is custom (not the default ASP.NET `ValidationProblemDetails`). Messages are **not** localized by the API; the client maps `messages[field][code]`. Client-side validation uses the same limits and codes.
|
||||
|
||||
## 4. Server behaviour agreements
|
||||
1. **Store first, mail after commit.** Validate → store and commit (`status: new`, `mailStatus: pending`) → respond 202. Mail is **not fire-and-forget** in the request scope: a `BackgroundService`/queue picks up `pending` rows, sends via `IEmailSender`/`IMailAvailability` (returns `MailSendResult`, does not throw) and updates `mailStatus` and `mailAttempts`. A short sweep (every few minutes) catches `pending` rows left by a crash; `failed` rows are retried with **backoff** up to a configurable max attempts (so a first outage does not mean 24 h delay). A mail failure never fails the request. If `Email:Smtp:Host` is not configured: store only, show a notice in the admin.
|
||||
2. **Stored entity `ContactMessage`**: `id` (GUID), `siteId`, `receivedAt`, `name`, `email`, `subject`, `message`, `status` (`new` | `read` | `archived` | `spam` [Bryan] | later `converted`), `mailStatus` (`pending` | `sent` | `failed` + the existing error code, e.g. `auth_failed`, `rejected_sender`, `timeout_*`), `mailAttempts`, `retentionUntil` (fixed per row at insert; a config change does **not** apply retroactively). `id` and `status` exist so a message can later become an assignment for quotes/invoices (**not built now**). No IP address is stored.
|
||||
3. **Retention**: per site, default **12 months**; a daily `BackgroundService` (pattern: `IntegrityCheckBackgroundService`) deletes messages with `retentionUntil < now` and idempotency records older than 24 h. Database backups may keep messages longer: mention in the privacy statement or shorten backup retention. The admin can delete a single message (right to erasure).
|
||||
4. **Spam** (captcha behind an `ICaptchaVerifier` interface with a Null implementation when disabled): honeypot must be empty; elapsed time since token issue ≥ `minSeconds`; optional captcha verified server-side; rate limit policy `ContactForm` (defaults, config `RateLimiting:ContactForm`: 5 submissions per 10 minutes per client IP; token endpoint 20 per 10 minutes). Spam is answered with the normal 202. **Decided (Bryan):** instead of discarding, honeypot/too-young submissions are stored with `status: spam` (never mailed, retention 30 days) so a real visitor who tripped the check (autofill, very fast typist) is not lost silently; the visitor still sees the normal thank-you. **Cap on spam rows** (suggestion of `AndreaSlopFotografie` and `SLS Software - CMS`): per site at most N spam rows per day (default e.g. 200; `Contact:MaxSpamRowsPerDay`); above N the submission still gets the normal 202 but is only counted and logged, not stored. Spam rows are excluded from the unread counter and hidden from the default admin list (separate filter), so spam content is never shown first. Spam rows are stored with `retentionUntil = receivedAt + 30 days`, so the retention job works on each row's own `retentionUntil`. Timing: spam may be slightly faster (skips mail); accepted consciously. **Captcha provider failure** (timeout/5xx of the verify endpoint): **decided fail-open** with a log entry. Captcha ships **disabled** (honeypot + time + rate limit); it is a per-site switch for when abuse appears.
|
||||
5. **Client IP**: **release prerequisite** — on CMS master (`d9cc539`) the rate-limit policies are plain global buckets; the per-client partitioning (`ClientPartitionKey`) and `ForwardedHeaders` exist only on the unmerged ASF branch `feature/identity-email-notifications`. A `ContactForm` policy of 5 per 10 minutes as a global bucket would block the whole site after five submissions, so the contact routes must not be enabled on a public host before the per-client partitioning is on the base branch. The rate limit needs `ForwardedHeaders:KnownProxies` on each host (set on the test hosts; ASF production on IIS will differ), otherwise all visitors share one bucket (5 per 10 minutes for the whole site).
|
||||
6. **Privacy / logging**: never log `name`, `email`, `message` or the request body for this route; the Sentry SDK request body/PII is explicitly off for it (`BeforeSend` scrubbing; extra rule in the existing `SecurityEventProcessor`; a test proves a logged exception holds no body); client side: no form fields in Sentry breadcrumbs or replay (masked). Log only status codes, site id and outcome. Configuration errors of the mail setup are logged as Error (so the Sentry rule fires) in the style of `identity_mail_failed`, without addresses or content.
|
||||
7. **Idempotency**: table (`key`, `siteId`, `createdAt`, `statusCode`; no request content, no PII), unique index, cleaned after 24 h by the retention job; in-memory is not enough. Spam submissions also get a key record so replay behaviour is identical. Same key → same response, no second row, no second mail.
|
||||
8. **Mail safety**: `From` = fixed site sender on `Email:AllowedFromAddresses`; `Reply-To` = visitor e-mail (never as `From`: SPF/DMARC). Reject/strip control characters (`EmailAddressRules` exists) in `name`, `email`, `subject` before use in mail headers; HTML-encode all values in the body; never put `subject` 1:1 in the mail subject line (sanitize, cut at 100). The recipient address never appears in client-reachable config or in OpenAPI examples.
|
||||
9. **Availability gate / 503**: see § 1.
|
||||
10. **CSP** (frontend/host): `connect-src 'self'` suffices for the same-origin API. A captcha provider needs more (per provider and version, e.g. Friendly Captcha v1 `api.friendlycaptcha.com`/`eu-api.friendlycaptcha.eu`, v2 `global.frcapi.com`; widget script via npm bundle = `'self'`, else `script-src`; possible `'wasm-unsafe-eval'`, `worker-src blob:`, inline styles). The module documents the required directives per provider/version; the site adds them and tests in a real browser. The captcha provider must be named in the privacy statement.
|
||||
|
||||
## 5. Per-site configuration
|
||||
|
||||
Server (appsettings per host, `Contact:` section):
|
||||
| Setting | Example | Notes |
|
||||
|---|---|---|
|
||||
| `Contact:Enabled` | `false` | **safety switch** (release condition, § 4.5): while `false` both public contact routes answer `404` with an empty body and nothing runs; the client treats `404` on the token route as "form not available" and shows the mailto fallback. Enabled per host after the per-client rate-limit partitioning is on the base branch |
|
||||
| `Contact:RecipientEmail` | — | never exposed to the client. ASF: **env-only** (no ASF addresses in code or committed config); SLP may keep a committed default |
|
||||
| `Contact:SenderEmail` | — | must be on `Email:AllowedFromAddresses`; env-only for ASF |
|
||||
| `Contact:RetentionMonths` | `12` | |
|
||||
| `Contact:MinSeconds` | `3` | |
|
||||
| `Contact:TokenLifetimeMinutes` | `120` | |
|
||||
| `Contact:Captcha:Enabled / Provider / SiteKey / Secret` | `false` | secret via secrets manager |
|
||||
| `RateLimiting:ContactForm` | 5 / 10 min | |
|
||||
|
||||
Frontend per-site options (not API): subject options and labels (incl. the label of `other`), reply-time text, **privacy sentence and link target** (ASF: "Lees in de privacyverklaring wat ik met je gegevens doe." → `/privacyverklaring`), per-field message texts.
|
||||
|
||||
## 5a. Form fields and on/off switch (decided by Bryan, 2026-11-09)
|
||||
- **Fixed fields** for now (name, email, subject, message). A form builder with per-site field definitions is **not** part of this feature; it can come later as its own feature (field definitions as CMS data). The model stays extendable (additive migrations, contract versioned).
|
||||
- **Two-layer switch**: (1) host level `Contact:Enabled` (deployment, default off, release condition § 4.5); (2) a CMS switch for the owner: singleton resource `GET /api/v1/contact-settings` and `PUT /api/v1/contact-settings` (AdminOnly, body `{ "enabled": true|false }`, stored as data, default `false`). The form is active only when **both** are on. When either is off, `GET .../token` and `POST .../contact-messages` answer `404` with an empty body and the client shows the mailto fallback. Admin screen "Berichten" gets a visible switch ("Contactformulier aan/uit"). Implemented in CMS-U4 (API) and CMS-U6 (UI); CMS-U3 builds the gate behind an interface so U4 adds the CMS switch without rewriting the filter.
|
||||
|
||||
## 6. Admin endpoints (CMS) — decided: in scope, full version
|
||||
AdminOnly (Owner + Administrator). Module appears in `/System/capabilities` so the admin menu "Berichten" only shows on hosts with the module.
|
||||
**Decided by Bryan (2026-11-09): RESTful routes without an `/admin` segment.** That an admin may use an endpoint does not require a separate admin route: the same resource is used by everyone, access is controlled by the authorization policy (AdminOnly = Owner + Administrator) and, for public endpoints, by the `[PublicSiteEndpoint]` marker. This supersedes both `/api/v1/admin/contact-messages` and `/api/v1/contact-messages/admin`.
|
||||
- `POST /api/v1/contact-messages` — **public** (submit, § 2.2). `GET /api/v1/contact-messages/token` — **public** (§ 2.1); the `{id}` routes use the constraint `{id:guid}` so `token` never collides.
|
||||
- `GET /api/v1/contact-messages` — AdminOnly: list with paging; filter `?status=new|read|archived|spam` (default excludes `spam`); the response carries the unread count (spam excluded).
|
||||
- `GET /api/v1/contact-messages/{id:guid}` — AdminOnly: detail.
|
||||
- `PATCH /api/v1/contact-messages/{id:guid}` — AdminOnly: status `new`/`read`/`archived`.
|
||||
- `DELETE /api/v1/contact-messages/{id:guid}` — AdminOnly: **hard delete** (no soft delete), for erasure requests.
|
||||
- `POST /api/v1/contact-messages/{id:guid}/resend` — AdminOnly: resend mail; itself rate-limited (policy `RateLimiting:ContactResend`, no mail-bomb button); `mailStatus` and error code visible.
|
||||
- The public client (`cms-client`) only uses the two public routes.
|
||||
- Offerings: categories are CMS data with RESTful CRUD under `/api/v1/offerings/categories` (AdminOnly), see § 7 (not `offerings/admin/categories`, and no longer an appsettings list). Existing `offerings/admin...` routes are out of scope for this feature (see the open item on a later RESTful refactor).
|
||||
- Spam rows: excluded from the unread counter and the default list; separate filter.
|
||||
|
||||
## 7. Offerings change
|
||||
**Decided by Bryan (2026-11-09, supersedes the appsettings list):** categories are **data managed in the CMS**, not settings. They are part of Offerings: a sub-section/dialog inside the Offerings admin screen (not a new page). Bryan starts with the categories **Websites** and **Onderhoud** (he currently offers complete packages and new builds; takeover/"overname" is not decided yet), created by him in the CMS (not seeded in code).
|
||||
|
||||
Model: `OfferingCategory` (`id`, `name`, `sortOrder`), unique name (case-insensitive), nullable `categoryId` on `Offering`. Routes (RESTful, no `/admin`): `GET /api/v1/offerings/categories` (AdminOnly; list), `POST /api/v1/offerings/categories`, `PUT /api/v1/offerings/categories/{id:guid}`, `DELETE /api/v1/offerings/categories/{id:guid}` (all AdminOnly). Deleting a category that is still used by offerings is rejected (`409` ProblemDetails) until those offerings are moved. Offering create/update accept `categoryId` (must exist) instead of free text; renaming a category updates every offering through the relation. Admin read DTOs carry `categoryId` and `category` (name).
|
||||
|
||||
Public `GET /api/v1/offerings` item gains `"category": "Websites"` — the category **name** as string or `null` (shape unchanged for the frontend). `null`/empty → no chip. The public response also carries the additive fields `categoryId` (GUID string or null) and `displayOrder` (int); the SLP site ignores both. Decision (CMS-U0, 2026-11-09): **one URL and one DTO for everybody** (`GET /api/v1/offerings`; the former admin DTO is removed); writes are `POST /api/v1/offerings`, `PUT|DELETE /api/v1/offerings/{id:guid}` and `PUT /api/v1/offerings/order` (`{ "orderedIds": [...] }`), all AdminOnly. The frontend builds chips from distinct non-empty values in order of first appearance, counts itself, and shows chips only when there are **4 or more** packages. Existing fields unchanged (see `aidlc-docs/features/react-frontend/construction/react-frontend-app/functional-design/packages-api-handoff.md`). Array order = display order; exactly one `featured: true`. Independent of the form; can start immediately.
|
||||
|
||||
## 8. OpenAPI sketch (intended shape; the CMS exports the definitive document)
|
||||
```yaml
|
||||
openapi: 3.0.3
|
||||
info: { title: SLP CMS public API, version: 0.2.0-draft }
|
||||
paths:
|
||||
/api/v1/contact-messages/token:
|
||||
get:
|
||||
responses:
|
||||
'200': { description: token, content: { application/json: { schema: { $ref: '#/components/schemas/ContactToken' } } } }
|
||||
'429': { $ref: '#/components/responses/RateLimited' }
|
||||
/api/v1/contact-messages:
|
||||
post:
|
||||
parameters:
|
||||
- { name: Idempotency-Key, in: header, required: true, schema: { type: string, format: uuid } }
|
||||
requestBody:
|
||||
required: true
|
||||
content: { application/json: { schema: { $ref: '#/components/schemas/ContactMessageRequest' } } }
|
||||
responses:
|
||||
'202': { description: received, content: { application/json: { schema: { $ref: '#/components/schemas/Received' } } } }
|
||||
'400': { $ref: '#/components/responses/Validation' }
|
||||
'413': { $ref: '#/components/responses/TooLarge' }
|
||||
'429': { $ref: '#/components/responses/RateLimited' }
|
||||
components:
|
||||
responses:
|
||||
Validation:
|
||||
description: validation failed (also expired/forged token and bad Idempotency-Key)
|
||||
content: { application/problem+json: { schema: { $ref: '#/components/schemas/ValidationProblem' } } }
|
||||
TooLarge:
|
||||
description: body too large
|
||||
content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
|
||||
RateLimited:
|
||||
description: too many requests
|
||||
headers: { Retry-After: { schema: { type: integer }, description: seconds } }
|
||||
content: { application/problem+json: { schema: { $ref: '#/components/schemas/Problem' } } }
|
||||
schemas:
|
||||
Problem:
|
||||
type: object
|
||||
properties: { type: { type: string }, title: { type: string }, status: { type: integer } }
|
||||
ValidationProblem:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/Problem'
|
||||
- type: object
|
||||
properties:
|
||||
errors:
|
||||
type: object
|
||||
additionalProperties: { type: array, items: { type: string, enum: [required, tooLong, invalid, expired] } }
|
||||
ContactToken:
|
||||
type: object
|
||||
required: [token, minSeconds]
|
||||
properties:
|
||||
token: { type: string }
|
||||
minSeconds: { type: integer }
|
||||
captcha: { type: object, nullable: true, properties: { provider: { type: string }, siteKey: { type: string } } }
|
||||
ContactMessageRequest:
|
||||
type: object
|
||||
required: [name, email, subject, message, hpCheck, token]
|
||||
properties:
|
||||
name: { type: string, minLength: 1, maxLength: 100 }
|
||||
email: { type: string, minLength: 1, maxLength: 254 }
|
||||
subject: { type: string, minLength: 1, maxLength: 100 }
|
||||
message: { type: string, minLength: 1, maxLength: 2000 }
|
||||
hpCheck: { type: string, maxLength: 0 }
|
||||
token: { type: string }
|
||||
captchaToken: { type: string, nullable: true }
|
||||
Received:
|
||||
type: object
|
||||
properties: { status: { type: string, enum: [received] } }
|
||||
```
|
||||
|
||||
## 9. Frontend package expectations (`cms-client`, headless, by subpath)
|
||||
- `cms-client/contact`: `useContactForm`, `contactFormReducer`, `validateContact`, `createContactClient`, types, default Dutch messages.
|
||||
- **Messages**: `messages[field][code]` with Dutch defaults **identical to the ASF texts** ("Vul je naam in.", "De naam is te lang.", "Vul je e-mailadres in.", "Het e-mailadres is te lang.", "Dit e-mailadres is ongeldig.", "Kies een soort shoot." → generic "Kies een onderwerp.", "Schrijf hier je vraag.", "Het bericht is te lang."), plus texts for 429 (shows "probeer het over X minuten" from `Retry-After`), 413, network/5xx/503, expired token. Fully overridable per site.
|
||||
- **Field ids**: derived from `idPrefix` + logical field name; a site can keep its own DOM names, ids and test ids; payload mapping lives in the client, not in the site.
|
||||
- **Idempotency-Key**: one UUID per attempt series; reused on "opnieuw proberen" until success; a new key after success/reset; provided by the hook.
|
||||
- **States**: `editing | sending | sent | failed` pure reducer; `sent` never reverts; edits and second submit while `sending` are ignored; input kept on `failed`. Spam gets the same 202, so there is one success path. The submit button is **not** blocked for `minSeconds`; the server answers early submissions with the normal 202 and stores them as `spam` (never mailed).
|
||||
- **Token**: fetched lazily after hydration on first focus/interaction; on `errors.token = ["expired"]` one fresh token and an automatic repeat, then the error message. No `Date.now` on the client.
|
||||
- **Preselect**: `{ subject, key }` with change counter; unknown value ignored; the site reads the query string.
|
||||
- **Captcha slot**: slot data `{ provider, siteKey, onToken(token), onExpired() }`; the site renders the widget client-only after hydration, reserves a fixed height (no layout shift), puts no captcha HTML in prerendered output, resets the widget when the token expires; with `captcha: null` the slot renders nothing and takes no space.
|
||||
- **Fallback**: on failure the hook returns `{ failed: true }`; the site renders the mailto fallback without the address in static HTML (assembled after hydration).
|
||||
- **Honeypot slot**: field name configurable (`hpCheck` default).
|
||||
- **Boundary**: no imports from the consuming app. Developed first in `slp-software-frontend/src/cms-client/` (decision of the user), then moved to SlpModularCms. `cms-client/offerings` (typed client from OpenAPI) follows later.
|
||||
|
||||
## 10. Open items
|
||||
- [x] **[Bryan, decided 2026-11-09]** Admin view for contact messages is in scope, full version (list with paging and unread count, detail, status new/read/archived, delete, resend mail).
|
||||
- [x] **[Bryan, decided 2026-11-09]** Honeypot/too-fast submissions are stored with `status: spam` (30 days, never mailed).
|
||||
- [x] **[Bryan, decided 2026-11-09]** Captcha provider failure: fail-open; captcha ships disabled.
|
||||
- [x] **[Bryan, decided 2026-11-09, revised]** Categories are data managed in the CMS inside the Offerings admin (sub-section, not a new page), not an appsettings list. Starting categories: Websites and Onderhoud. (The earlier decision "fixed list in appsettings" is superseded.)
|
||||
- [ ] `SLS Software - CMS`: confirm the build plan incl. `Retry-After` in `OnRejected`, own ProblemDetails mapping, DataProtection tokens, idempotency table, retry job, `AvailabilityMiddleware` aligned with the decision "only the CMS/admin is blocked, public content stays available" (public offerings + contact routes reachable, admin routes still gated), capabilities entry.
|
||||
- [ ] `CMS & API`: decide `other` (label per site) vs ASF `overig`; plan the ASF migration to `cms-client` as an own ASF-web feature (not part of this feature; existing ContactForm/reducer tests can serve as acceptance tests).
|
||||
- [ ] Host: `ForwardedHeaders:KnownProxies` per host; reverse-proxy route `/api/v1/` for test and production (nginx for SLP, IIS for ASF production).
|
||||
- [x] **[Bryan, decided 2026-11-09]** Existing routes with an `/admin` segment are refactored to RESTful routes **now, in this feature** (Bryan maintains both websites and prefers doing it now): Offerings (`GET/POST offerings/admin`, `PUT/DELETE offerings/admin/{id}`, `admin/reorder`, `admin/{id}/move-up|down`) in phase 1 together with the admin-frontend call sites and tests, before the category work; `Availability` `POST admin/status` in phase 2 after the merge of the ASF branch (that branch touches Availability and master/slave callers must be checked).
|
||||
- [x] Reviews received 2026-11-09: `SLS Software - CMS`, `CMS & API`, `AndreaSlopFotografie`; folded into v0.2.0 and v0.3.x.
|
||||
|
||||
## 10a. Notes for the CMS builder on the availability gate (from review)
|
||||
- The latest commit on the CMS branch (`701091f`, "Beschikbaarheidspoort blokkeert alleen de API, niet de website en de admin") touches the same middleware: build on it; limiting the gate to admin/CMS routes is a second step, not a rewrite.
|
||||
- Prefer an **explicit allowlist of public routes** (offerings GET, contact token GET, contact POST) over a prefix exception, so a new admin endpoint can never fall under the bypass by accident; add a test proving that every endpoint without `[PublicSiteEndpoint]` (iterating all endpoints, including all admin routes) still returns 503 when the gate is closed. (Replaces the earlier prefix test `/api/v1/admin/*`; the repo has no common admin prefix.)
|
||||
|
||||
## 11. Suggested CMS build order (from the review; build only after Bryan confirms the whole)
|
||||
(a) `category` on Offerings (migration on existing SLP and ASF databases; field in admin forms and tests); (b) `OnRejected` / `Retry-After` / ProblemDetails unit (existing policies, `PipelineTests`); (c) Contact module: storage, token, submit, idempotency, spam checks; (d) mail background service + retry; (e) admin API; (f) admin UI. Build and test per unit.
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
# Services
|
||||
|
||||
## Frontend services
|
||||
### ThemeService (inside ThemeProvider)
|
||||
- Reads/writes mode in localStorage key `slp-software-mode` (guarded try/catch); never writes the variant. Applies `data-variant`/`data-mode`. Migration: ignore the old `slp-software-theme` key.
|
||||
|
||||
### OfferingsService (usePackagesQuery)
|
||||
- `GET /api/v1/offerings` via TanStack Query; later replaced by `cms-client/offerings`.
|
||||
|
||||
### ContactService (cms-client/contact)
|
||||
Orchestration of one submission:
|
||||
1. On first focus (or mount), `getToken()` fetches the server-signed timestamp token and captcha info.
|
||||
2. `useContactForm` validates on blur / submit; honeypot filled → no request, show success (silent drop).
|
||||
3. Submit sends `POST /api/v1/contact-messages` with `Idempotency-Key`.
|
||||
4. `202` → `sent`; `400` token expired → refetch token and retry once; `400` field errors → map to fields; `429` → `failed` with retry-after message; other → `failed` (input kept).
|
||||
5. No PII in logs, Sentry breadcrumbs or analytics events (Sentry `beforeBreadcrumb`/`beforeSend` scrub for the form route).
|
||||
|
||||
### Observability
|
||||
- Existing Sentry and Umami remain. Umami event for form outcome without field data (`contact-sent`, `contact-failed`).
|
||||
|
||||
## Backend services (SlpModularCms, by `SLS Software - CMS`)
|
||||
- **ContactMessageService**: validate → store (status `new`) → send mail best-effort via `IEmailSender` → update `mailStatus`.
|
||||
- **ContactTokenService**: issues and verifies HMAC-signed timestamp tokens (site-bound).
|
||||
- **SpamGuard**: honeypot, minimum elapsed time from the token, optional captcha verification (Friendly Captcha), identical 202 response on spam.
|
||||
- **RetentionJob**: deletes messages older than the configured retention (12 months).
|
||||
- **RateLimiting**: extends `AddCmsRateLimiting` with policy `ContactForm`; needs `ForwardedHeaders:KnownProxies` for the real client IP.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
# Unit Dependencies
|
||||
|
||||
## Matrix
|
||||
| Unit | Depends on | Blocks |
|
||||
|---|---|---|
|
||||
| U1 theme-foundation | — | U2, U3, U4, U5 |
|
||||
| U2 b-modern-sections | U1 | U3, U4 (container frames) |
|
||||
| U3 packages-block | U1, U2 | U4 (preselect), U5 (shared packages logic) |
|
||||
| U4 contact-form | U1, U2, U3 (preselect context) | U5 (`cms-client` reused by the terminal skin) |
|
||||
| U5 e-timetravel | U1, U3, U4 | — |
|
||||
| X-a category | — | U3 real data (soft) |
|
||||
| X-b gate + rate limit | — | U4 end-to-end test (soft) |
|
||||
| X-c contact module | X-b (marker) | U4 end-to-end test |
|
||||
| X-d mail + retry | X-c, merge of ASF branch | owner notification in production (not frontend) |
|
||||
| X-e admin API | X-c | X-f |
|
||||
| X-f admin UI | X-e, merge of ASF branch | — |
|
||||
|
||||
## Diagram
|
||||
```mermaid
|
||||
graph TD
|
||||
U1[U1 theme-foundation] --> U2[U2 b-modern-sections]
|
||||
U2 --> U3[U3 packages-block]
|
||||
U3 --> U4[U4 contact-form]
|
||||
U4 --> U5[U5 e-timetravel]
|
||||
Xa[X-a category] -.soft.-> U3
|
||||
Xb[X-b gate and rate limit] --> Xc[X-c contact module]
|
||||
Xc -.end to end.-> U4
|
||||
Xc --> Xd[X-d mail and retry]
|
||||
Xc --> Xe[X-e admin API]
|
||||
Xe --> Xf[X-f admin UI]
|
||||
Merge[(merge of ASF branch decided by Bryan)] -.-> Xd
|
||||
Merge -.-> Xf
|
||||
classDef fe fill:#63b3ed,stroke:#2b6cb0,color:#000;
|
||||
classDef cms fill:#9ae6b4,stroke:#2f855a,color:#000;
|
||||
classDef gate fill:#f6e05e,stroke:#c05621,color:#000;
|
||||
class U1,U2,U3,U4,U5 fe;
|
||||
class Xa,Xb,Xc,Xd,Xe,Xf cms;
|
||||
class Merge gate;
|
||||
```
|
||||
Text alternative: frontend units run in sequence U1 to U5; CMS units run in parallel, with the form unit's end-to-end test depending on the contact module and mail and admin UI waiting for the merge of the ASF branch.
|
||||
|
||||
## Integration points and checkpoints
|
||||
- **Contract**: `contact-api-contract.md` v0.3.1 (source of truth, OpenAPI exported by the CMS later).
|
||||
- **Checkpoint 1 (after U3)**: packages with mock data of 3 and 6, swipe row on a phone viewport.
|
||||
- **Checkpoint 2 (after U4)**: form against mock server; contract tests; notify the CMS builder if the contract needs changes.
|
||||
- **Checkpoint 3 (Build and Test)**: end-to-end against a test host once X-b and X-c are deployed there.
|
||||
- **Rollback**: each unit is its own commit; the form is behind `VITE_CONTACT_FORM_ENABLED`; E is a separate lazy chunk.
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
# Requirement-to-Unit Map
|
||||
|
||||
User Stories were skipped (single visitor persona, detailed requirements). Requirements are mapped to units instead.
|
||||
|
||||
| Requirement | Summary | Unit(s) |
|
||||
|---|---|---|
|
||||
| FR-1 | Design B default site | U2 (+U3, U4 parts) |
|
||||
| FR-2 | Variant E full, five eras | U5 |
|
||||
| FR-3 | Theme model variant × mode, accents | U1 |
|
||||
| FR-4 | Mode switch + icon-only variant button | U1 |
|
||||
| FR-5 | System preference, persisted mode, variant not remembered | U1 |
|
||||
| FR-6 | E lazy-loaded | U1 (boundary), U5 (content) |
|
||||
| FR-7 | Any number of packages | U3 |
|
||||
| FR-8 | Chips from 4 packages, category from API | U3, X-a |
|
||||
| FR-9 | Maatwerk banner | U3, U5 |
|
||||
| FR-10 | Mobile swipe row | U3 |
|
||||
| FR-11 | Extra package content out of scope; mock data | U3 (tests) |
|
||||
| FR-12 | Packages styling B and E | U3 (B), U5 (E) |
|
||||
| FR-13 | Form fields, all required, limits | U4 |
|
||||
| FR-14 | Submit to CMS, store, mail, 12 months | U4 (client), X-c, X-d |
|
||||
| FR-14a | Future: message to assignment | none (out of scope; data model leaves room in X-c) |
|
||||
| FR-15 | Form states | U4 |
|
||||
| FR-16 | Spam protection | U4 (client), X-c |
|
||||
| FR-17 | Privacy sentence, per-site config | U4 |
|
||||
| FR-18 | Reusable cms-client package | U4 (first version), moves to SlpModularCms later |
|
||||
| FR-19 | Form skins B and E | U4 (B), U5 (E) |
|
||||
| NFR-1 | WCAG AA, reduced motion | all; verified in U1, U3, U4, U5 |
|
||||
| NFR-2 | Responsive | U2, U3, U5 |
|
||||
| NFR-3 | Performance, fonts, code split | U1, U5 |
|
||||
| NFR-4 | Security baseline | U4 (+ X-b, X-c) |
|
||||
| NFR-5 | Privacy | U4, X-c |
|
||||
| NFR-6 | Testing, PBT partial | all; PBT in U4 |
|
||||
| NFR-7 | Maintainability | U1 |
|
||||
| NFR-8 | Compatibility | all |
|
||||
|
||||
All FR/NFR are assigned. Open external items are tracked in `unit-of-work.md` (X-a..X-f).
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
# Units of Work
|
||||
|
||||
**Code organization**: brownfield monolith SPA (Vite/React/TS) in the workspace root `src/`; no new deployable services. Target layout is described in `components.md`. Application code never goes in `aidlc-docs/`.
|
||||
|
||||
## Frontend units (this repo)
|
||||
|
||||
### U1 — theme-foundation
|
||||
- **Purpose**: replace red/purple with variant (B|E) × mode (light|dark).
|
||||
- **Responsibilities**: `ThemeProvider` (mode from system preference + persisted choice; variant app-state only, always starts in B), tokens as CSS variable sets per `[data-variant][data-mode]`, `ModeToggle`, icon-only `VariantToggle`, `VariantRenderer` (B eager, E lazy placeholder), removal of old themes and storage key migration, self-hosted fonts for B, `usePrefersReducedMotion`/`usePrefersDark`, tests.
|
||||
- **Design stages**: Functional Design (theme state rules). NFR: covered by requirements.
|
||||
- **Requirements**: FR-3, FR-4, FR-5, FR-6 (shell), NFR-1 (focus/aria for toggles), NFR-3 (fonts), NFR-7.
|
||||
|
||||
### U2 — b-modern-sections
|
||||
- **Purpose**: design B default site (light and dark), without packages and form internals.
|
||||
- **Responsibilities**: NavB, HeroB, AboutB (photo, existing WebP variants), ProcessB ("Van idee naar live in drie stappen" progress bar), FooterB, contact block frame (red block, white/dark panel container), section anchors without years in the menu, B accent `#7A1414`, responsive 360px-1440px+, tests.
|
||||
- **Design stages**: none (design exists in the canvas).
|
||||
- **Requirements**: FR-1, NFR-1, NFR-2.
|
||||
|
||||
### U3 — packages-block
|
||||
- **Purpose**: generic packages block for B.
|
||||
- **Responsibilities**: `PackageCardData.category`, `usePackageFilter` (chips from 4+ packages, counts, order of first appearance), `useSwipeRow` (mobile scroll-snap row, ~85% card width, dots, featured first), skeleton for any count, banner "Past er niets bij?", "Kies …" button feeding `ContactPreselectContext`, mock data for 6 packages in tests, tests.
|
||||
- **Design stages**: Functional Design (filter and swipe behaviour).
|
||||
- **Requirements**: FR-7, FR-8, FR-9, FR-10, FR-11, FR-12 (B part), NFR-1, NFR-2.
|
||||
- **External dependency**: X-a (`category` in the API) for real data; works without (no category → no chips).
|
||||
|
||||
### U4 — contact-form
|
||||
- **Purpose**: working contact form in B and the movable headless package.
|
||||
- **Responsibilities**: `src/cms-client/` (`http`, `contact`: reducer, validation, `useContactForm`, `createContactClient`, default messages), import-boundary lint rule, `ContactFormView` (B skin), privacy sentence, honeypot/idempotency/token handling, mailto fallback with feature flag `VITE_CONTACT_FORM_ENABLED`, CSP/connect-src notes, Sentry/Umami scrubbing, PBT for pure functions (partial), tests incl. contract tests against a mock server.
|
||||
- **Design stages**: Functional Design, NFR Requirements, NFR Design, Infrastructure Design (nginx route, CSP, env). Security Baseline enforced.
|
||||
- **Requirements**: FR-13..FR-19, NFR-4, NFR-5, NFR-6.
|
||||
- **External dependencies**: contract v0.3.x; X-b/X-c (rate limit, contact endpoint) for end-to-end; X-d (mail) and X-e (admin) are not needed for the frontend.
|
||||
|
||||
### U5 — e-timetravel
|
||||
- **Purpose**: variant E in full, lazy-loaded.
|
||||
- **Responsibilities**: `LandingE` with eras 2026/2013/2006/1998/1989, year badges, Win98 Werkwijze step cards, packages 2006 style (glossy tabs/cards, star badge, "Maatwerk!" banner), terminal form skin (`ContactFormTerminal`) on `cms-client`, light/dark tokens, EffectsLayer (marquee, scanlines, dither, caret) fully disabled under reduced motion, E fonts only in the E chunk, tests (render per era, reduced motion, variant switch round-trip).
|
||||
- **Design stages**: NFR Requirements and NFR Design (performance with effects, accessibility). No Functional Design (design exists).
|
||||
- **Requirements**: FR-2, FR-12 (E part), FR-19 (E part), NFR-1, NFR-2, NFR-3.
|
||||
|
||||
## External units (CMS builder, SlpModularCms — feature `contact-forms-module`)
|
||||
| Id | Content | Base |
|
||||
|---|---|---|
|
||||
| X-0 | RESTful refactor of the existing Offerings routes (no `/admin` segment) incl. admin-frontend call sites and tests (CMS-U0) | master |
|
||||
| X-a | `category` on Offerings as CMS-managed data (`OfferingCategory` CRUD, FK on Offering) + categories sub-section and dropdown in the Offerings admin (CMS-U1, CMS-U1b) | master |
|
||||
| X-b | `OnRejected` with `Retry-After` + ProblemDetails; `[PublicSiteEndpoint]` marker for the availability gate | master |
|
||||
| X-c | Contact module: token, submit, idempotency, spam, retention fields (mail behind own interface) | master |
|
||||
| X-d | Mail with retry job (new `MailKind`) | after merge of `feature/identity-email-notifications` + rebase |
|
||||
| X-e | Admin API (list/detail/status/delete/resend) | master |
|
||||
| X-f | Admin UI "Berichten" | after merge + rebase |
|
||||
| X-g | RESTful `Availability` status route (PUT instead of `POST admin/status`), callers checked | after merge + rebase |
|
||||
|
||||
Frontend integration with the real API happens in Build and Test once X-b/X-c exist on a test host.
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
# Application Design Plan — redesign-modern-timetravel
|
||||
|
||||
## Steps
|
||||
- [x] Analyze context (requirements.md, execution-plan.md, RE artifacts, replies from SLS Software - CMS and CMS & API)
|
||||
- [x] Resolve design questions (asked interactively in chat at the user's request, answers below)
|
||||
- [x] Generate components.md
|
||||
- [x] Generate component-methods.md
|
||||
- [x] Generate services.md
|
||||
- [x] Generate component-dependency.md
|
||||
- [x] Generate contact-api-contract.md (draft contract for the CMS sessions)
|
||||
- [x] Generate application-design.md (consolidated)
|
||||
- [x] Validate design completeness and consistency
|
||||
|
||||
## Design Questions and Answers (asked interactively, 2026-11-09)
|
||||
|
||||
## Question 1 — How do B and E share content and logic?
|
||||
- A) Shared layer + separate presentation per variant (E lazy-loaded)
|
||||
- B) Two fully separate component trees
|
||||
- C) One component set, variant via CSS only
|
||||
- X) Other
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Question 2 — Is the variant visible in the URL?
|
||||
- A) App state only; always start in B; E stays a surprise
|
||||
- B) Shareable link to E (e.g. `/#/?v=tijdreis`); still not remembered
|
||||
- X) Other
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Question 3 — How is the form UI built before the cms-client package exists?
|
||||
- A) Contract adapter + mock; replace when the CMS repo delivers the package
|
||||
- B) Pre-build the headless form logic here (based on the ASF form), then hand over to the CMS repo
|
||||
- C) Wait for the package (start U4 later)
|
||||
- X) Other
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Decisions derived from the answers
|
||||
- Q1-A: shared `content`, data hooks and form logic; per-variant presentational components under `src/variants/b` and `src/variants/e`; `React.lazy` boundary for E.
|
||||
- Q2-A: variant lives only in React context; no URL parameter; not persisted. Only the mode (light/dark) is persisted.
|
||||
- Q3-B: the headless form logic is written **in this repo** inside a self-contained folder `src/cms-client/` (subpaths `contact/`, later `offerings/`), with an enforced import boundary (it may not import from the rest of the app), so it can be moved to SlpModularCms as the package `cms-client` without rewriting. `SLS Software - CMS` builds the API module and takes over the package afterwards; the API contract in `contact-api-contract.md` is the shared source of truth until then.
|
||||
@@ -0,0 +1,162 @@
|
||||
# Execution Plan — redesign-modern-timetravel
|
||||
|
||||
## Detailed Analysis Summary
|
||||
|
||||
### Transformation Scope (Brownfield Only)
|
||||
- **Transformation Type**: Multi-component application change (frontend re-theme + new capability) with a cross-repo dependency (CMS/API).
|
||||
- **Primary Changes**: Replace the red/purple dark theme with variant (B/E) × mode (light/dark); rebuild all landing sections to design B; build variant E (five eras) as a lazy-loaded alternative; generic packages block with filter and mobile swipe row; contact form with headless module.
|
||||
- **Related Components**: this repo (`slp-software-frontend`); SlpModularCms (endpoint, `category` field, headless form package); consumer sites such as AndreaSlopFotografie (own `ContactForm` today).
|
||||
|
||||
### Change Impact Assessment
|
||||
- **User-facing changes**: Yes — complete visual redesign, new variant switch, new form, new mobile packages UX.
|
||||
- **Structural changes**: Yes — theme model, route/variant composition with lazy E bundle, new form module boundary.
|
||||
- **Data model changes**: Yes — `PackageCardData.category`; new contact message entity (CMS side).
|
||||
- **API changes**: Yes — new `POST /api/v1/contact-messages`; extended `GET /api/v1/offerings`.
|
||||
- **NFR impact**: Yes — security (PII, spam, rate limiting), accessibility (WCAG AA, reduced motion), performance (code split, fonts).
|
||||
|
||||
### Component Relationships
|
||||
```mermaid
|
||||
graph TD
|
||||
FE[slp-software-frontend - PRIMARY, major] --> API[SlpModularCms API - endpoint and category, major]
|
||||
FE --> Mod[Headless form package - from SlpModularCms, major]
|
||||
Mod --> API
|
||||
Andrea[AndreaSlopFotografie and other sites - consumers, later] --> Mod
|
||||
FE --> Nginx[nginx proxy and CSP - config only]
|
||||
classDef primary fill:#63b3ed,stroke:#2b6cb0,color:#000;
|
||||
classDef ext fill:#f6e05e,stroke:#c05621,color:#000;
|
||||
classDef cfg fill:#9ae6b4,stroke:#2f855a,color:#000;
|
||||
class FE primary;
|
||||
class API,Mod,Andrea ext;
|
||||
class Nginx cfg;
|
||||
```
|
||||
Text alternative: the frontend depends on the CMS API and on the headless form package that the CMS repo ships; other sites consume the same package; nginx and CSP need configuration changes.
|
||||
|
||||
| Component | Change type | Reason | Priority |
|
||||
|---|---|---|---|
|
||||
| slp-software-frontend | Major | redesign, theme model, form UI | Critical |
|
||||
| SlpModularCms API | Major | contact endpoint, `category` | Critical (form), Important (category) |
|
||||
| Headless form package (SlpModularCms) | Major | agreed reusable module | Critical (for form unit) |
|
||||
| nginx / CSP | Configuration-only | API route, fonts | Important |
|
||||
| Other sites (Andrea etc.) | Minor, later | adopt module | Optional (out of this feature) |
|
||||
|
||||
### Risk Assessment
|
||||
- **Risk Level**: Medium-High (large visual scope, cross-repo contract, PII handling)
|
||||
- **Rollback Complexity**: Easy for the frontend (branch/PR revert, hash-routed static bundle); Moderate for CMS endpoint (data stored)
|
||||
- **Testing Complexity**: Complex (themes × variants × viewports, form states, cross-repo contract)
|
||||
|
||||
## Workflow Visualization
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["User Request"])
|
||||
|
||||
subgraph INCEPTION["🔵 INCEPTION PHASE"]
|
||||
WD["Workspace Detection<br/><b>COMPLETED</b>"]
|
||||
RE["Reverse Engineering<br/><b>COMPLETED</b>"]
|
||||
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
|
||||
US["User Stories<br/><b>SKIP</b>"]
|
||||
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
|
||||
AD["Application Design<br/><b>EXECUTE</b>"]
|
||||
UG["Units Generation<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
|
||||
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE (per unit U1..U5)"]
|
||||
FD["Functional Design<br/><b>EXECUTE U1 U3 U4</b>"]
|
||||
NFRA["NFR Requirements<br/><b>EXECUTE U4 U5</b>"]
|
||||
NFRD["NFR Design<br/><b>EXECUTE U4 U5</b>"]
|
||||
ID["Infrastructure Design<br/><b>EXECUTE U4</b>"]
|
||||
CG["Code Generation<br/><b>EXECUTE</b>"]
|
||||
BT["Build and Test<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
|
||||
OPS["Operations Phase<br/><b>UNDECIDED - asked after Construction</b>"]
|
||||
|
||||
Start --> WD --> RE --> RA
|
||||
RA -.-> US
|
||||
RA --> WP --> AD --> UG --> FD
|
||||
FD --> NFRA --> NFRD --> ID --> CG
|
||||
CG -.->|next unit| FD
|
||||
CG --> BT
|
||||
BT -.-> OPS
|
||||
BT --> End(["Complete"])
|
||||
|
||||
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RE fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style NFRD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style ID fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style OPS fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
|
||||
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
|
||||
linkStyle default stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
Text alternative: inception runs Application Design and Units Generation (User Stories skipped), then construction loops over five units with design stages only where useful; Operations is decided after construction.
|
||||
|
||||
## Phases to Execute
|
||||
|
||||
### 🔵 INCEPTION PHASE
|
||||
- [x] Workspace Detection (COMPLETED)
|
||||
- [x] Reverse Engineering (COMPLETED)
|
||||
- [x] Requirements Analysis (COMPLETED)
|
||||
- [x] User Stories (SKIP) — single visitor persona, requirements already detailed; can be added on request
|
||||
- [~] Workflow Planning (IN PROGRESS)
|
||||
- [ ] Application Design — EXECUTE
|
||||
- **Rationale**: new components and boundaries: variant/mode theme model, lazy E bundle composition, packages block (grid/filter/swipe), headless form module and its API contract with the CMS. The **form contract** produced here is what the CMS session and other form sessions can start from.
|
||||
- [ ] Units Generation — EXECUTE
|
||||
- **Rationale**: multiple units with different risk and dependency (see below).
|
||||
|
||||
### 🟢 CONSTRUCTION PHASE
|
||||
Units (proposed order, B first as requested):
|
||||
- **U1 theme-foundation**: variant × mode model, tokens (B light/dark, E tokens placeholder), system preference, nav switch buttons (mode + icon-only variant button), removal of red/purple, fonts.
|
||||
- **U2 b-modern-sections**: hero, Over (photo), Werkwijze, nav/footer, contact block frame, light/dark.
|
||||
- **U3 packages-block**: generic grid, skeleton, filter chips (4+), swipe row on mobile, `category` field, B styling.
|
||||
- **U4 contact-form**: headless form logic + validation + states, B styling, contract with CMS, spam fields, privacy line. **Coordination gate**: the user is notified before this unit's design/implementation starts (see below).
|
||||
- **U5 e-timetravel**: lazy-loaded E with five eras, Win98 Werkwijze step cards, packages (2006 style) and form styling per era, light/dark, reduced-motion handling.
|
||||
|
||||
Stage decisions:
|
||||
- [ ] Functional Design — EXECUTE for U1, U3, U4; SKIP for U2, U5 (design exists in the canvas)
|
||||
- **Rationale**: U1 theme state rules, U3 filter/swipe behaviour, U4 form states/validation/contract are real logic; U2/U5 are visual ports of the canvas.
|
||||
- [ ] NFR Requirements — EXECUTE for U4, U5; SKIP for U1-U3
|
||||
- **Rationale**: U4 security/PII/rate-limit/spam; U5 performance (code split, effects) and accessibility with heavy effects. Other units covered by requirements.md NFR-1..8.
|
||||
- [ ] NFR Design — EXECUTE for U4, U5 (follows NFR Requirements)
|
||||
- [ ] Infrastructure Design — EXECUTE for U4 only (lightweight)
|
||||
- **Rationale**: nginx route for the form endpoint, CSP/connect-src, env configuration; skipped for U1-U3 and U5 (no infra impact).
|
||||
- [ ] Code Generation — EXECUTE (ALWAYS), per unit, with automatic per-unit build/test
|
||||
- [ ] Build and Test — EXECUTE (ALWAYS)
|
||||
|
||||
### 🟡 OPERATIONS PHASE
|
||||
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation — UNDECIDED
|
||||
- **Rationale**: Requirements Q15-C; asked again at Build and Test.
|
||||
|
||||
## Package Change Sequence / Module Update Strategy
|
||||
- **Update Approach**: Hybrid — frontend units sequential; CMS work parallel to U1-U3 once the contract exists.
|
||||
- **Critical Path**: Application Design (form contract) → CMS endpoint + headless package → U4 integration.
|
||||
- **Coordination Points**: `POST /api/v1/contact-messages` contract; `category` on `GET /api/v1/offerings`; headless package API (hook/component slots); nginx route and CSP.
|
||||
- **Testing Checkpoints**: per-unit tests; contract test (mock server) for U4; integrated check once the CMS endpoint exists.
|
||||
- **Rollback**: frontend by PR revert; CMS endpoint behind the agreed contract version; mailto fallback while the endpoint is unavailable (feature flag).
|
||||
|
||||
## Coordination Plan
|
||||
- **Form notice (user request)**: the user is told **before the form unit starts**, so they can attach the CMS session and the sessions of other sites that want a form. Because the headless module comes from the CMS repo, the recommended moment is the end of **Application Design** (contract ready, CMS can start in parallel with U1-U3).
|
||||
- Candidate sessions to attach (from the session list, to be chosen by the user): `CMS & API`, `slpmodularcms-ec`, `slpmodularcms-f7`, `slpmodularcms-6b`, `AndreaSlopFotografie`, `slpsoftware-5d`.
|
||||
|
||||
## Estimated Timeline
|
||||
- **Total Phases**: 2 active (Inception remaining 2 stages; Construction 5 units), Operations undecided
|
||||
- **Estimated Duration**: several working sessions; U5 is the largest unit.
|
||||
|
||||
## Success Criteria
|
||||
- **Primary Goal**: B live as default site with working light/dark and an icon button revealing E; contact form working end-to-end.
|
||||
- **Key Deliverables**: variant/mode theme system, B sections, generic packages block with mobile swipe row, contact form + contract + CMS hand-off, E variant, tests.
|
||||
- **Quality Gates**: `pnpm lint`, `tsc -b`, `vitest run` green; WCAG AA checks; security baseline rules compliant; reduced-motion verified; contract test passing.
|
||||
- **Integration Testing**: frontend ↔ CMS endpoint once available.
|
||||
- **Operational Readiness**: decided at Build and Test (Operations undecided).
|
||||
@@ -0,0 +1,25 @@
|
||||
# Unit of Work Plan — redesign-modern-timetravel
|
||||
|
||||
## Steps
|
||||
- [x] Analyze requirements, execution plan and application design for decomposition
|
||||
- [x] Resolve decomposition question (asked interactively)
|
||||
- [x] Generate `inception/application-design/unit-of-work.md`
|
||||
- [x] Generate `inception/application-design/unit-of-work-dependency.md`
|
||||
- [x] Generate `inception/application-design/unit-of-work-story-map.md` (requirements-to-unit map; User Stories were skipped)
|
||||
- [x] Validate unit boundaries and dependencies
|
||||
- [x] Ensure all requirements (FR/NFR) are assigned to units
|
||||
|
||||
## Question (asked interactively, 2026-11-09)
|
||||
|
||||
## Question 1 — Order of the last two frontend units
|
||||
- A) Form first (U4 before U5)
|
||||
- B) E first (U5 before U4)
|
||||
- C) In parallel
|
||||
- X) Other
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Decomposition approach (from the execution plan, confirmed)
|
||||
- Single repository, brownfield, **monolith SPA**: units are logical modules delivered sequentially, each with its own design/code/test cycle. Branch `feature/redesign-modern-timetravel`, commits per unit, one PR at the end.
|
||||
- Frontend units U1-U5 here; **external units** X-a..X-f are built by the CMS builder (`SLS Software - CMS`, feature `contact-forms-module` in SlpModularCms) and tracked here only as dependencies.
|
||||
- Order (user decision): U1 → U2 → U3 → U4 → U5. The form (U4) works against a mock/contract client until the CMS endpoint exists.
|
||||
+173
@@ -0,0 +1,173 @@
|
||||
# Requirements-vragen — redesign B (Modern) + E (Tijdreis) + contactformulier
|
||||
|
||||
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies de laatste (Anders) en beschrijf je voorkeur.
|
||||
|
||||
Context uit de analyse: de zusterrepo `AndreaSlopFotografie-cms-api-foundation` bevat feature-briefs voor de aparte repo **SlpModularCms** (de CMS/API) en een afgeronde `contact-page`-feature met een eigen `ContactForm`. Daar sluiten de andere formulier-sessies en de CMS-sessie op aan (vragen 9 t/m 13).
|
||||
|
||||
---
|
||||
|
||||
## Vraag 1 — Scope van B en E in deze feature
|
||||
B is het uitgangspunt. E (Tijdreis) is een grote bouw met vijf tijdperken (2026, 2013, 2006, 1998, 1989).
|
||||
|
||||
- A) B volledig + E volledig, in deze feature, als aparte units (B eerst, dan E)
|
||||
- B) B volledig + de wissel-infrastructuur (knop, thema-model, laden van E) nu; de E-secties in een vervolgfeature
|
||||
- C) Alleen B nu; de knop naar E pas bouwen zodra E aan de beurt is
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 2 — Uiterlijk van de knop naar E
|
||||
Naast de licht/donker-schakelaar in de nav.
|
||||
|
||||
- A) Icoon + tekst (bijv. een klokje/terugspoelpijl met "Tijdreis")
|
||||
- B) Alleen een icoon met tooltip en toegankelijk label
|
||||
- C) Tekst die van label wisselt ("Tijdreis" in B, "Terug naar nu" in E)
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Vraag 3 — Onthouden van de variant
|
||||
Moet de bezoeker na een bezoek aan E de volgende keer weer in E starten?
|
||||
|
||||
- A) Nee, altijd starten in B (E blijft een verrassing); alleen licht/donker wordt onthouden
|
||||
- B) Ja, variant én licht/donker worden onthouden (localStorage)
|
||||
- C) Alleen binnen dezelfde sessie onthouden (sessionStorage)
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 4 — Bestaande rood/paars-thema's
|
||||
Nu zijn er twee kleurthema's (rood, paars). In het ontwerp heeft B accent #7A1414 en E #AC0000, met licht en donker.
|
||||
|
||||
- A) Rood/paars vervalt; thema wordt: variant (B/E) × modus (licht/donker)
|
||||
- B) Paars blijft als extra accentkeuze voor B
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 5 — Beginstand licht/donker
|
||||
- A) Standaard licht, daarna de gekozen modus onthouden
|
||||
- B) Volg de systeeminstelling van de bezoeker (prefers-color-scheme); gekozen modus overschrijft dit en wordt onthouden
|
||||
- C) Standaard donker (zoals de huidige site)
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Vraag 6 — Pakketten: aantal, filter en categorieën
|
||||
De API levert nu 3 pakketten. Het ontwerp toont ook 6 pakketten met filterchips (Websites / Software / Beheer). Vier daarvan hebben nog geen inhoud.
|
||||
|
||||
- A) Het blok moet met elk aantal pakketten overweg kunnen; de filterchips verschijnen pas vanaf 4 pakketten; categorie komt als veld uit de API
|
||||
- B) Zoals A, maar de categorie wordt in de frontend afgeleid uit de slug (geen API-wijziging)
|
||||
- C) Altijd 3 kaarten zonder filter; het 6-pakkettenontwerp is alleen een toekomstvoorbeeld
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 7 — Pakketten op mobiel
|
||||
Je suggestie: naast elkaar en swipeable in plaats van onder elkaar.
|
||||
|
||||
- A) Horizontale swipe-rij (scroll-snap) op mobiel bij elk aantal pakketten: ~85% kaartbreedte zodat de volgende kaart zichtbaar is, stipjes, uitgelicht pakket als eerste in beeld; raster op tablet/desktop
|
||||
- B) Swipe-rij alleen bij meer dan 3 pakketten; bij 3 pakketten onder elkaar
|
||||
- C) Op mobiel onder elkaar laten staan
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 8 — Inhoud van de vier extra pakketten
|
||||
- A) Niet in scope: ik bouw het blok generiek en test met nepdata; de echte inhoud volgt via de API/CMS
|
||||
- B) Wel in scope: ik lever de teksten en prijzen aan voordat de code gegenereerd wordt
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 9 — Velden van het contactformulier
|
||||
- A) Naam, e-mail, onderwerp/pakket (keuzelijst, voorgeselecteerd via de "Kies …"-knop op een kaart), bericht
|
||||
- B) Zoals A, plus telefoonnummer (optioneel) en bedrijf (optioneel)
|
||||
- C) Zoals A, plus indicatie budget en gewenste startdatum (optioneel)
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 10 — Wat gebeurt er met een verzonden formulier?
|
||||
- A) De CMS/API (SlpModularCms) krijgt een eindpunt (bijv. `POST /api/v1/contact-messages`) dat het bericht opslaat én een e-mail naar mij stuurt
|
||||
- B) Alleen een e-mail naar mij via de API, geen opslag
|
||||
- C) Voorlopig de mailto-link behouden tot de API klaar is; formulier-UI en validatie wel bouwen en achter een instelling (feature flag) zetten
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 11 — Hoe delen de sessies het formulier?
|
||||
Andere sessies willen ook een formulier (o.a. de Andrea-site met een eigen `ContactForm`); de CMS-sessie bouwt de API.
|
||||
|
||||
- A) Eén gedeeld contract (request/response, foutcodes, spamregels) in de CMS-repo; elke site bouwt zijn eigen formulier-UI daartegen
|
||||
- B) De CMS-repo levert een herbruikbare formuliermodule (frontend-component + endpoint) die alle sites gebruiken
|
||||
- C) Elke site volledig eigen formulier en eindpunt (geen deling)
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: B
|
||||
|
||||
## Vraag 12 — Spambescherming
|
||||
- A) Honeypot-veld + tijdcontrole + rate-limit op de server, zonder externe dienst
|
||||
- B) Externe captcha (bijv. Cloudflare Turnstile of hCaptcha)
|
||||
- C) Combinatie: A, met een captcha als terugvaloptie als er misbruik komt
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: C
|
||||
|
||||
## Vraag 13 — Privacy bij het formulier
|
||||
- A) Korte privacyzin onder het formulier (waarvoor de gegevens gebruikt worden en hoe lang bewaard), zonder aanvinkvakje
|
||||
- B) Verplicht aanvinkvakje voor toestemming
|
||||
- C) Geen aparte tekst
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 14 — Toegankelijkheid en beweging
|
||||
E heeft veel effecten (scanlines, marquee, dithering, glanzende knoppen).
|
||||
|
||||
- A) WCAG 2.1 AA voor B en E (contrast, toetsenbord, schermlezer) en alle animatie uit bij `prefers-reduced-motion`
|
||||
- B) WCAG AA voor B; in E mogen effecten blijven, maar tekst blijft leesbaar en animatie stopt bij `prefers-reduced-motion`
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
|
||||
## Vraag 15 — Operations-fase
|
||||
Deployment (Gitea Actions + test/productie op de Pi's) bestaat al uit de vorige feature.
|
||||
|
||||
- A) Ja — Operations-fase draaien (deployment- en monitoringaanpassingen, bijv. voor het formulier-eindpunt in de nginx-proxy)
|
||||
- B) Nee — stoppen na Build and Test; bestaande pipeline blijft ongewijzigd
|
||||
- C) Nog niet zeker — vraag het opnieuw na de Construction-fase
|
||||
- X) Anders (beschrijf na de [Answer]:-tag)
|
||||
|
||||
[Answer]: C
|
||||
|
||||
## Vraag: Beveiligingsextensies
|
||||
Moeten de beveiligingsregels als harde vereisten worden afgedwongen voor dit project? (Het formulier verwerkt persoonsgegevens, dus A ligt voor de hand.)
|
||||
|
||||
- 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: Property-Based Testing Extensie
|
||||
Moeten de property-based testing (PBT) regels worden afgedwongen voor dit project? (Denkbare kandidaat: formuliervalidatie.)
|
||||
|
||||
- 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 16 — Vervolg op vraag 11: vorm van de formuliermodule
|
||||
Antwoord gekozen in de chat (interactieve vragenronde, 2026-11-09).
|
||||
|
||||
- A) Headless + thema-slots
|
||||
- B) Vooraf gestyled component
|
||||
- C) Web component
|
||||
|
||||
[Answer]: A
|
||||
|
||||
---
|
||||
Opmerking: alle antwoorden zijn interactief in de chat gegeven op verzoek van de gebruiker en hierboven overgenomen.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Requirements — redesign-modern-timetravel
|
||||
|
||||
## Intent Analysis
|
||||
- **User request**: Build design option B (Modern) as the default site, add a button next to the light/dark switch to switch to option E (Time-travel), and build the contact form along with it. Other sessions that also need a form, and the CMS & API session, are attached when the form build starts.
|
||||
- **Request type**: New Feature (redesign + variant switch + new capability: contact form)
|
||||
- **Scope estimate**: Multiple components / cross-system (frontend theme system, nav, all landing sections, form; CMS/API repo SlpModularCms for the endpoint and shared module)
|
||||
- **Complexity estimate**: Complex
|
||||
- **Requirements depth**: Standard (comprehensive for the form/cross-repo part)
|
||||
- **Design source**: Claude Design canvas https://claude.ai/artifact/UkpzA5YPLheZm3fpmWdPtn — B = Modern.dc.html, E = Tijdreis2.dc.html, PakkettenModern.dc.html, PakkettenTijd.dc.html, plus dark wrappers. Accent B `#7A1414`, E `#AC0000`.
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### Variants and theming
|
||||
- **FR-1** Variant B (Modern) is the default experience: hero, Over (with photo), Pakketten, Werkwijze ("Van idee naar live in drie stappen"), Contact (with form), footer, per the canvas design. Section years are not in the menu.
|
||||
- **FR-2** Variant E (Time-travel) is built in full (this feature, separate unit after B): eras 2026 modern, 2013 flat, 2006 web 2.0, 1998 Windows-98 style with the redesigned Werkwijze step cards, 1989 terminal; per canvas design E. Years remain as badges per block.
|
||||
- **FR-3** The theme model becomes **variant (B | E) × mode (light | dark)**. The old red/purple themes are removed (answer Q4-A). B accent `#7A1414`, E accent `#AC0000`. The 1989 terminal section looks the same in light and dark.
|
||||
- **FR-4** Nav contains the existing mode switch and, next to it, an **icon-only** button to switch to E (and back to B), with tooltip and accessible label (Q2-B).
|
||||
- **FR-5** Mode starts from the visitor's system preference (`prefers-color-scheme`); an explicit choice overrides it and is remembered (Q5-B). The **variant is not remembered**: every visit starts in B; E is an easter egg (Q3-A).
|
||||
- **FR-6** E is loaded lazily (code-split) so the default B bundle stays small. *(Design decision proposed by AI; revisit in Application Design.)*
|
||||
|
||||
### Packages
|
||||
- **FR-7** The packages block works with any number of packages from `/api/v1/offerings` (Q6-A). Skeleton count and grid are no longer hard-coded to 3.
|
||||
- **FR-8** Filter chips (category + count, e.g. Alles/Websites/Onderhoud) appear from **4 packages** on. Category is a **new field in the API** (`category`, the category name), a CMS/API change handed to the CMS builder. Categories are **managed in the CMS** (sub-section of the Offerings admin), not in settings; Bryan starts with *Websites* and *Onderhoud* (decision 2026-11-09, revised; earlier example values Websites/Software/Beheer were only placeholders). Mock data for 6 packages in tests uses these names.
|
||||
- **FR-9** A "Past er niets bij? / Maatwerk" banner always stays below the cards.
|
||||
- **FR-10** On mobile the cards form a **horizontal swipe row** (CSS scroll-snap) for any number of packages (Q7-A): ~85% card width so the next card peeks, dot indicator, the featured package first in view; grid on tablet/desktop (3 columns, 2 columns at ≤1000px). Must be keyboard and screen-reader usable and not depend on JavaScript for scrolling.
|
||||
- **FR-11** Content for the four additional packages (Webshop, CMS, Koppelingen & API's, Onderhoud) is **out of scope**; layout is built generically and tested with mock data of 6 packages (Q8-A).
|
||||
- **FR-12** Both B and E have their own styling of the packages block (B: square chips and cards; E: 2006 glossy tabs and cards), light and dark.
|
||||
|
||||
### Contact form
|
||||
- **FR-13** Fields: name, e-mail, subject/package (select, preselected via the "Kies …" button of a package card) and message (Q9-A). **All four fields are required** (follow-up decision 2026-11-09). All fields validated on the client and on the server. Limits and messages are aligned with the ASF form: name max 100, e-mail max 254, message max 2000.
|
||||
- **FR-14** Submit sends the message to the CMS/API, which **stores it and e-mails the site owner** (Q10-A), e.g. `POST /api/v1/contact-messages`. Exact contract defined together with the CMS sessions. Store first, mail best-effort with a status; a mail failure never fails the save. Stored messages are kept **12 months** (follow-up decision), then removed by a retention job.
|
||||
- **FR-14a (future, out of scope)** The owner may later turn a stored message into an assignment in an administration system to produce quotes and invoices. Not built now; the stored message keeps its own id and a status so this stays possible.
|
||||
- **FR-15** Form states: idle, validating (inline errors), submitting, success, server error with retry; no loss of input on error.
|
||||
- **FR-16** Spam protection (Q12-C): honeypot field + time check + server-side rate limit, with an external captcha as a fallback to switch on if abuse occurs (ASF plans Friendly Captcha; provider to be settled in the contract). Suggested hardening from the CMS session: server-signed timestamp token for the time check, idempotency key against double submit, identical response on spam detection so bots learn nothing, site id derived from host/config (never from the request body).
|
||||
- **FR-17** A one-sentence privacy note under the form (purpose and retention), no consent checkbox (Q13-A). Recipient e-mail, retention period and the privacy-statement link/text are **configurable per site** (requested by the ASF website session; ASF keeps its sentence "Lees in de privacyverklaring wat ik met je gegevens doe." linking to /privacyverklaring). Captcha provider: Friendly Captcha fits ASF (its code already has a [data-robot-check] slot).
|
||||
- **FR-18** **Reusable module** (Q11-B, Q16-A, follow-up decision): two parts. (1) A **Contact/Forms API module** in SlpModularCms (endpoint, storage, mail, spam checks, retention job). (2) **One frontend package `cms-client`** (working name) in SlpModularCms that types and calls the CMS API, with **separately importable parts** (subpath imports such as `/contact`, later `/offerings`) so a site only bundles what it uses. The contact part is **headless** (state/reducer, validation, preselect with change counter, idPrefix, render slots for honeypot/robot check/status, injectable texts and submit function, a11y wiring); each site, including B and E here and the other sites, supplies its own markup and styling. Types come from the CMS OpenAPI description. Offerings moves into the same package later for consistency (not in this feature unless cheap). Consumption route (workspace/file dependency or tagged copy first, private registry only with a third consumer) is a recommendation awaiting the user's confirmation.
|
||||
- **FR-19** Form copy and layout per design: B has a red contact block with a white (light) / dark form panel; E has the terminal-style form in 1989 and matching styles per era where applicable.
|
||||
|
||||
## Non-Functional Requirements
|
||||
- **NFR-1 Accessibility**: WCAG 2.1 AA for B and E (contrast, keyboard, screen reader, visible focus); all animation (marquee, scanlines, dither, caret) disabled under `prefers-reduced-motion` (Q14-A).
|
||||
- **NFR-2 Responsive**: layouts work from 360px to 1440px+; no horizontal page scroll (swipe row excepted).
|
||||
- **NFR-3 Performance**: E is code-split; fonts are self-hosted via `@fontsource` (no Google Fonts requests) and limited to the weights used; images keep the existing responsive WebP variants.
|
||||
- **NFR-4 Security (Security Baseline enabled)**: server-side validation and output encoding, no secrets in the frontend bundle, rate limiting, no PII in logs or Sentry/Umami events, security headers / CSP compatible with the new fonts and API origin, dependency hygiene. Applicable SECURITY rules are enforced as blocking at each stage.
|
||||
- **NFR-5 Privacy**: stored contact messages contain personal data; retention is **12 months**, stated in the privacy note and enforced by the CMS retention job. No e-mail address or message text in logs or Sentry breadcrumbs.
|
||||
- **NFR-6 Testing**: Vitest + Testing Library for components (theme switch, variant switch, packages grid with 3 and 6 items, swipe row semantics, form states). Property-based testing **partial** (Q-PBT-B): applies to pure functions and serialization round-trips, e.g. form validation functions and request/response serialization.
|
||||
- **NFR-7 Maintainability**: theme tokens as CSS variables per variant × mode; Tailwind semantic color names remain; content stays in `content.ts`/API.
|
||||
- **NFR-8 Compatibility**: hash routing and static hosting remain; the existing Sentry/Umami integration and the CI/CD pipeline keep working.
|
||||
|
||||
## Assumptions
|
||||
- Current copy and texts of the live site (incl. the November text update) are leading unless the design says otherwise.
|
||||
- The packages API keeps its current shape plus `category`; the CMS session implements it.
|
||||
- E may use period-appropriate fonts (Archivo for B; Open Sans, Trebuchet/Verdana, Times/Arial, VT323 for E) as self-hosted or system fonts.
|
||||
- Delivery: one branch `feature/redesign-modern-timetravel`, commits per unit, one PR at the end.
|
||||
|
||||
## Risks and Dependencies
|
||||
- **Cross-repo**: the endpoint, the `category` API field and the headless form module live in SlpModularCms; the CMS session must be attached. See `aidlc-docs/features/redesign-modern-timetravel/aidlc-state.md` § Coordination Notes.
|
||||
- **Form coordination moment**: the user wants to be told **before** the form build starts so other sessions (e.g. Andrea site with its own `ContactForm`) and the CMS session can join.
|
||||
- E is a large build; B-first ordering limits risk.
|
||||
|
||||
## Operations
|
||||
- Include Operations Phase: **Undecided** — asked again after Construction (Q15-C). Likely topics: nginx route for the form endpoint, monitoring of form errors.
|
||||
|
||||
## Extension Compliance Summary
|
||||
- Security Baseline: enabled (Q-Security-A). Requirements-level compliance: NFR-4/5 added; detailed per-rule checks run in later stages.
|
||||
- Property-Based Testing: partial (Q-PBT-B). Requirements-level: NFR-6.
|
||||
Reference in New Issue
Block a user