Hero-module: Application Design (componenten, methoden, services, afhankelijkheden); antwoorden van Bryan verwerkt

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 14:44:37 +01:00
co-authored by Claude Sonnet 5.5
parent a1e740c558
commit 47fcaeb0a1
9 changed files with 458 additions and 22 deletions
@@ -0,0 +1,125 @@
# Component methods: hero-module
Signatures and purposes only; business rules are detailed in Functional Design per unit. Types are C# sketches.
## Core.Media
```csharp
public interface IMediaStore
{
Task PutAsync(string key, Stream content, string contentType, CancellationToken ct);
Task<MediaFile?> OpenReadAsync(string key, CancellationToken ct); // null = not found; MediaFile has Stream, ContentType, Length, LastWriteTime
Task<bool> ExistsAsync(string key, CancellationToken ct);
Task DeleteAsync(string key, CancellationToken ct);
Task DeletePrefixAsync(string prefix, CancellationToken ct); // removes every file below an area/hash directory
}
public interface IImageProcessor
{
// Real format, pixel size and frame count; throws ImageRejectedException (reason code) for anything unsafe or unsupported.
Task<ImageInfo> InspectAsync(Stream source, CancellationToken ct);
// Decode (orientation applied), crop around the focus for a ratio, resize without upscaling, strip metadata, encode.
Task<RenderedImage> RenderAsync(Stream source, RenderRequest request, CancellationToken ct);
IReadOnlySet<ImageFormat> SupportedInput { get; }
IReadOnlySet<ImageFormat> SupportedOutput { get; } // WebP always; AVIF when the platform can
}
public sealed record RenderRequest(Ratio Ratio, int Width, ImageFormat Format, int Quality, FocusSetting Focus);
public sealed record FocusSetting(double X, double Y, double Zoom); // 0..1, 0..1, >= 1; default (0.5, 0.5, 1)
public sealed record Ratio(string Name, int Numerator, int Denominator); // wide 3:2, tall 4:5
public interface IMediaUploadGuard
{
// Size, real format, pixel/memory bounds, timeout and parallel gate; returns ImageInfo or throws ImageRejectedException.
Task<GuardedUpload> AdmitAsync(Stream upload, long declaredLength, CancellationToken ct);
}
public static class FocusMath // pure, property-tested
{
public static CropRect CropFor(int imageWidth, int imageHeight, Ratio ratio, FocusSetting focus);
public static FocusSetting Normalize(FocusSetting focus); // clamps to valid ranges
}
public static class VariantPlanner // pure, property-tested
{
public static IReadOnlyList<VariantSpec> Plan(int sourceWidth, int sourceHeight, IReadOnlyList<RatioPlan> ratios, IReadOnlySet<ImageFormat> outputs);
}
public static class MediaPaths // pure
{
public static string SetHash(string originalSha256, IEnumerable<(string Ratio, FocusSetting Focus)> crops);
public static string Url(string area, string setHash, string name); // "/media/hero/<setHash>/wide-1600.webp"
public static bool TryParse(string path, out MediaAddress address); // strict allow-list of characters
}
```
`MediaEndpoint` is a minimal-API/endpoint mapping `GET|HEAD /media/{**path}`: parse, open from the store, answer with the immutable headers and `304` on a matching `If-None-Match`; any failure is a plain 404.
## Core.Hosting.Website
```csharp
public interface ICmsDataBlockContributor
{
string Key { get; } // "offerings", "banners", "hero"
int Order { get; } // 100 Offerings, 200 Hero: fixes the key order in the block
Task<object?> GetAsync(HtmlTransformContext context, CancellationToken ct); // null is written as JSON null
}
public sealed class CmsDataBlockTransform(IEnumerable<ICmsDataBlockContributor> contributors) : IHtmlPageTransform
{
public bool Wants(string html); // page contains <!--CMS:DATA-->
public Task<string> ApplyAsync(string html, HtmlTransformContext context, CancellationToken ct);
}
```
## Modules.Hero
```csharp
public interface IHeroService
{
Task<HeroAdminDto?> GetAsync(string language, CancellationToken ct); // management read incl. inactive
Task<HeroAdminDto> SaveAsync(HeroSaveRequest request, string actor, CancellationToken ct);
}
public interface IHeroImageService
{
Task<HeroImageDto> UploadAsync(Stream upload, long length, string actor, CancellationToken ct);
Task<HeroImageDto> SetFocusAsync(Guid imageId, HeroFocusRequest request, string actor, CancellationToken ct); // general + optional per ratio
Task DeleteAsync(Guid imageId, string actor, CancellationToken ct); // refuses while a slide uses it, or detaches (decided in Functional Design)
Task RemoveOrphansAsync(CancellationToken ct);
}
public interface IPublicHeroService
{
Task<PublicHeroDto?> GetActiveAsync(string language, DateTimeOffset now, CancellationToken ct); // null = 204
}
public static class ButtonTargetValidator
{
public static ButtonTargetResult Validate(string? target); // Anchor | Path | Https | Invalid(reason)
}
public static class HeroPictureRenderer
{
public static string RegionHtml(PublicHeroDto hero, ITextCatalog texts); // title, tagline, buttons, first slide <picture>
public static string PreloadHtml(PublicHeroDto hero); // one or two <link rel="preload" as="image"> elements
}
```
DTO shape (public, `GET /api/v1/hero` and `hero` in `#cms-data`):
```json
{ "display": "slideshow", "title": "…", "tagline": "…", "lead": null,
"buttons": [ { "label": "…", "target": "/over-mij" } ],
"slides": [ { "id": "guid", "alt": "…", "decorative": false,
"image": { "width": 1600, "height": 1067, "focus": { "x": 0.5, "y": 0.5, "zoom": 1 },
"src": "/media/hero/<set>/wide-1600.webp",
"variants": [ { "ratio": "wide", "width": 1600, "type": "image/webp", "url": "…" },
{ "ratio": "tall", "width": 960, "type": "image/webp", "url": "…" } ] } } ] }
```
## Frontend
`heroApi.getHero()`, `saveHero()`, `uploadImage(file, onProgress)`, `setFocus(imageId, …)`, `deleteImage(imageId)`; `focusMath.cropFor(...)` (TypeScript twin of `FocusMath`, same test vectors).