# 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|read|archived|spam` (a single value). **Default (no status) = `new`, `read`, `archived` — spam is never in the default list.** `page` from 1, `pageSize` 1-100 (default 25), out-of-range values -> 400 `errors.page/pageSize=["invalid"]`. Response `{ items:[{id, receivedAt, name, email, subject, status, mailStatus}], page, pageSize, totalCount, unreadCount }`. `unreadCount` = messages with status `new`, **never counting spam**, independent of the chosen filter. Message text is not in the list. | | `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"|"read"|"archived" }`. Setting one of these on a spam row "un-spams" it (a real visitor tripped a check); its `retentionUntil` is then extended to the normal retention (now + `RetentionMonths`) so it is not deleted in 30 days; `mailStatus` stays `notApplicable` until it is resent. Other values (`spam`, `converted`, unknown) -> 400 `errors.status=["invalid"]`. 404 unknown. | | `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|failed`; `Skipped` leaves the status and reports it) and returns `200 { mailStatus, mailAttempts, mailed: true|false }`. Until the mail unit the sender is the no-op, so `mailed=false`. 404 unknown. | | `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|false }`; replaces the singleton, returns the same shape as GET. Stores who changed it and when. | 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?