mathieu/mabibli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
ab878b4d3cb987aaf5b7fd1d7a232e1281a72bbf
mabibli/CLAUDE.md
T

31 KiB
Raw Blame History

CLAUDE.md — Contexte projet MaBibli

Ce fichier donne le contexte complet du projet à Claude Code. Lis-le en entier avant de commencer à coder.

Voir aussi IDEES.md : améliorations identifiées mais non encore actées. Rien n'y fait autorité — ce fichier-ci reste la référence.

Objectif du projet

Application self-hosted de gestion de bibliothèque personnelle, à héberger sur YunoHost, accessible depuis smartphone et PC.

Fonctionnalités attendues (v1)

  1. Catalogue de livres physiques — liste, ajout, édition, suppression
  2. Catalogue de livres numériques (ebooks) — même chose, avec un champ format distinct du physique
  3. Gestion de prêts
    • Prêter un livre à une personne (nom, date de prêt)
    • Marquer comme récupéré (date de retour)
    • Historique des prêts passés par livre (pas juste l'état courant)
  4. Récupération automatique des infos via ISBN
    • Scan caméra du code-barres (EAN-13 / ISBN)
    • Saisie manuelle de l'ISBN
    • Dans les deux cas : appel à une ou plusieurs API pour pré-remplir titre, auteur, éditeur, couverture
  5. Statuts de lecture — à lire / en cours / lu (au minimum), assignable à chaque livre

Décisions techniques actées

Sujet Décision Pourquoi
Langage backend C# / ASP.NET Core Choix de l'utilisateur, typage fort
Frontend Blazor WebAssembly Support PWA quasi natif (dotnet new blazorwasm --pwa), tout en C#, offline partiel
Base de données SQLite + Entity Framework Core Fichier unique, pas de serveur DB séparé, adapté à un usage perso/familial
Auth / multi-utilisateur SSO YunoHost via en-têtes SSOwat (YNH_USER) Pas de login custom. OIDC écarté : non documenté par YunoHost (vérifié le 2026-08-17). Voir « Intégration SSO »
Portée des données Collection commune à tous les utilisateurs, avec traçabilité de qui a ajouté chaque livre Usage familial : une bibliothèque de foyer, pas des collections étanches. Laisse la possibilité de cloisonner plus tard sans migration lourde
Statut de lecture Par utilisateur, pas commun (décidé le 2026-08-17, après la phase 3) Le livre est commun, sa lecture est personnelle : deux membres du foyer lisent le même exemplaire à des rythmes différents. Sort Statut de Livre vers une table dédiée
Auteurs Table dédiée avec nom normalisé, remplaçant le champ texte libre Nécessaire au regroupement par auteur et à la recherche insensible aux accents. Regroupement automatique seulement quand c'est sûr, sinon proposé à l'utilisateur
Ebooks Fiches uniquement, pas de stockage de fichiers Inventaire, pas hébergement. Évite l'espace disque YunoHost, les sauvegardes lourdes, et garde le cache hors-ligne léger
Architecture serveur x86_64 → publish linux-x64 Serveur PC/VPS confirmé par l'utilisateur
Production des binaires Compilation locale + release manuelle, via un script réutilisable en CI plus tard Ne pas se bloquer sur l'outillage ; Gitea Actions nécessiterait un runner, non vérifié
Cache hors-ligne IndexedDB (pas le cache du service worker) Seule option permettant recherche et tri hors-ligne sur toute la bibliothèque, et l'affichage de la date de dernière synchro
Notices BnF multiples Demander systématiquement à l'utilisateur Exactitude de l'édition privilégiée sur la vitesse de saisie en série
AOT WebAssembly Désactivé par défaut, à réévaluer après mesure Le mode interprété devrait suffire (~5-10 ms/frame estimés) ; ne pas payer le coût de build avant d'avoir constaté un problème
Hébergement YunoHost, installation native (pas Docker) YunoHost déconseille Docker pour ses apps (moins fiable, plus lourd) ; installation native = meilleures perfs sur petit matériel
Packaging YunoHost S'inspirer de radarr_ynh Radarr est aussi en .NET, packagé sans Docker sur YunoHost. Leur manifest.toml montre un déploiement self-contained (dotnet publish -r linux-x64 --self-contained), donc pas besoin d'installer dotnet-runtime via apt côté serveur — le binaire embarque son propre runtime
Scan ISBN ZXing.Net (C#, Apache 2.0) exécuté dans le WASM ; le JS ne fournit que les pixels caméra Décodage en C#, réutilisable hors navigateur si le projet évolue en scanner de bibliothèque. Voir la section dédiée ci-dessous
Consultation hors-ligne Cache local des données côté client (mécanisme à trancher) Le besoin est de consulter la bibliothèque existante sans réseau, pas d'enrichir de nouveaux livres. Voir « Stratégie hors-ligne »

Scan du code-barres — ZXing.Net (décision actée)

Le décodage EAN-13 se fait en C# avec ZXing.Net (micjahn, Apache 2.0), et non avec une bibliothèque JS type html5-qrcode.

Pourquoi

  • Réutilisable hors navigateur. Si le projet évolue vers un scanner de bibliothèque (app native, scan en masse, décodage d'une photo côté serveur), le code de décodage se transpose tel quel. Une bibliothèque JS serait à réécrire intégralement.
  • Un seul langage, cohérent avec le reste de la stack.
  • L'argument « offline » n'entre pas en compte ici : html5-qrcode fonctionne aussi hors-ligne (fichier JS servi par la PWA, aucun appel réseau). Ce n'est pas un critère de départage.

Mesures réelles (validées sur .NET 10, publish Blazor WASM OK)

Mesure Résultat
Décodage EAN-13 propre (380×160) 0,04 ms/frame
Pire cas : frame 640×480 bruitée sans code-barres (échec) 0,53 ms/frame
Poids de l'assembly zxing.wasm seul +192 Ko (brotli)

Le pire cas est le chiffre qui gouverne le framerate : la majorité des frames caméra ne contiennent pas de code-barres lisible, et c'est l'échec de décodage qui coûte le plus cher.

Mesures en WASM réel — faites le 2026-08-18, phase scan

L'estimation « ~5-10 ms/frame en interprété » ci-dessus n'était qu'une extrapolation. Elle a été vérifiée dans un vrai navigateur (Chromium 148, x86_64 de bureau), sur le publish Release du client, en appelant le décodeur depuis la console via BancEssaiScan :

Configuration Pire cas 640×288 (bande visée) Pire cas 640×480
Publish Release, interprété 4,4 – 6,4 ms/frame 6,7 – 7,8 ms/frame
Build Debug, interprété 17,7 ms/frame 28,7 ms/frame

L'estimation était bonne : le mode interprété tient largement les 10-15 fps visés (une frame toutes les 80 ms n'utilise que ~6 % du budget). Aucune raison d'activer l'AOT — il reste à confirmer sur un téléphone, sensiblement plus lent qu'un x86_64 de bureau.

⚠️ Ne jamais juger la fluidité sur un build Debug : il est 4 à 5× plus lent que le Release, de quoi conclure à tort qu'il faut l'AOT.

⚠️ Le surcoût de payload réel est bien supérieur à 192 Ko

Mesuré par différence entre deux publish Release complets (somme brotli de _framework) : +351 Ko au total, dont ~4,7 Ko de code applicatif. Le coût imputable à ZXing.Net est donc d'environ +346 Ko brotli, soit 1,8× le poids de son propre assembly. Le surplus vient des assemblies BCL que le trimmer ne peut plus retirer :

Assembly Delta brotli
zxing.wasm +192 495 o
System.Text.RegularExpressions +91 237 o (de 7 Ko à 98 Ko : ZXing utilise Regex, tout le moteur reste)
System.Runtime.Numerics +30 701 o (nouveau)
System.Private.CoreLib +17 586 o
divers (Threading, Collections, InteropServices…) ~14 Ko

Ne pas reprendre « +192 Ko » comme coût du scan : c'est le poids de l'assembly, pas celui de la fonctionnalité.

Pièges à connaître

  • Le JS interop ne disparaît pas. getUserMedia et <canvas>/getImageData sont des API web sans équivalent C#. Prévoir ~30 lignes de JS maison dont le seul rôle est de pousser un byte[] vers C#. Toute la logique de décodage reste en C#.
  • Ne pas perdre de temps à essayer de réduire la taille via un reader ciblé. Remplacer MultiFormatReader par EAN13Reader pour aider le trimmer ne change rien : mesuré à 192 495 octets à l'octet près dans les deux cas. ZXing.Net n'est pas trim-friendly.
  • RGBLuminanceSource accepte directement le buffer RGBA du canvas (BitmapFormat.RGBA32) — aucune bibliothèque d'image nécessaire (pas de SkiaSharp ni ImageSharp).
  • Le scan caméra exige HTTPS (garanti par YunoHost en prod ; en dev, localhost est considéré comme sûr). Corollaire vérifié : tester le scan depuis un téléphone en pointant l'IP locale du PC (http://192.168.x.x) échouera toujours — ce n'est pas un contexte sécurisé. Le composant détecte ce cas et le dit explicitement.
  • Une DOMException perd son name en traversant le pont JS→C# : getUserMedia refusé remonte en C# sous la forme « Permission denied undefined », sans NotAllowedError. Or c'est ce nom qui distingue « permission refusée » de « pas de caméra » de « caméra occupée ». Le JS doit donc attraper l'erreur et renvoyer un code de statut ; parser le message côté C# ne marche pas.
  • L'import du module JS doit porter une chaîne de requête (./js/scanner-camera.js?m=1). En développement, l'import map généré par Blazor réécrit le chemin vers un nom empreinté que l'API hôte ne sert pas (elle utilise UseStaticFiles, qui ignore les points d'entrée empreintés) : l'import part en 404 et le scan ne démarre jamais. La chaîne de requête empêche cette réécriture ; en publication rien n'est réécrit pour ce fichier, donc le comportement est identique.

Squelette validé

using ZXing;
using ZXing.Common;

public static class IsbnScanner
{
    static readonly MultiFormatReader Reader = new()
    {
        Hints = new Dictionary<DecodeHintType, object>
        {
            [DecodeHintType.POSSIBLE_FORMATS] = new List<BarcodeFormat>
            {
                BarcodeFormat.EAN_13, BarcodeFormat.EAN_8,
            },
            [DecodeHintType.TRY_HARDER] = true,
        },
    };

    /// rgba : buffer brut issu de ctx.getImageData(...).data
    public static string? TryDecode(byte[] rgba, int width, int height)
    {
        var source = new RGBLuminanceSource(
            rgba, width, height, RGBLuminanceSource.BitmapFormat.RGBA32);
        return Reader.decode(new BinaryBitmap(new HybridBinarizer(source)))?.Text;
    }
}

Stratégie hors-ligne — décidé : consultation seule

Besoin réel : consulter la bibliothèque déjà enregistrée sans réseau (liste des livres, statuts, prêts en cours). Il ne s'agit pas d'enrichir de nouveaux livres hors-ligne — le lookup ISBN exige de toute façon un accès réseau.

⚠️ Piège à ne pas sous-estimer : « les données sont déjà en local » n'est vrai qu'au sens serveur. En Blazor WebAssembly, le code tourne dans le navigateur, alors que SQLite vit côté serveur YunoHost. Le service worker de la PWA met en cache les assets (HTML/CSS/WASM), mais pas les réponses de l'API. Sans travail explicite, l'app se lancera hors-ligne et affichera une liste vide.

Décision : cache client des réponses GET de l'API (IndexedDB, ou cache du service worker), en lecture seule.

  • Pas de file d'attente d'écritures, pas de synchronisation, pas de résolution de conflits.
  • Hors-ligne, l'interface doit désactiver explicitement les actions d'écriture (ajout, édition, prêt) plutôt que de les laisser échouer silencieusement, et indiquer que les données affichées proviennent du cache.
  • SQLite compilé en WASM côté client a été écarté : ne se justifierait que si l'écriture hors-ligne devenait nécessaire.

Sources de données ISBN — point d'attention important

Ne pas dépendre d'une seule source, et éviter Google Books si possible (préférence explicite de l'utilisateur : pas de dépendance à Google).

