feat: add concil page

2025-08-11 06:01:23 +02:00
parent 13f0e69bb0
commit c132419213
17 changed files with 5072 additions and 12 deletions
--- a/docs/features/CONSEIL_DE_CLASSE.md
+++ b/docs/features/CONSEIL_DE_CLASSE.md
@@ -0,0 +1,440 @@
+# 📋 Préparation du Conseil de Classe
+
+La **Préparation du Conseil de Classe** est une fonctionnalité avancée de Notytex qui permet aux enseignants de préparer efficacement leurs conseils de classe en centralisant les données d'évaluation et en rédigeant les appréciations individuelles.
+
+## 🎯 Vue d'ensemble
+
+### Objectifs principaux
+- **Centraliser** les résultats de tous les élèves pour un trimestre donné
+- **Rédiger** les appréciations individuelles avec auto-sauvegarde
+- **Analyser** les performances de classe avec statistiques automatiques
+- **Optimiser** le workflow avec deux modes de visualisation
+
+### Accès à la fonctionnalité
+```
+Navigation : Classes → [Nom de la classe] → Dashboard → Conseil de classe T[X]
+URL : /classes/{id}/council?trimestre={1|2|3}
+```
+
+## 📊 Architecture des Données
+
+### Services principaux
+
+#### CouncilPreparationService
+```python
+# Orchestrateur principal
+class CouncilPreparationService:
+    def prepare_council_data(class_id, trimester) -> CouncilPreparationData
+```
+
+#### StudentEvaluationService  
+```python
+# Calculs et analyse des performances
+class StudentEvaluationService:
+    def get_students_summaries(class_id, trimester) -> List[StudentTrimesterSummary]
+    def calculate_student_trimester_average(student_id, trimester) -> float
+```
+
+#### AppreciationService
+```python
+# Gestion des appréciations
+class AppreciationService:
+    def save_appreciation(data) -> CouncilAppreciation
+    def auto_save_appreciation(data) -> CouncilAppreciation
+```
+
+### Modèles de données
+
+#### StudentTrimesterSummary
+```python
+@dataclass
+class StudentTrimesterSummary:
+    student: Student
+    overall_average: Optional[float]
+    assessment_count: int
+    grades_by_assessment: Dict[int, Dict]  # {assessment_id: {score, max, title}}
+    appreciation: Optional[CouncilAppreciation]
+    performance_status: str  # 'excellent', 'good', 'average', 'struggling'
+```
+
+#### CouncilPreparationData
+```python
+@dataclass  
+class CouncilPreparationData:
+    class_group_id: int
+    trimester: int
+    student_summaries: List[StudentTrimesterSummary]
+    class_statistics: Dict
+    appreciation_stats: Dict
+    total_students: int
+    completed_appreciations: int
+```
+
+## 🎨 Interface Utilisateur
+
+### Page principale
+
+#### Section Hero
+- **Informations contextuelles** : Classe, trimestre, nombre d'élèves
+- **Sélecteur de trimestre** : Navigation rapide entre T1, T2, T3
+- **Actions principales** : Export PDF, Synthèse de classe, Mode Focus
+
+#### Statistiques de classe
+```javascript
+{
+  "mean": 14.2,           // Moyenne générale
+  "median": 14.5,         // Médiane
+  "min": 8.5,            // Note minimum
+  "max": 18.5,           // Note maximum  
+  "std_dev": 2.1,        // Écart-type
+  "performance_distribution": {
+    "excellent": 3,       // ≥ 16/20
+    "good": 8,           // ≥ 14/20
+    "average": 12,       // ≥ 10/20
+    "struggling": 2,     // < 10/20
+    "no_data": 0
+  }
+}
+```
+
+#### Filtres et recherche
+- **Recherche par nom** : Filtre instantané (300ms debounce)
+- **Tri** : Alphabétique, par moyenne, par statut de performance
+- **Filtre par statut** : Toutes, Appréciations terminées, En attente, En difficulté
+
+### Cartes élèves individuelles
+
+#### Informations affichées
+```html
+<!-- En-tête de carte -->
+<div class="student-card-header">
+  <h3>NOM Prénom</h3>
+  <div class="performance-badge">[excellent|good|average|struggling]</div>
+  <div class="appreciation-status">[Rédigée|À rédiger]</div>
+</div>
+
+<!-- Résultats par évaluation -->
+<div class="assessment-results">
+  <div class="assessment-item">
+    <span>Évaluation Title</span>
+    <span>15.5/20</span>
+  </div>
+</div>
+
+<!-- Zone d'appréciation (expansible) -->
+<div class="appreciation-area">
+  <textarea placeholder="Rédiger l'appréciation..."></textarea>
+  <div class="appreciation-controls">
+    <button>Sauvegarder</button>
+    <div class="save-indicator">Auto-sauvegarde...</div>
+  </div>
+</div>
+```
+
+## 🎛️ Modes de Visualisation
+
+### Mode Liste (par défaut)
+- **Vue d'ensemble** : Toutes les cartes élèves simultanément
+- **Filtres actifs** : Recherche, tri et filtres disponibles
+- **Actions globales** : Export PDF, synthèse de classe
+- **Navigation** : Scroll vertical traditionnel
+
+### Mode Focus 🎯
+- **Vue unitaire** : Un seul élève à la fois
+- **Interface minimale** : Hero, filtres et actions masqués
+- **Navigation dédiée** : Boutons Précédent/Suivant + raccourcis clavier
+- **Focus automatique** : Curseur positionné dans le textarea
+- **Optimisation** : Pas de scroll, interface pleine hauteur
+
+#### Activation du Mode Focus
+```javascript
+// Bouton ou raccourci
+document.querySelector('[data-toggle-focus-mode]').click();
+
+// Raccourcis clavier en mode focus
+// ← : Élève précédent
+// → : Élève suivant  
+// Échap : Retour mode liste
+```
+
+## 💾 Système de Sauvegarde
+
+### Auto-sauvegarde intelligente
+- **Délai** : 2 secondes après arrêt de frappe (debounce)
+- **Événements** : `input` (auto), `blur` (immédiat)
+- **Visual feedback** : Indicateurs colorés temps réel
+
+### États visuels
+```javascript
+// États des indicateurs de sauvegarde
+{
+  "modified": "bg-yellow-100 text-yellow-800",  // Modifié
+  "saving": "bg-blue-100 text-blue-800",       // Sauvegarde...
+  "saved": "bg-green-100 text-green-800",      // Sauvegardé ✓
+  "error": "bg-red-100 text-red-800"           // Erreur ✗
+}
+```
+
+### Synchronisation bidirectionnelle
+- **Focus → Liste** : Modifications synchronisées automatiquement
+- **Statut partagé** : Indicateur "Rédigée/À rédiger" mis à jour
+- **Données persistantes** : Dernière modification horodatée
+
+## 🔄 API et Endpoints
+
+### Routes principales
+
+#### Page de préparation
+```python
+@bp.route('/<int:id>/council')
+def council_preparation(id):
+    # GET /classes/5/council?trimestre=2
+    # Affiche la page complète de préparation
+```
+
+#### Sauvegarde d'appréciation
+```python
+@bp.route('/<int:class_id>/council/appreciation/<int:student_id>', methods=['POST'])
+def save_appreciation_api(class_id, student_id):
+    # POST /classes/5/council/appreciation/123
+    # Body: {"appreciation": "text", "trimester": 2}
+    # Response: {"success": true, "appreciation_id": 456}
+```
+
+#### Données par trimestre
+```python
+@bp.route('/<int:class_id>/council/api')
+def council_data_api(class_id):
+    # GET /classes/5/council/api?trimestre=2
+    # Response: JSON avec tous les données élèves
+```
+
+### Format des requêtes AJAX
+
+#### Sauvegarde d'appréciation
+```javascript
+const response = await fetch(`/classes/${classId}/council/appreciation/${studentId}`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Requested-With': 'XMLHttpRequest'
+  },
+  body: JSON.stringify({
+    appreciation: "Élève sérieux et appliqué...",
+    trimester: 2,
+    strengths: "Participation active",
+    areas_for_improvement: "Organisation des révisions"
+  })
+});
+```
+
+#### Réponse type
+```javascript
+{
+  "success": true,
+  "appreciation_id": 789,
+  "last_modified": "2025-08-10T14:30:00.000Z",
+  "status": "draft",
+  "has_content": true
+}
+```
+
+## ⚡ Architecture JavaScript
+
+### Classe principale
+```javascript
+class CouncilPreparation {
+  constructor(classId, options = {})
+  
+  // Modules spécialisés
+  stateManager: StateManager        // Gestion d'état et persistance URL
+  filterManager: FilterManager      // Filtres, tri, recherche
+  autoSaveManager: AutoSaveManager  // Auto-sauvegarde intelligente
+  uiManager: UIManager             // Animation des cartes
+  focusManager: FocusManager       // Mode focus complet
+}
+```
+
+### Gestionnaires spécialisés
+
+#### FocusManager
+```javascript
+class FocusManager {
+  toggleFocusMode(forcedState = null)     // Basculer entre modes
+  showCurrentStudent()                    // Afficher élève courant
+  navigatePrevious() / navigateNext()     // Navigation
+  focusAppreciationTextarea()             // Focus automatique
+  bindFocusStudentEvents()                // Événements élément cloné
+  syncAppreciationToOriginal()            // Sync bidirectionnelle
+}
+```
+
+#### AutoSaveManager
+```javascript
+class AutoSaveManager {
+  queueSave(studentId, appreciation, immediate)  // File de sauvegarde
+  executeSave(saveTask)                         // Exécution HTTP
+  showSavingState() / showSavedState()          // États visuels
+  updateAppreciationStatus()                    // Sync statuts
+}
+```
+
+### État centralisé
+```javascript
+this.state = {
+  currentTrimester: 2,
+  expandedStudents: new Set(),          // Cartes ouvertes
+  searchTerm: '',
+  sortBy: 'alphabetical',
+  filterStatus: 'all',
+  savingStates: new Map(),              // États de sauvegarde  
+  modifiedAppreciations: new Set(),     // Appréciations modifiées
+  
+  // Mode Focus
+  isFocusMode: false,
+  focusCurrentIndex: 0,
+  filteredStudents: []                  // Liste filtrée pour navigation
+}
+```
+
+## 🎯 Fonctionnalités Avancées
+
+### Raccourcis clavier globaux
+```javascript
+// Raccourcis disponibles
+Ctrl/Cmd + S  : Sauvegarder toutes les appréciations pending
+Ctrl/Cmd + F  : Focus sur champ de recherche
+
+// En mode Focus uniquement  
+←            : Élève précédent
+→            : Élève suivant
+Échap        : Retour au mode liste
+```
+
+### Animations et transitions
+- **Cartes** : Animation d'expansion/contraction fluide (300ms)
+- **Filtres** : Apparition staggered des résultats (50ms par élément)
+- **Mode Focus** : Transition interface sans saut visuel
+- **Sauvegarde** : Indicateurs animés (spinner, fade)
+
+### Gestion d'erreurs
+- **Validation côté client** : Champs obligatoires, longueur
+- **Retry automatique** : En cas d'erreur réseau temporaire
+- **États dégradés** : Fonctionnement offline partiel
+- **Messages contextuels** : Toasts informatifs
+
+## 📱 Responsive Design
+
+### Breakpoints
+- **Mobile** (`< 768px`) : Navigation tactile, cartes stack
+- **Tablette** (`768-1024px`) : Interface hybride
+- **Desktop** (`> 1024px`) : Interface complète
+
+### Optimisations mobile
+- **Touch gestures** : Swipe pour navigation en mode focus
+- **Keyboard friendly** : Focus automatique sans clavier virtuel gênant
+- **Performance** : Lazy loading, virtual scrolling pour grandes classes
+
+## 🔧 Configuration et Paramétrage
+
+### Options par défaut
+```javascript
+const defaultOptions = {
+  debounceTime: 2000,           // Auto-sauvegarde (ms)
+  searchDebounceTime: 300,      // Recherche instantanée (ms)
+  cacheTimeout: 10 * 60 * 1000, // Cache données (10min)
+  animationDuration: 300,       // Durée animations (ms)
+  enableTouchGestures: true     // Gestes tactiles
+}
+```
+
+### Variables d'environnement
+```env
+# Configuration spécifique conseil de classe
+COUNCIL_AUTO_SAVE_INTERVAL=2000
+COUNCIL_CACHE_TIMEOUT=600000
+COUNCIL_MAX_APPRECIATION_LENGTH=2000
+```
+
+## 🧪 Tests et Débogage
+
+### Tests automatisés
+```bash
+# Tests complets du module conseil
+uv run pytest tests/test_council_services.py -v
+
+# Tests JavaScript (si configuré)  
+npm run test:council-preparation
+```
+
+### Debugging JavaScript
+```javascript
+// Console logs disponibles par défaut
+console.log('🎯 Mode Focus activé');
+console.log('💾 Sauvegarde en cours pour élève 123');
+console.log('✅ Synchronisation bidirectionnelle OK');
+console.log('⬅️ Navigation vers élève précédent');
+```
+
+### Monitoring
+- **Performance** : Temps de chargement, auto-sauvegarde
+- **Erreurs** : Taux d'échec sauvegarde, problèmes réseau
+- **Usage** : Mode préféré, temps passé par appréciation
+
+## 📋 Guide d'Utilisation Enseignant
+
+### Workflow recommandé
+
+#### 1. Préparation (avant le conseil)
+1. **Naviguer** vers la classe concernée
+2. **Sélectionner** le trimestre approprié
+3. **Analyser** les statistiques de classe
+4. **Identifier** les élèves prioritaires (filtrer par "struggling")
+
+#### 2. Rédaction des appréciations
+1. **Activer le mode Focus** pour une meilleure concentration
+2. **Naviguer** élève par élève avec ←/→
+3. **Rédiger** directement dans le textarea (focus automatique)
+4. **Valider** la sauvegarde automatique (indicateur vert)
+
+#### 3. Finalisation
+1. **Revenir en mode Liste** pour vue d'ensemble
+2. **Vérifier** que toutes les appréciations sont "Rédigées"
+3. **Exporter en PDF** pour impression/archivage
+4. **Générer la synthèse** de classe
+
+### Bonnes pratiques
+- **Sauvegarde régulière** : Laisser l'auto-sauvegarde opérer
+- **Navigation efficace** : Utiliser les raccourcis clavier
+- **Structuration** : Commencer par les cas prioritaires
+- **Révision** : Mode Liste final pour cohérence globale
+
+## 🔄 Évolutions Futures
+
+### Version 2.1
+- [ ] **Collaboration** : Plusieurs enseignants simultanément
+- [ ] **Templates** : Appréciations pré-rédigées personnalisables
+- [ ] **IA Assistant** : Suggestions d'amélioration automatiques
+- [ ] **Analytics** : Tendances longitudinales élèves
+
+### Version 2.2  
+- [ ] **Mobile App** : Application native iOS/Android
+- [ ] **Voice-to-text** : Dictée vocale des appréciations
+- [ ] **Integration ENT** : Synchronisation avec Pronote/Scolinfo
+- [ ] **PDF Avancé** : Mise en page personnalisée
+
+---
+
+## 🎓 Conclusion
+
+La **Préparation du Conseil de Classe** de Notytex révolutionne le workflow traditionnel des enseignants en offrant :
+
+- ✅ **Interface moderne** avec Mode Focus innovant
+- ✅ **Auto-sauvegarde intelligente** et synchronisation temps réel
+- ✅ **Analyse statistique** automatique des performances
+- ✅ **Navigation optimisée** avec raccourcis clavier
+- ✅ **Architecture robuste** avec gestion d'erreurs complète
+
+Cette fonctionnalité transforme une tâche chronophage en un processus fluide et efficace, permettant aux enseignants de se concentrer sur l'essentiel : l'analyse pédagogique et la rédaction d'appréciations personnalisées.
+
+**Développé avec ❤️ par l'équipe Notytex**