lafrite/notytex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a28777f1e1f92b4cc53251eee034df6c7e13dd22
notytex/docs/features/EMAIL_REPORTS.md

12 KiB
Raw Blame History

📧 Système d'Envoi de Bilans par Email

Notytex intègre un système complet d'envoi automatique des bilans d'évaluation individuels par email aux élèves et à leurs familles.

🎯 Vue d'ensemble

Cette fonctionnalité permet aux enseignants d'envoyer facilement des rapports détaillés et personnalisés de chaque évaluation directement dans la boîte mail des élèves, avec une présentation professionnelle et des analyses approfondies.

Fonctionnalités principales

  • ✅ Configuration SMTP flexible via interface web
  • ✅ Génération automatique de bilans individualisés
  • ✅ Templates HTML responsives optimisés email
  • ✅ Validation et gestion d'erreurs robuste
  • ✅ Serveur de test intégré pour développement
  • ✅ Analyses détaillées par compétences et domaines

🏗️ Architecture Technique

Services Découplés

services/
├── email_service.py           # Service d'envoi SMTP avec configuration dynamique
└── student_report_service.py  # Service de génération de bilans individualisés

templates/email/
├── base_email.html           # Template de base pour emails (responsive)
└── student_report.html       # Template de bilan d'élève (complet et détaillé)

routes/
├── assessments.py            # Routes d'envoi de bilans (/send-reports, /preview-report)
└── config.py                 # Configuration SMTP via interface web

Configuration Stockée

Les paramètres SMTP sont stockés de manière sécurisée dans la base de données via app_config :

# Configuration dans SQLite
email.smtp_host = 'smtp.gmail.com'
email.smtp_port = 587
email.username = 'professeur@etablissement.fr'
email.password = 'mot_de_passe_application'
email.use_tls = true
email.from_name = 'Professeur Martin'
email.from_address = 'professeur@etablissement.fr'

⚙️ Configuration SMTP

Interface Web

Accès via Configuration > Email dans l'interface d'administration.

Paramètres configurables :

  • Serveur SMTP : Adresse du serveur (ex: smtp.gmail.com)
  • Port SMTP : Port de connexion (587 pour TLS, 465 pour SSL)
  • Nom d'utilisateur : Identifiant de connexion SMTP
  • Mot de passe : Mot de passe ou mot de passe d'application
  • Chiffrement TLS : Activation/désactivation du chiffrement
  • Nom d'expéditeur : Nom affiché dans l'email
  • Adresse d'expéditeur : Adresse email expéditrice

Fournisseurs Supportés

Gmail

Outlook/Hotmail

  • Serveur : smtp-mail.outlook.com
  • Port : 587 (TLS)
  • Sécurité : Authentification moderne

Serveurs Personnalisés

Configuration flexible pour tous types de serveurs SMTP compatibles.

Test de Configuration

L'interface propose un test d'envoi pour valider la configuration :

  • Envoi d'un email de test à une adresse spécifiée
  • Validation automatique de tous les paramètres
  • Rapport détaillé en cas d'erreur

🧪 Environnement de Test

Serveur SMTP de Développement

Notytex inclut un script de test SMTP intégré pour le développement local :

# Lancement du serveur de débogage
python debug_smtp_server.py

Configuration pour les tests :

  • Serveur SMTP : localhost
  • Port : 1025
  • Utilisateur/Mot de passe : Laisser vides
  • TLS : Désactivé

Avantages :

  • 📧 Emails affichés en console avec contenu HTML complet
  • 🚫 Aucun envoi réel pour la sécurité des tests
  • 🎨 Formatage amélioré pour une lecture facile
  • ⚡ Feedback immédiat pour valider les templates

📊 Génération de Bilans

Service StudentReportService

Le StudentReportService génère des rapports complets et personnalisés pour chaque élève.

Données Incluses

📋 Informations sur l'évaluation :

  • Titre, description, date
  • Classe, trimestre, coefficient

🎯 Note globale :

  • Score total avec pourcentage
  • Visualisation colorée (barre de progression)
  • Position dans la classe

📝 Détail par exercice :

  • Score détaillé par exercice
  • Questions individuelles avec résultats
  • Types de notation (points/compétences)

