svg alignemment

SVG_CONTENT_ARCHITECTURE.md

@@ -0,0 +1,98 @@
+# Architecture des contenus SVG pédagogiques
+
+## Diagnostic
+
+Le problème des traits de fraction n'est pas un simple défaut ponctuel de mise en page.
+Les retours du 2026-05-07 montrent le même motif sur plusieurs supports fractions :
+
+- traits obliques à proscrire pour les élèves de CM1 ;
+- barres horizontales qui recouvrent le numérateur ou le dénominateur ;
+- expressions de fractions qui se chevauchent dans les équations ;
+- corrections faites directement dans les SVG finaux.
+
+L'architecture actuelle sait charger, servir, recadrer et relire des SVG. Elle ne sait pas garantir que les objets mathématiques dessinés à l'intérieur du SVG sont corrects.
+
+## État actuel
+
+- Les contenus sont stockés comme fichiers SVG finaux dans `backend/contenus_pedagogiques`.
+- Le backend expose les SVG tels quels via `/program/assets/{asset_token}`.
+- Le découpage en cards est fait par détection de grands groupes `<g>` dans `backend/app/program_content.py`.
+- Les retours de validation sont stockés séparément dans `review_updates`.
+- Les SVG fractions récents utilisent déjà une convention locale : `math-expression` et `fraction-g`.
+
+Cette convention est utile, mais elle arrive trop tard : elle est écrite dans le SVG produit, sans source structurée, sans composant unique et sans validation automatique.
+
+## Décision recommandée
+
+Garder SVG comme format de sortie, mais ne plus considérer le SVG final comme la source principale pour les objets mathématiques sensibles.
+
+Pour les prochaines générations, il faut ajouter une couche intermédiaire :
+
+1. Une source structurée décrivant les cards et les objets pédagogiques.
+2. Une petite bibliothèque de primitives SVG contrôlées.
+3. Un validateur automatique lancé après génération.
+4. Une revue humaine uniquement sur les points que l'automatique ne peut pas juger.
+
+## Primitive prioritaire : fraction verticale
+
+Une fraction ne doit plus être écrite à la main dans un SVG.
+
+La primitive `fraction(numerateur, denominateur, options)` doit produire :
+
+- un groupe `<g class="math-expression fraction-g" data-math="fraction">` ;
+- deux textes centrés ;
+- une barre horizontale ;
+- des espacements calculés depuis la taille de police ;
+- une largeur calculée depuis le plus long texte ;
+- aucun trait oblique pour les fractions CM1 ;
+- une boîte logique exportable, pour éviter les collisions dans les équations.
+
+Règle de rendu CM1 :
+
+- fraction verticale obligatoire ;
+- barre horizontale visible et séparée des chiffres ;
+- pas de notation `3/4` dans les SVG destinés à l'élève, sauf dans les notes Markdown ou les contextes de card.
+
+## Validation automatique minimale
+
+Le validateur doit refuser ou signaler :
+
+- texte SVG contenant une fraction oblique du type `3/4` ;
+- groupe `fraction-g` sans numérateur, barre et dénominateur ;
+- barre qui n'est pas située entre les deux textes ;
+- espacement vertical trop faible autour de la barre ;
+- barre trop courte par rapport aux chiffres ;
+- SVG sans `viewBox` ou dimensions incohérentes ;
+- card sans grand rectangle détectable, quand elle doit être découpée.
+
+Le premier filet de sécurité est disponible dans `backend/tools/validate_svg_quality.py`.
+
+## Architecture cible courte
+
+À court terme :
+
+- continuer à servir les SVG existants ;
+- imposer `fraction-g` pour toutes les fractions verticales ;
+- lancer `python backend/tools/validate_svg_quality.py backend/contenus_pedagogiques` après chaque génération ;
+- corriger les fichiers signalés avant revue utilisateur.
+
+À moyen terme :
+
+- générer les SVG depuis des descriptions structurées, par exemple `*.content.json` ou `*.content.yaml` ;
+- centraliser les primitives dans un module de génération ;
+- faire produire aux agents du contenu structuré plutôt que du SVG brut ;
+- rendre le SVG final reproductible à partir de la source.
+
+À long terme :
+
+- ajouter une capture raster automatique en CI pour détecter les chevauchements visuels réels ;
+- comparer certains rendus à des snapshots de référence ;
+- étendre les primitives aux droites graduées, bandes partagées, tableaux de nombres, zones de réponse et schémas en barres.
+
+## Évaluation
+
+L'architecture actuelle est acceptable pour afficher et relire des supports déjà produits.
+Elle n'est pas suffisante pour produire régulièrement des contenus mathématiques propres.
+
+La bonne direction n'est pas de remplacer SVG, mais de déplacer l'intelligence avant le SVG final : composants mathématiques, contraintes géométriques, validation automatique, puis rendu.
+