using System.Text.Json.Serialization;

namespace Elternbeirat.Contracts;

/// <summary>
///     A news post of the site, as stored in PocketBase.
/// </summary>
/// <remarks>
///     Post lists are ordered by <see cref="Date"/>, newest first.
/// </remarks>
public record Post
{
    /// <summary>
    ///     Gets the PocketBase record id.
    /// </summary>
    /// <remarks>
    ///     <see langword="required"/>: every stored record has an id. Modeling it as
    ///     required states which fields a record must carry, independent of the store,
    ///     so a future data source has to supply them too.
    /// </remarks>
    [JsonPropertyName("id")]
    public required string Id { get; init; }

    /// <summary>
    ///     Gets the publication date as a calendar day.
    /// </summary>
    /// <remarks>
    ///     A post's date is a plain day, not a point in time. It is read as the
    ///     Berlin calendar day: the UTC value is converted to Europe/Berlin and only
    ///     the day is kept, so the day an editor picked is the day shown -- no
    ///     time-of-day, no off-by-one at midnight. See <see cref="DateOnlyConverter"/>.
    /// </remarks>
    [JsonPropertyName("date")]
    [JsonConverter(typeof(DateOnlyConverter))]
    public DateOnly Date { get; init; }

    /// <summary>
    ///     Gets the heading shown to visitors.
    /// </summary>
    /// <remarks>
    ///     Free text; may contain umlauts and spaces. For the URL, see <see cref="Slug"/>.
    ///     <see langword="required"/>: a post without a heading is incomplete, and the
    ///     field is required in PocketBase.
    /// </remarks>
    [JsonPropertyName("title")]
    public required string Title { get; init; }

    /// <summary>
    ///     Gets the post body as Markdown.
    /// </summary>
    [JsonPropertyName("body")]
    public string Body { get; init; } = string.Empty;

    /// <summary>
    ///     Gets the URL slug of the post, e.g. <c>"herbstbasar"</c> for <c>/posts/herbstbasar</c>.
    /// </summary>
    /// <value>
    ///     A URL path segment: lowercase letters, digits and single hyphens as
    ///     separators, no umlauts. PocketBase enforces this on save via a field
    ///     pattern (<c>^[a-z0-9]+(-[a-z0-9]+)*$</c>), so every stored slug is already
    ///     canonical and the app can use it verbatim in comparisons and generated URLs.
    /// </value>
    /// <remarks>
    ///     <see langword="required"/>: the slug is how a post is addressed, so a record
    ///     without one is broken. It is a required field in PocketBase, so deserializing
    ///     one that lacks it should fail loudly rather than yield a post with no URL.
    /// </remarks>
    [JsonPropertyName("slug")]
    public required string Slug { get; init; }
}