Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/plans/cms-u4-contact-admin-api-code-generation-plan.md
SluijsensandClaude Sonnet 5.5 e53b318c31 Contactbeheer: berichten, schakelaar en tweelaagse poort voor het formulier
Beheerroutes zonder /admin-segment op contact-messages (lijst met spam apart en ongelezen-teller zonder spam, detail, status, verwijderen, opnieuw versturen met eigen limiet) en contact-settings voor de CMS-schakelaar, allemaal AdminOnly. Het formulier is alleen open als de hostvlag EN de CMS-schakelaar (standaard uit) aan staan; de hostvlag wordt eerst gecontroleerd zodat de database niet wordt aangeraakt. Bij uitgeschakelde host antwoorden de beheerroutes 404. OpenAPI-document bijgewerkt.

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

8.0 KiB

Code Generation Plan — CMS-U4 contact-admin-api

Phase 1, after CMS-U3b. Inputs: requirements D1/D2, contract § 6 (RESTful, no /admin segment), Bryan's two-layer switch (SLS message), CMS-U3 gate design (IContactFormGate). Scope: everything an administrator does with contact messages through the API, plus the CMS-controlled on/off switch. The UI is CMS-U6; the real mail sender is CMS-U5.

Routes (all AdminOnly, same resource names as the public routes, no /admin)

New controller ContactMessagesAdminController (class-level [Authorize(Policy = "AdminOnly")], route contact-messages; no action is anonymous or marked [PublicSiteEndpoint]), so public and admin actions are separated and the route-table tests stay trivial. Routes cannot clash with the public ones (GET token, POST "") because of the {id:guid} constraint.

Route Behaviour
GET /contact-messages?status=&page=&pageSize= list, newest first. status = `new
GET /contact-messages/{id:guid} full message: all list fields plus message, mailAttempts, mailError (code only), retentionUntil. 404 unknown.
PATCH /contact-messages/{id:guid} body `{ "status": "new"
DELETE /contact-messages/{id:guid} hard delete (erasure request), 204; 404 unknown.
POST /contact-messages/{id:guid}/resend policy contact-resend (5 per 600 s). Spam rows -> 409 ProblemDetails ("mark it as not spam first"). Otherwise calls IContactMailSender, records the outcome (attempts+1, status `sent
GET /contact-settings singleton: { "enabled": bool, "hostEnabled": bool }. enabled = the CMS switch (data, default false when no row exists); hostEnabled = the host switch Contact:Enabled (read-only, so the UI can explain why the form is closed).
PUT /contact-settings body `{ "enabled": true

Statuses and mail statuses are serialized as lower-camel strings (new, read, archived, spam, converted; pending, sent, failed, notApplicable).

Two-layer gate (the CMS switch)

  • New table ContactSettings (singleton row: Id fixed, Enabled, UpdatedAt, UpdatedByUserId), migration AddContactSettings (additive).
  • CmsFlagContactFormGate (layer 2) reads the row (absent = closed) through a short in-process cache (5 s absolute) that PUT /contact-settings invalidates immediately, so the public routes do not hit the database on every request. CompositeContactFormGate is registered as the IContactFormGate: the form is open only if both layers are open; layers are evaluated in order host flag first and short-circuit, so with the host switch off the database (and its not-yet-existing tables) is never touched.
  • ContactRouteFilter is not modified (it only knows the interface), as agreed.

Admin routes and the host switch

The admin routes need the Contact tables, which exist only when the host switch is on (the module migrates only then — the CMS-U3 requirement that a disabled module touches nothing). So when Contact:Enabled=false every admin route (including contact-settings) answers 404 with an empty body via a small ContactAdminRouteFilter (host flag only; the CMS switch deliberately does not close the admin routes, otherwise nobody could switch the form back on). The UI (CMS-U6) treats a 404 on GET /contact-settings as "feature not available on this host" and hides the menu entry. /System/capabilities lists the module whenever it is loaded, so it is not enough on its own.

Authorization and gate

All new routes require AdminOnly (Owner/Administrator). They are not marked [PublicSiteEndpoint], so the availability gate blocks them when the CMS is off or in maintenance (verified by the route-table test).

Steps

  • Step 1 — Settings model + migration AddContactSettings (generated; applied to a real MariaDB for verification).
  • Step 2 — Repositories/services: list/detail/patch/delete/resend (IContactMessageAdminService), settings (IContactSettingsService), gates (CmsFlagContactFormGate, CompositeContactFormGate), cache with invalidation. Resend uses the existing IContactMailSender seam.
  • Step 3 — Controllers + filter + rate-limit policy contact-resend (registered in ContactModule, config RateLimiting:ContactResend, default 5/600; same single partition function as the other contact policies, so the rebase checklist still has one line).
  • Step 4 — Tests: services (default list excludes spam; each status filter; ordering and paging bounds; unreadCount ignores spam and filters; detail fields; patch transitions incl. un-spam extending retention; invalid statuses; delete; resend rules incl. spam -> 409 and Skipped/Sent/Failed; settings default false, PUT/GET round trip, cache invalidated on PUT); gates (host off -> closed without calling the database gate; host on + CMS off -> closed; both on -> open; unit test with substitutes proving short-circuit order); controllers (status codes, response shapes, lower-camel enum strings); route-table test (explicit, as requested): every action of ContactMessagesAdminController is under class-level AdminOnly, none has [AllowAnonymous] or [PublicSiteEndpoint], no route contains admin; the set of public contact actions stays exactly {GetToken, Submit} and AllowedPublicActions in the Availability route-table test is unchanged (the new routes are covered by its "everything else answers 503" check); pipeline tests on the real host and MariaDB: anonymous -> 401, authenticated without admin role -> 403 (minted JWT with the host's development JWT settings), administrator -> 200 flows (list/detail/patch/delete/resend), host switch off -> admin routes 404 empty, CMS switch off -> public routes 404 but admin routes still 200, switching it on through PUT /contact-settings makes the public routes work within the cache window, the CMS being disabled (availability) blocks admin routes with 503, contact-resend returns 429 with Retry-After after its limit, no personal data in any log entry written by the admin services.
  • Step 5 — Verification (automatic): build; all test projects; pipeline tests against a temporary MariaDB (removed afterwards); real output.
  • Step 6 — Docs/commit: summary with the JSON shapes for the frontend handoff and the rebase notes (none new); one commit; no push.

Explicitly NOT touched

ContactRouteFilter (the public filter), the public controller, the public validation/submission logic, Core/Availability, Email, Identity, the frontend.

Notes / assumptions to confirm

  1. hostEnabled in GET /contact-settings is an addition to the agreed { enabled } shape (read-only, lets the UI explain a closed form). OK?
  2. Un-spamming extends retention to the normal period (otherwise the row would be deleted after the remaining spam days). OK?
  3. Resend of a spam row = 409 instead of mailing it silently. OK?
  4. Admin routes answer 404 when the host switch is off (tables do not exist then). OK?