Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/plans/cms-u6-admin-ui-berichten-code-generation-plan.md
T

5.9 KiB
Raw Blame History

Code Generation Plan — CMS-U6 admin-ui-berichten

Phase 2, frontend only (frontend/src/features/contact, router.tsx, Sidebar.tsx, locales). Backend routes exist (CMS-U4); the JSON shapes are in construction/phase-1-handoff.md and openapi/slpsoftware.v1.json. Decisions: D1 (admin view in scope, full version), Bryan: the form switch must be visible and switchable in the "Berichten" screen (spam attack, maintenance). Areas the ASF session touched in the frontend (auth/refresh, users, theme assets) are not changed; Sidebar/router get one added entry each.

Findings on the merged master

  • Sidebar items are declared in NAV_ITEMS with roles and requiredModule; routes use RoleGuard + ModuleGuard. useSystemCapabilities lists loaded modules (cached for the session) and emailEnabled.
  • A loaded Contact module does not mean the API is usable: while the host switch is off every management route answers 404 with an empty body. The UI therefore treats 404 on GET /contact-settings as "not available on this host".
  • Offerings (CMS-U0/U1b) set the pattern: feature folder with services/, components/, pages/, mocks/, msw handlers, ['feature','list'] query keys, nl/en translations, Vitest + Testing Library.

Behaviour

  1. Navigation: menu entry "Berichten" (icon: mail) for Owner and Administrator, shown only when capabilities list Contact and GET /contact-settings did not answer 404 (loaded once per session, cached). Route /messages, guarded by role and the same availability check; a direct visit while unavailable shows the existing "not found" page.
  2. Form switch card at the top: "Contactformulier op de website — Aan/Uit" with a clear state text, one toggle button, an explanation line ("Als het formulier uit staat ziet de bezoeker alleen je e-mailadres") and, when hostEnabled is false, no toggle but the host-level explanation (cannot occur while the screen is reachable; handled defensively). Switching uses PUT /contact-settings; success toast, error banner with the Dutch generic/network messages; the state comes from the server response. First-time hint: the switch is off by default, so a short note tells Bryan that the form is closed until he switches it on.
  3. List: filter chips "Inbox" (default: new+read+archived), "Nieuw", "Gelezen", "Gearchiveerd", "Spam" (each calls GET /contact-messages?status= — "Inbox" sends no status); the chip "Nieuw" shows unreadCount; paging 25 per page with previous/next and "x–y van z"; newest first; columns: received (locale date and time), name, e-mail, subject (the opaque site value, shown as is), status badge, mail icon (sent / pending / failed / n.v.t.). Empty states per filter. Spam rows are visually separate (only visible under "Spam").
  4. Detail (dialog, not a new page): full message with preserved line breaks, e-mail as mailto: link, received time, status select (Nieuw/Gelezen/Gearchiveerd → PATCH), mail status with attempts, error code (translated: disabled, not configured, auth, rejected, timeout...), next attempt time, retention date. Buttons: Verwijderen (confirm dialog, DELETE), Opnieuw mailen (POST .../resend; disabled with hint when emailEnabled is false; shows "Verstuurd" when mailed:true, "Niet verstuurd (mail staat uit)" when mailed:false; 409 for spam → "Markeer het bericht eerst als geen spam."; 429 → "Probeer het over {n} seconden opnieuw." from Retry-After), Geen spam on spam rows (PATCH status=read, then it moves to the Inbox).
  5. Opening an unread message marks it as read (PATCH read), so the counter drops. (Decision to confirm.)
  6. Cache: keys ['contact','messages',filter,page] and ['contact','settings']; mutations invalidate messages (and the counter); the switch updates the settings cache from the response.
  7. All user-facing texts Dutch with English counterparts (contact.*); errors and 4xx/5xx mapped to translated messages, never the API's English titles. Accessibility: switch with accessible name and state, focus management in dialogs, status icons with text alternatives.

Steps

  • Step 1 — Types, services and msw mocks (settings get/put incl. 404 = unavailable, messages list/detail/patch/delete/resend with the real status codes and shapes).
  • Step 2 — Components: FormSwitchCard, MessagesFilterChips, MessagesTable + pager, MessageDialog, DeleteMessageDialog.
  • Step 3 — Page, route, sidebar entry, guards, translations (nl/en).
  • Step 4 — Tests (Vitest + Testing Library + msw): sidebar entry visible/hidden (module missing, 404 on settings, role); direct route when unavailable; switch card off→on→off with server response, error path, first-time hint; list default shows no spam, each chip sends the right query, counter from unreadCount, paging; detail opens, marks unread as read, line breaks preserved, status change, un-spam moves the row, delete confirm/cancel, resend (mailed true/false, 409, 429 with seconds, email disabled), empty states, translated error codes; no raw API titles shown.
  • Step 5 — Verification (automatic): pnpm lint, npx tsc -b, full pnpm test; new files formatted with prettier (the 15 old prettier warnings in offerings stay); real output reported.
  • Step 6 — Docs/commit: summary; one commit; no push.

Explicitly NOT touched

Backend, auth/refresh, users, theme assets, existing features except the one entry in Sidebar.tsx and the route in router.tsx, shared UI primitives (used, not edited; a switch is built from the existing button/checkbox primitives unless a primitive is missing, then added as a new file).

Questions for approval

  1. Auto-mark as read when a message is opened: OK?
  2. Sidebar badge with the unread count (extra request per page load for admins): wanted, or only the chip counter? (I propose chip counter only.)
  3. Keep the filter as chips (above) or a select? (Chips proposed.)