6.7 KiB
6.7 KiB
Functional Design: business rules (units H1 to H5)
IDs are used in the code, tests and the build and test summary.
Hero content (H2)
| ID | Rule |
|---|---|
| BR-H01 | One hero per language; the language defaults to nl. Language is unique. Only nl is exposed and edited now. |
| BR-H02 | title required (after trimming), at most 200 characters and at most 5 lines; line breaks are \n (\r\n is normalised). Plain text. |
| BR-H03 | tagline optional, at most 120 characters, single line (line breaks are replaced by a space). lead optional, at most 600 characters, line breaks kept. |
| BR-H04 | display is single or slideshow; default single; any other value is rejected. |
| BR-H05 | 0 to 2 buttons. Both label (1 to 50 characters) and target (at most 500) are required for a button; a half-filled button is rejected. |
| BR-H06 | A target is exactly one of: anchor # followed by a letter and then letters, digits, - or _ (at most 100 characters); path starting with a single / (not //), no \, no control characters, no whitespace, no : before the first /; https address with the scheme https, a host, no user info, parsed as an absolute URI. Anything else is rejected with the message "Kies een #anker, een /pad of een https://-adres." |
| BR-H07 | Removed 2026-11-17 (no schedule, no hero-wide switch; see FR-05). Was: Schedule: startsAt and endsAt optional; when both exist endsAt must be after startsAt. Stored in UTC; displayed in the admin in local time. |
| BR-H08 | Text in every field is plain text. The server stores it as typed (control characters other than the line break are removed) and encodes it when writing HTML (& < > " ') and JSON in a script element (< > & and U+2028/2029 as \uXXXX). No field can produce markup or script. |
| BR-H09 | Slides: no administrator limit on the number. Each slide has an existing image, alt (at most 300 characters) or decorative = true, an order, and isActive. A slide that is not decorative needs a non-empty alt to be saved. decorative and a non-empty alt together are accepted; the alt is then ignored when published. |
| BR-H10 | Technical safety ceiling: at most Hero:MaxPublishedSlides (default 50) slides are published; the rest stay saved. Reported to Bryan (see the logic model). |
| BR-H11 | Saving replaces the whole hero (one transaction). A slide id the caller sends must belong to this hero; unknown ids are rejected. Slides not listed are removed. |
| BR-H12 | Actor and time of every change are stored (UpdatedBy, UpdatedAt) and logged. |
Public availability (H2, H4)
| ID | Rule |
|---|---|
| BR-P01 | Since 2026-11-17 the hero exists as soon as it has a title (no switch, no schedule); the rest below still holds for slides. Was: The public hero exists only when the hero isActive, now is within the schedule (start inclusive, end exclusive), the title is non-empty. Otherwise 204 and the baked hero stays. |
| BR-P02 | Only active slides with a stored image are published, in saved order. |
| BR-P03 | GET /api/v1/hero answers with Cache-Control: public, max-age=60, rate-limited (policy hero-public, 120 per 60 s), anonymous, through the availability gate. |
| BR-P04 | The HTML region, the preload and the data block are derived from the same read model per request cycle. |
Images (H1, H2)
| ID | Rule |
|---|---|
| BR-I01 | Upload only for Administrator and higher; at most 20 uploads per user per hour; body at most 10 MB. |
| BR-I02 | The format is decided from the signature (see the logic model); not on the allow-list = unsupported_format. SVG is never accepted. |
| BR-I03 | Pixel ceiling Media:MaxPixels (default 64 million) and a side ceiling of 16 384 pixels; decode timeout Media:DecodeTimeoutSeconds (default 20). |
| BR-I04 | Metadata (EXIF including GPS, XMP, IPTC, embedded thumbnails) is never written to an output file; the original is also stored without GPS (the stored original is re-encoded without metadata only when it contains GPS or other metadata; the pixel data are not altered otherwise). |
| BR-I05 | Output never exceeds the source size (no upscaling); every ratio gets at least one variant. |
| BR-I06 | Focus values: x and y between 0 and 1, zoom between 1 and 4; an invalid value is rejected. The default is the centre (0.5, 0.5) and zoom 1 for every ratio. A ratio override is optional; without it the general setting applies. |
| BR-I07 | An image used by a slide cannot be deleted (409, "Deze afbeelding wordt nog gebruikt door een slide."). |
| BR-I08 | Retired files (old sets, deleted images) are removed after 7 days by the clean-up; referenced files are never removed. |
| BR-I09 | Rejection reasons are stable codes (too_large, unsupported_format, corrupt, too_many_pixels, timeout, busy, unavailable); the messages shown come from the texts files, with no file names or internals. |
Media serving (H3)
| ID | Rule |
|---|---|
| BR-M01 | Only addresses that match the registered area pattern are served; everything else is a 404 without detail. |
| BR-M02 | Served files carry the immutable cache header, a strong ETag and nosniff; HEAD and 304 are supported. |
| BR-M03 | Writes are atomic per set; a failed write leaves nothing visible. |
| BR-M04 | A start-up check proves the media directory exists and is writable; if not, uploads are refused (503) and an error is logged; public reads of existing files and the public hero keep working. |
Injection (H4)
| ID | Rule |
|---|---|
| BR-J01 | The output must equal the ASF golden files byte for byte (six cases: standard, minimal, two-lines, hostile, no-alt, none). |
| BR-J02 | Only WebP in the picture and the preload; the img has the original width and height; fetchpriority="high"; the object-position from the general focus, formatted without trailing zeros and at most two decimals; no style without a valid focus. |
| BR-J03 | Fail-open per part; a failing contributor leaves the whole data block as baked. |
| BR-J05 | Before writing the hero into a page the transform checks that the first kept slide's variant files exist in the store; when they do not, regions and preload stay as baked. |
| BR-J04 | The Offerings output stays byte-identical after the change to the shared data block (existing golden files stay green). |
Admin (H5)
| ID | Rule |
|---|---|
| BR-A01 | The Hero screen shows a badge "Live" or "Niet live" (with the schedule dates) and nothing more about the reason. |
| BR-A02 | The focus editor shows wide and tall previews cut with the same maths as the host (a TypeScript twin tested with the same vectors). A ratio can be reset to "use the general point". |
| BR-A03 | Upload errors show the server message at the upload control; validation errors at the field. |