99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# 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.
|
|
|