Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/inception/plans/execution-plan.md
T
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

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); category on Modules.Offerings; OnRejected and 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), new Offering.Category column. All additive.
  • API changes: Yes: new endpoints + category on 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.
  • 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/Migrations and 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, branch feature/contact-forms-module from master d9cc539. 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.