Mediabibliotheek fase A: gebruikscontract, opruimselectie en selectiecomponent #21
@@ -25,4 +25,4 @@
|
||||
| Feature | [Vertaalbestanden backend (translation-files)](../docs/translation-files.md) | ✅ Afgesloten 2026-11-16 (stappen 1-8, docs; buiten AI-DLC gebouwd; goedgekeurd door Bryan via SLS-Main; productie via de checklist) | feature/contact-forms-module | Core (Texts, Email, Identity, Hosting), Modules.Availability, Modules.Offerings | 2026-11-15 |
|
||||
| Bug | [theme-toggle-first-click](bugs/theme-toggle-first-click/bug-fix.md) | ✅ Complete (niet gecommit/gemerged; buiten AI-DLC gebouwd; oorzaak niet in een echte browser nagebootst) | feature/contact-forms-module | Frontend (useTheme, index.html) | 2026-11-15 |
|
||||
| Feature | [Hero module (hero-module)](features/hero-module/aidlc-state.md) | ✅ Afgesloten 2026-11-17 (Build and Test gesloten, Operations in de gezamenlijke productie-checklist 4b; op test door Bryan geaccepteerd; merge naar master via SLS-Main, productie wacht op Bryans go) | feature/hero-module | Modules (new Hero), Core (Hosting/Website, host injection), CI (release/-regel voor SLS-productie), Frontend (admin) | 2026-11-16 |
|
||||
| Feature | [Mediabibliotheek (media-library)](features/media-library/overview.md) | ⚪ Gepland (volgt na de Hero-merge; nog geen AI-DLC-stappen) | n.v.t. | Core (Media), Modules.Hero, later gallerij-module, Frontend (admin) | 2026-11-17 |
|
||||
| Feature | [Mediabibliotheek (media-library)](features/media-library/overview.md) | 🟡 Inception: requirements en ontwerp als concept op aannames (2026-11-17; Bryan controleert later; niets gebouwd dat data verhuist) | feature/media-library | Core (Media), Modules.Hero, later gallerij-module, Frontend (admin) | 2026-11-17 |
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# AI-DLC State Tracking
|
||||
|
||||
## Project Information
|
||||
- **Feature Name**: Media library (one place to manage, keep and reuse photos for all modules)
|
||||
- **Feature Slug**: media-library
|
||||
- **Project Type**: Brownfield
|
||||
- **Start Date**: 2026-11-17
|
||||
- **Current Stage**: INCEPTION - Requirements Analysis and Application Design drafted on assumptions (awaiting Bryan's later check); nothing that moves data is built
|
||||
- **Branch**: feature/media-library (from origin/master e0b3782)
|
||||
|
||||
## Workspace State
|
||||
- **Existing Code**: Yes (Core/Media, Modules.Hero)
|
||||
- **Reverse Engineering Needed**: No (artifacts in `_shared/reverse-engineering/`; targeted read of Core/Media and Modules.Hero)
|
||||
- **Workspace Root**: K:\Development\Projects\SlpModularCms
|
||||
|
||||
## Language Configuration
|
||||
- **Documentation Language**: English
|
||||
- **Conversation Language**: User Language (Dutch)
|
||||
- **Note**: Inherited from the other features. `overview.md` stays Dutch (written by SLS-Main for Bryan).
|
||||
|
||||
## Source Of Truth / Coordination
|
||||
- Requirements 1 to 7 of Bryan are in `overview.md` (2026-11-17). Bryan is away: no questions to him; every open question has a most probable assumption in `assumptions-and-open-questions.md`; Bryan checks them later.
|
||||
- Allowed now: requirements, design, and safe, reversible building. **Not allowed without prior alignment (via SLS-Main with Bryan)**: an EF migration that moves existing `HeroImages`, any change of public addresses (`/media/hero/<hash>/...`), set-hashes or golden files.
|
||||
- No merge to master, production deploy or production variables without go.
|
||||
|
||||
## Extension Configuration
|
||||
| Extension | Enabled | Decided At |
|
||||
|---|---|---|
|
||||
| Security Baseline | Yes (blocking), as for hero-module | Inherited (upload, delete and file serving are security relevant) |
|
||||
| Property-Based Testing | Partial (pure functions and round-trips) | Inherited |
|
||||
|
||||
## Operations Configuration
|
||||
- **Include Operations Phase**: No (points go into docs/release-checklist-productie.md when built)
|
||||
|
||||
## Stage Progress
|
||||
### INCEPTION PHASE
|
||||
- [x] Workspace Detection (Feature, brownfield)
|
||||
- [x] Reverse Engineering (skipped: targeted read)
|
||||
- [x] Requirements Analysis (inception/requirements/requirements.md; no questions file: assumptions instead)
|
||||
- [ ] User Stories - SKIP (one persona, acceptance criteria in the requirements)
|
||||
- [x] Workflow Planning (section 9 of requirements: phases A to D)
|
||||
- [x] Application Design (inception/application-design/application-design.md, draft)
|
||||
- [ ] Units Generation (after Bryan's check of the assumptions)
|
||||
### CONSTRUCTION PHASE
|
||||
- [ ] Not started. Phase A (safe, reversible) may start after the assumptions are acknowledged; phases B and C move data and need alignment first.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Assumptions and deferred questions: media-library
|
||||
|
||||
Kept while Bryan is away (2026-11-17): no questions to him, a most probable assumption per open question instead. Per item: the question, the assumption made, what changes if Bryan chooses differently, and where in code or design. To be put to Bryan by the SLS session; he checks and corrects later. Same form as the Hero list.
|
||||
|
||||
| # | Question | Assumption made | If Bryan chooses differently | Where |
|
||||
|---|---|---|---|---|
|
||||
| 1 | Which **uses** (places and ratios) exist? | Hero `wide` (3:2) and `tall` (2:3), ASF shoot-page **mosaic** tiles (a small fixed set of ratios per page, to be listed by the ASF session), **masonry** (natural ratio, no crop), **thumb** (library thumbnails, 1:1 or natural). A use is `(module, place, ratio set)`. | Other ratios only add rows to the use definitions; a free-form ratio per tile would need a ratio editor and more variants per photo. | Application design section 4 (`MediaUseDefinition`) |
|
||||
| 2 | **Several formats/variants per photo**: who decides the set? | The **use** decides the ratios and widths (as `VariantPlanner` does for Hero); the library never cuts a fixed set per photo. Formats stay WebP and AVIF as today. | A fixed set per photo costs more disk and CPU on the Pi and cuts variants nobody uses. | `VariantPlanner`, application design section 4 |
|
||||
| 3 | The **7-day automatic clean-up** of unattached Hero images until the library is built. | Switch it off behind a setting (`Media:AutoCleanupUnattached`, default `true` until the library screen exists, then default `false`), so nothing is lost silently once the library can show and delete photos. Retired-file removal (after a replaced set) stays: that is housekeeping of generated files, not a person's photos. | Keep it on until phase C; or switch off now (risk: unused uploads pile up with no screen to remove them). | `HeroMediaCleanup`, `MediaOptions` |
|
||||
| 4 | **Rights per module**: who may see, use and delete which photos? | One shared library for Owner and Administrator (like Hero and Offerings). No per-module visibility yet. | Per-module visibility needs an owner field on a photo and a filter; the contract has room for it (`ModuleKey` on a use). | `[Authorize(Policy = "AdminOnly")]`, `MediaUse.Module` |
|
||||
| 5 | **Public addresses**: per module (`/media/<module>/...`) or a shared path? | Keep `/media/{area}/{setHash}/{name}`; `area` stays the module (`hero`; a gallery would use `gallery`). The set hash still comes from the original's hash plus the crops of that **use**. A photo used in two modules is two sets (two addresses), cached separately. | A shared path would change addresses and golden files: not allowed without alignment. | `MediaPaths`, `MediaEndpoint` |
|
||||
| 6 | **Usage register**: do modules report, or does the library keep it centrally? | Modules report: `IMediaUsageProvider` per module answers "where is this photo used" and "detach this photo" from the module's own data. Computed, never copied, so it cannot go stale. The library warns when a module has no provider. | A central register table keeps the answer fast but must be kept in step on every module save (risk of drift); can be added later as a cache. | Application design section 3, `IMediaUsageProvider` |
|
||||
| 7 | **What counts as "unused"** in the clean-up? | A photo is unused when **no provider** reports a use. A photo used only by an inactive or unpublished slide still counts as used (it is in a slide). | Treating an inactive slide as unused would delete photos a person may want to switch on again; stricter would be safer than looser. | `MediaUsageService` |
|
||||
| 8 | **Clean-up default period** and slider range. | Default 7 days, slider 1 to 365 days, step 1; "Only unused photos" on. The period is measured from the upload date. | Measured from last use, or another range: a one-line change in the filter. | Clean-up component, `CleanupSelection` |
|
||||
| 9 | **Storage limit and warning**. | Limit = existing `Media:MaxTotalBytes` (2 GB, decided by Bryan, Hero assumption 12). Warning at 80 percent (amber) and at 100 percent (red, uploads refused with a clear message). Used bytes = originals plus all variants, cached 60 s. | Another threshold or limit: configuration only. | `MediaOptions`, `MediaStorageUsage` |
|
||||
| 10 | **Delete of a photo that is in use**. | Not possible from Clean-up (those rows are not selectable); possible from the library after a second confirmation that names the uses; the module detaches it first (Hero: the slide loses its image and is unpublished until a new one is chosen, as today). | Block deleting in-use photos completely: the extra confirmation path is removed. | `IMediaUsageProvider.DetachAsync`, library screen |
|
||||
| 11 | **Shared upload service**: does Hero's upload move into the library? | In phase A Hero keeps its own upload endpoint; the library also lists those photos. In phase B both call one upload service in Core. | Moving Hero upload earlier gives a single path sooner but touches Hero before the data model exists. | `HeroImageService`, `MediaUploadGuard` |
|
||||
| 12 | **Trash delay** (deleted photos recoverable for a while)? | No trash in phase A: the confirmation naming the count is the safety. A 7-day trash can be added in phase B (a `DeletedAt` and the existing retired-file mechanism). | Trash from the start: reuse `HeroRetiredFile` logic generalised in Core; about 1 day extra. | `HeroRetiredFile`, application design section 5 |
|
||||
| 13 | **Migration of existing `HeroImages`** (phase C). | Expand then contract: new `MediaAsset` and `MediaUse` tables are filled from `HeroImages` and `HeroSlides` with the **same ids, hashes and set hashes**; Hero reads the library; old columns are dropped in a later release. Needs a back-up and alignment: **not built**. | A one-step move is smaller but cannot be rolled back; or no migration at all and the library keeps reading through Hero (the provider approach) until the gallery module needs own tables. | Requirements section 9, application design section 6 |
|
||||
| 14 | **Crop per use**: data per use or per photo? | A use owns its crop (focus x, y and zoom per ratio); the photo owns the default focus new uses start from. The set hash of a use is `SetHash(originalSha256, crops of that use)` exactly as today, so existing Hero addresses are unchanged. | Crop per photo only (today's model) cannot serve a mosaic with several tiles of the same photo. | `MediaPaths.SetHash`, `MediaUse` |
|
||||
| 15 | **Selection range** with shift-click and "select all": across pages or the loaded page? | The loaded list (the clean-up list is loaded fully, the library list incrementally; "select all" says how many are loaded and offers "select all N" for a filtered list). | Strictly the current page: simpler, less useful for a clean-up of hundreds. | Selection component |
|
||||
| 16 | **Deleting files from the store** when a photo is deleted. | The original and the set directories of that photo are deleted through `IMediaStore` after the database rows; a set shared with another use (same hash) is kept until no use references it. | Soft delete first (see 12). | `IMediaStore.DeleteSetAsync`, `HeroRepository.GetReferencedSetHashesAsync` |
|
||||
| 17 | **Language of the screen**: nl and en like the rest of the admin. | Yes, `media.*` keys in both files; terms: "Mediabibliotheek", "Opruimen", "Alleen ongebruikte foto's". | Dutch only: remove one file. | `frontend/src/i18n/locales` |
|
||||
@@ -0,0 +1,13 @@
|
||||
# Audit Log - media-library
|
||||
|
||||
## Workspace Detection (initial request)
|
||||
|
||||
**Timestamp**: 2026-11-17T00:00:00Z
|
||||
|
||||
**User Input**: Cross-session instruction from SLP Software - SLS - Main relaying Bryan: start AI-DLC for `media-library` per `aidlc-docs/features/media-library/overview.md` once Hero and the form controls are on master; Requirements Analysis without questions to Bryan, record the most probable assumption per open question; use the gallery needs (ASF shoot-page mosaic, masonry) and Hero as design sources; design allowed; do not build anything that moves data or touches public addresses/golden files without alignment via SLS-Main.
|
||||
|
||||
**AI Response**: Classified as Feature (new capability). Brownfield. Hero (#17) and admin-form-controls (#19) are on master (4c88ea8), messages-badge (#18) too (e0b3782). Branch `feature/media-library` created from origin/master. Wrote aidlc-state, requirements, assumptions and a draft application design.
|
||||
|
||||
**Context**: Requirements Analysis and Application Design drafted on assumptions. Bryan checks the assumptions later.
|
||||
|
||||
---
|
||||
@@ -0,0 +1,176 @@
|
||||
# Application design (draft on assumptions): media-library
|
||||
|
||||
Status: draft, built on `assumptions-and-open-questions.md`. Nothing here moves data or changes public addresses.
|
||||
|
||||
## 1. Components
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
UI[Admin: Media library screen] --> API[MediaLibraryController]
|
||||
UI --> SEL[Selection + BulkActionBar components]
|
||||
API --> LIB[MediaLibraryService]
|
||||
LIB --> USE[MediaUsageService]
|
||||
LIB --> STO[MediaStorageUsage]
|
||||
LIB --> STORE[IMediaStore]
|
||||
USE --> PH[Hero IMediaUsageProvider]
|
||||
USE --> PG[Gallery IMediaUsageProvider, later]
|
||||
PH --> HERO[(HeroImages / HeroSlides)]
|
||||
HOST[Public /media endpoint] --> STORE
|
||||
classDef ui fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef mod fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef data fill:#fbb6ce,stroke:#b83280,stroke-width:1px,color:#000;
|
||||
class UI,SEL ui;
|
||||
class API,LIB,USE,STO,STORE,HOST core;
|
||||
class PH,PG mod;
|
||||
class HERO data;
|
||||
```
|
||||
|
||||
Text alternative: the admin screen calls the library service in Core, which asks each module's usage provider where a photo is used and reads files and sizes through `IMediaStore`; the public media endpoint is unchanged.
|
||||
|
||||
| Component | Where | Responsibility |
|
||||
|---|---|---|
|
||||
| `IMediaUsageProvider` | Core (contract), implemented per module | `ListUsesAsync(photoKey[])`, `DetachAsync(photoKey)`, `ListPhotosAsync(paging)` (phase A read-through) |
|
||||
| `MediaUsageService` | Core | Fans out to all providers, merges uses, knows which modules have no provider |
|
||||
| `MediaLibraryService` | Core | Listing (newest first), delete orchestration, clean-up preview |
|
||||
| `MediaStorageUsage` | Core | Bytes of originals plus variants, cached 60 s, warning level |
|
||||
| `CleanupSelection` | Core, pure | Given photos, uses, now, days and the unused flag: the preselected set |
|
||||
| `MediaLibraryController` | Core or new module (see 7) | `GET /api/v1/media`, `GET /api/v1/media/storage`, `POST /api/v1/media/cleanup/preview`, `POST /api/v1/media/delete` |
|
||||
| Frontend `features/media` | frontend | Screen, `PhotoSelectionList`, `BulkActionBar`, `CleanupDialog`, `StorageMeter`, React Query hooks |
|
||||
|
||||
## 2. Data (target, phase B and later; phase A uses Hero data read-only)
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
MediaAsset ||--o{ MediaUse : "is used by"
|
||||
MediaAsset {
|
||||
guid Id
|
||||
string OriginalSha256
|
||||
string OriginalKey
|
||||
int Width
|
||||
int Height
|
||||
long Bytes
|
||||
double DefaultFocusX
|
||||
double DefaultFocusY
|
||||
double DefaultZoom
|
||||
datetime CreatedAt
|
||||
guid CreatedByUserId
|
||||
}
|
||||
MediaUse {
|
||||
guid Id
|
||||
guid AssetId
|
||||
string Module
|
||||
string Place
|
||||
string RatioSet
|
||||
double FocusX
|
||||
double FocusY
|
||||
double Zoom
|
||||
string SetHash
|
||||
}
|
||||
```
|
||||
|
||||
Text alternative: one photo (`MediaAsset`) has many uses (`MediaUse`); each use has its module, place, ratio set, its own crop and the set hash derived from the photo hash plus that crop.
|
||||
|
||||
- `SetHash` of a use is computed by the existing `MediaPaths.SetHash(OriginalSha256, crops)`; for a Hero slide this equals today's value (verified by a test in phase A against current golden data).
|
||||
- Variants stay files in the store (`/media/{area}/{setHash}/...`); no variants table is needed (the Hero `Variants` list is derived from the planner and the files).
|
||||
- A use is `Module` + `Place` (for Hero "slide 3", id of the slide), not a free text.
|
||||
|
||||
## 3. Usage contract
|
||||
|
||||
```csharp
|
||||
public interface IMediaUsageProvider
|
||||
{
|
||||
string Module { get; } // "hero"
|
||||
Task<IReadOnlyList<MediaUse>> ListUsesAsync(IReadOnlyCollection<Guid> photoIds, CancellationToken ct);
|
||||
Task<IReadOnlyList<MediaPhoto>> ListPhotosAsync(MediaPaging paging, CancellationToken ct); // phase A read-through
|
||||
Task DetachAsync(Guid photoId, CancellationToken ct); // before the library deletes the photo
|
||||
Task<bool> DeleteAsync(Guid photoId, CancellationToken ct); // phase A: the module deletes its own photo
|
||||
}
|
||||
```
|
||||
|
||||
A `MediaUse` carries `Module`, `PlaceLabel` (for display, translated by the module, for example "Hero, slide 3"), `PlaceId` and `Active`. In phase A the Hero provider implements all four members over `HeroImages` and `HeroSlides`; from phase B the library owns the photos and `ListPhotosAsync`/`DeleteAsync` fall away.
|
||||
|
||||
## 4. Uses and crops
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P[Photo + default focus] --> U1[Use: hero wide]
|
||||
P --> U2[Use: hero tall]
|
||||
P --> U3[Use: mosaic tile 4:5]
|
||||
P --> U4[Use: masonry natural]
|
||||
U1 --> S1[set hash A]
|
||||
U2 --> S1
|
||||
U3 --> S2[set hash B]
|
||||
U4 --> S3[set hash C]
|
||||
classDef p fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef u fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef s fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class P p;
|
||||
class U1,U2,U3,U4 u;
|
||||
class S1,S2,S3 s;
|
||||
```
|
||||
|
||||
Text alternative: one photo has uses in Hero (wide and tall share one set), a mosaic tile and a masonry gallery; each set has its own hash and address.
|
||||
|
||||
- `MediaUseDefinition` (code, per module): ratio names, ratio values and widths for the variant planner. Hero's `wide` and `tall` exist today; the mosaic's tile ratios and masonry's natural ratio are added by the gallery module.
|
||||
- A natural-ratio use stores no crop (focus ignored); the planner produces widths only.
|
||||
- The Hero sets are unchanged: one use per slide carrying the image's `wide` and `tall` crops, one set hash.
|
||||
|
||||
## 5. Delete and clean-up flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(246,224,94,0.4) Admin
|
||||
participant U as Person
|
||||
end
|
||||
box rgba(99,179,237,0.4) Core
|
||||
participant L as MediaLibraryService
|
||||
participant S as MediaUsageService
|
||||
end
|
||||
box rgba(154,230,180,0.4) Module
|
||||
participant P as Usage provider
|
||||
end
|
||||
U->>L: Clean-up preview (days, only unused)
|
||||
L->>S: Uses of all photos in the period
|
||||
S->>P: ListUsesAsync
|
||||
P-->>S: Uses
|
||||
L-->>U: Newest first, all selected, bytes to free
|
||||
U->>L: Confirm selected ids
|
||||
L->>S: Re-check uses
|
||||
L->>P: DetachAsync / DeleteAsync
|
||||
L->>L: Delete files in the store
|
||||
L-->>U: Result per photo
|
||||
```
|
||||
|
||||
Text alternative: the person previews, the service re-checks usage at confirmation time (a photo used since the preview is skipped), the module detaches and deletes, the service removes files and reports per photo.
|
||||
|
||||
- The re-check at confirmation protects against a photo that became used after the preview.
|
||||
- Bulk delete is limited (100 photos per request), idempotent and reports per photo.
|
||||
|
||||
## 6. Migration outline (phase C, designed only)
|
||||
|
||||
1. Back-up the database and the media directory.
|
||||
2. Create `MediaAsset` and `MediaUse` (additive migration). No existing table changes.
|
||||
3. Copy: one asset per `HeroImage` with the **same id, hash, key and set hash**; one use per slide that references it. A verification query compares counts, ids and set hashes and aborts on any difference.
|
||||
4. Switch Hero reads to the library behind a setting; keep the old columns written for one release (expand), then drop them (contract).
|
||||
5. Rollback until step 4: delete the new tables (no consumer changed).
|
||||
|
||||
## 7. Module placement (assumed)
|
||||
|
||||
The model and services live in **Core** (`SlpModularCms.Core.Media`, next to the store) so Hero and the gallery module depend on Core only; the controller and the EF tables (phase B) go in a new module `SlpModularCms.Modules.Media` with its own `DbContext` and migrations, like the other modules, and a test project under `Tests/Modules`. Phase A needs no new tables, so the first controller can ship in the Hero-independent Core registration.
|
||||
|
||||
## 8. Frontend
|
||||
|
||||
- `PhotoSelectionList`: virtualised or incremental list of cards (thumbnail, name, size, date, usage chips), with the shared `Checkbox`, shift-click range, select all and clear, `aria-live` count.
|
||||
- `BulkActionBar`: sticky, shows the count and the actions; actions are data (`{id, label, destructive, run}`) so tags or move can be added.
|
||||
- `CleanupDialog`: slider (days), `CheckboxField` "Only unused photos" (default on), the same `PhotoSelectionList` preselected, summary of count and bytes, confirm.
|
||||
- `StorageMeter`: used, limit, warning colour plus text.
|
||||
- Sidebar entry "Mediabibliotheek" for Owner and Administrator.
|
||||
|
||||
## 9. Test strategy
|
||||
|
||||
- Pure: `CleanupSelection` (age, unused flag, ordering), range selection, set-hash per use equals the Hero value (property tests).
|
||||
- Service: delete re-check, partial failure, limit of 100, in-use rules, storage warning thresholds.
|
||||
- Hero provider: uses per slide, detach.
|
||||
- Regression: golden files and the host-injection tests unchanged; a set made before the library is still served.
|
||||
- Frontend: selection by mouse and keyboard, announcements, dialog flow, i18n nl and en.
|
||||
@@ -0,0 +1,105 @@
|
||||
# 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-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) | 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, 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 |
|
||||
| 7 Crop per use | ML-11, ML-12, design section 4 |
|
||||
| Boundary: addresses and set hashes | ML-14, NFR-ML-05 |
|
||||
@@ -1,6 +1,6 @@
|
||||
# Mediabibliotheek (media-library)
|
||||
|
||||
**Status:** Gepland, nog niet gestart. Er zijn bewust geen AI-DLC-stappen uitgevoerd. De Hero-module (feature `hero-module`) wordt eerst afgerond: acceptatie door Bryan op test, daarna de merge. Besluit van Bryan, 2026-11-17.
|
||||
**Status:** Gestart 2026-11-17 (Hero staat op master). Requirements Analysis en Application Design staan als concept op aannames in `inception/` en `assumptions-and-open-questions.md`; Bryan controleert die later. Er is niets gebouwd dat data verhuist of adressen wijzigt. Branch: `feature/media-library`.
|
||||
|
||||
**Doel:** een algemene Core-mediabibliotheek (niveau 3 uit de schatting) voor alle modules: Hero nu, later de gallerij-module. Foto's worden op één plek beheerd, bewaard en hergebruikt.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user