Hero-module: Functional Design, NFR Requirements, NFR Design en Infrastructure Design (H1-H5)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -5,7 +5,7 @@
|
||||
- **Feature Slug**: hero-module
|
||||
- **Project Type**: Brownfield
|
||||
- **Start Date**: 2026-11-16
|
||||
- **Current Stage**: INCEPTION - Application Design (artifacts written, waiting for approval)
|
||||
- **Current Stage**: CONSTRUCTION - Code Generation (H1 first)
|
||||
- **Branch**: feature/hero-module (worktree K:\Development\Projects\SlpModularCms-contact-forms, from master b2cacfe)
|
||||
|
||||
## Workspace State
|
||||
@@ -49,10 +49,10 @@
|
||||
- [x] Application Design (artifacts in inception/application-design/, awaiting approval)
|
||||
- [x] Units Generation (unit-of-work.md, -dependency.md, -story-map.md; plan answered 2026-11-16)
|
||||
### 🟢 CONSTRUCTION PHASE
|
||||
- [ ] Functional Design - EXECUTE
|
||||
- [ ] NFR Requirements - EXECUTE
|
||||
- [ ] NFR Design - EXECUTE
|
||||
- [ ] Infrastructure Design - EXECUTE for the media unit (storage is a directory outside the release)
|
||||
- [x] Functional Design (bundled H1-H5, construction/functional-design/; answered 2026-11-16)
|
||||
- [x] NFR Requirements (construction/nfr-requirements/)
|
||||
- [x] NFR Design (construction/nfr-design/)
|
||||
- [x] Infrastructure Design (media directory; construction/infrastructure-design/)
|
||||
- [ ] Code Generation - EXECUTE (per unit H0 to H6)
|
||||
- [ ] Build and Test - EXECUTE
|
||||
### 🟡 OPERATIONS PHASE
|
||||
|
||||
@@ -131,3 +131,15 @@
|
||||
**Context**: Functional Design planning; waiting for answers.
|
||||
|
||||
---
|
||||
|
||||
## Functional Design answered; design stages written
|
||||
|
||||
**Timestamp**: 2026-11-16T00:00:00Z
|
||||
|
||||
**User Input**: "Bryans besluiten (2026-11-16): BIBLIOTHEEK: Magick.NET-Q8 goedgekeurd, achter IImageProcessor. arm64 niet vooraf testen; de Pi bevestigt het bij de eerste test-deploy, met de opstart-zelftest ... Noteer HEIC als alleen-capability ... FUNCTIONAL DESIGN (6 vragen): 1. weigeren met melding. 2. 7 dagen bewaren. 3. Maximaal aantal slides: ONBEGRENSD ... Leg wel een technische bovengrens vast die geen beheerdersgrens is maar een veiligheidsgrens ... en meld Bryan als je die nodig vindt ... 4. platte tekst, altijd gecodeerd. 5. Admin als de hero niet live is: ALLEEN EEN BADGE. 6. Administrator en hoger met limiet per gebruiker. De defaults onderaan het plan ... zijn akkoord. Ga door met NFR Requirements, NFR Design, Infrastructure Design (mediamap) en Code Generation." (relayed by SLP Software - SLS - Main)
|
||||
|
||||
**AI Response**: Wrote the bundled Functional Design (business logic model, business rules, domain entities, admin screens), NFR Requirements and tech stack decisions, NFR Design patterns, and Infrastructure Design for the media directory. A technical ceiling of 50 published slides (`Hero:MaxPublishedSlides`) is set and reported for Bryan.
|
||||
|
||||
**Context**: Construction; moving to Code Generation (H1).
|
||||
|
||||
---
|
||||
|
||||
+72
@@ -0,0 +1,72 @@
|
||||
# Functional Design: business logic model (units H1 to H5)
|
||||
|
||||
Bundled for all units; answers of Bryan (2026-11-16) are applied. Names refer to `application-design/`. HTML for the region and preload is defined by the ASF golden files (`web/contract/host-injection/hero/`, commit 13f78c4), which are authoritative.
|
||||
|
||||
## H1. Image pipeline
|
||||
|
||||
### Upload admission (`IMediaUploadGuard.AdmitAsync`)
|
||||
|
||||
1. Reject at once when the declared length is above the maximum (10 MB) or the stream turns out longer (read through a counting stream, stop at the limit).
|
||||
2. Read the first bytes and decide the format from the **signature**, never from a name or `Content-Type`: JPEG, PNG, GIF, BMP, TIFF (both byte orders), WebP (`RIFF....WEBP`), and the ISO-BMFF family for AVIF and HEIC/HEIF (`ftyp` with brand `avif`, `avis`, `heic`, `heix`, `hevc`, `mif1`, `msf1`). Anything else (SVG, PDF, executables, text) is rejected as `unsupported_format`.
|
||||
3. Inspect through the library with an explicit format and resource limits: pixel size, frame count. Reject `too_many_pixels` (above the pixel ceiling), `corrupt` (decode error), `timeout`.
|
||||
4. Animated input (GIF, WebP, AVIF sequences) is reduced to the first frame.
|
||||
5. Wait for a free processing slot (at most `MaxParallelJobs`); when none frees within a few seconds answer `busy` (HTTP 429).
|
||||
|
||||
### Render planning (pure)
|
||||
|
||||
For an image of `W x H` pixels, a ratio `r = n:d`, a focus setting `(fx, fy, z)` (centre `0.5, 0.5` and `z = 1` by default; a ratio may have its own setting, otherwise the general one applies):
|
||||
|
||||
- The **largest crop** of ratio `r` inside the image: `cw0 x ch0` (if `W/H > n/d` then `ch0 = H`, `cw0 = ch0 * n / d`, else `cw0 = W`, `ch0 = cw0 * d / n`).
|
||||
- With zoom `z >= 1` the crop is `cw = cw0 / z` by `ch = ch0 / z`.
|
||||
- The crop is centred on the point `(fx * W, fy * H)` and then moved the smallest amount needed to lie inside the image. So the subject stays as close to the centre of the crop as the image allows, and a crop never leaves the image.
|
||||
- Widths: from the configured steps for the ratio (`wide`: 640, 960, 1280, 1600, 2560; `tall`: 480, 640, 960, 1280) keep those `<= cw` (never upscale). If none is `<= cw`, one variant at `cw` is made. The height is `round(width * d / n)`.
|
||||
- Formats per width: WebP always; AVIF when the processor reports AVIF output; the page-critical HTML uses WebP only (contract).
|
||||
- Quality: WebP 80, AVIF 50. Metadata is removed from every output; EXIF orientation is applied before cropping.
|
||||
|
||||
### Set hash and addresses
|
||||
|
||||
`setHash` = first 16 hex characters of SHA-256 over the canonical string `sha256-of-original | wide:fx,fy,z | tall:fx,fy,z` (numbers rounded to 4 decimals, invariant culture). A change of focus therefore gives a new set and new addresses; an identical upload of the same photo with the same focus gives the same set (no second copy is stored). Variant file name: `<ratio>-<width>.<ext>` (`wide-1600.webp`, `tall-960.avif`); address `/media/hero/<setHash>/<name>`.
|
||||
|
||||
### Self-test at start-up
|
||||
|
||||
The processor decodes and encodes a tiny embedded image in every supported format and logs the capability list (input and output formats, library version). A failure marks the processor unavailable: uploads answer 503 with a generic message; reading and publishing are unaffected.
|
||||
|
||||
## H3. Media store and serving
|
||||
|
||||
- **Keys**: variants `hero/<setHash>/<ratio>-<width>.<ext>`; originals `originals/<sha256>.<ext>` (never served). Only keys made by the code exist; a client file name is never used in a path.
|
||||
- **Write**: a set is written to a temporary directory next to the target and moved into place with one rename; a half-written set is never visible.
|
||||
- **Serve** `GET|HEAD /media/{**path}`: the path must match `^hero/[0-9a-f]{16}/(wide|tall)-[0-9]{2,5}\.(webp|avif|jpg)$` (area pattern from a registered allow-list, so other areas can register their own); otherwise 404. Headers: `Content-Type` from the extension, `Cache-Control: public, max-age=31536000, immutable`, strong `ETag` (from the set hash and name), `X-Content-Type-Options: nosniff`, `Vary: Accept-Encoding` not needed (images are not recompressed). `If-None-Match` equal gives 304. Rate limit policy `media-public`.
|
||||
- **Clean-up** (hosted service, daily): removes sets and originals that no image row references and that are older than 7 days (a retired set is stamped when it stops being referenced; the files go 7 days later). Never removes a referenced file.
|
||||
- **Free space and size**: before writing, check free space (at least the expected output plus a margin) and the total size of the media directory against the safety limit `Media:MaxTotalBytes`; refuse with a generic message when exceeded.
|
||||
|
||||
## H2. Hero backend
|
||||
|
||||
### Save (`PUT /api/v1/hero`, whole hero replaced)
|
||||
|
||||
Input: hero fields, buttons, display, schedule, slide list in order (`id` optional for a new slide, `imageId`, `alt`, `decorative`, `isActive`). In one transaction: validate everything, update the hero, upsert slides, remove slides no longer listed, renumber the order, record actor and time. Afterwards `IIndexHtmlCache.Invalidate()`.
|
||||
|
||||
### Public read model (`PublicHeroService.GetActiveAsync`)
|
||||
|
||||
Returns null (204) when: no hero row for the language, `IsActive` false, `now` before `StartsAt` or at or after `EndsAt`, or the hero has no title. Otherwise: only active slides that have a stored image; a slide without alt that is not decorative is **not** published (the admin does not allow saving it anyway); order as saved. Each slide carries the general focus, plus the per-ratio overrides, and all stored variants (WebP and AVIF) with their ratio, width, type and address. The result is also what the HTML transform and the data block use, so the three always agree.
|
||||
|
||||
### Image operations
|
||||
|
||||
- **Upload** (`POST /api/v1/hero/images`): guard, store original, render the planned sets for the default focus, save the row, return the image with its variants.
|
||||
- **Set focus** (`PUT /api/v1/hero/images/{id}/focus`): validate ranges (`0..1`, zoom `1..4`), compute the new set hash, render the sets into new addresses, update the row, stamp the old set as retired; the slides keep pointing at the same image id.
|
||||
- **Delete** (`DELETE /api/v1/hero/images/{id}`): refused with 409 and a clear message while any slide uses the image (Bryan, Q1); otherwise the row goes and its set and original are stamped retired.
|
||||
|
||||
## H4. Injection
|
||||
|
||||
Order of work for a page that mentions hero markers: get `PublicHeroDto?` once per request cycle; if null, leave regions and preload as baked (and the data block carries `"hero": null`); otherwise:
|
||||
|
||||
1. `HERO-HTML` region: exactly the ASF golden rules (title lines with `<br>`, tagline span, buttons, first kept slide as `<picture>`; slides skipped when they have no alt and are not decorative, a path outside our host, or no size; WebP only; `object-position` from the focus of the ratio that the `img` shows, i.e. the general focus).
|
||||
2. `HERO-PRELOAD` region in the head: one preload for `tall` with `media="(orientation: portrait)"` and one for `wide` with `media="(orientation: landscape)"` when both exist; one without `media` when only one ratio exists; `srcset`, `sizes`, `media` byte-equal to the picture.
|
||||
3. Data block: key `hero` with the whole `PublicHeroDto` (all slides) in the shared block.
|
||||
|
||||
Fail-open: any exception, an unreadable hero or a missing marker leaves that part as baked; a failing data-block contributor leaves the whole block as baked.
|
||||
|
||||
**Safety ceiling for unlimited slides** (Bryan: no administrator limit, a technical ceiling only): the hero endpoint, the HTML transform and the data block never emit more than `Hero:MaxPublishedSlides` slides (default 50, configurable) so the first HTML and the data block cannot grow without bound; when a hero has more active slides the first 50 in order are published and the admin shows a notice. The ceiling is reported to Bryan; LCP and page weight stay leading (the first HTML contains only the first slide).
|
||||
|
||||
## H5. Admin
|
||||
|
||||
Screens and states are in `frontend-components.md`; the admin only shows a **live badge** (Bryan, Q5): "Live" or "Niet live" with the schedule dates, no long reason text. Uploads are limited per user (20 per hour). Every validation message comes from the server (`ProblemDetails`-style error with a field) and is shown at the field.
|
||||
@@ -0,0 +1,70 @@
|
||||
# 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 | 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 | 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. |
|
||||
@@ -0,0 +1,75 @@
|
||||
# Functional Design: domain entities (units H1 to H5)
|
||||
|
||||
Database: one new migration in the Hero module's own DbContext (MariaDB, hand-written like the Offerings migrations). Tables use the prefix `Hero`.
|
||||
|
||||
## Tables
|
||||
|
||||
### `Heroes`
|
||||
|
||||
| Column | Type | Notes |
|
||||
|---|---|---|
|
||||
| `Id` | `char(36)` | primary key |
|
||||
| `Language` | `varchar(10)` | default `nl`, unique |
|
||||
| `Title` | `varchar(1000)` | max 200 chars by validation; room for 5 lines |
|
||||
| `Tagline` | `varchar(200)` | max 120 |
|
||||
| `Lead` | `varchar(1000)` | max 600 |
|
||||
| `Display` | `varchar(20)` | `single` or `slideshow` |
|
||||
| `Button1Label`, `Button1Target`, `Button2Label`, `Button2Target` | `varchar(100)` / `varchar(500)` | nullable pairs |
|
||||
| `StartsAt`, `EndsAt` | `datetime(6)` | nullable, UTC |
|
||||
| `IsActive` | `bit` | default true |
|
||||
| `UpdatedAt` | `datetime(6)` | UTC |
|
||||
| `UpdatedBy` | `varchar(256)` | actor id or name |
|
||||
|
||||
### `HeroImages`
|
||||
|
||||
| Column | Type | Notes |
|
||||
|---|---|---|
|
||||
| `Id` | `char(36)` | primary key |
|
||||
| `OriginalSha256` | `char(64)` | content hash of the stored original |
|
||||
| `OriginalKey` | `varchar(200)` | `originals/<sha256>.<ext>` |
|
||||
| `SourceFormat` | `varchar(10)` | `jpeg`, `png`, ... |
|
||||
| `Width`, `Height` | `int` | original pixel size |
|
||||
| `Bytes` | `bigint` | size of the stored original |
|
||||
| `FocusX`, `FocusY`, `Zoom` | `double` | general setting; default 0.5, 0.5, 1 |
|
||||
| `WideFocusX`, `WideFocusY`, `WideZoom` | `double?` | optional override |
|
||||
| `TallFocusX`, `TallFocusY`, `TallZoom` | `double?` | optional override |
|
||||
| `SetHash` | `char(16)` | current set |
|
||||
| `VariantsJson` | `json`/`longtext` | list of `{ratio, width, height, type, key, bytes}` of the current set |
|
||||
| `RetiredSetsJson` | `longtext` | previous sets with their retire time (for the 7-day clean-up) |
|
||||
| `CreatedAt`, `CreatedBy` | `datetime(6)`, `varchar(256)` | |
|
||||
|
||||
### `HeroSlides`
|
||||
|
||||
| Column | Type | Notes |
|
||||
|---|---|---|
|
||||
| `Id` | `char(36)` | primary key, stable id used by the sites |
|
||||
| `HeroId` | `char(36)` | foreign key, cascade delete |
|
||||
| `ImageId` | `char(36)` | foreign key, restrict (deleting an image in use is refused) |
|
||||
| `Alt` | `varchar(600)` | max 300 chars by validation |
|
||||
| `Decorative` | `bit` | |
|
||||
| `SortOrder` | `int` | unique per hero |
|
||||
| `IsActive` | `bit` | |
|
||||
|
||||
Indexes: `Heroes(Language)` unique; `HeroSlides(HeroId, SortOrder)` unique; `HeroSlides(ImageId)`.
|
||||
|
||||
## Public DTOs (shape fixed in `component-methods.md`)
|
||||
|
||||
`PublicHeroDto { display, title, tagline, lead, buttons[], slides[] }`, `PublicSlideDto { id, alt, decorative, image }`, `PublicImageDto { width, height, focus{x,y,zoom}, focusByRatio?, src, srcset?, variants[] }`, `PublicVariantDto { ratio, width, height, type, url }`. `focusByRatio` is present only when an override exists. Fields that are null are written as JSON null (like the offerings data); the shapes match the ASF golden inputs (`web/contract/host-injection/hero/*.input.json`).
|
||||
|
||||
## Pure value types (H1, Core.Media)
|
||||
|
||||
`ImageFormat` (enum), `ImageInfo { Format, Width, Height, FrameCount }`, `Ratio`, `FocusSetting`, `CropRect { X, Y, Width, Height }`, `VariantSpec { Ratio, Width, Height, Format, Quality }`, `RenderedImage { Bytes, Width, Height, Format }`, `MediaAddress { Area, SetHash, Name }`.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Key | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `Media:Directory` | none (required for uploads) | the media directory outside the release |
|
||||
| `Media:MaxUploadBytes` | 10 485 760 | upload limit |
|
||||
| `Media:MaxPixels` | 64 000 000 | pixel ceiling |
|
||||
| `Media:MaxParallelJobs` | 2 | processing slots |
|
||||
| `Media:DecodeTimeoutSeconds` | 20 | per image |
|
||||
| `Media:MaxTotalBytes` | 2 147 483 648 | safety limit of the directory |
|
||||
| `Media:RetentionDays` | 7 | retired files |
|
||||
| `Hero:MaxPublishedSlides` | 50 | technical ceiling on published slides |
|
||||
| `RateLimiting:HeroPublic`, `MediaPublic`, `HeroUpload` | 120/60 s, 600/60 s, 20/hour per user | policies |
|
||||
@@ -0,0 +1,44 @@
|
||||
# Functional Design: admin screens (unit H5)
|
||||
|
||||
New navigation item "Hero" (visible when `/api/v1/System/capabilities` lists the Hero module; for the Administrator role and higher). Follows the existing admin conventions (React Query, `nl` and `en` translation files, the Offerings feature as the pattern). Admin texts live in the frontend translation files.
|
||||
|
||||
## Screen: Hero
|
||||
|
||||
```
|
||||
[Hero] [Live | Niet live van .. tot ..]
|
||||
-------------------------------------------------------------------------------
|
||||
Tekst Titel (meerdere regels) Tagline Lead
|
||||
Weergave ( ) Enkel ( ) Diavoorstelling
|
||||
Knoppen Knop 1: label + doel Knop 2: label + doel (0 tot 2)
|
||||
Planning Aan/uit Van ... Tot ...
|
||||
-------------------------------------------------------------------------------
|
||||
Slides [+ Afbeelding toevoegen]
|
||||
#1 [thumb] alt-tekst / decoratief aan/uit omhoog omlaag [Focus] [Verwijder]
|
||||
#2 ...
|
||||
-------------------------------------------------------------------------------
|
||||
[Opslaan]
|
||||
```
|
||||
|
||||
- **Badge** (Bryan, Q5): "Live" or "Niet live" with the schedule dates; no reason text. It reflects the public rules (active, within the schedule, a title, at least one usable slide) as computed by the server (`GET /hero/all` returns `isLive`).
|
||||
- **Form** validates on the server; messages come back per field and are shown at the field. A button target hint shows the three accepted forms. A slide without alt text and not marked decorative blocks saving, with the message at that slide.
|
||||
- **Slides** are listed in order; reorder with up and down buttons (keyboard accessible); on/off per slide; the number is not limited in the screen (a notice appears above the safety ceiling).
|
||||
- **Upload**: a file picker and a drop area; shows the accepted formats (from the server's capability list) and the 10 MB limit; progress; the server message on rejection (`unsupported_format`, `too_large`, `corrupt`, `too_many_pixels`, `busy`, `unavailable`).
|
||||
- **Delete** of an image or slide: a confirmation; the server refuses an image still in use (409) and the screen shows the message.
|
||||
|
||||
## Dialog: Focus
|
||||
|
||||
- The image with a draggable focus point (keyboard: arrow keys move by 1%, with shift by 5%), a zoom slider (1 to 4), the numeric values, and two live previews: `wide` (3:2) and `tall` (4:5), each cut exactly as the host will cut (shared maths, TypeScript twin of `FocusMath` with the same test vectors).
|
||||
- Tabs or toggles: "Algemeen punt" (default centre) and optional "Alleen wide" / "Alleen tall" overrides; a "Gebruik algemeen punt" reset per ratio.
|
||||
- Save sends `PUT /api/v1/hero/images/{id}/focus`; the previews update from the response variants.
|
||||
|
||||
## States
|
||||
|
||||
Loading, empty (no hero yet: an empty form with the button "Opslaan"), saving, error (server messages), saved. Unsaved-changes warning when leaving the screen.
|
||||
|
||||
## API used
|
||||
|
||||
`GET /api/v1/hero/all`, `PUT /api/v1/hero`, `POST /api/v1/hero/images` (multipart), `PUT /api/v1/hero/images/{id}/focus`, `DELETE /api/v1/hero/images/{id}`, `GET /api/v1/System/capabilities`.
|
||||
|
||||
## Accessibility and tests
|
||||
|
||||
Labels and descriptions on all fields, focus management in the dialog, keyboard operation of reorder and focus point, `aria-live` for save and upload results. Tests: component tests (form validation display, slide reorder, upload errors, badge), the `focusMath` vectors shared with the C# tests, and an interaction test for the focus dialog.
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
# Infrastructure Design: media directory (unit H3)
|
||||
|
||||
Bryan's decision: images live in a **directory outside the release**. This stage records how the directory is provided on each host and what is still unknown.
|
||||
|
||||
## Requirements on the directory
|
||||
|
||||
1. Outside the release and outside the web root (not served by IIS or nginx as static content; only the host's `/media/...` endpoint serves from it).
|
||||
2. Survives deploys (the release directory is replaced on every deploy).
|
||||
3. Writable by the account the host runs as; nothing else writes to it.
|
||||
4. Included in the backup of the site.
|
||||
5. Large enough: default safety limit `Media:MaxTotalBytes` 2 GB; expected use well below 100 MB.
|
||||
|
||||
## Per host
|
||||
|
||||
| Host | Directory | Setting | Backup | Status |
|
||||
|---|---|---|---|---|
|
||||
| **Pi test, SLP** (`~/apps/slpsoftware/test`) | `~/apps/slpsoftware/test/shared/media` (next to `shared/env`, `shared/wwwroot-web`) | `Media__Directory=%h/apps/slpsoftware/test/shared/media` in `shared/env` | Add the directory to the host backup routine for test (a test site may also be re-seeded) | To do by Pi-Main with the first test deploy: `mkdir -p`, mode 700, owner the service account |
|
||||
| **Pi test, ASF** | `~/apps/<asf test>/shared/media` (same pattern, its own env file) | `Media__Directory=…` | as above | same |
|
||||
| **SLP production** (Pi, later) | `~/apps/slpsoftware/production/shared/media` | `shared/env` | The production backup script (`backup-slpsoftware-db.sh` covers the database only): the directory must be added | Open until the release; listed in the production checklist |
|
||||
| **ASF production** (MijnHostingPartner, IIS, self-contained win-x64) | A data directory beside the site, outside the web root (for example `..\data\media`), writable by the application pool identity | environment variable or `appsettings.Production.json` | The hosting provider's file backup, or an FTP copy; to confirm | **Unknown: write permission and backup on this hosting are not known.** Bryan tests with ASF (hosting package, application pool identity). If the test fails, Bryan is asked again and the database store (behind `IMediaStore`) is built. |
|
||||
|
||||
## Deployment behaviour
|
||||
|
||||
- `deploy-scp.yaml` builds `releases/<ts>/` and switches `current`; `shared/` is not touched, so `shared/media` survives. No workflow change is needed for the Pi.
|
||||
- The directory is created by Pi-Main once (documented in `docs/hero-module.md` and in the checklist); the host also creates it at start-up when it is missing and the account may.
|
||||
- Release artifact size: Magick.NET adds about 35 MB native per platform; the upload limit of the deploy path (`deployment-instructions.md` 1.7.3, the nginx `client_max_body_size` for artifact upload) must allow the artifact; to be measured at the first deploy (the current artifact size is the reference).
|
||||
|
||||
## Backup and restore
|
||||
|
||||
- Files are immutable and content-addressed; a restore of the directory plus the database brings the site back; a restore needs both. A restored database without the directory leaves slides without files. Two safeguards: the start-up check logs a warning with the count of sets that the database refers to but the directory lacks, and the page injection (H4) checks that the first slide's files exist (through `IMediaStore.ExistsAsync`, cached with the page for 60 seconds) and leaves the baked hero in place when they do not, so a missing directory never produces a broken first image.
|
||||
- Test hosts: the seed script can rebuild the hero and images from the ASF sources, so a test restore is optional.
|
||||
|
||||
## Risks
|
||||
|
||||
| Risk | Handling |
|
||||
|---|---|
|
||||
| Write permission or backup unavailable on the ASF production hosting | Bryan tests with ASF before the release; `IMediaStore` allows a database implementation; Bryan is asked again when the test fails |
|
||||
| Disk fills | `Media:MaxTotalBytes`, free-space check before writing, clean-up of retired files, an error log line when 80% is reached |
|
||||
| Directory missing after a server move | Start-up check disables uploads and logs; the injection sees the missing first-slide files and leaves the baked hero (no broken image); documented in the checklist |
|
||||
| Deploy artifact too large for the proxy limit | Measured at the first deploy; the limit is raised on the proxy when needed |
|
||||
@@ -0,0 +1,50 @@
|
||||
# NFR Design: patterns for the hero-module (H1, H3, H4)
|
||||
|
||||
Each NFR of `nfr-requirements.md` is mapped to a pattern and the component that carries it.
|
||||
|
||||
## Patterns
|
||||
|
||||
| Pattern | Applies to | Where it lives | Notes |
|
||||
|---|---|---|---|
|
||||
| **Defence in depth for uploads**: size gate, signature allow-list, library decode with resource limits, parallelism gate, per-user rate limit, timeout, rejection codes | SEC-01, SEC-07, R-02 | `IMediaUploadGuard` (Core.Media), `HeroImagesController` (size limit attribute and `hero-upload` policy) | Each layer rejects alone; no single check is the only protection. A counting stream enforces the byte limit even when the declared length lies. |
|
||||
| **Resource limits in the library**: `ResourceLimits.Width/Height/Area/Memory/Time` set once at start-up from `Media:*` options | SEC-01, P-03 | `MagickImageProcessor` initialisation | Process-wide limits, not per call; documented because Magick's limits are global. Format policy: decode only the allow-listed formats by passing the explicit `MagickFormat` after the signature check. |
|
||||
| **Bulkhead**: a semaphore with `MaxParallelJobs` slots and a short wait; when full the answer is `busy` (429) | SEC-01, S-01 | `MediaProcessingGate` | Protects the host's CPU and memory on the Pi. |
|
||||
| **Atomic publish of a set**: write to a temp directory, then one rename into place; clean the temp on failure (`try/finally`) | R-02, BR-M03 | `FileSystemMediaStore.PutSetAsync` | Nothing half-written is ever addressable. |
|
||||
| **Content-addressed, immutable addresses** | P-05, FR-14 | `MediaPaths` | The set hash contains the original's SHA-256 and the crop parameters; a change gives a new address; long immutable caching is safe. |
|
||||
| **Retire, then delete** (grace of 7 days) | R-04, BR-I08 | `HeroMediaCleanupService` (hosted, daily) | Sets are stamped when they stop being referenced; deleted later; idempotent; never deletes a referenced key (checked against the database right before deleting). |
|
||||
| **Single read model** | NFR-09, BR-P04 | `PublicHeroService` | The endpoint, the region, the preload and the data block cannot disagree. |
|
||||
| **One renderer for picture and preload** | P-01, BR-J01 | `HeroPictureRenderer` | Same inputs and the same formatting functions produce `srcset`, `sizes`, `media`; golden-tested. |
|
||||
| **Fail-open injection, fail-closed upload** | R-01, R-02 | transforms catch and log; upload throws typed rejections | Documented deliberate asymmetry (SECURITY-15). |
|
||||
| **Composable data block** | C-01 | `CmsDataBlockTransform` + contributors | Output of Offerings unchanged; contributors ordered by `Order`; a throwing contributor leaves the block baked. |
|
||||
| **Self-test and capability reporting** | R-03, C-02 | `ImageProcessorSelfTest` hosted service; `GET /api/v1/System/capabilities` lists the accepted input formats | A failed self-test disables uploads only. |
|
||||
| **Start-up directory check** | R-03, BR-M04 | `MediaDirectoryCheck` hosted service | Creates the directory when missing (when permitted), writes and deletes a probe file; logs the result; a failed check disables uploads. |
|
||||
| **Output encoding at the edge** | SEC-03, BR-H08 | `HeroPictureRenderer` and the data contributor | Text stored as typed, encoded when written; the JSON for the script element uses the existing `HtmlMarkerEditor.EscapeForScript`. |
|
||||
| **Allow-listed addresses** | SEC-03, BR-M01 | `MediaPaths.TryParse` and the endpoint's area registry | Anything else is a 404. |
|
||||
| **Audit trail** | SEC-05 | `HeroService`, `HeroImageService` | Log line per change with actor, entity and id (no content), plus `UpdatedBy`/`CreatedBy` columns. |
|
||||
| **Rate-limit policies** | SEC-07 | `ServiceCollectionExtensions` of the module and Core | `hero-public` 120/60 s per client address, `media-public` 600/60 s, `hero-upload` 20 per hour per user. |
|
||||
|
||||
## Logical components added by this stage
|
||||
|
||||
| Component | Role |
|
||||
|---|---|
|
||||
| `MagickImageProcessor` | The `IImageProcessor` implementation (sets limits, decodes, crops, resizes, strips, encodes) |
|
||||
| `MediaProcessingGate` | The bulkhead |
|
||||
| `ImageProcessorSelfTest` | Hosted self-test and capability list |
|
||||
| `MediaDirectoryCheck` | Hosted start-up check of the directory |
|
||||
| `HeroMediaCleanupService` | Daily clean-up of retired files |
|
||||
| `MediaAreaRegistry` | The allow-list of media areas and their path patterns (`hero`) |
|
||||
|
||||
## Security compliance summary (this stage)
|
||||
|
||||
| Rule | Status | Evidence |
|
||||
|---|---|---|
|
||||
| SECURITY-03 | Compliant (design) | structured logs with request id and actor, no contents or client names |
|
||||
| SECURITY-04 | Compliant | `nosniff` on media; existing headers on pages |
|
||||
| SECURITY-05 | Compliant | validation of every field, signature allow-list, target allow-list, encoding |
|
||||
| SECURITY-08 | Compliant | `AdminOnly`, object checks, public endpoints expose published data only |
|
||||
| SECURITY-09 | Compliant | generic errors, no listing, media outside the web root |
|
||||
| SECURITY-10 | Compliant | pinned package, vulnerability scan covers it |
|
||||
| SECURITY-11 | Compliant | rate limits, gate, abuse cases listed in the tests |
|
||||
| SECURITY-13 | Compliant | audit logs and columns; no unsafe deserialization (typed JSON only) |
|
||||
| SECURITY-15 | Compliant | explicit error handling, global handler, deliberate fail-open and fail-closed split |
|
||||
| SECURITY-01, 02, 06, 07, 12, 14 | N/A | no new infrastructure or authentication |
|
||||
@@ -0,0 +1,68 @@
|
||||
# NFR Requirements: hero-module (units H1, H3, H4; applies to H2 and H5 where noted)
|
||||
|
||||
Derived from `requirements.md` section 5, the security extension (blocking), the functional design and the library proof. Bryan approved the library, the defaults and the safety approach on 2026-11-16.
|
||||
|
||||
## Performance
|
||||
|
||||
| ID | Requirement | Measure |
|
||||
|---|---|---|
|
||||
| P-01 | **LCP**: the LCP element is in the first HTML and does not regress against the baked version: ASF the first slide `<picture>` with `fetchpriority="high"`, `width`/`height`, and the matching preload; SLS the title text. | Lighthouse (lab) on the test hosts before and after, mobile profile: LCP not worse than the baked page; no layout shift from the hero (CLS contribution 0). |
|
||||
| P-02 | **Weight**: the first slide image sent to a phone is the `tall` variant; target at most 80 KB WebP at 960 wide for a photo like the ASF ones (measured 37 to 64 KB), at most 250 KB for the largest desktop variant. | Recorded in the build and test summary. |
|
||||
| P-03 | **Processing time**: an upload of a 10 MB photo is processed (all sets) within 10 seconds on the Pi and 5 seconds on a workstation; the request does not time out. | Timed in the integration test and on the test host. |
|
||||
| P-04 | **Page build**: the hero adds at most 5 ms (cached) to building an injected page; the 60-second cache and ETag/304 behaviour stay as for the other parts. | Unit and integration tests. |
|
||||
| P-05 | **Media serving**: a media file answers from disk with a strong ETag and 304; no processing on the request path. | Integration test. |
|
||||
|
||||
## Scalability and capacity
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| S-01 | Expected size: one hero per site, tens of slides at most, a few uploads per day; the design must stay correct under concurrent uploads (processing gate) but is not built for throughput. |
|
||||
| S-02 | Disk: the media directory is limited by `Media:MaxTotalBytes` (2 GB default); uploads refused with a generic message above it; free space checked before writing. |
|
||||
| S-03 | The data block and the hero JSON are bounded by `Hero:MaxPublishedSlides` (50): the first HTML does not grow without bound. |
|
||||
|
||||
## Reliability and availability
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| R-01 | Page injection is fail-open per part; a failing media directory, library or database read never takes a page down. |
|
||||
| R-02 | Uploads fail closed with a stable code and a generic message; nothing partial is visible (atomic set writes); a crash during processing leaves no referenced half-set. |
|
||||
| R-03 | Start-up self-test of the image library and a writability check of the media directory; when they fail, uploads answer 503 and a clear error is logged; public reads continue. |
|
||||
| R-04 | Orphan clean-up never deletes referenced files and tolerates being interrupted (idempotent, daily). |
|
||||
| R-05 | A restart or deploy keeps all images (directory outside the release) and the metadata (database). |
|
||||
|
||||
## Security (blocking, extension enabled)
|
||||
|
||||
| ID | Requirement | Rule |
|
||||
|---|---|---|
|
||||
| SEC-01 | Upload hardening: size limit at framework level, signature allow-list, library decode with explicit format and resource limits (pixels, side length, memory, time), parallelism gate, per-user rate limit, no client file names in paths, no SVG. | SECURITY-05, 11 |
|
||||
| SEC-02 | Management endpoints require `AdminOnly` server side; object ids are verified against the hero; the public endpoints expose only published data. | SECURITY-08 |
|
||||
| SEC-03 | Output encoding: all text encoded for HTML and for JSON in script; the button target allow-list prevents `javascript:` and other schemes; the media endpoint only serves registered path patterns; `X-Content-Type-Options: nosniff`. | SECURITY-04, 05 |
|
||||
| SEC-04 | Generic error responses; no stack traces or paths; the global handler stays. | SECURITY-09, 15 |
|
||||
| SEC-05 | Logging with request id and actor, no file contents and no client file names; changes auditable (who, what, when). | SECURITY-03, 13 |
|
||||
| SEC-06 | Dependencies pinned and scanned: `Magick.NET-Q8-AnyCPU` 15.1.0 (Apache-2.0) is added to the vulnerability scan; the package is kept current; no unused packages. | SECURITY-10 |
|
||||
| SEC-07 | Rate limiting on `hero-public`, `media-public` and `hero-upload`; abuse cases covered by tests (oversized, decompression bomb, polyglot, path tricks, repeated uploads). | SECURITY-11 |
|
||||
| SEC-08 | Media directory permissions: only the host's service account writes; no directory listing; files are never executed (no handler mapping in IIS for the media directory when it lives under a web root; it lives outside the web root). | SECURITY-09 |
|
||||
|
||||
## Maintainability and testability
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| M-01 | The image library only behind `IImageProcessor`; the store only behind `IMediaStore`; both replaceable. |
|
||||
| M-02 | Pure functions (`FocusMath`, `VariantPlanner`, `MediaPaths`, `ButtonTargetValidator`, `HeroPictureRenderer`) property-tested (extension partial): crop inside the image; widths monotonic and never above the source; the set hash changes iff the crop parameters change; targets accepted are of the three forms; encoded text round-trips; the first slide and the preload attributes equal the picture attributes. |
|
||||
| M-03 | Golden files for the region and the preload (ASF), for the data block and for the Offerings output stay byte-exact. |
|
||||
| M-04 | Image fixtures for each input format, including corrupt, truncated, oversized and polyglot files; a real HEIC photo is added when one can be obtained (HEIC is a declared capability only until then, per Bryan). |
|
||||
| M-05 | Texts per `docs/translation-files.md`; OpenAPI snapshot regenerated. |
|
||||
|
||||
## Usability and accessibility
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| U-01 | Admin: keyboard operation of reorder and focus point, labels, live regions, a clear badge; the server messages in Dutch. |
|
||||
| U-02 | Sites: alt text required (or decorative), slider accessibility kept in the site (contract). |
|
||||
|
||||
## Compatibility
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| C-01 | The existing public contracts and markers do not change; the Offerings data block output is byte-identical. |
|
||||
| C-02 | Platforms: win-x64 self-contained (IIS), linux-x64 (CI), linux-arm64 (Pi); proven on the first two, confirmed on the Pi at the first test deploy by the start-up self-test. |
|
||||
@@ -0,0 +1,19 @@
|
||||
# Tech stack decisions: hero-module
|
||||
|
||||
| # | Decision | Rationale | Alternatives and why not |
|
||||
|---|---|---|---|
|
||||
| T1 | **Magick.NET-Q8-AnyCPU 15.1.0** (Apache-2.0) behind `IImageProcessor` | Widest formats (JPEG, PNG, GIF, BMP, TIFF, WebP, AVIF read and write; HEIC/HEIF read as a declared capability), WebP and AVIF output, 128 MB peak for 24 MP, resource limits; proven on win-x64 and linux-x64 (library-proof.md) | NetVips (reserve; no BMP, LGPL natives); ImageSharp 4 (paid licence key needed to build); SkiaSharp (no TIFF or AVIF) |
|
||||
| T2 | Q8 build (8 bit per channel) | Enough for web output, half the memory of Q16 | Q16 |
|
||||
| T3 | `IMediaStore` with a **file-system store** in a directory outside the release (`Media:Directory`) | Bryan's decision; database store possible later behind the interface | Database blobs (rejected by Bryan; `max_allowed_packet` risk) |
|
||||
| T4 | New module project `SlpModularCms.Modules.Hero` + test project; `Core.Media` in the existing Core project | Follows the existing module layout and the decision for a general media service | A separate Media assembly (not needed yet) |
|
||||
| T5 | EF Core with the existing MySQL provider and hand-written migration, `NonLockingMySQLHistoryRepository` | Same as Offerings | n/a |
|
||||
| T6 | Frontend: existing React, React Query, i18n; focus editor an own component; `focusMath` TypeScript twin | Bryan's choice (no cropping package) | react-easy-crop |
|
||||
| T7 | Property-based tests: **FsCheck** (xUnit integration) for the pure functions in C#; **fast-check** if already present in the frontend, otherwise example vectors shared between C# and TypeScript | Extension partial; check the existing test dependencies in H1 and add only what is missing | Hand-written random loops |
|
||||
| T8 | Start-up self-test as a hosted service; clean-up as a hosted `BackgroundService` (daily) | Same pattern as `ContactRetentionService` | A cron outside the host |
|
||||
| T9 | Rate limiting through the existing ASP.NET Core rate limiter policies (`hero-public`, `media-public`, `hero-upload`) | Existing mechanism | n/a |
|
||||
|
||||
## Package and publish notes
|
||||
|
||||
- `Magick.NET-Q8-AnyCPU` carries natives for several platforms; the self-contained win-x64 publish must keep only the matching native (to be verified in a publish test in H1) and the Linux publish must include `Magick.Native-Q8-x64.dll.so` or `-arm64`.
|
||||
- The CI vulnerability scan covers the new package automatically (transitive and direct).
|
||||
- The package size (about 35 MB per platform native) is acceptable for the release artifacts; checked against the SCP upload limit (see `deployment-instructions.md` 1.7.3) in Infrastructure Design.
|
||||
Reference in New Issue
Block a user