notytex/docs/features/CONSEIL_DE_CLASSE.md

📋 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

# Orchestrateur principal
class CouncilPreparationService:
    def prepare_council_data(class_id, trimester) -> CouncilPreparationData

StudentEvaluationService

# 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

# Gestion des appréciations
class AppreciationService:
    def save_appreciation(data) -> CouncilAppreciation
    def auto_save_appreciation(data) -> CouncilAppreciation

Modèles de données

StudentTrimesterSummary

@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

@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

{
  "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

<!-- 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

// 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

// É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

@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

@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

@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

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

{
  "success": true,
  "appreciation_id": 789,
  "last_modified": "2025-08-10T14:30:00.000Z",
  "status": "draft",
  "has_content": true
}

⚡ Architecture JavaScript

Classe principale

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

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

class AutoSaveManager {
  queueSave(studentId, appreciation, immediate)  // File de sauvegarde
  executeSave(saveTask)                         // Exécution HTTP
  showSavingState() / showSavedState()          // États visuels
  updateAppreciationStatus()                    // Sync statuts
}

État centralisé

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

// 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

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

# 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

# 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

// 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