mabibli/MaBibli.Shared/Catalogue/CritereLivres.cs

using MaBibli.Shared.Entites;

namespace MaBibli.Shared.Catalogue;

/// <summary>
/// Critères de consultation du catalogue.
/// </summary>
/// <remarks>
/// <b>Il n'existe volontairement aucun critère sur <c>AjoutePar</c>.</b> La bibliothèque est
/// commune à tout le foyer : filtrer les lectures sur ce champ serait un bug de conception.
/// L'absence de ce critère est l'endroit où l'invariant est le plus visible.
/// <para>
/// <see cref="Statut"/> n'est pas une exception : il filtre sur le statut de <b>l'appelant</b>,
/// que le serveur connaît par les en-têtes SSOwat. Le client ne désigne jamais de qui il parle.
/// </para>
/// </remarks>
public record CritereLivres
{
    /// <summary>
    /// Texte cherché dans le titre <i>ou</i> les auteurs. Insensible à la casse
    /// <b>et aux accents</b> : « emile » trouve « Émile ».
    /// </summary>
    public string? Recherche { get; init; }

    /// <summary>Physique ou numérique. <c>null</c> = les deux : le catalogue est unique.</summary>
    public Format? Format { get; init; }

    /// <summary>
    /// Roman, bande dessinée… <c>null</c> = tous.
    /// </summary>
    /// <remarks>
    /// <c>TypeDocument.NonPrecise</c> <b>est</b> une valeur filtrable : « ce que je n'ai pas
    /// encore rangé » est justement la question qu'on se pose après avoir introduit ce champ.
    /// C'est ce qui la distingue du statut de lecture, dont l'absence n'est pas une valeur.
    /// </remarks>
    public TypeDocument? TypeDocument { get; init; }

    /// <summary>
    /// Statut de lecture de l'utilisateur courant. <c>null</c> = tous.
    /// </summary>
    /// <remarks>
    /// Un livre sans statut pour cette personne ne remonte sous <b>aucune</b> valeur : « non
    /// commencé » n'est pas un statut, c'est l'absence de statut. Il reste visible sans filtre.
    /// </remarks>
    public Statut? Statut { get; init; }

    /// <summary>Ne garder que les livres d'un auteur — le « cliquer sur un auteur » d'CLAUDE.md.</summary>
    public int? AuteurId { get; init; }

    /// <summary>
    /// <c>true</c> = ce qui est dehors, <c>false</c> = ce qui est à la maison, <c>null</c> = tout.
    /// </summary>
    /// <remarks>
    /// ⚠️ Contrairement à <see cref="Statut"/>, ce critère est <b>commun au foyer</b> : un prêt
    /// n'appartient à personne en particulier, et aucune identité n'entre dans son évaluation.
    /// C'est la même dissymétrie que partout ailleurs — le livre absent l'est pour tout le monde,
    /// sa lecture ne l'est que pour soi.
    /// <para>
    /// L'écran « Prêts » répond déjà à « qu'est-ce qui est dehors ? ». Ce critère-ci répond à
    /// l'autre moitié de la question, celle qu'aucun écran ne servait : « qu'est-ce que j'ai
    /// réellement sous la main ? », par exemple avant de promettre un livre à quelqu'un.
    /// </para>
    /// </remarks>
    public bool? Prete { get; init; }

    /// <summary>
    /// <c>true</c> = seulement les livres sans couverture, <c>false</c> = seulement ceux qui en
    /// ont une, <c>null</c> = tous.
    /// </summary>
    /// <remarks>
    /// Répond à « quels livres me reste-t-il à illustrer ? ». Comme <see cref="Prete"/>, le
    /// critère est <b>commun au foyer</b> : une couverture décrit l'ouvrage, pas la relation
    /// d'un lecteur à lui.
    /// <para>
    /// ⚠️ <b>« Sans couverture » veut dire « sans URL enregistrée », et rien d'autre.</b> Ce
    /// critère ne dit pas si l'image se charge : le savoir demanderait d'interroger chaque URL,
    /// ce que <c>CLAUDE.md</c> interdit — OpenLibrary rend des 502 intermittents, et le même
    /// livre entrerait et sortirait du filtre d'un rafraîchissement à l'autre. Une couverture
    /// cassée reste donc « avec couverture » ici, et c'est volontaire.
    /// </para>
    /// <para>
    /// Une URL <b>vide</b> compte comme absente : les deux implémentations du filtre doivent
    /// s'accorder là-dessus, un test les y confronte.
    /// </para>
    /// </remarks>
    public bool? SansCouverture { get; init; }
}