Documents build and test, operations and the approved privacy wording
Adds the build and test summary and instructions, the deployment and monitoring plans, the production readiness checklist with the go-live conditions, and the approved privacy draft (retention, controller). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -5,7 +5,7 @@
|
||||
- **Feature Slug**: contact-form-cms
|
||||
- **Project Type**: Brownfield
|
||||
- **Start Date**: 2026-11-10T21:42:54Z
|
||||
- **Current Stage**: INCEPTION - Workflow Planning (awaiting approval)
|
||||
- **Current Stage**: OPERATIONS - documents written, awaiting approval
|
||||
- **Branch**: feature/contact-form-cms (from master 7d594ff)
|
||||
- **Worktree**: K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-contact-form
|
||||
|
||||
@@ -43,13 +43,13 @@
|
||||
- [x] INCEPTION - Workspace Detection (2026-11-10)
|
||||
- [x] INCEPTION - Requirements Analysis (approved by SLP Software - SLS - Main on behalf of Bryan, 2026-11-10)
|
||||
- [x] INCEPTION - User Stories: SKIP
|
||||
- [x] INCEPTION - Workflow Planning (written, awaiting approval)
|
||||
- [x] INCEPTION - Workflow Planning (approved by SLP Software - SLS - Main on behalf of Bryan)
|
||||
- [x] INCEPTION - Application Design: SKIP
|
||||
- [x] INCEPTION - Units Generation: SKIP (one unit: contact-form)
|
||||
- [ ] CONSTRUCTION - Functional Design: EXECUTE
|
||||
- [ ] CONSTRUCTION - NFR Requirements: SKIP
|
||||
- [ ] CONSTRUCTION - NFR Design: SKIP
|
||||
- [ ] CONSTRUCTION - Infrastructure Design: EXECUTE
|
||||
- [ ] CONSTRUCTION - Code Generation: EXECUTE (plan first)
|
||||
- [ ] CONSTRUCTION - Build and Test: EXECUTE
|
||||
- [ ] OPERATIONS - EXECUTE
|
||||
- [x] CONSTRUCTION - Functional Design: EXECUTE (approved by SLS-Main for Bryan)
|
||||
- [x] CONSTRUCTION - NFR Requirements: SKIP
|
||||
- [x] CONSTRUCTION - NFR Design: SKIP
|
||||
- [x] CONSTRUCTION - Infrastructure Design: EXECUTE (approved; CSP set by Bryan: exact frame hosts)
|
||||
- [x] CONSTRUCTION - Code Generation: EXECUTE (plan approved; steps 1-13 done)
|
||||
- [x] CONSTRUCTION - Build and Test: EXECUTE (summary written; awaiting approval)
|
||||
- [x] OPERATIONS - deployment plan, monitoring plan, production readiness checklist written (go-live conditions open)
|
||||
|
||||
@@ -57,3 +57,15 @@
|
||||
**Context**: Workflow Planning complete; approval requested from SLS-Main.
|
||||
|
||||
---
|
||||
|
||||
## Construction and Operations
|
||||
|
||||
**Timestamp**: 2026-11-10T23:55:00Z
|
||||
|
||||
**User Input**: (SLP Software - SLS - Main, on behalf of Bryan) approved functional design, infrastructure design (frame-src exact hosts global, global0, global1) and the code generation plan; privacy wording approved with retention 12 months / 30 days spam and Andrea as controller; the full privacy statement is a separate feature required before go-live.
|
||||
|
||||
**AI Response**: Built steps 1-13 (commits e094594, a1444b7 and later), ran build and test (summary in construction/build-and-test), tested the real widget in Chrome against the local ASF host (202, no CSP violation), wrote deployment plan, monitoring plan and production readiness checklist with the go-live conditions.
|
||||
|
||||
**Context**: Build and Test and Operations documents written; approval requested from SLS-Main. Production stays off until Bryan go.
|
||||
|
||||
---
|
||||
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# Build and test summary: contact-form-cms
|
||||
|
||||
Date: 2026-11-10. Branch feature/contact-form-cms (a1444b7 plus later commits). Unit: contact-form (web only).
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| `tsc` (typecheck in `pnpm build`) | clean |
|
||||
| `pnpm lint` (ESLint incl. cms-client import boundary) | clean |
|
||||
| `pnpm format:check` | clean |
|
||||
| `pnpm test` (Vitest, 100% thresholds for pure functions) | 134 files, 1473 tests passed |
|
||||
| cms-client package tests (copied) | 62 passed (boundary test included) |
|
||||
| `pnpm build` + prerender | ok, 12 pages |
|
||||
| E2E `contactForm.e2e.ts` + `hydration.e2e.ts` (real Chrome, built site, mocked `/api`) | 49 passed, 2 skipped with the switch off; the 2 "switch on" tests pass in a build with the switch on |
|
||||
| `pnpm audit --prod` | no known vulnerabilities |
|
||||
| Lighthouse mobile | all pages pass, except `/` performance 0.84 (threshold 0.85); same chance result as on master earlier (0.84); not a regression of this feature |
|
||||
| Lighthouse desktop | all 12 pages pass |
|
||||
| Real widget in real Chrome against the local ASF host (CMS 192.168.1.2:5291, captcha on, global endpoint) | form opens, widget loads and solves, POST 202, thank-you shown, no CSP violation, no console message |
|
||||
|
||||
## Requirement coverage
|
||||
FR-CF-01..12 and NFR-CF-01..05 are covered by the unit/component tests (ContactForm, ContactPanel, useContactAvailability through the panel, securityHeaders, shootOptions), the e2e and the real-browser run. PBT (partial): label length 1-100 and uniqueness, JSON round trip with special characters, and the package's own property tests.
|
||||
|
||||
## Findings and decisions
|
||||
- CSP: only `frame-src` with the exact hosts global, global0, global1 is needed; the real-browser run showed no violation without `connect-src`, `script-src` or `worker-src` additions (the widget's own fetches run inside its iframe).
|
||||
- With the switch on, a `404` on the token route (form closed) logs a console message in the browser; the hydration e2e tests therefore run with the switch off and the switch-on behaviour has its own e2e with a mocked API.
|
||||
- The package needed two small changes for ASF's stricter rules (explicit field instead of a constructor parameter property; a loop instead of a recursive `useCallback`); SLS-Main made them upstream (93fa729), so the copy is unchanged.
|
||||
- Dev (StrictMode) asks for the token twice; the production build asks once.
|
||||
|
||||
## Not done / needs others
|
||||
- Test of the form against a deployed ASF test host (needs the CMS branch merged and deployed; not requested yet).
|
||||
- EU endpoint (`eu`, `eu0`, `eu1` in `frame-src`) is not tested; it needs a paid plan.
|
||||
- Screen reader check by a person.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Build instructions
|
||||
From `web/`: `pnpm install --frozen-lockfile`, then `pnpm build` (typecheck, Vite build with prerender, inline scripts moved to files). Output in `web/dist/client`.
|
||||
Local run against a CMS host: `API_PROXY_TARGET=http://<host>:<port> pnpm exec vite --host --port <port>` (no proxy without the variable). The form only talks to the server when `siteContent.contactForm.enabled` is `true`.
|
||||
+3
@@ -0,0 +1,3 @@
|
||||
# Integration and e2e test instructions
|
||||
1. Built site against a mocked API: `pnpm build` then `pnpm e2e` (real Chrome; `e2e/contactForm.e2e.ts` runs the "off" or "on" variant depending on the switch in `siteContent.ts`; to run the "on" variant build with the switch on locally and run only that file).
|
||||
2. Real server: start the local ASF host (SLS Software - CMS: API `192.168.1.2:5291`, captcha on, smtp4dev for mail), run the dev server with `API_PROXY_TARGET=http://192.168.1.2:5291`, and open `/contact`. Expected: the notice disappears, the widget solves, sending gives the thank-you, the message appears in the ASF CMS admin and in smtp4dev. Check the browser console for CSP messages.
|
||||
+2
@@ -0,0 +1,2 @@
|
||||
# Performance test instructions
|
||||
Build with the switch off (as in production now) and run `pnpm lighthouse` (mobile) and `lhci autorun --config=lighthouserc.desktop.cjs` (desktop). The form and the captcha SDK are lazy chunks loaded only when the form is near the screen and open, so pages without a form in view load no new JavaScript. Known: `/` mobile performance varies around the 0.85 threshold (0.84 also on master).
|
||||
+2
@@ -0,0 +1,2 @@
|
||||
# Unit and component test instructions
|
||||
`pnpm test` (Vitest, jsdom, coverage thresholds). Relevant files: `src/components/ContactForm/ContactForm.test.tsx` (fake Friendly Captcha SDK, fake client), `src/components/ContactPanel/ContactPanel.test.tsx` (availability states), `src/lib/shootOptions.test.ts`, `config/securityHeaders.test.ts`, `src/cms-client/**/__tests__` (copied package tests incl. the boundary test). Property tests print their fast-check seed; rerun with `FC_SEED=<seed>`.
|
||||
+7
-8
@@ -1,10 +1,10 @@
|
||||
# Privacy statement: draft text for the contact form (needs Bryan's approval)
|
||||
|
||||
Status: DRAFT. Nothing of this is in the site yet: the page `/privacyverklaring` is still the placeholder "Deze pagina is nog in de maak". The text is site copy in Dutch, so Bryan (and Andrea, as the controller) decide the wording. Items marked **[CHECK]** are facts that must be confirmed before publishing; they are not guessed here.
|
||||
Status: DRAFT, wording approved by Bryan (via SLP Software - SLS - Main, 2026-11-10) with the retention periods and the controller below; the captcha sentence is published together with the captcha only. Nothing of this is in the site yet: the page `/privacyverklaring` is still the placeholder "Deze pagina is nog in de maak". The text is site copy in Dutch, so Bryan (and Andrea, as the controller) decide the wording. Items marked **[CHECK]** are facts that must be confirmed before publishing; they are not guessed here.
|
||||
|
||||
## What the form sends and stores (from the API contract v0.3.x)
|
||||
- Sent: name, e-mail address, the chosen shoot (the readable label, e.g. "Newborn"), the message, a signed time token, and (when the captcha is on) the captcha response.
|
||||
- Stored by the CMS: the four fields, the time of receipt, a status and the mail status. **No IP address is stored** by the contact module (contract section 4.2). Retention period: **[CHECK]** (`retentionUntil` is fixed per message from the server setting; the value for ASF is not decided yet).
|
||||
- Stored by the CMS: the four fields, the time of receipt, a status and the mail status. **No IP address is stored** by the contact module (contract section 4.2). Retention (decided by Bryan): 12 months for contact messages, 30 days for messages marked as probable spam (`retentionUntil` is fixed per message from the server setting).
|
||||
- Mail: each message is sent to Andrea's mailbox. **[CHECK]** mail provider and where it processes the data.
|
||||
- The reply: Andrea answers by e-mail to the address given.
|
||||
|
||||
@@ -15,7 +15,7 @@ Status: DRAFT. Nothing of this is in the site yet: the page `/privacyverklaring`
|
||||
## Draft text (Dutch)
|
||||
|
||||
### Contactformulier
|
||||
Als je het contactformulier gebruikt, verwerk ik de gegevens die je invult: je naam, je e-mailadres, de soort shoot waarvoor je interesse hebt en je bericht. Ik gebruik die gegevens alleen om te reageren op je vraag. Het bericht wordt opgeslagen in het beheersysteem van deze website en als e-mail naar mij gestuurd. Je IP-adres wordt daarbij niet bewaard. Ik bewaar je bericht **[CHECK: bewaartermijn]** en verwijder het daarna.
|
||||
Als je het contactformulier gebruikt, verwerk ik de gegevens die je invult: je naam, je e-mailadres, de soort shoot waarvoor je interesse hebt en je bericht. Ik gebruik die gegevens alleen om te reageren op je vraag. Het bericht wordt opgeslagen in het beheersysteem van deze website en als e-mail naar mij gestuurd. Je IP-adres wordt daarbij niet bewaard. Ik bewaar je bericht 12 maanden en verwijder het daarna. Berichten die waarschijnlijk spam zijn, bewaar ik 30 dagen.
|
||||
|
||||
Je kunt me ook gewoon mailen via de knop onder het formulier; dan gebruik je het formulier niet.
|
||||
|
||||
@@ -23,14 +23,13 @@ Je kunt me ook gewoon mailen via de knop onder het formulier; dan gebruik je het
|
||||
Om spam tegen te gaan gebruikt het formulier een onzichtbaar veld en een korte wachttijd voordat je kunt versturen. **[Alleen bij ingeschakelde captcha:]** Daarnaast controleert de dienst Friendly Captcha (Friendly Captcha GmbH, Duitsland) of je een persoon bent. Volgens de aanbieder gebruikt die controle geen cookies en volgt hij je niet. Daarbij wordt wel je IP-adres naar de dienst gestuurd. **[Bij het gratis `global`-endpoint kan dat buiten de EU verwerkt worden; bij het EU-endpoint blijft het binnen de EU. Kies de zin die past.]** **[CHECK: welke gegevens deze dienst precies ontvangt, dit uit hun privacyinformatie overnemen]**
|
||||
|
||||
### Je rechten
|
||||
Je kunt me vragen welke gegevens ik van je heb, ze te laten corrigeren of verwijderen. Mail daarvoor naar het adres onder het formulier.
|
||||
Je kunt me vragen welke gegevens ik van je heb, ze te laten corrigeren of verwijderen. Mail daarvoor naar info@andreaslop.nl, het adres onder het formulier. Andrea Slop is verantwoordelijk voor de verwerking van deze gegevens.
|
||||
|
||||
## Where it appears
|
||||
1. `PrivacyNote` under the form already links to `/privacyverklaring`; no change to that line is needed.
|
||||
2. The page `routes/privacyverklaring.tsx` still has to be written; this draft is the part about the form. A full privacy statement (analytics: Umami without cookies, Sentry, hosting) is a separate piece of content.
|
||||
|
||||
## Questions for Bryan (via SLP Software - SLS - Main)
|
||||
1. Retention period of contact messages for ASF (server setting `retentionUntil`).
|
||||
2. Is Andrea the controller, and which contact address goes into the text?
|
||||
3. Approve the wording, or change it.
|
||||
4. The privacy page is still a placeholder: should the full privacy page be a separate feature, and is the form allowed to go live (test only) before it exists?
|
||||
Answered by Bryan (via SLS-Main, 2026-11-10): retention 12 months (30 days for probable spam); Andrea is the controller and the contact address is info@andreaslop.nl; wording approved; the captcha sentence is published together with the captcha (off at go-live). The full ASF privacy statement is a SEPARATE feature that must be ready before the form goes live (not needed for testing); recorded as a go-live condition in the Operations checklist.
|
||||
|
||||
Still open for that privacy feature: the mail provider and where it processes the data, and exactly what the captcha widget sends to the provider (quote the provider's documentation).
|
||||
|
||||
+3
-3
@@ -18,9 +18,9 @@ Order matters: steps 1-2 can start with the current package (without captcha); t
|
||||
- [x] **10. CaptchaWidget**: new lazy chunk `src/components/ContactForm/CaptchaWidget.tsx` using `@friendlycaptcha/sdk` (`createWidget`, `startMode: focus`, `language: nl`, `apiEndpoint` per Bryan's host choice); complete -> `setCaptchaToken(response)`; expire/error -> `setCaptchaToken(null)` and `reset()`; `destroy()` on unmount; reserved height; add the pinned dependency (check `minimumReleaseAge` rules of pnpm). Tests with a fake SDK: expired token not sent, error resets, unsupported or missing provider keeps the gate, submit blocked with message until solved.
|
||||
- [x] **11. Preselect with `initialSubject`**: Panel passes the remembered preselect to the form, the form to the hook; test "Boek..." before the form is mounted.
|
||||
- [x] **12. Privacy text (draft, for Bryan's approval; not in the site)**: PrivacyNote and the privacy page name the captcha provider and what the form stores (wording needs Bryan's approval; draft goes to SLS-Main for routing).
|
||||
- [ ] **13. PBT and e2e**: fast-check properties (PBT-02/03/07/08/09) for the label/payload mapping and trim; e2e with a mocked `/api` route: token 200 -> form, 404 -> gate, 202 success, 400 expired -> retry, prerendered HTML check; extend `noJs` e2e (gate and mail button without JS).
|
||||
- [ ] **14. Documentation**: update `LAYOUT.md` if the contact block changes; README note for the copied package (source and sync rule); `aidlc-docs` code summary.
|
||||
- [ ] **15. Automatic build and test (Step 13.5)**: `pnpm` typecheck, lint, unit tests, e2e where available, build and prerender; fix and repeat; report any decision only Bryan can make.
|
||||
- [x] **13. PBT and e2e**: fast-check properties (PBT-02/03/07/08/09) for the label/payload mapping and trim; e2e with a mocked `/api` route: token 200 -> form, 404 -> gate, 202 success, 400 expired -> retry, prerendered HTML check; extend `noJs` e2e (gate and mail button without JS).
|
||||
- [x] **14. Documentation**: update `LAYOUT.md` if the contact block changes; README note for the copied package (source and sync rule); `aidlc-docs` code summary.
|
||||
- [x] **15. Automatic build and test (Step 13.5)**: `pnpm` typecheck, lint, unit tests, e2e where available, build and prerender; fix and repeat; report any decision only Bryan can make.
|
||||
|
||||
## Not in this plan
|
||||
- Server module, verifier, openapi, ASF host configuration (other sessions).
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
# Deployment plan: contact-form-cms
|
||||
|
||||
Scope: the web change only. The server module and host configuration are delivered by other sessions.
|
||||
|
||||
## Method
|
||||
The existing Gitea pipeline (continuous_integration.yaml). A push to master deploys the test site and ASF test; production only by manual dispatch. Nothing is merged or deployed without Bryan (a test deploy of the feature branch is allowed on request of Bryan or SLP Software - SLS - Main).
|
||||
|
||||
## What changes on deploy
|
||||
- Site bundle with the form (lazy chunks), cms-client package, captcha widget chunk, new `frame-src` in the generated server configs (`web/deploy/iis/web.config`, `web/deploy/nginx/*.conf`, regenerated with `pnpm server-config`).
|
||||
- `siteContent.contactForm.enabled` stays `false` in the merge: the site then asks the server nothing and shows the "Binnenkort" gate.
|
||||
|
||||
## Server side prerequisites for turning it on (not built here)
|
||||
| Item | Owner |
|
||||
|---|---|
|
||||
| Contact module in the ASF host, `openapi/andreaslopfotografie.v1.json` | SLS Software - CMS |
|
||||
| `Contact__RecipientEmail` (env only), sender in `Email:AllowedFromAddresses`, `Contact:Enabled` + CMS switch, `MinSeconds`, retention 12 months / 30 days spam | AndreaSlopFotografie (host) |
|
||||
| `ForwardedHeaders:KnownProxies` / `ClientPartitionKey` on IIS | AndreaSlopFotografie (host) |
|
||||
| ASF host CSP `frame-src`: global, global0, global1 (`AllowedSiteFrameOrigins__0..2`) | AndreaSlopFotografie (host) |
|
||||
| Captcha: verifier configured with the secret; free key only for tests, paid plan before commercial use | Bryan / SLS Software - CMS |
|
||||
|
||||
## Rollback
|
||||
Set `siteContent.contactForm.enabled = false` and redeploy (the gate returns, no token request). The server can also close the form (`Contact:Enabled` off answers 404, which keeps the gate). Captcha problems are handled by the form itself (message plus mail button).
|
||||
|
||||
## Test deploy steps (on request)
|
||||
1. Merge or deploy the feature branch to the ASF test site through the pipeline (switch on only if the test host serves the contact endpoint).
|
||||
2. Run the real-browser check from the build and test instructions against the test host.
|
||||
@@ -0,0 +1,7 @@
|
||||
# Monitoring plan: contact-form-cms
|
||||
|
||||
- **Events (Umami)**: only `contact-sent` and `contact-failed`, names only. No field values, token, idempotency key or captcha response anywhere in analytics, logs or Sentry.
|
||||
- **Sentry**: the existing browser setup stays; the form logs nothing itself. Check once on the test site that a failed send does not put form values into a breadcrumb or event (Build and Test of the next deploy).
|
||||
- **Server side (CMS)**: the contact module's message list (status, mail status, attempts) is the operational view; failed mails and spam counts are watched there. Owner: CMS sessions.
|
||||
- **Watch after go-live**: ratio `contact-failed` to `contact-sent` in Umami; messages with mail status `failed`; captcha problem message shown (not counted separately, visible through failed sends).
|
||||
- **Alerts**: none new on the web side; mail failures are shown in the CMS admin.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Production readiness checklist: contact-form-cms
|
||||
|
||||
Status: web side ready for a test deploy; NOT ready for production (go-live conditions open). The form stays off in production (`siteContent.contactForm.enabled = false`) until Bryan gives an explicit go.
|
||||
|
||||
## Done (web)
|
||||
- [x] Form on the headless `cms-client` package, no forked logic; import boundary enforced
|
||||
- [x] No request to the server while the switch is off; token only when the form is near the screen
|
||||
- [x] No token, widget or e-mail address in the prerendered HTML (tests)
|
||||
- [x] Honeypot, idempotency key, one token refresh, server-side time check, captcha slot with fail-safe message and mail button
|
||||
- [x] CSP: `frame-src` with exact global, global0, global1 hosts; no wildcard; real-browser run without violations
|
||||
- [x] No personal data in analytics/logs; events limited to `contact-sent`/`contact-failed`
|
||||
- [x] Tests: unit, component, property, e2e, real-browser widget run; lint, format, audit clean; Lighthouse as before
|
||||
- [x] Dependency: `@friendlycaptcha/sdk` 1.1.3 (MPL-2.0), audit clean
|
||||
|
||||
## Go-live conditions (all must be true; Bryan decides)
|
||||
- [ ] **Full ASF privacy statement published** (separate feature; the form text in `privacy-statement-draft.md` is input; mail provider and widget data still to check). Not needed for testing, required before go-live.
|
||||
- [ ] **Captcha decision**: off at go-live until a paid Friendly Captcha plan exists (free key is for testing only); with the EU endpoint the CSP gets eu, eu0, eu1 and the privacy text changes.
|
||||
- [ ] Server: contact module deployed on the ASF host, recipient and sender configured, retention 12 months / 30 days spam, proxies/partition key set, host CSP `frame-src` set.
|
||||
- [ ] A real mail from the production host checked (SPF/DKIM, "toon origineel") and the message visible in the ASF CMS.
|
||||
- [ ] Test of the form on the deployed ASF test host with the real server (after the CMS branch is merged and deployed).
|
||||
- [ ] ASF production hosting (IIS) in place (separate feature).
|
||||
- [ ] Bryan's explicit go, then `siteContent.contactForm.enabled = true` in its own reviewed change.
|
||||
|
||||
## Rollback
|
||||
`enabled = false` and redeploy, or `Contact:Enabled` off on the server (404 keeps the gate).
|
||||
|
||||
## Risks and notes
|
||||
- Free captcha tier must not be used commercially.
|
||||
- The global endpoint processes IP addresses possibly outside the EU; EU needs the paid plan.
|
||||
- With the switch on, a closed form (404) logs one console message per page view in the browser.
|
||||
- Hydration e2e tests run with the switch off; if it is on, they need the API mocked.
|
||||
Reference in New Issue
Block a user