⭐ Analyse par compétences :

  • Performance par compétence évaluée
  • Système d'étoiles visuelles (0-3)
  • Labels configurables

🏷️ Analyse par domaines :

  • Groupement thématique des résultats
  • Codes couleur par domaine
  • Pourcentages de réussite

📈 Statistiques de classe :

  • Position de l'élève
  • Moyenne, médiane, écart-type
  • Nombre total d'élèves

Gestion des Types de Notation

Notes classiques :

  • Affichage "15.5/20" avec barres de progression colorées
  • Calcul automatique des pourcentages

Évaluation par compétences :

  • Système d'étoiles (0-3) avec labels configurables
  • Conversion intelligente score → étoiles

Valeurs spéciales :

  • "." : Pas de réponse (affiché avec ❓)
  • "d" : Dispensé (ne compte pas dans le calcul)
  • Autres valeurs configurables via l'interface

📧 Interface d'Envoi

Accès Multiple

Page de résultats d'évaluation :

  • Bouton "📧 Envoyer les bilans"
  • Interface de sélection d'élèves

Workflow d'envoi :

  1. Sélection des élèves

    • Cases à cocher pour chaque élève
    • Validation automatique des adresses email

  2. Message personnalisé

    • Champ texte libre pour ajouter un commentaire
    • Message inclus dans tous les bilans

  3. Prévisualisation

    • Aperçu du bilan via /preview-report/<student_id>
    • Validation visuelle avant envoi

  4. Génération et envoi

    • Création automatique des bilans individualisés
    • Envoi groupé en arrière-plan
    • Rapport détaillé des résultats

Validation et Contrôles

Validation des emails :

  • Regex strict pour vérifier le format
  • Exclusion automatique des adresses invalides
  • Rapport détaillé des élèves sans email

Gestion d'erreurs :

  • Retry automatique en cas d'échec temporaire
  • Logs détaillés pour le debugging
  • Messages d'erreur explicites

🎨 Design des Emails

Template Responsive

Le template student_report.html est optimisé pour une compatibilité maximale :

Optimisations techniques :

  • CSS inliné via Premailer pour compatibilité clients email
  • Responsive design avec adaptation mobile/desktop
  • Polices système pour une lecture optimale
  • Images vectorielles (émojis) pour améliorer la lisibilité

Structure hiérarchique :

  • Header personnalisé avec branding
  • Sections clairement délimitées
  • Palette de couleurs intelligente selon les performances
  • Typographie lisible et professionnelle

Exemple de Rendu

📊 Bilan d'Évaluation
Contrôle Chapitre 3 - Fonctions - Marie DUPONT

📋 Informations sur l'évaluation
Classe: 3ème A | Date: 15/03/2025 | Trimestre: T2 | Coefficient: ×2

🎯 Note globale
15.5/20 (77.5%)
[■■■■■■■■□□] Barre de progression verte

📝 Résultats par exercice
Exercice 1: Calculs de base (8.0/10)
├─ Question 1a: Dérivées → 4/4 pts
├─ Question 1b: Limites → 3/4 pts  
└─ Question 1c: Primitives → 1/2 pts (Calcul différentiel: ⭐⭐☆)

⭐ Performances par compétences
Calcul différentiel: ⭐⭐☆ (12.5/18)
Raisonnement: ⭐⭐⭐ (15/15)

🏷️ Performances par domaines  
Analyse: ⭐⭐⭐ (16.5/18)
Algèbre: ⭐⭐☆ (11/15)

Position: 12e/28 élèves | Moyenne classe: 14.2/20

💬 Message du professeur
Très bon travail Marie ! Continue tes efforts en calcul différentiel.

🔒 Sécurité et Fiabilité

Validation et Protection

Validation des données :

  • Format des adresses email avec regex strict
  • Vérification de l'existence des élèves
  • Contrôle d'accès aux évaluations

Protection des données :

  • Mots de passe chiffrés en base de données
  • Authentification sécurisée SMTP
  • Logs sans données sensibles

Gestion d'erreurs robuste :

  • Timeouts configurables pour les connexions SMTP
  • Retry automatique avec backoff exponentiel
  • Messages d'erreur explicites et non techniques

Monitoring et Logs

Logs structurés JSON :

