Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/plans/cms-u0-offerings-restful-routes-code-generation-plan.md
T
SluijsensandClaude Sonnet 5.5 bc763c8ef6 Aanbod: RESTful routes zonder /admin, één OfferingDto en herordenen via PUT /offerings/order
Admin en bezoeker gebruiken dezelfde resource; alleen GET is anoniem, de rest vereist AdminOnly. OfferingAdminDto vervalt (displayOrder zit nu in OfferingDto), move-up/move-down zijn vervangen door de order-route die een onbekende of onvolledige lijst met 400 afwijst. De admin-frontend en alle tests zijn mee aangepast.

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

5.5 KiB

Code Generation Plan — CMS-U0 offerings-restful-routes

Decision (Bryan via Redesign - SLS): no /admin segment in API routes; admin uses the same resource with the same verbs, access via authorization (AdminOnly), public endpoints via [PublicSiteEndpoint] (CMS-U2). Applies now to Offerings, in this feature, before the category units. API and admin frontend are deployed together, so no old routes are kept.

Unit context

  • Phase 1, base master d9cc539, first unit. No data model change, no migration.
  • Touches: Modules.Offerings (controller, service, DTOs, tests) and frontend/src/features/offerings (api calls, mocks, tests). Does not touch Core, Availability, Identity, ASF-owned areas (auth/refresh, users, theme assets).

Route mapping

Today New Auth
GET /offerings (public DTO) GET /offerings (single DTO, see below) anonymous (rate limit offerings-public unchanged; [PublicSiteEndpoint] added in CMS-U2)
GET /offerings/admin removed (same GET /offerings)
POST /offerings/admin POST /offerings AdminOnly, 201 + Location: /api/v1/offerings/{id}
PUT /offerings/admin/{id} PUT /offerings/{id:guid} AdminOnly
DELETE /offerings/admin/{id} DELETE /offerings/{id:guid} AdminOnly (soft delete unchanged)
PUT /offerings/admin/reorder PUT /offerings/order body { "orderedIds": [...] } AdminOnly (collection action, order cannot clash with {id:guid})
POST .../{id}/move-up, .../move-down removed UI computes the new order and calls PUT /offerings/order

PATCH is not introduced (no partial-update use case); PUT keeps its current full-replace semantics.

Design question: public vs admin DTO on one URL

Today the admin DTO differs from the public DTO by exactly one field: displayOrder.

  • Recommended (A): one URL, one DTO for everybody, OfferingDto gains displayOrder (additive, harmless to the SLS frontend which already relies on array order). No auth-dependent response => no Vary: Authorization, no cache split, a single OpenAPI schema, OfferingAdminDto is deleted.
  • Alternative (B): auth-dependent DTO on the same URL: needs Vary: Authorization/no shared caching, an OpenAPI oneOf, and hides nothing sensitive. Alternative (C): ?view=admin query switch: not RESTful-pure, adds a parameter for one integer.
  • Other side effects of (A): the offerings-public limiter (120/min) now also covers admin list calls (fine). Needs your OK; default is A.

Steps

  • Step 1 — DTO: OfferingDto gets int DisplayOrder (appended); delete OfferingAdminDto; service GetPublicOfferingsAsync/GetAllForAdminAsync collapse into GetOfferingsAsync.
  • Step 2 — Controller routes: rewrite OfferingsController per the table; class stays [Authorize(Policy = "AdminOnly")] with [AllowAnonymous] only on GET; Create returns Created("/api/v1/offerings/{id}", dto); remove MoveUp/MoveDown actions and IOfferingsService.MoveUpAsync/MoveDownAsync (+ repository GetPreviousAsync/GetNextAsync if unused elsewhere); reorder route order.
  • Step 3 — Backend tests: update OfferingsControllerTests, OfferingsServiceTests, repository tests (removed methods); add a route-table test (reflection over OfferingsController action routes + auth attributes: only GET is anonymous, all other actions inherit AdminOnly, no route contains admin).
  • Step 4 — Frontend: change URLs in useOfferings, useCreateOffering, useUpdateOffering, useDeleteOffering, useReorderOfferings; useMoveOffering computes the new id order client-side and calls PUT /offerings/order (keeps the UI buttons); types.ts: OfferingAdminDto becomes OfferingDto incl. displayOrder (or alias); update mocks/handlers.ts and tests (OfferingsListPage.test.tsx, OfferingFormPage.test.tsx, any others that assert URLs).
  • Step 5 — Build + test (automatic): dotnet build solution; dotnet test Offerings.Tests (and Core.Tests/Availability.Tests as regression); Api.Tests need a local MySQL (they fail here with "connection refused" independent of this change; will be reported as such); frontend: lint + type-check + unit tests (npm/pnpm scripts as in frontend/package.json). Report real output.
  • Step 6 — Docs: summary in construction/cms-u0-offerings-restful-routes/code/summary.md, incl. the handoff note for the SLS site: GET /api/v1/offerings unchanged except the additive displayOrder.
  • Step 7 — Commit (one commit, Dutch message, Co-Authored-By line). No push.

Explicitly NOT touched

Core, Availability (incl. POST admin/status, see below), Identity, Master, host config, [PublicSiteEndpoint] (CMS-U2), OpenAPI export (CMS-U3), category work (CMS-U1), ASF-owned frontend areas.

Findings for other controllers (report only)

  • Only AvailabilityController has another admin segment: POST /availability/admin/status. Per your instruction it becomes PUT /availability/status (AdminOnly; GET /availability/status stays public) in Phase 2, after the ASF merge, checking callers: Master/SlaveStatus, poll client, frontend.
  • No other controller has an admin segment. Several are verb-style RPC routes (Auth/login, Auth/revoke, Master/register, Master/status POST, CmsInstance/{id}/status PUT) — not changed; flagged for your later RESTful review.

Traceability

Bryan's route decision (SLS message), contract § 6/§ 7 (to be aligned by SLS); Security: authorization unchanged in effect (only GET anonymous), covered by the route-table test.