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:
@@ -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).
|
||||
Reference in New Issue
Block a user