Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/phase-1-handoff.md
T
2026-11-10 13:26:27 +01:00

13 KiB

Phase 1 handoff (CMS side) — for the frontend work

Branch feature/contact-forms-module (worktree ..\SlpModularCms-contact-forms), base master d9cc539, phase 1 units CMS-U0, U1, U1b, U2, U3, U3b, U4 all committed (last commit 44f161a). Nothing pushed, merged or deployed. Phase 2 (CMS-U5 mail + retry, CMS-U6 "Berichten" UI, CMS-U7 PUT /availability/status) waits for the merge of feature/identity-email-notifications and a rebase.

The machine-readable source for types is openapi/slpsoftware.v1.json (one file per host, named after the host; regenerate with UPDATE_OPENAPI=1 dotnet test --filter OpenApiSnapshot). Per-unit details: construction/cms-u*/code/summary.md.

All paths are under /api/v1. "Gate" = the availability gate: routes without the public marker answer 503 to visitors while the CMS is off or in maintenance; a verified Owner/Administrator always gets through. 401 = no/invalid login, 403 = logged in without Administrator/Owner. JSON is camelCase.

1. Routes

Offerings (module Offerings)

Method + path Auth Success Other status codes
GET /offerings public (marker, survives a closed gate); limiter offerings-public 120/60 s 200 array of offerings 429
POST /offerings AdminOnly 201 + Location: /api/v1/offerings/{id} + offering 400 (framework validation shape; bad categoryId = errors.categoryId=["invalid"]), 409 slug taken, 401, 403, 503
PUT /offerings/{id:guid} AdminOnly 200 offering (full replace; omitting categoryId clears the category) 400, 404, 409, 401, 403, 503
DELETE /offerings/{id:guid} AdminOnly 204 (soft delete) 404, 401, 403, 503
PUT /offerings/order body { "orderedIds": [guid,...] } AdminOnly 204 400 problem unless the list holds every existing offering exactly once, 401, 403, 503

Offering JSON: { id, slug, title, description, price, priceNote, features[], ctaLabel, featured, displayOrder, categoryId|null, category|null }. category = the category name (a rename shows up at once; no response caching in the code); categoryId and displayOrder are additive fields the SLP site can ignore. Create/update body: title, description, price, priceNote, features[], ctaLabel, featured, slug?, categoryId? (categoryId must exist; null clears).

Offering categories (CMS data, nothing seeded)

Method + path Auth Success Other
GET /offerings/categories AdminOnly 200 [{ id, name, sortOrder, offeringCount }] 401, 403, 503
POST /offerings/categories { name } (1-100) AdminOnly 201 + Location + category 400, 409 name taken (case-insensitive)
PUT /offerings/categories/{id:guid} { name } AdminOnly 200 category 400, 404, 409
DELETE /offerings/categories/{id:guid} AdminOnly 204 404, 409 while live offerings use it

Contact — public (module Contact)

Both answer 404 with an empty body while the form is closed (host switch OR CMS switch off); the website then shows its mailto fallback. Both stay reachable when the CMS is disabled.

Method + path Auth Success Other
GET /contact-messages/token public (marker); limiter contact-token 20/600 s 200 { token, minSeconds, captcha: null | { provider, siteKey } } 404 closed, 429
POST /contact-messages headers Idempotency-Key: <uuid> (required), body { name, email, subject, message, hpCheck, token, captchaToken? } public (marker); limiter contact-form 5/600 s 202 { "status": "received" } — identical for genuine, spam and replay 400 problem+json (errors per field), 404 closed, 413 problem (> 16384 bytes), 429

Limits: name 1-100, email 1-254 (regex ^[^\s@]+@[^\s@]+\.[^\s@]{2,}$), subject 1-100 (opaque value chosen by the site), message 1-2000; all trimmed; control characters rejected (line breaks and tabs allowed in message). hpCheck is the honeypot, must be empty. 400 shape: { type, title, status, errors: { <field>: [code] } }, codes required | tooLong | invalid | expired; fields name, email, subject, message, token, idempotencyKey, body. A forged, other-site or expired token is always errors.token=["expired"] (fetch a fresh token and retry once). Replays with the same key within 24 h get the same 202 without a second message; a 400 does not use up the key.

