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>
8.3 KiB
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)
categoryon Offerings, (b) rate-limitRetry-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.mdv0.3.1-draft (in the SlpSoftware repo, featureredesign-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), ownDbContext(MySQL,NonLockingMySQLHistoryRepository),Database.Migrate()inUseModule. Contact follows this exactly. - Capabilities:
SystemControllerreturnsModuleOrchestrator.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 branchfeature/identity-email-notifications.Api.AndreaSlopFotografieis also not on master. Unit (d) therefore depends on that merge (or a rebase on their branch); see § 5. - Rate limiting:
AddCmsRateLimitingwith named per-client policies;OnRejectedcurrently logs a security event only (no body, noRetry-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
categoryfield; 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
categorystring|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:
OnRejectedwrites429 application/problem+jsonwithRetry-After; existing policies keep their numbers; new policyContactForm(5/10 min per client IP, configRateLimiting:ContactForm) and token policy (20/10 min). - FR-B2 Gate:
[PublicSiteEndpoint]marker; applied toGET /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-messageswith validation + error codes per contract § 3, own 413 ProblemDetails (16 KB),Idempotency-Keytable (no PII), honeypothpCheck, min-time, optional captcha behindICaptchaVerifier(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
IEmailSenderwith a newMailKind;Fromfixed site sender (allow-list),Reply-Tovisitor, header-injection and HTML-encoding protections;BackgroundServicesweepspendingfrequently and retriesfailedwith 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
retentionUntiland idempotency records older than 24 h. - FR-H OpenAPI: exported definitive OpenAPI document committed in the repo (path fixed in design) for
cms-clienttype 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/Emailbeing on the base branch. Options: wait for the ASF merge, or rebase the feature branch ontofeature/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:
AvailabilityMiddlewareand 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:Categoriesconfig key name; Contact module namedContact(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).