diff --git a/aidlc-docs/features/contact-forms-module/aidlc-state.md b/aidlc-docs/features/contact-forms-module/aidlc-state.md index cfdeda6..a7ddf1b 100644 --- a/aidlc-docs/features/contact-forms-module/aidlc-state.md +++ b/aidlc-docs/features/contact-forms-module/aidlc-state.md @@ -5,7 +5,7 @@ - **Feature Slug**: contact-forms-module - **Project Type**: Brownfield - **Start Date**: 2026-11-09 -- **Current Stage**: CONSTRUCTION - CMS-U3 built and committed (awaiting review); next CMS-U3b plan, then CMS-U4 +- **Current Stage**: CONSTRUCTION - CMS-U3b and CMS-U4 Code Generation Part 1 (plans awaiting approval by Redesign - SLS) - **Branch**: feature/contact-forms-module (worktree ..SlpModularCms-contact-forms, from master d9cc539; main checkout stays on feature/identity-email-notifications — never switch it) ## Workspace State diff --git a/aidlc-docs/features/contact-forms-module/audit.md b/aidlc-docs/features/contact-forms-module/audit.md index 390924f..3f0ac40 100644 --- a/aidlc-docs/features/contact-forms-module/audit.md +++ b/aidlc-docs/features/contact-forms-module/audit.md @@ -107,3 +107,15 @@ **Context**: Code Generation Part 1. --- + +## CMS-U3 done, CMS-U3b and CMS-U4 plans + +**Timestamp**: 2026-11-09 + +**User Input**: "CMS-U3 geaccepteerd ... Stuur het U3b-plan en het U4-plan in een bericht ... contact-settings-routes, lijst/detail/status/verwijderen/resend, spam apart, ongelezen-teller zonder spam, route-table-test als AdminOnly." (via Redesign - SLS) + +**AI Response**: U3 committed (b9af7df); plans for U3b and U4 written; Sentry/IP privacy note added to the U3 summary. + +**Context**: Code Generation Part 1. + +--- diff --git a/aidlc-docs/features/contact-forms-module/construction/cms-u3-contact-core/code/summary.md b/aidlc-docs/features/contact-forms-module/construction/cms-u3-contact-core/code/summary.md index 3dd97e4..f4b6856 100644 --- a/aidlc-docs/features/contact-forms-module/construction/cms-u3-contact-core/code/summary.md +++ b/aidlc-docs/features/contact-forms-module/construction/cms-u3-contact-core/code/summary.md @@ -53,3 +53,6 @@ Build 0 errors. Contact.Tests 113 passed (unit and pipeline), Core 205, Availabi ## Running the tests The `Pipeline` tests need `ConnectionStrings__DefaultConnection` pointing at a MariaDB/MySQL server on which databases may be created (same requirement as `Api.Tests`). Unit tests only: `dotnet test --filter "FullyQualifiedName!~Pipeline"`. + +## Attention point for the privacy statement (SLS request) +Sentry runs with `SendDefaultPii = true`: an error event for ANY request, including the contact routes, carries the caller's IP address. Nothing from the form (name, e-mail, subject, message) is ever in a Sentry event, and no IP address is stored in the contact database. The privacy statement should mention error reporting with IP addresses as a processing activity (and the Sentry data location/retention); no code action now. diff --git a/aidlc-docs/features/contact-forms-module/construction/plans/cms-u3b-openapi-export-code-generation-plan.md b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u3b-openapi-export-code-generation-plan.md new file mode 100644 index 0000000..ca129a4 --- /dev/null +++ b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u3b-openapi-export-code-generation-plan.md @@ -0,0 +1,34 @@ +# Code Generation Plan — CMS-U3b openapi-export + +Phase 1, right after CMS-U3. Contract: "the definitive OpenAPI document is generated by the CMS and committed, so `cms-client` generates its types from it" (§ 8, FR-H). Scope: the SlpSoftware host's API document as a committed file plus a test that keeps it current, and the contact contract details in it (reusable problem responses, required header, required request fields). No behaviour change of any endpoint. + +## Findings +- The host already registers `services.AddOpenApi()` (Core, document `v1`) and, in Development only, `app.MapOpenApi()` which serves `/openapi/v1.json`; the pipeline test host runs in Development, so the document can be fetched over HTTP from the real composed host (no internal API needed). +- The shared registration lives in a Core file the ASF branch also changes. Everything contact-specific is therefore added **from the Contact module** through named options (`services.Configure("v1", ...)`), leaving Core untouched. +- `.NET 10`'s OpenAPI uses `Microsoft.OpenApi` 2.x types; the transformers are written against that model (risk noted below). + +## Behaviour +1. **Committed file** `openapi/cms-api.v1.json` (repo root), the OpenAPI document of the SlpSoftware host (Offerings, Contact, Identity, Availability, Master, System). Written deterministically: `servers` removed (it is derived from the request host), keys in the order the generator emits, 2-space indentation, LF line endings, trailing newline. +2. **Snapshot test** (pipeline test, needs the database like the other pipeline tests): fetches `/openapi/v1.json` from the real host, normalizes it the same way, and compares it with the committed file; any drift fails the test with a message that names `UPDATE_OPENAPI=1`. With `UPDATE_OPENAPI=1` the test rewrites the file instead (and still passes), so regenerating is one command: `UPDATE_OPENAPI=1 dotnet test --filter OpenApiSnapshot`. +3. **Contact contract details in the document** (module-level transformers): + - Reusable `components.responses`: `Validation` (400, `application/problem+json`, `ValidationProblem` with `errors` map of arrays of the codes `required|tooLong|invalid|expired`), `TooLarge` (413), `RateLimited` (429 with the `Retry-After` header, `Problem`), plus schemas `Problem` and `ValidationProblem`; referenced by the contact operations. + - `POST /api/v1/contact-messages`: required header parameter `Idempotency-Key` (uuid); request body schema marks `name, email, subject, message, hpCheck, token` as required with the contract's `maxLength` values (100, 254, 100, 2000, 0 for `hpCheck`), `captchaToken` nullable; responses 202/400/413/429 (404 is documented as "form closed"). + - `GET /api/v1/contact-messages/token`: 200 (`ContactToken`: `token`, `minSeconds`, `captcha` nullable object) and 429; 404 "form closed". + - Attributes (`[ProducesResponseType]`) on the public contact actions drive the operations; the transformers only add what attributes cannot express (components, header, required/maxLength). +4. **cms-client note**: the file is the single source for generated types; the Andrea host will get its own file when it exists on the base branch (name per host, e.g. `openapi/andrea.v1.json`); this unit documents the convention in the file's README line in the summary. + +## Steps +- [ ] **Step 1 — Attributes**: `[ProducesResponseType]` on `GetToken` and `Submit` (and `[ProducesResponseType<...>]` for the offerings list is already inferred by return types; nothing else is touched). +- [ ] **Step 2 — Transformers** in `Modules.Contact/OpenApi/`: `ContactOpenApiDocumentTransformer` (components), `ContactOpenApiOperationTransformer` (header, response refs), `ContactOpenApiSchemaTransformer` (required/maxLength). Registered from `ContactModule.RegisterServices` via `services.Configure("v1", ...)`. +- [ ] **Step 3 — Snapshot test + helper** in `Contact.Tests/Pipeline/OpenApiSnapshotTests.cs`: normalization (drop `servers`, stable formatting), repo-root lookup (walk up to `SlpModularCms.sln`), `UPDATE_OPENAPI=1` rewrite, a failing message with the exact regeneration command. Plus unit assertions on the fetched document (not only equality with the file): the contract details in item 3 exist (header required, reusable responses present, required fields and maxLength), so a regenerated file cannot silently lose them. +- [ ] **Step 4 — Generate and commit** `openapi/cms-api.v1.json`; review it (no PII, no secrets, no host names, no example addresses). +- [ ] **Step 5 — Verification (automatic)**: build; Contact.Tests (pipeline against a temporary MariaDB); full solution tests; real output. The test is run twice: once with `UPDATE_OPENAPI=1`, once without (must pass unchanged). +- [ ] **Step 6 — Docs/commit**: summary (how to regenerate, how the frontend consumes it, convention per host); one commit; no push. + +## Explicitly NOT touched +Core (`AddOpenApi`, `MapOpenApi`), any endpoint behaviour, other modules' controllers (their operations simply appear in the document as generated), the Andrea host (not on the base branch), frontend. + +## Risks / open points +- The Microsoft.OpenApi 2.x model differs from 1.x examples found online; if a detail cannot be expressed through the transformer API, the unit documents it in the summary instead of faking it, and the test asserts what the document really contains. +- The file will be large (the whole host API). It is committed as is; reviewers diff it like code. +- Needs SLS confirmation: file name `openapi/cms-api.v1.json` for the SlpSoftware host (per-host naming convention proposed above). diff --git a/aidlc-docs/features/contact-forms-module/construction/plans/cms-u4-contact-admin-api-code-generation-plan.md b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u4-contact-admin-api-code-generation-plan.md new file mode 100644 index 0000000..b4cd929 --- /dev/null +++ b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u4-contact-admin-api-code-generation-plan.md @@ -0,0 +1,46 @@ +# 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?