Files

177 lines
8.7 KiB
Markdown

# 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.