Docs: plannen CMS-U3b en CMS-U4 en privacy-aandachtspunt Sentry/IP
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
+34
@@ -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<OpenApiOptions>("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<OpenApiOptions>("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).
|
||||
+46
@@ -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?
|
||||
Reference in New Issue
Block a user