Files
SluijsensandClaude Sonnet 5.5 321234dfa6 CMS: één bannerlijst met Locatie, SLP-thema, thema-schakelaar, documentatie
- Banner-admin: één lijst met Locatie-badge (Boven/Onder), Locatie-keuzeveld in het formulier, "Live" en "Wordt niet getoond" per locatie, aan/uit per rij
- Thema slpsoftware: Archivo, bordeaux #7A1414 (WCAG AA licht en donker), <SLP/>-logo, favicon, mail-logo; VITE_THEME in de SLP-builds (test en productie-config)
- Thema-schakelaar: eerste klik wisselt altijd het getoonde thema (klasse op <html> als bron van waarheid, gedeelde status, startscript valideert opslag) + tests
- Docs: README, docs/cms-themas.md, docs/deploy-en-testomgevingen.md, docs/privacy-gegevens-contactformulier.md, aidlc-docs (offering-banners, bug theme-toggle-first-click)

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

84 lines
7.0 KiB
Markdown

# Offering Banners (offering-banners)
- **Slug**: offering-banners
- **Type**: Feature (small), built outside the AI-DLC flow and documented afterwards
- **Status**: On test (not merged, not pushed)
- **Branch**: feature/contact-forms-module
- **Affected components**: `SlpModularCms.Modules.Offerings` (+ Tests), openapi/slpsoftware.v1.json, frontend admin (`frontend/src/features/offerings`)
- **Documented**: 2026-11-15
- **Documentation Language**: English
- **Conversation Language**: Dutch (user language)
> This feature was **not** run through the AI-DLC stages (no requirements, design or audit trail). This file records what the code does, checked against the code on 2026-11-15. There are no `requirements`, `plans` or `audit.md` for it.
## Purpose
A site-wide, schedulable announcement ("banner") for offers and campaigns, managed by administrators in the CMS and fetched by the website through one public endpoint. A banner has a **position**: `top` (a narrow one-line bar above the page) or `bottom` (the large banner, which is also what every banner was before positions existed).
## History
| Commit | What |
|---|---|
| a2f4513 (2026-11-12) | `OfferingBanner` entity, `GET /offerings/banner`, banner layout removed (backend) |
| 5386abb (2026-11-12) | Banner tab in the admin (list, form, schedule); layout removed from the frontend |
| 4b09089 (2026-11-14) | Position `top`/`bottom` (backend, migration, admin tab, OpenAPI) |
| 2026-11-15 (commit "CMS: één bannerlijst met Locatie, SLP-thema, thema-schakelaar", on test) | Admin list: one list with a Location badge, "Live" / "Not shown" markers, on/off toggle per row; Location field in the form (`OfferingBannersTab.tsx`, `OfferingBannerDialog.tsx`, translations) |
## Contract
Routes are served under `/api/v1` (like all module routes).
### Public: `GET /api/v1/offerings/banner?position=top|bottom`
Source: `Controllers/OfferingBannersController.cs` (`PublicOfferingBannerController`).
| Aspect | Behaviour |
|---|---|
| Authentication | Anonymous (`[AllowAnonymous]`, `[PublicSiteEndpoint]`: stays reachable through the availability gate) |
| `position` | Optional. Absent or empty = `bottom`. Any other value than `top` / `bottom` (case sensitive) = `400` with `{ "error": "Position must be 'top' or 'bottom'." }` |
| No active banner at that position | `204 No Content` |
| Active banner | `200` with `{ title, text, linkLabel, linkUrl, position }` (no scheduling fields, no id) |
| Caching | `Cache-Control: public, max-age=60` is set on every answer that gets past the position check (so 200 and 204; not on the 400) |
| Rate limit | Policy `offerings-public`: fixed window per client address, `RateLimiting:OfferingsPublic:PermitLimit` / `WindowSeconds`, default 120 per 60 s (`ServiceCollectionExtensions.cs`); beyond it `429` |
### Management: `/api/v1/offerings/banners` (policy `AdminOnly`, i.e. role Administrator or higher)
| Method and route | Result |
|---|---|
| `GET /offerings/banners` | `200` list of all banners, most recently changed first (`id, position, title, text, linkLabel, linkUrl, isActive, startsAt, endsAt, updatedAt`) |
| `POST /offerings/banners` | `201` with the banner |
| `PUT /offerings/banners/{id}` | `200` with the banner (full replace), `404` if unknown |
| `DELETE /offerings/banners/{id}` | `204`, `404` if unknown |
### Fields and validation (`Models/OfferingBannerModels.cs`, `Data/Entities/OfferingBanner.cs`)
| Field | Rule |
|---|---|
| `position` | `top` or `bottom`; default `bottom` |
| `title` | Max 100 characters. **Required for `bottom`**, optional for `top` (may be empty) |
| `text` | Required, max 300 characters (`MaxLength`). For `top` the trimmed text is max **120** characters |
| `linkLabel` (max 50) and `linkUrl` (max 500) | Both or neither. Empty values are stored as null |
| `linkUrl` form | An `https://` URL with a host, or a site path starting with a single `/`. Not allowed: `//host`, backslashes, whitespace or control characters |
| `isActive` | Default `true` |
| `startsAt`, `endsAt` | Optional; if both are given, `endsAt` must be after `startsAt` |
Text fields are trimmed before storage. Every change logs `Offering banner {id} {Created|Updated|Deleted} by user {id}` and invalidates the `IIndexHtmlCache` when one is registered (`OfferingBannersService.Changed`). Whether a banner is injected into any HTML through that cache is not verified (no reference to banners was found in `Core/Hosting/Website`).
### Database
Table `OfferingsBanners`. Migration `20261114100000_AddOfferingBannerPosition` adds `Position varchar(10) NOT NULL DEFAULT 'bottom'`, so **every banner that existed before becomes `bottom`**. (Earlier migration `20261112100000_AddOfferingBannerRemoveLayout` created the table and dropped the `Layout` column of `OfferingsOfferings`.)
## Decisions (as implemented)
1. **"At most one per position" is enforced when reading, not when saving.** Any number of banners can be stored and switched on. `GetActiveAsync(position)` takes the banners that are switched on, at that position, inside their schedule (`StartsAt <= now` and `now < EndsAt`, either may be empty), and returns the one with the latest `UpdatedAt`. A top and a bottom banner can therefore be shown at the same time.
2. **The schedule is evaluated on the server at request time** (UTC, via `TimeProvider`); the browser's time zone only matters in the admin form (datetime-local, converted to UTC).
3. **The admin shows one list for both positions**, not one tab per position: a Location badge on each row (Top / Bottom), a status badge (Active / Planned / Expired / Off), and a "Live" badge on the banner visitors see now. An active banner shadowed by a more recently changed one at the same position gets "Not shown" plus a hint. `shownBannerIds` in `OfferingBannersTab.tsx` is a client-side copy of the server rule, not a server field. Each row has an on/off button (re-sends the banner through `PUT` with `isActive` flipped).
4. **The form follows the position**: changing Location changes the text limit (120 / 300) and whether the title is optional; the limits are mirrored in `schemas/offeringBanner.ts`.
5. **Links are restricted to `https://` or own-site paths**, which excludes `javascript:` and protocol-relative links.
## Known gaps and notes
- The OpenAPI document (`openapi/slpsoftware.v1.json`) describes the public endpoint with only a `200` answer: no `204`, `400` or `429`, no response body schema, no allowed values for `position`. The request schema has no length limits and no enum for `position`; `POST` is documented as `200` while the code returns `201`. The controllers carry no `[ProducesResponseType]` annotations. Not changed here.
- The website that shows the banner is not in this repository; how it fetches and renders the banner is not verified. The admin hint says that for Andrea's website the schedule applies at the next (nightly) build; that build is not in this repository either (not verified).
- Hosts that expose the module: `Api.SlpSoftware` and `Api.AndreaSlopFotografie` reference `Modules.Offerings` (csproj); the dev host `Api` does not.