Files
SluijsensandClaude Sonnet 5.5 bc763c8ef6 Aanbod: RESTful routes zonder /admin, één OfferingDto en herordenen via PUT /offerings/order
Admin en bezoeker gebruiken dezelfde resource; alleen GET is anoniem, de rest vereist AdminOnly. OfferingAdminDto vervalt (displayOrder zit nu in OfferingDto), move-up/move-down zijn vervangen door de order-route die een onbekende of onvolledige lijst met 400 afwijst. De admin-frontend en alle tests zijn mee aangepast.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 13:06:08 +01:00

8.3 KiB

Requirements — contact-forms-module

1. Intent Analysis

  • Request: Build the CMS/API side of the contact form and related contract items: (a) category on Offerings, (b) rate-limit Retry-After + own ProblemDetails, public-route marker for the availability gate, (c) Contact module (token + submit), (d) mail + retry, (e) admin API, (f) admin UI "Berichten".
  • Source of truth: contact-api-contract.md v0.3.1-draft (in the SlpSoftware repo, feature redesign-modern-timetravel). This document does not restate its field-level detail; it records scope, decisions, repo findings and deviations. Where they disagree, the contract wins unless listed under § 6.
  • Type: New feature (multi-component). Scope: multiple components. Complexity: Complex. Depth: Standard (decisions already made by Bryan / technical lead).
  • Coordination: stages approved by "Redesign - SLS" (leads the build; Bryan's permission runs through it).

2. Decisions (all recorded, not re-asked)

# Decision Source
D1 Admin "Berichten" view in scope, full version (list+paging+unread count, detail, status new/read/archived, delete, mail status + resend; AdminOnly; capabilities entry) Bryan
D2 Honeypot/too-fast submissions stored as spam (30 days, never mailed, per-site daily cap, outside unread count and default list), visitor sees normal 202 Bryan
D3 Captcha disabled by default; provider failure = fail-open Bryan
D4 Category list = fixed list per site in appsettings; admin only picks from it (no free text) Bryan
D5 Retention 12 months (per row, fixed at insert), daily cleanup job Bryan
D6 Availability gate blocks only CMS/admin routes; public routes stay open; deny-by-default; admin routes never exempt Bryan
D7 Security Baseline extension enabled; Property-Based Testing partial (pure functions + serialization round-trips: validation rules, token/idempotency logic); Operations phase undecided (decide at Build and Test) Bryan via Redesign - SLS
D8 New projects SlpModularCms.Modules.Contact + .Contact.Tests; own DbContext, MySQL, Database.Migrate() at startup, additive migration (like Offerings); migration regenerated after rebase Redesign - SLS
D9 Availability marker attribute [PublicSiteEndpoint] in Core, read from endpoint metadata in AvailabilityMiddleware; own unit together with (b); test that every /api/v1/admin/* route still returns 503; /api/v1/Availability/status stays open Redesign - SLS
D10 No full reverse-engineering rerun; targeted review (§ 3). Contact mail = new MailKind, existing mail code untouched, keep dark-mode contrast Redesign - SLS
D11 Admin UI (f) last, on rebased branch after the ASF merge, only new files + menu entry; report to SLS if the merge takes long Redesign - SLS
D12 No push/merge/PR; no ASF addresses in code/committed config (env-only); no PII in logs; no deploy to production Bryan / SLS

3. Targeted review findings (master d9cc539)

  • Module pattern: Modules.Offerings = IModule (RegisterServices + UseModule), own DbContext (MySQL, NonLockingMySQLHistoryRepository), Database.Migrate() in UseModule. Contact follows this exactly.
  • Capabilities: SystemController returns ModuleOrchestrator.ModuleNames; a registered module named "Contact" appears automatically. The frontend menu entry keys off it.
  • Availability: AvailabilityMiddleware (Modules.Availability) blocks everything not on a prefix bypass list (/api/v1/Availability/status, /Auth/, /Setup/status, /master/, /SlaveStatus, /health) except verified Owner/Administrator tokens. The marker-attribute check slots in before the master/local gate.
  • Mail: Core/Email (IEmailSender, MailSendResult, SMTP, templates) does not exist on master; it lives on the unmerged ASF branch feature/identity-email-notifications. Api.AndreaSlopFotografie is also not on master. Unit (d) therefore depends on that merge (or a rebase on their branch); see § 5.
  • Rate limiting: AddCmsRateLimiting with named per-client policies; OnRejected currently logs a security event only (no body, no Retry-After). To be extended (unit b) for all policies, with existing tests adjusted. ForwardedHeaders/KnownProxies are env-configured (no code change).
  • Observability: SecurityEvents / SecurityEventProcessor (Sentry): extra scrub rule for the contact routes; test that a logged exception holds no body.
  • Offerings: has no category field; additive migration + DTO + admin DTO/requests + validation against the per-site configured list.
  • ASF-owned areas (do not touch without SLS): Email (MailTemplateRenderer, MailColours, EmailOptions, IdentityMailService), Identity, Core Hosting/Website/Proxy, Core migrations, frontend auth/users/theme. Expected rebase conflicts: appsettings, Program.cs/host config, AvailabilityMiddleware, EF snapshots.

4. Functional Requirements (summary; detail in contract)

  • FR-A Offerings category: optional category string|null on offering (public + admin DTOs); value must be in the per-site configured list (Offerings:Categories); null/empty = no chip. Additive migration.
  • FR-B1 Rate limiter: OnRejected writes 429 application/problem+json with Retry-After; existing policies keep their numbers; new policy ContactForm (5/10 min per client IP, config RateLimiting:ContactForm) and token policy (20/10 min).
  • FR-B2 Gate: [PublicSiteEndpoint] marker; applied to GET /api/v1/offerings, GET /api/v1/contact-messages/token, POST /api/v1/contact-messages.
  • FR-C Contact module: GET .../token (DataProtection token, per-site purpose, persistent key ring); POST .../contact-messages with validation + error codes per contract § 3, own 413 ProblemDetails (16 KB), Idempotency-Key table (no PII), honeypot hpCheck, min-time, optional captcha behind ICaptchaVerifier (Null default, fail-open), identical 202, spam stored with daily cap, site id from host/config, retention fields.
  • FR-D Mail: after commit, send via IEmailSender with a new MailKind; From fixed site sender (allow-list), Reply-To visitor, header-injection and HTML-encoding protections; BackgroundService sweeps pending frequently and retries failed with backoff and max attempts; no SMTP host = store only + admin notice.
  • FR-E Admin API: GET list/detail, PATCH status, DELETE (hard), POST resend (rate-limited); AdminOnly; spam shown separately; unread count excludes spam.
  • FR-F Admin UI: "Berichten" screen per D1 (last unit, after ASF merge).
  • FR-G Retention job: daily deletion of rows past retentionUntil and idempotency records older than 24 h.
  • FR-H OpenAPI: exported definitive OpenAPI document committed in the repo (path fixed in design) for cms-client type generation.

5. Non-Functional Requirements and risks

  • Security (baseline enabled): anonymous endpoint, so input validation, size limits, no oracle on token errors, no PII in logs/Sentry, secrets only via env/secrets manager, deny-by-default gate, generic 5xx, baseline rules checked at each stage.
  • Privacy: IP not stored; retention per row; hard delete on erasure; privacy statement must mention backups and the captcha provider (site side).
  • Reliability: mail failure never fails the request; at-least-once mail with attempt counter; idempotent submit.
  • Testability: per-unit build + tests (xUnit); PBT partial per D7; /admin/* 503 regression test; token/validation round-trip tests.
  • Risk R1: mail unit (d) depends on Core/Email being on the base branch. Options: wait for the ASF merge, or rebase the feature branch onto feature/identity-email-notifications. To be decided by SLS in the plan.
  • Risk R2: EF migration snapshot conflicts after rebase; regenerate own migration (D8).
  • Risk R3: AvailabilityMiddleware and rate-limiter edits overlap ASF-touched files; keep diffs minimal, coordinate via SLS.

6. Deviations / additions vs. contract v0.3.1

  • None blocking. Additions: OpenAPI export path; Offerings:Categories config key name; Contact module named Contact (capabilities entry).

7. Open points for the plan stage (not blockers for requirements)

  • Base for unit (d): wait for ASF merge vs. rebase now (R1).
  • Exact config key names and OpenAPI export location (decide in Application Design).