notytex/docs/features/EMAIL_REPORTS.md

# 📧 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` :

```python
# 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
- **Serveur** : smtp.gmail.com
- **Port** : 587 (TLS)
- **Sécurité** : Mot de passe d'application requis
- **Documentation** : [Mots de passe d'application Google](https://support.google.com/accounts/answer/185833)

#### 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 :

```bash
# 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 :**
```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 :**
```bash
# 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 !**