{
  "timestamp": "2025-03-15T14:30:25.123Z",
  "level": "INFO",
  "event_type": "student_report_sent", 
  "assessment_id": 15,
  "student_id": 42,
  "student_email": "marie.dupont@eleve.fr",
  "success": true,
  "correlation_id": "uuid-1234-5678"
}

Rapports d'envoi détaillés :

  • ✅ Nombre d'envois réussis avec destinataires
  • ❌ Erreurs détaillées par élève
  • 📊 Statistiques globales (taux de succès, durée)
  • 🔄 Possibilité de relance pour les échecs

📈 Cas d'Usage

Scénario Typique

  1. Professeur termine une évaluation

    • Toutes les notes sont saisies et validées
    • Indicateur "Correction 100%" affiché

  2. Accès aux résultats

    • Navigation via page de résultats
    • Bouton "📧 Envoyer les bilans" visible

  3. Sélection des destinataires

    • Interface avec liste des élèves
    • Cases à cocher avec validation emails
    • Exclusion automatique des adresses manquantes

  4. Personnalisation

    • Ajout d'un message d'encouragement
    • Prévisualisation d'un bilan type

  5. Envoi groupé

    • Génération automatique de 25 bilans individualisés
    • Envoi en 2-3 minutes
    • Suivi en temps réel

  6. Confirmation

    • Rapport détaillé : "23 envois réussis, 2 erreurs"
    • Liste des erreurs avec raisons explicites

  7. Réception par les élèves

    • Email professionnel dans la boîte de réception
    • Bilan détaillé consultable sur mobile/desktop
    • Analyses impossibles à obtenir sur papier

Bénéfices Pédagogiques

Pour l'enseignant :

  • ⏱️ Gain de temps massif : Plus de photocopies ni distribution
  • 📊 Analyses enrichies : Statistiques automatiques impossibles sur papier
  • 🌱 Impact écologique : Réduction drastique de l'usage papier
  • 📱 Communication moderne : Canal privilégié des familles

Pour les élèves/familles :

  • 📈 Feedback détaillé : Analyses par compétences et domaines
  • 🎯 Messages personnalisés : Conseils adaptés aux performances
  • 📊 Contexte de classe : Position et comparaisons statistiques
  • 📱 Accès immédiat : Consultation sur tous appareils

Pour l'établissement :

  • 💚 Démarche écologique : Réduction significative du papier
  • 📈 Communication digitale : Modernisation des échanges
  • 🔄 Traçabilité : Historique automatique des envois
  • 📊 Suivi longitudinal : Conservation des bilans précédents

🛠️ Guide de Développement

Extension du Système

Ajouter un nouveau fournisseur SMTP :

  1. Étendre la validation dans EmailService.is_configured()
  2. Ajouter les paramètres spécifiques dans la configuration
  3. Mettre à jour l'aide contextuelle dans templates/config/email.html

Personnaliser les templates email :

  1. Modifier templates/email/student_report.html
  2. Étendre templates/email/base_email.html pour le branding
  3. Tester avec le serveur de débogage local

Ajouter de nouvelles données aux bilans :

  1. Étendre StudentReportService.generate_student_report()
  2. Modifier le template pour afficher les nouvelles données
  3. Mettre à jour les tests correspondants

Tests et Debug

Lancer les tests du système email :

# Tests unitaires
uv run pytest tests/test_email_service.py -v

# Tests d'intégration  
uv run pytest tests/test_student_reports.py -v

# Test manuel avec serveur debug
python debug_smtp_server.py

Debugging des envois :

  • Consulter les logs : logs/notytex.log
  • Vérifier la configuration SMTP via l'interface web
  • Utiliser la prévisualisation pour valider les templates
  • Tester avec le serveur local avant production

🚀 Évolutions Prévues

Fonctionnalités Futures

Phase 1 - Améliorations UX :

  • Interface d'envoi avec prévisualisation en temps réel
  • Templates personnalisables par établissement
  • Planification d'envois différés

Phase 2 - Analytics :

  • Statistiques d'ouverture des emails
  • Taux de rebond et délivrabilité
  • Rapports d'envoi historiques

Phase 3 - Intégrations :

  • Export PDF des bilans
  • Intégration avec des services externes (Pronote, etc.)
  • API pour envois automatisés

📧 Système d'envoi de bilans opérationnel et prêt pour la production !