Files
slp-modular-cms/aidlc-docs/features/hero-module/construction/functional-design/business-rules.md
T

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.