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 :

Une source structurée décrivant les cards et les objets pédagogiques.
Une petite bibliothèque de primitives SVG contrôlées.
Un validateur automatique lancé après génération.
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.

4.5 KiB Raw Blame History