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>
12 KiB
12 KiB
Execution Plan — contact-forms-module
Detailed Analysis Summary
Transformation Scope
- Transformation Type: Multiple components (new module + targeted changes in existing ones). No infrastructure/deployment model change.
- Primary Changes: new
Modules.Contact(+ Tests);categoryonModules.Offerings;OnRejectedand a public-route marker in Core/Availability; later mail integration (Core/Email) and admin UI (frontend). - Related Components: Core (rate limiting, hosting, observability), Modules.Availability (middleware), Modules.Offerings, Api.SlpSoftware (+ Api.AndreaSlopFotografie after the ASF merge), frontend (admin).
Change Impact Assessment
- User-facing changes: Yes: public contact endpoints (consumed by
cms-client), admin "Berichten" screen (unit 6). - Structural changes: Yes: one new module, one new marker attribute in Core.
- Data model changes: Yes: new tables (
ContactMessage, idempotency record, DataProtection key ring), newOffering.Categorycolumn. All additive. - API changes: Yes: new endpoints +
categoryon offerings; 429 body/header change on existing rate-limited endpoints. - NFR impact: Yes: security baseline (anonymous PII endpoint), privacy (retention, logging), reliability (mail retry).
Component Relationships
flowchart LR
FE["cms-client (SLP site)"] --> API["Api.SlpSoftware / Api.AndreaSlopFotografie"]
API --> CONTACT["Modules.Contact (NEW)"]
API --> OFF["Modules.Offerings (+category)"]
API --> AVAIL["Modules.Availability (middleware)"]
CONTACT --> CORE["Core (marker, rate limiter, observability)"]
AVAIL --> CORE
CONTACT -. "after ASF merge" .-> MAIL["Core/Email (ASF branch)"]
ADMIN["frontend admin: Berichten"] -. "after ASF merge" .-> CONTACT
classDef new fill:#9ae6b4,stroke:#2f855a,color:#000;
classDef changed fill:#f6e05e,stroke:#c05621,color:#000;
classDef ext fill:#bee3f8,stroke:#2b6cb0,color:#000;
classDef later fill:#e2e8f0,stroke:#4a5568,stroke-dasharray: 5 5,color:#000;
class CONTACT new;
class OFF,AVAIL,CORE,API changed;
class FE ext;
class MAIL,ADMIN later;
Text alternative: the Contact module (new, green) hangs off the API hosts and uses Core; Offerings, Availability, Core and the hosts change (yellow); mail and the admin UI (grey, dashed) wait for the ASF merge.
Risk Assessment
- Risk Level: Medium (anonymous endpoint with PII; shared files with the ASF session).
- Rollback Complexity: Easy to Moderate (additive migrations; new module can be left unregistered per host).
- Testing Complexity: Moderate (gate regression, rate limiter behaviour, token/idempotency, background jobs).
Workflow Visualization
flowchart TD
Start(["Request via Redesign - SLS"])
subgraph INCEPTION["🔵 INCEPTION"]
WD["Workspace Detection<br/><b>COMPLETED</b>"]
RE["Reverse Engineering<br/><b>SKIP (targeted review)</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 (minimal)</b>"]
UG["Units Generation<br/><b>EXECUTE</b>"]
end
subgraph CONSTRUCTION["🟢 CONSTRUCTION (per unit)"]
FD["Functional Design<br/><b>EXECUTE (U3, U4, U5)</b>"]
NFR["NFR Requirements + Design<br/><b>EXECUTE (U2, U3)</b>"]
ID["Infrastructure Design<br/><b>SKIP (config noted in design)</b>"]
CG["Code Generation<br/><b>EXECUTE</b>"]
BT["Build and Test<br/><b>EXECUTE</b>"]
end
OPS["Operations<br/><b>UNDECIDED (at Build and Test)</b>"]
Start --> WD --> RA --> WP --> AD --> UG --> FD --> NFR --> CG --> BT --> OPS
style WD 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 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 NFR fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style OPS fill:#FFF59D,stroke:#F9A825,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
linkStyle default stroke:#333,stroke-width:2px
Text alternative: Inception runs Application Design and Units Generation, then each unit goes through design (where needed), Code Generation and Build and Test; Operations is undecided.
Phases to Execute
🔵 INCEPTION
- Workspace Detection (COMPLETED)
- Reverse Engineering (SKIPPED by D10: targeted review recorded in requirements)
- Requirements Analysis (COMPLETED, approved by Redesign - SLS)
- User Stories (SKIPPED: contract-driven backend work; acceptance criteria live in the contract and the SLS requirements FR-13..19)
- Workflow Planning (IN PROGRESS)
- Application Design - EXECUTE (minimal depth)
- Rationale: new module, new Core marker attribute; must fix component/service names, config keys (
Offerings:Categories,Contact:*,RateLimiting:ContactForm), OpenAPI export path, DataProtection key-ring storage, purpose strings.
- Rationale: new module, new Core marker attribute; must fix component/service names, config keys (
- Units Generation - EXECUTE
- Rationale: six units with an ordering constraint and a split at the ASF merge.
🟢 CONSTRUCTION
- Functional Design - EXECUTE for U3, U4, U5 (validation rules, state/status machine, idempotency, spam cap, retry/backoff); SKIP for U1, U2, U6 (covered by contract/design)
- NFR Requirements + NFR Design - EXECUTE for U2 and U3 (security baseline: PII logging, token oracle, size limits, rate limiting); SKIP for the others (covered by baseline checks in code generation)
- Infrastructure Design - SKIP (no new infrastructure; key-ring storage and config keys are recorded in Application Design)
- Code Generation - EXECUTE per unit (plan approved by Redesign - SLS before any code); automatic build+test per unit
- Build and Test - EXECUTE (after U1-U4, again after U5-U6)
🟡 OPERATIONS
- UNDECIDED: resolved at Build and Test (D7)
Units (execution order)
Phase 1: now, on the master base. Phase 2: only after Bryan merges feature/identity-email-notifications and the branch is rebased (not before; no rebase now).
| Unit | Scope | Delivers | Tests | Depends on |
|---|---|---|---|---|
| U1 offerings-category (a) | Category on Offering entity, public + admin DTOs, create/update requests; validation against Offerings:Categories (per host appsettings); null/empty allowed |
additive migration AddOfferingCategory in Offerings; config key documented; handoff note for the frontend (field name and semantics) |
Offerings.Tests: mapping, validation (in list / not in list / null), repository; migration builds | none |
| U2 gate-and-limiter (b) | OnRejected: 429 application/problem+json + Retry-After for all policies; [PublicSiteEndpoint] marker in Core; AvailabilityMiddleware lets marked endpoints through (deny-by-default); mark GET /api/v1/offerings. Minimal diffs in these two files (R3) |
marker attribute, middleware check, updated 429 response, security-event kept | Core.Tests/Api.Tests: 429 body + header for existing policies (adjust existing tests); Availability.Tests: marked route open while disabled/maintenance/master-down; every /api/v1/admin/* route still 503; /api/v1/Availability/status open; ~6-10 existing tests touched |
none (U1 for the offerings route mark) |
| U3 contact-core (c) | new Modules.Contact (+Tests): entities ContactMessage, IdempotencyRecord; DbContext + migration; token endpoint (DataProtection, per-site purpose, persistent key ring in DB); submit endpoint (validation codes, 413 ProblemDetails, Idempotency-Key, honeypot hpCheck, min-time, ICaptchaVerifier + Null, identical 202, spam stored with daily cap and 30-day retention, site id from config); ContactForm rate-limit policies; both routes [PublicSiteEndpoint]; IContactMailSender interface with no-op implementation (mail is wired in U5); retention BackgroundService; log/Sentry scrubbing for the routes |
module registered in Api.SlpSoftware (Andrea host later), additive migration InitialCreate, config section Contact:*, exported OpenAPI document (path fixed in design) |
Contact.Tests: validation rules incl. PBT (partial: round-trips, trim/length invariants), token sign/verify/expiry/foreign-site, idempotency replay, spam paths identical response, spam cap, retention job, no-PII-in-log test, endpoint tests via WebApplicationFactory | U2 |
| U4 contact-admin-api (e) | AdminOnly endpoints: list (paging, unread count, spam separate), detail, PATCH status (new/read/archived), DELETE (hard), POST resend (rate-limited; calls IContactMailSender, so a no-op until U5); capabilities entry is automatic from the module name |
admin controller + DTOs, OpenAPI updated | Contact.Tests: authorization (non-admin 403/401), paging, counts exclude spam, status transitions, hard delete, resend rate-limit | U3 |
| U5 contact-mail (d) | PHASE 2. Implement IContactMailSender on Core/Email with a new MailKind, dark-mode contrast kept; From/Reply-To rules, header-injection and HTML-encoding protections; mailStatus/mailAttempts; BackgroundService sweeping pending (minutes) and retrying failed with backoff/max attempts; "no SMTP host = store only + admin notice" |
mail path + retry job; Andrea host registration via env-only addresses | Contact.Tests: sender with fake IEmailSender, retry/backoff, header injection, encoding, failure never fails the request |
merge of ASF branch + rebase; U3, U4 |
| U6 admin-ui (f) | PHASE 2. "Berichten" in frontend/: list+paging+unread count, detail, status, delete, mail status + resend; menu entry via capabilities; only new files + menu entry |
UI + tests | frontend unit tests (Vitest as in repo) | merge of ASF branch + rebase; U4 |
Migration Approach
- Contact and Offerings have their own DbContext and migration history, applied with
Database.Migrate()at startup (D8). All migrations are additive (new tables, one nullable column). - ASF changes live in
Core/Migrationsand the Identity/Availability contexts, so snapshot conflicts with U1/U3 are not expected. If the rebase still produces conflicts in any snapshot, delete and regenerate my own migration after the rebase (R2). - DataProtection key ring: table owned by the Contact module's context (persistent per host; per-site purpose string).
Branch and Process
- Worktree
..\SlpModularCms-contact-forms, branchfeature/contact-forms-modulefrom masterd9cc539. The main checkout is never switched. - One commit per unit minimum; no push, merge or PR without explicit instruction. Per unit: Code Generation plan -> approval by Redesign - SLS -> code + automatic build+test -> status message.
- Stage status reports to Redesign - SLS after each stage; contract deviations reported immediately.
Estimated Timeline
- Total units: 6 (4 now, 2 after the ASF merge). Rough effort: U1 small, U2 small-medium, U3 large, U4 medium, U5 medium, U6 medium. No calendar estimate (depends on approval turnaround and the ASF merge).
Success Criteria
- Primary Goal: contract v0.3.1 implemented on the CMS side without breaking ASF-owned behaviour.
- Key Deliverables: category on offerings; public contact endpoints; admin API; mail + retry; admin UI; exported OpenAPI.
- Quality Gates: per-unit build+test green; Security Baseline checked per stage; no PII in logs (tested);
/api/v1/admin/*stays gated (tested); no ASF addresses in committed config.