Continuous Integration / config-sls (pull_request) Successful in 9s
Continuous Integration / config-asf (pull_request) Successful in 5s
Continuous Integration / changes (pull_request) Canceled after 2m2s
Continuous Integration / backend-build (pull_request) Canceled after 0s
Continuous Integration / compile-sites (pull_request) Canceled after 0s
Continuous Integration / backend-test (pull_request) Canceled after 0s
Continuous Integration / vulnerability-scan (pull_request) Canceled after 0s
Continuous Integration / frontend-prepare (pull_request) Canceled after 0s
Continuous Integration / frontend-build (pull_request) Canceled after 0s
Continuous Integration / frontend-test (pull_request) Canceled after 0s
Continuous Integration / frontend-lint (pull_request) Canceled after 0s
Continuous Integration / publish-sls-test (pull_request) Canceled after 0s
Continuous Integration / publish-sls-production (pull_request) Canceled after 0s
Continuous Integration / deploy-sls-test (pull_request) Canceled after 0s
Continuous Integration / deploy-sls-production (pull_request) Canceled after 0s
Continuous Integration / publish-asf-test (pull_request) Canceled after 0s
Continuous Integration / deploy-asf-test (pull_request) Canceled after 0s
Continuous Integration / smoke-sls-test (pull_request) Canceled after 0s
Continuous Integration / smoke-asf-test (pull_request) Canceled after 0s
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
108 lines
13 KiB
Markdown
108 lines
13 KiB
Markdown
# Requirements: Media library (media-library)
|
|
|
|
- **Feature slug**: media-library
|
|
- **Status**: Draft on assumptions (Bryan is away; he checks `assumptions-and-open-questions.md` later and corrects where needed)
|
|
- **Depth**: Standard (comprehensive for deletion, file serving and the data migration, which are security and data-loss relevant)
|
|
- **Documentation Language**: English; **Conversation Language**: Dutch
|
|
- **Inputs**: `overview.md` (Bryan's requirements 1 to 7, 2026-11-17), the Hero module as built (`Core/Media`, `Modules.Hero`), `docs/hero-module.md`, the gallery needs of ASF (shoot-page mosaic, masonry) as relayed by SLS-Main.
|
|
|
|
## 1. Intent analysis
|
|
|
|
| Item | Value |
|
|
|---|---|
|
|
| User request | One place in the CMS where photos are managed, kept and reused by all modules; nothing is removed automatically; a clean-up tool and bulk actions in the admin |
|
|
| Request type | New capability (Core abstraction plus a new admin area), later used by a gallery module |
|
|
| Scope | Core (media model and usage register), `Modules.Hero` (becomes a first user), new admin screen, later a gallery module |
|
|
| Complexity | Complex: abstraction at the right level, address stability, data migration of existing `HeroImages` |
|
|
| Reverse engineering | Targeted read only: `Core/Media` (store, paths, variants, focus), `Modules.Hero` (entity `HeroImage`, `HeroMediaCleanup`, render service) |
|
|
|
|
## 2. What exists today (facts the design builds on)
|
|
|
|
- `IMediaStore` stores originals and variant sets on disk (`Media__Directory`); public address `/media/{area}/{setHash}/{ratio}-{width}.{ext}` (`MediaPaths`, strict allow-list). `area` is a module name (`hero`).
|
|
- The **set hash** is 16 hex characters of SHA-256 over the original's hash and the crops (ratio name plus canonical focus), so a changed focus gives a new address and files are cached for a long time.
|
|
- `HeroImage` holds the original (hash, key, size), one general focus and an optional focus per ratio (`wide`, `tall`), the current set hash and its variants. A slide references an image. Uploading the same photo twice gives one image (same hash).
|
|
- A background renderer (`HeroRenderService`) cuts variants; an image without a complete set is not published.
|
|
- `HeroMediaCleanup` retires uploaded-but-unused images after `Media:RetentionDays` (7) and removes retired files after the same period. This is the automatic clean-up Bryan wants to stop.
|
|
|
|
## 3. Principles (from Bryan, 2026-11-17)
|
|
|
|
1. **Keep everything.** An upload stays until a person deletes it.
|
|
2. **A person decides what goes**: through "Clean up" (a guided, previewed bulk delete) or through bulk actions in the library.
|
|
3. **Crop per use, not per photo.** A photo has a default focus; every use (module and place) can carry its own crop. A photo in a masonry gallery needs no crop.
|
|
4. **Addresses stay stable.** `/media/hero/<hash>/...` and the set hashes do not change; ASF, SLS and the golden files keep working.
|
|
|
|
## 4. Functional requirements
|
|
|
|
| ID | Requirement | Acceptance criteria |
|
|
|---|---|---|
|
|
| ML-01 | **Library overview.** An admin screen lists all photos of all modules, newest first, with a thumbnail, file name, size, upload date and a usage indicator. | Order is `CreatedAt` descending; paging or incremental loading beyond 100 photos; an empty state; keyboard and screen-reader usable. |
|
|
| ML-02 | **Usage indicator.** Per photo: "in use" or "not used", and where (module and place, for example "Hero, slide 3"). | Several uses are all listed; the indicator is computed from the modules' own data, not guessed; a photo used nowhere shows "Not used". |
|
|
| ML-03 | **Keep everything.** No automatic removal of any photo or its files. | The Hero step that retires unattached images is switched off once the library owns the retention (see section 8, phase A: behind a setting, default decided in the assumptions); a test proves nothing is removed without a person's action. |
|
|
| ML-04 | **Selection component** (own reusable component): checkboxes per photo, select all and clear, a range with shift-click, keyboard operation, a visible count, and a live-region announcement of the count. | Works for mouse, keyboard and screen reader; reused by the library and the clean-up; uses the shared `Checkbox` of the theme. |
|
|
| ML-05 | **Bulk actions** on the selection, in the library itself. First action: **Delete**. The action bar is a separate component so more actions (tags, move) can be added without touching the list. | Delete asks for confirmation naming the number of photos and how many are in use; a failure of one photo does not stop the others and is reported per photo. |
|
|
| ML-06 | **Delete rules.** A photo that is in use is not deleted unless the person explicitly confirms and the use is detached first. | Default: in-use photos are not selectable for delete in "Clean up" and are marked in the library; deleting an in-use photo from the library shows what will lose its image and requires a second confirmation; the host falls back as it does today for a slide without a set. |
|
|
| ML-07 | **"Clean up" button.** Opens the overview of photos that would be cleaned: default everything older than 7 days, with a slider to look more or fewer days back, and a checkbox **Only unused photos**, default on (off = all photos in the period). | The list is newest first; all rows start selected; the person can deselect before confirming; confirming deletes exactly the selected rows; the summary shows the number and the bytes that will be freed. |
|
|
| ML-08 | **Clean-up is the same component as the library** (ML-04, ML-05) in a preselected view, not a second implementation. | One list/selection component, two entry points. |
|
|
| ML-09 | **Storage usage and limit warning.** The screen shows the used space (originals plus variants), the configured limit, and a warning at a threshold and at the limit. | Used bytes are computed from the store and cached for a short time; the warning level is configurable (assumption: 80 percent); at the limit, uploads give a clear message instead of a failure; the existing `Media:MaxTotalBytes` (2 GB) is the limit. |
|
|
| ML-10 | **Upload into the library** (single and multiple), with the same limits and checks as Hero today (type signature, size, megapixels, rate limit). | The Hero upload path and the library share one upload service; the same file is one photo (hash). |
|
|
| ML-11 | **Crop per use.** A use (module, place, ratio) can have its own focus and zoom, defaulting to the photo's default focus. Changing a use's crop never affects other uses. | A use owns its crop; the set hash of a use is derived exactly as today from the original's hash plus that use's crops, so addresses stay as they are. |
|
|
| ML-12 | **Default focus per photo.** The photo carries the default focus that new uses start from. | Setting it does not change existing uses that have their own crop. |
|
|
| ML-13 | **Usage register for modules.** A module reports where it uses photos and can be asked to detach a photo. | Contract in the design (section 3 of the application design); Hero is the first provider; a module without a provider counts as "uses nothing" and the library shows a warning that its uses are unknown (so a photo is not silently deleted). |
|
|
| ML-14 | **Public addresses unchanged.** `/media/hero/<setHash>/<ratio>-<width>.<ext>` and every existing set hash stay valid. | Golden files and the host-injection tests stay green without edits; a regression test serves a set created before the library. |
|
|
| ML-15 | **Permissions.** Owner and Administrator may use the library (like Hero and Offerings). | `[Authorize(Policy = "AdminOnly")]`; rate limits on upload and bulk delete. |
|
|
| ML-17 | **Choose or upload, in every part that needs an image** (new requirement of Bryan, 2026-11-17). In every module that needs an image (Hero, later gallery, mosaic, masonry) the person can upload on the spot, also when the library holds no suitable image yet, and can choose from the existing library photos. An image uploaded on the spot is added to the library automatically and can be chosen everywhere afterwards. | One shared component "choose or upload" (a picker of the library photos plus an upload button) is reused by every module; it applies the same validation, limits and background processing as the Hero upload today; after an upload the new photo is chosen at once; the module keeps its own use (place, crop) of the chosen photo; a photo uploaded in one module is listed and choosable in the others. Until the library owns uploads (phase B) the Hero upload flow stays as it is. |
|
|
| ML-16 | **Audit.** Each deletion (single, bulk, clean-up) is logged with user, photo ids and count. | Structured log entry per action; no photo content in the log. |
|
|
|
|
## 5. Non-functional requirements
|
|
|
|
| ID | Requirement |
|
|
|---|---|
|
|
| NFR-ML-01 | **Data safety**: a delete is a two-step action (confirm, then act) and the originals can be kept behind a short "trash" delay (assumption 12). No data-moving migration runs without a recent back-up and prior alignment. |
|
|
| NFR-ML-02 | **Security** (Security Baseline): the same upload checks as Hero (content signature, size, pixel limit, rate limit), strict address allow-list, no path from user input, authorisation on every endpoint, bulk delete limited in size per request. |
|
|
| NFR-ML-03 | **Performance**: the overview loads the first page within 500 ms on the Raspberry Pi test host (thumbnails come from existing variants, never decoding originals in the request); storage usage is cached. |
|
|
| NFR-ML-04 | **Accessibility**: WCAG 2.2 AA; selection, range and bulk actions work by keyboard; counts are announced; no information by colour alone; forced-colors safe (shared Checkbox). |
|
|
| NFR-ML-05 | **Compatibility**: no change to the public address scheme, set-hash algorithm, `HeroImages` table or golden files in phase A. |
|
|
| NFR-ML-06 | **Testability**: selection state, clean-up selection (age and unused filter) and the set-hash derivation per use are pure functions with unit and property tests. |
|
|
| NFR-ML-07 | **Operability**: storage limit and warning level configurable (`Media__*`), documented in the release checklist when built. |
|
|
|
|
## 6. Design sources
|
|
|
|
- **Hero**: general focus plus `wide` and `tall` crops, background rendering, usage by slides, retention logic. It shows what a "use" is today (a slide with a ratio set) and what must keep working.
|
|
- **ASF gallery needs**: the shoot-page **mosaic** has several tile ratios per page (so crop per use and several ratios per photo), the **masonry** gallery shows a photo in its own ratio (no crop, only a variant set in the natural ratio). Both are served by "a use decides its ratio set", with a natural-ratio use as a first-class case.
|
|
- **Thumbnails** in the library are a use of the library itself (ratio `thumb`), cut once per photo.
|
|
|
|
## 7. Out of scope (for now)
|
|
|
|
- Tags, albums, search by content, moving photos between modules (the bulk action bar leaves room).
|
|
- Replacing a photo's file while keeping its uses (replace-in-place).
|
|
- Video or other media types.
|
|
- A CDN or database-backed store (`IMediaStore` already allows it; see Hero assumption 20).
|
|
|
|
## 8. Constraints and the migration question
|
|
|
|
- The existing `HeroImages` table and the Hero admin keep working unchanged in phase A. The library **reads through** the Hero data (a provider that lists `HeroImages` as photos and slides as uses) before any data moves.
|
|
- Moving existing photos into a Core table (phases B and C below) is a data migration that needs a back-up and prior alignment; it is designed here and **not built**.
|
|
- The automatic retirement of unattached Hero images (7 days) stays until the library can show and delete photos (phase A done); then it is switched off by setting, default per assumption 3.
|
|
|
|
## 9. Workflow plan (phases)
|
|
|
|
| Phase | Content | Moves data? | Build now? |
|
|
|---|---|---|---|
|
|
| A. Foundations (safe, reversible) | The shared `ImagePicker` component (pure, not wired), usage contract in Core (`IMediaUsageProvider`), Hero provider (read only), library read model over `HeroImages`, storage usage service, selection and bulk-action components (frontend), clean-up selection logic, library screen (list, usage, selection, bulk delete through the Hero service), Hero retention setting | No (delete uses existing Hero delete path) | After Bryan acknowledges the assumptions; pure and read-only parts can start earlier |
|
|
| B. Own tables | `MediaAsset` and `MediaUse` tables, upload into the library (one library record per upload, ML-17), default focus | New tables only | Needs alignment |
|
|
| C. Migration of Hero | Copy `HeroImages` into `MediaAsset` plus `MediaUse` (one use per slide), keep set hashes and addresses, switch Hero to the library, drop old columns later (expand then contract) | Yes | Needs alignment and a back-up |
|
|
| D. Gallery module | First other consumer (mosaic, masonry) | Own data | Separate feature |
|
|
|
|
## 10. Traceability to Bryan's requirements
|
|
|
|
| Bryan (overview.md) | Here |
|
|
|---|---|
|
|
| 1 Keep everything | ML-03, principle 1 |
|
|
| 2 Clean-up button, slider, only unused | ML-07 |
|
|
| 3 Overview newest first, usage indicator | ML-01, ML-02, ML-07 |
|
|
| 4 and 6 Bulk actions as own component | ML-04, ML-05, ML-08 |
|
|
| 5 Storage and limit warning | ML-09 |
|
|
| 8 (2026-11-17) Choose or upload in every part that needs an image | ML-17, design section 10 |
|
|
| 7 Crop per use | ML-11, ML-12, design section 4 |
|
|
| Boundary: addresses and set hashes | ML-14, NFR-ML-05 |
|