Stratégie : interroger plusieurs sources libres et gratuites, sans clé API obligatoire, en cascade (si la première ne répond pas ou renvoie des données incomplètes, essayer la suivante).

Ordre décidé : BnF d'abord, OpenLibrary ensuite. La collection est majoritairement francophone, or OpenLibrary (Internet Archive) est très fourni sur l'édition anglophone mais lacunaire sur le fonds français — éditions françaises récentes et poches d'éditeurs modestes y manquent souvent, ou n'ont qu'un titre sans auteur. Une source unique lacunaire ruinerait l'intérêt du scan, qui est précisément d'éviter la saisie manuelle.

  1. BnF — source principale, via son API SRU, gratuite et sans clé. Le dépôt légal français garantit structurellement la meilleure couverture possible sur le francophone. API testée et validée le 2026-08-17 — voir la section « API BnF » ci-dessous pour les pièges, dont un bloquant.
  2. OpenLibrary (https://openlibrary.org/isbn/{isbn}.json) — source de secours, pour les livres étrangers et tout ce que la BnF ne connaît pas
    • ⚠️ Bug connu identifié lors des tests avec BookLogr : l'endpoint /isbn/{isbn}.json renvoie souvent le titre mais l'auteur est juste une référence (/authors/OL...A), pas le nom directement. Il faut faire un second appel vers /authors/{id}.json pour récupérer le nom. Un projet qui oublie ce second appel se retrouve avec titre rempli mais auteur vide (symptôme exact observé et diagnostiqué chez BookLogr) — ne pas reproduire ce bug.
    • La couverture est un service séparé : https://covers.openlibrary.org/b/isbn/{isbn}-L.jpg (peut exister même si la fiche bibliographique est incomplète)
  3. Fallback ultérieur envisageable : Wikidata. Ne pas l'implémenter tant que la cascade BnF → OpenLibrary n'a pas montré ses limites en usage réel.

Google Books reste écarté conformément à la préférence de l'utilisateur, sauf changement d'avis explicite de sa part.

Quelle que soit la source, prévoir que le formulaire de saisie manuelle reste toujours accessible pour compléter ou corriger une fiche incomplète.

API BnF — validée le 2026-08-17

Endpoint SRU, gratuit, sans clé API, réponse en ~240 ms :

https://catalogue.bnf.fr/api/SRU
  ?version=1.2
  &operation=searchRetrieve
  &query=bib.isbn all "{isbn}"
  &recordSchema=dublincore
  &maximumRecords=5

Utiliser recordSchema=dublincore, pas MARC. Le Dublin Core renvoie directement dc:title, dc:creator, dc:publisher, dc:date, dc:language, dc:format — bien plus simple à mapper que l'UNIMARC. Le nombre de résultats se lit dans <srw:numberOfRecords>.

⚠️ Piège bloquant : ISBN-13 vs ISBN-10

La BnF indexe l'ISBN tel qu'imprimé sur le livre. Les ouvrages publiés avant 2007 ne portent qu'un ISBN-10 et sont donc introuvables par leur ISBN-13, alors que le scanner de code-barres lit toujours un EAN-13.

Mesuré sur un échantillon de livres français dont l'existence a été confirmée via OpenLibrary :

ISBN-13 Recherche ISBN-13 Recherche ISBN-10
9782070612758 (Le Petit Prince, 2007) 1 notice 0
9782253004226 (Germinal, Livre de poche) 0 3 notices
9782080704092 (Le Horla, Flammarion) 0 1 notice

Sans conversion, on perd la majorité du fonds ancien — précisément les livres d'une bibliothèque constituée. Toujours interroger les deux formes : ISBN-13 d'abord, puis ISBN-10 converti si aucun résultat.

Conversion ISBN-13 → ISBN-10 (uniquement pour le préfixe 978) : retirer 978, garder les 9 chiffres, recalculer la clé (somme pondérée 10→2, modulo 11, X si le reste vaut 10).

Autres pièges confirmés

  • Pas de couverture. Le Dublin Core BnF n'en fournit aucune. Utiliser OpenLibrary pour l'image, quelle que soit la source des métadonnées : https://covers.openlibrary.org/b/isbn/{isbn}-L.jpg?default=false. Le ?default=false est indispensable — sans lui, OpenLibrary renvoie une image placeholder au lieu d'un 404. Testé : disponible pour les 4 ISBN de l'échantillon, y compris ceux absents d'OpenLibrary côté bibliographique.
  • Plusieurs notices pour un même ISBN. Germinal en renvoie 3 (rééditions successives partageant l'ISBN, éditeurs et années différents). Ne pas prendre aveuglément la première : soit proposer le choix à l'utilisateur, soit retenir la plus récente via dc:date. À trancher à l'implémentation.
  • Ponctuation ISBD à nettoyer. Les champs ne sont pas exploitables bruts. Règles validées :
Champ Brut Nettoyé
dc:title Germinal / Émile Zola ; préface d'Armand Lanoux Germinal — couper au premier /
dc:creator Zola, Émile (1840-1902). Auteur du texte Émile Zola — retirer les dates entre parenthèses, le rôle après le point, puis inverser Nom, Prénom
dc:publisher le Livre de poche (Paris) le Livre de poche — retirer la ville en fin de chaîne
  • Couvertures OpenLibrary : 502 intermittents. Mesuré en phase 2 — trois appels consécutifs sur le même ISBN ont donné 200, 200, puis 502. Ne jamais valider l'URL par un HEAD avant de l'afficher : on supprimerait au hasard des couvertures existantes. L'URL est émise systématiquement, et l'interface doit gérer l'image cassée (onerror), le ?default=false garantissant un 404 franc plutôt qu'un placeholder silencieux.
  • OpenLibrary : le double appel auteur ne suffit pas toujours. Cas réel (Introduction to Algorithms) : l'édition n'a aucun champ authors, seulement contributions et by_statement. Le repli implémenté passe par /works/{id}.json → clés d'auteurs → /authors/{id}.json, puis en dernier recours by_statement. Sans ce repli, l'auteur serait vide — c'est la même classe de bug que celui de BookLogr, sous une autre forme.
  • Livres étrangers absents, comme attendu du dépôt légal français : Introduction to Algorithms et Effective Java introuvables sous les deux formes d'ISBN. C'est exactement le rôle d'OpenLibrary en second rideau — la cascade est donc bien nécessaire, pas seulement confortable.

Intégration SSO YunoHost

Mécanisme retenu : en-têtes HTTP injectés par SSOwat. nginx authentifie le visiteur via le portail YunoHost, puis transmet l'identité à l'application dans des en-têtes que l'app se contente de lire :

En-tête Contenu
YNH_USER nom d'utilisateur authentifié
YNH_USER_EMAIL email
YNH_USER_FULLNAME nom complet

YNH_USER_FULLNAME évite une requête LDAP supplémentaire pour l'affichage.

OIDC a été écarté (vérifié le 2026-08-17) : la documentation de packaging YunoHost ne documente aucun fournisseur OpenID Connect pour les apps. Les seuls mécanismes officiels sont LDAP direct et ces en-têtes.

Points de vigilance

  • La doc YunoHost indique que ces en-têtes sont protégés contre l'injection depuis le client (SSOwat les écrase). Malgré cela, faire écouter le service .NET uniquement sur 127.0.0.1, jamais sur 0.0.0.0 — défense en profondeur, à traiter comme une contrainte dure dans systemd.service et nginx.conf. Un service exposé directement sur le réseau permettrait de forger YNH_USER et de contourner tout le portail.
  • Limite connue : se déconnecter du portail YunoHost ne déconnecte pas des apps, chacune conservant sa propre session/cookie.
  • En développement local, il n'y a pas de SSOwat : prévoir un utilisateur simulé (en-tête forcé ou configuration de dev) plutôt que de désactiver l'auth.

Architecture de déploiement YunoHost

Trois projets .NET, un seul service

Le client Blazor WebAssembly n'est pas un serveur : compilé, ce ne sont que des fichiers statiques (HTML/CSS/.wasm) servis par l'API. Un seul processus tourne donc sur le serveur.

DÉVELOPPEMENT              COMPILATION                DÉPLOIEMENT
MaBibli.Client  ─┐
MaBibli.Shared  ─┼──►  dotnet publish  ──►  un dossier  ──►  un service systemd
MaBibli.Api     ─┘        MaBibli.Api        unique           sur 127.0.0.1:PORT

MaBibli.Api référence MaBibli.Client ; à la compilation, les fichiers du client atterrissent dans le wwwroot de l'API.

Commande de publication cible :

dotnet publish MaBibli.Api -c Release -r linux-x64 --self-contained

Le self-contained embarque le runtime .NET dans le binaire : aucun dotnet-runtime à installer côté serveur, pas de conflit de versions. C'est le modèle de radarr_ynh.

⚠️ BLOQUANT CONNU : le publish de l'API produit un index.html cassé

Constaté le 2026-08-18, non résolu. À corriger impérativement avant tout packaging YunoHost.

dotnet publish MaBibli.Api -c Release produit un wwwroot/index.html dont les placeholders ne sont pas substitués :

<script type="importmap"></script>                                  <!-- vide -->
<script src="_framework/blazor.webassembly#[.{fingerprint}].js">    <!-- littéral -->

Or seuls les noms empreintés existent sur disque (blazor.webassembly.958z1vx7fr.js). Résultat vérifié en exécutant le binaire publié : la racine répond 200, mais le script de démarrage et _framework/dotnet.js renvoient 404. L'application publiée affiche une page blanche — elle ne démarre pas.

dotnet publish MaBibli.Client seul produit au contraire un index.html correct : le défaut vient de l'hébergement du client par l'API, qui embarque le wwwroot de build du client plutôt que son wwwroot publié.

Piège de diagnostic : vérifier que / renvoie 200 ne prouve rien — c'est ce qui a fait passer le défaut inaperçu à la phase 1. Il faut vérifier les scripts que index.html référence réellement, ou charger la page dans un navigateur.

Pistes déjà essayées sans succès (inutile de les retenter à l'identique) :

  • <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders> sur MaBibli.Api ;
  • <WasmFingerprintAssets>false</WasmFingerprintAssets> sur le client — donne bien un dotnet.js stable, mais blazor.webassembly.js reste empreinté car il provient des assets du package framework ;
  • <StaticWebAssetsFingerprintContent>false</StaticWebAssetsFingerprintContent> sur les deux projets.

Le développement n'est pas affecté : dotnet run --project MaBibli.Api fonctionne normalement.

Deux dépôts distincts

Dépôt Contenu Rôle
mabibli Le code C#, les 3 projets Ce qui est développé
mabibli_ynh manifest.toml, scripts, conf nginx/systemd Comment l'installer sur YunoHost

Le paquet _ynh ne contient aucun code C# : il porte des instructions d'installation et une URL vers une archive compilée, avec son empreinte SHA256.

mabibli_ynh/
├── manifest.toml          ← identité, version, URL du binaire + sha256
├── conf/
│   ├── systemd.service    ← lancement du service, port
│   └── nginx.conf         ← reverse proxy + intégration SSO
└── scripts/
    ├── install / remove
    ├── upgrade
    └── backup / restore

Chaîne de publication

Compilation locale, puis dépôt manuel de l'archive en release sur le Gitea de l'utilisateur, et mise à jour du sha256 dans le manifest.toml. Prévoir un script de build encapsulant ces étapes, écrit pour être réutilisable tel quel dans une CI (Gitea Actions) si l'utilisateur bascule plus tard.

Ne jamais compiler sur le serveur à l'installation : cela imposerait le SDK .NET complet sur la machine YunoHost, pour une compilation lente — l'inverse exact de ce que permet le self-contained.

Modèle de données

Schéma en vigueur depuis la migration StatutPersonnelEtTableAuteurs (2026-08-18).

Livre
├── Id
├── Isbn                      (index)
├── Titre
├── TitreNormalise            (index — minuscules sans accents, recalculé à chaque écriture)
├── Editeur
├── Format : Physique | Numerique
├── CoverUrl
├── DateAjout
└── AjoutePar (YNH_USER — traçabilité, PAS un cloisonnement)
        ⚠ pas de colonne Statut, pas de colonne Auteur

Auteur
├── Id
├── Nom                       (affichage : « Émile Zola »)
├── NomNormalise              (index — recherche : « emile zola »)
└── CleRegroupement           (index UNIQUE — mots normalisés triés : « emile zola »)

LivreAuteur                   (n-n : un livre peut avoir plusieurs auteurs)
├── LivreId  ─┐ clé primaire composite
├── AuteurId ─┘   FK Livre = cascade, FK Auteur = restrict
└── Position                  (rang sur la couverture, à partir de 0)

StatutLecture                 (le statut est PERSONNEL)
├── Id
├── LivreId                   (FK vers Livre, cascade)
├── Utilisateur               (YNH_USER)
├── Statut : ALire | EnCours | Lu
├── DateMaj
└── UNIQUE (LivreId, Utilisateur)
        absence de ligne = « non commencé »

RapprochementRefuse           (mémoire des « non » de l'utilisateur)
├── Id
├── AuteurAId ─┐ UNIQUE, couple toujours rangé (petit Id d'abord)
└── AuteurBId ─┘   pour qu'un refus vaille dans les deux sens

Pret
├── Id
├── LivreId (FK vers Livre)
├── Emprunteur (nom, texte libre)
├── DatePret
└── DateRetour (nullable — NULL tant que non rendu)

Garder Pret comme table séparée (pas un champ sur Livre) pour conserver l'historique complet des prêts passés, pas juste l'état actuel.

AjoutePar est une information, pas une frontière. La bibliothèque est commune : ne jamais filtrer les requêtes de lecture sur ce champ. Il sert à savoir qui a saisi le livre (et implicitement à qui il appartient), pas à restreindre l'accès. Ce choix permet de basculer plus tard vers des bibliothèques cloisonnées sans migration de schéma.

Le statut de lecture n'appartient plus à Livre. Il vit dans une table par utilisateur (LivreId + YNH_USER + statut, unicité sur le couple). Un livre sans ligne pour l'utilisateur courant est simplement « non commencé ». Ne jamais réintroduire de colonne Statut sur Livre : elle redeviendrait commune à tout le foyer.

L'auteur n'est plus un champ texte sur Livre. Une table dédiée porte le nom d'affichage et une forme normalisée servant au regroupement et à la recherche. Le regroupement automatique ne s'applique qu'aux variantes sûres (casse, accents, initiales, ordre nom/prénom) ; les rapprochements ambigus — « Hamilton » seul vers « Peter F. Hamilton » — doivent être proposés, jamais appliqués silencieusement : une fusion erronée est difficile à défaire.

Recherche sans accents : pourquoi des colonnes normalisées

SQLite ne sait pas ignorer les accents. Sa collation NOCASE ne couvre que l'ASCII et il n'existe pas de unaccent() intégré. La seule façon d'obtenir « Emile » → « Émile » sans charger tout le catalogue en mémoire est de stocker la forme mise à plat dans une colonne dédiée, et d'y chercher un terme passé par exactement la même fonction (NormalisationTexte).

Conséquence à ne pas oublier : toute écriture doit recalculer ces colonnes (Livre.RecalculerFormes(), Auteur.RecalculerFormes()).

Deux formes cohabitent sur Auteur, et ce n'est pas une redondance :

  • NomNormalise garde l'ordre de saisie — c'est ce que la recherche parcourt en sous-chaîne ;
  • CleRegroupement trie les mots, ce qui rend Zola, Émile et Émile Zola identiques. C'est elle qui porte l'index unique, donc l'invariant « un auteur, une fiche ».

La clé ne sait pas rapprocher les initiales (P.F. Hamilton ↔ Peter F. Hamilton) : cela demande d'aligner les mots un à un, ce qui n'a pas d'équivalent SQL. Ce cas est traité en mémoire par RapprochementAuteurs.Comparer, sur une table qui compte au plus quelques centaines de lignes.

Reprise des données existantes

La migration recopie l'ancien contenu avec les moyens du bord, puis ServiceRenormalisation finit le travail en C# au démarrage — idempotent, il sert aussi de filet si les règles de normalisation changent un jour.

  • L'ancien Livres.Statut, commun à tout le foyer, est rattaché à AjoutePar, seule personne que la base associe au livre. Les statuts des livres sans AjoutePar sont perdus : les attribuer serait une invention.
  • L'ancien Livres.Auteur devient une fiche par valeur distincte. SQLite ne regroupant qu'à la casse près, les variantes accentuées ressortent en double — c'est le passage C# qui les réunit, en gardant le nom d'affichage le plus présentable (accents conservés, ni NOM, Prénom ni capitales intégrales).

Les prêts ne concernent en pratique que les livres physiques — les ebooks étant de simples fiches, il n'y a pas d'objet à prêter. Emprunteur reste un texte libre, sans lien avec les comptes YunoHost : on suit les prêts à des personnes extérieures au foyer, pas les échanges entre utilisateurs de l'app.

Historique du projet (pourquoi ces choix)

L'utilisateur a testé deux solutions existantes avant de se lancer dans un projet custom :

  • uBiblio (Docker, Python) — gère prêts + scan ISBN, mais dépend de Google Books (clé API requise) pour l'autofill, ce qui ne convient pas à l'utilisateur qui veut éviter cette dépendance
  • BookLogr (Docker, Python) — utilise OpenLibrary nativement mais a le bug décrit ci-dessus (auteur non récupéré)

Conclusion : aucune des deux solutions existantes ne coche toutes les cases (prêts + pas de dépendance Google + autofill fiable) → développement d'une solution sur mesure.

Prochaines étapes suggérées

  1. Scaffolder le projet Blazor WebAssembly PWA (dotnet new blazorwasm --pwa) — commande vérifiée valide en .NET 10, l'option --pwa existe toujours
  2. Ajouter le projet API ASP.NET Core : le client WASM tourne dans le navigateur, SQLite vit côté serveur — une API est indispensable, elle n'était pas explicitée dans la version initiale de ce document
  3. Mettre en place le modèle EF Core + SQLite + migrations
  4. Implémenter le service de lookup ISBN (OpenLibrary avec le double-appel titre+auteur)
  5. CRUD livres (physique/numérique, statuts de lecture)
  6. Gestion des prêts
  7. Intégration scan caméra (ZXing.Net + interop caméra minimal)
  8. Cache hors-ligne pour la consultation (voir « Stratégie hors-ligne »)
  9. Packaging YunoHost (manifest.toml, conf/systemd.service, conf/nginx.conf, scripts/install) en s'inspirant de radarr_ynh

Questions ouvertes

Tous les choix structurants ont été tranchés le 2026-08-17 — voir le tableau des décisions. Le cadrage est clos, le développement peut commencer.

Points à réévaluer en cours de route, sans blocage :

  • AOT WASM : mesurer le scan sur un vrai téléphone une fois fonctionnel. Activer RunAOTCompilation seulement si la fluidité est insuffisante.
  • Runner Gitea Actions : à vérifier le jour où l'utilisateur voudra automatiser les releases.
  • Wikidata en 3ᵉ source ISBN : uniquement si la cascade BnF → OpenLibrary montre ses limites en usage réel.
Reference in New Issue View Git Blame Copy Permalink