Contact — management (AdminOnly; not public; behind the gate)

All answer 404 with an empty body while the host switch Contact:Enabled is off (the tables do not exist then). The CMS switch never closes them.

Method + path Success Other
GET /contact-messages?status=&page=&pageSize= 200 { items[{id,receivedAt,name,email,subject,status,mailStatus}], page, pageSize, totalCount, unreadCount }; default list = new,read,archived (no spam), status=spam shows spam apart; pageSize 1-100 (default 25); unreadCount = new only, never spam 400 (errors.page/pageSize/status), 401, 403, 404, 503
GET /contact-messages/{id:guid} 200 detail (list fields + message, mailAttempts, mailError, retentionUntil) 404
PATCH /contact-messages/{id:guid} { "status": "new"|"read"|"archived" } 200 detail (on a spam message = "not spam": normal retention from now) 400 errors.status=["invalid"], 404
DELETE /contact-messages/{id:guid} 204 (hard delete) 404
POST /contact-messages/{id:guid}/resend (limiter contact-resend 5/600 s) 200 { mailStatus, mailAttempts, mailed } (mailed:false until CMS-U5) 404, 409 spam message, 429
GET /contact-settings 200 { enabled, hostEnabled } (enabled = CMS switch, default false) 401, 403, 404, 503
PUT /contact-settings { "enabled": true|false } 200 same shape 400 errors.enabled=["invalid"] for anything that is not a JSON boolean, 401, 403, 404, 503

status: new|read|archived|spam|converted; mailStatus: pending|sent|failed|notApplicable.

Unchanged but relevant

POST /availability/admin/status still has its admin segment; it becomes PUT /availability/status in phase 2 (CMS-U7, after the ASF merge; callers to check then: master/slave status, poll client, frontend). GET /availability/status stays public.

Key Default Notes
Contact:Enabled false host switch; release condition, see § 3
Contact:SiteId slpsoftware (code default default) stored on rows, in the token purpose; never from a request
Contact:MinSeconds 3 returned as minSeconds; faster = spam
Contact:TokenLifetimeMinutes 120
Contact:RetentionMonths 12 fixed per row at insert
Contact:SpamRetentionDays 30
Contact:MaxSpamRowsPerDay 200 per site per UTC day; beyond it spam is answered but not stored
Contact:MaxBodyBytes 16384 413 beyond
Contact:ProblemTypeBase none -> about:blank {base}/validation when set
Contact:Captcha:Enabled false
Contact:Captcha:Provider, :SiteKey none returned in the token response when enabled
Contact:Captcha:Secret none environment / secrets manager only, never committed
RateLimiting:ContactForm 5 / 600 PermitLimit / WindowSeconds
RateLimiting:ContactToken 20 / 600
RateLimiting:ContactResend 5 / 600
(removed) Offerings:Categories no longer exists; categories are data

CMS switch (not configuration): table ContactSettings, PUT /contact-settings, default off. Mail recipient/sender settings arrive with CMS-U5 (environment only, no addresses in committed config).

3. Release / rebase checklist (do in this order, after Bryan merges feature/identity-email-notifications)

  1. Rebase feature/contact-forms-module onto the merged base. Expected conflicts: AvailabilityMiddleware.cs (one block), AddCmsRateLimiting (OnRejected), appsettings files, host composition, maybe EF snapshots (own contexts, so none expected; regenerate our migration only if a snapshot conflicts). Re-run all test projects.
  2. Per-client rate limiting: in Modules.Contact/Services/ContactSeams.cs, class ContactRateLimitPartition, change public static string KeyFor(HttpContext context) => GlobalKey; to => ClientPartitionKey.For(context); (add the ASF using; drop GlobalKey if unused). In Contact.Tests/ContactRetentionAndPartitionTests.cs, test OnTheBaseBranch_EveryCallerSharesOneBucket becomes "two different client addresses give two different keys". Until this is done every visitor shares one bucket per policy (5 form submissions per 10 minutes for the whole site), which is why the module is off by default.
  3. ForwardedHeaders:KnownProxies configured on the host (environment).
  4. Phase 2 units (CMS-U5 mail + retry job, CMS-U6 UI, CMS-U7) on the rebased branch; give the Andrea host the Contact module reference and its own openapi/andreaslopfotografie.v1.json when it is in scope.
  5. Only then set Contact:Enabled=true on the host (environment or its appsettings).
  6. Switch the CMS switch on: it is OFF by default, so Bryan must open the form himself (screen "Berichten" in CMS-U6, or PUT /api/v1/contact-settings {"enabled":true}). Until both switches are on the website shows its mailto fallback.
  7. Nothing is deployed to production without Bryan; no push/merge/PR happened.

