177 lines
8.7 KiB
Markdown
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.
|