4. Known deviations from contract v0.3.x and design decisions to adopt

  • Admin routes are RESTful on the resource (/contact-messages, /offerings, /contact-settings), no admin segment, per Bryan's decision; old offerings/admin... routes and move-up/move-down are gone (reorder via PUT /offerings/order).
  • One offering DTO for everybody (OfferingAdminDto removed): adds displayOrder, categoryId; category is the name.
  • Categories are CMS data (table + CRUD), not Offerings:Categories.
  • Honeypot JSON name is fixed hpCheck (no configurable name); a missing hpCheck counts as empty.
  • Unbindable body (malformed JSON, wrong types) -> 400 with errors.body=["invalid"] in the same problem shape (the contact controllers are deliberately not [ApiController]).
  • Contact:ProblemTypeBase configurable, default about:blank (instead of a fixed URL).
  • Two-layer switch: host Contact:Enabled and the CMS switch; both default off; 404 empty body when closed.
  • GET /contact-settings returns the extra read-only hostEnabled.
  • Un-spam (PATCH spam -> new/read/archived) extends retention to the normal period; resend of spam = 409.
  • Management routes answer 404 while the host switch is off; an Owner/Administrator passes the availability gate while the CMS is disabled (existing design), visitors get 503.
  • Mail: stored first; the mail seam (IContactMailSender) is a no-op until CMS-U5, so messages stay pending and resend reports mailed:false.
  • Rate limits are global buckets on this base until the checklist step 2 (documented, enforced by the default-off switches).
  • Privacy: no IP address is stored; Sentry error events carry the caller's IP (SendDefaultPii) but never form content — mention error reporting in the privacy statement. Backups may keep deleted messages longer than the retention period — mention or shorten backup retention.

5. Tests and tooling worth knowing

  • Pipeline tests (Contact.Tests/Pipeline, Api.Tests) need ConnectionStrings__DefaultConnection pointing at a MariaDB/MySQL server on which databases may be created (CI provides it: .gitea/workflows/continuous_integration.yaml). Each fixture creates and drops its own database. Unit tests only: dotnet test --filter "FullyQualifiedName!~Pipeline".
  • Frontend (frontend/): pnpm lint, npx tsc -b, pnpm test (278 tests at CMS-U1b). 15 pre-existing files under features/offerings fail prettier --check (tech debt, not touched).
  • The admin frontend work of phase 1 is only the offerings part (new routes, useMoveOffering via PUT /offerings/order, categories dialog + select, query key ['offerings','list']).
  • Last test run (CMS-U4): Contact.Tests 223, Core 205, Availability 95, Offerings 86, Identity 37, Master 57, Api.Tests 4 — all green.

6. Rebase result (2026-11-10)

Rebased onto origin/master e671078 (merge of PR #11: identity-email-notifications + andreaslop-site-hosting). Conflicts: aidlc-docs/active-features.md (kept master's table, appended our row), AvailabilityMiddleware (kept their CheckAdmin / expired-token 401 behaviour, our marker block before it), AddCmsRateLimiting.OnRejected (kept their Retry-After logic for sliding windows, added the 60 s fallback for policies without a wait and the problem+json body), SlpModularCms.sln (took master's, re-added the two Contact projects). No EF snapshot conflict (own contexts). Checklist steps 1 and 2 are DONE: ContactRateLimitPartition.KeyFor now returns ClientPartitionKey.For(context) and its test asserts different buckets per address. Still open: step 3 (ForwardedHeaders:KnownProxies per host), step 5 (Contact:Enabled=true), step 6 (CMS switch). GET /System/capabilities now carries [PublicSiteEndpoint] (never 503; separate commit). The pipeline tests for the management routes log in with a real user (the host validates every access token against its user and security stamp).