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

22 KiB
Raw Blame History

📋 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
    
    # Nouvelles méthodes 2025
    def get_student_special_values_summary(student_id, trimester) -> Dict[str, Any]
    def get_student_competence_domain_breakdown(student_id, trimester) -> Dict[str, List[Dict]]

GradeRepository (Nouvelles méthodes 2025)

# Repository étendu pour valeurs spéciales et commentaires
class GradeRepository:
    # Méthodes existantes...
    
    # Nouvelles méthodes pour valeurs spéciales
    def get_special_values_counts_by_student_trimester(student_id, trimester) -> Dict[str, int]
    def get_special_values_counts_by_student_assessment(student_id, assessment_id) -> Dict[str, int]
    def get_special_values_details_by_student_trimester(student_id, trimester) -> Dict[str, List[Dict]]
    def get_special_values_details_by_student_assessment(student_id, assessment_id) -> Dict[str, List[Dict]]
    
    # Nouvelle méthode pour commentaires organisés
    def get_all_comments_by_student_trimester(student_id, trimester) -> Dict[str, Any]

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'
    competence_domain_breakdown: Optional[Dict] = None  # Données compétences/domaines
    special_values_summary: Optional[Dict] = None  # Nouvelle: résumé valeurs spéciales et commentaires

Structure special_values_summary (Nouveau 2025)

special_values_summary = {
    # Résumé global des valeurs spéciales pour le trimestre
    "global": {
        ".": {"count": 2, "label": "Pas de réponse", "color": "#ef4444", "details": [...]},
        "d": {"count": 1, "label": "Dispensé", "color": "#6b7280", "details": [...]},
        "a": {"count": 1, "label": "Absent", "color": "#f59e0b", "details": [...]}
    },
    
    # Détail par évaluation
    "by_assessment": {
        1: {
            "title": "Contrôle Chapitre 1",
            "date": "2025-08-10",
            "special_values": {
                ".": {"count": 1, "label": "Pas de réponse", "details": [...]}
            }
        }
    },
    
    # Commentaires organisés par évaluations (Nouveau)
    "comments_by_assessments": {
        "assessments": [
            {
                "id": 1,
                "title": "Contrôle Chapitre 1 - Nombres entiers",
                "date": "2025-08-10",
                "comments": [
                    {
                        "element_label": "Additions",
                        "element_description": "Calculs simples",
                        "value": ".",
                        "comment": "Élève absent lors de cette question"
                    }
                ]
            }
        ],
        "total_comments": 3,
        "has_comments": true
    },
    
    # Métadonnées
    "total_special_values": 4,
    "has_special_values": true
}

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ésumé compact des valeurs spéciales -->
<div class="special-values-summary">
  <span class="text-gray-500">Valeurs spéciales:</span>
  <span class="badge-absent">. 2</span>  <!-- Absent/Pas de réponse -->
  <span class="badge-excused">d 1</span>  <!-- Dispensé -->
  <span class="badge-away">a 1</span>     <!-- Absent justifié -->
</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>

Vue détaillée expandable

Chaque carte élève peut être étendue pour révéler des informations complémentaires essentielles à la préparation du conseil de classe.

Valeurs spéciales par évaluation

<!-- Section des valeurs spéciales détaillées -->
<div class="special-values-detail">
  <h6>Valeurs spéciales</h6>
  <div class="assessment-special-values">
    <div class="assessment-row">
      <span>Contrôle Chapitre 1</span>
      <div class="special-badges">
        <span class="badge" title="Pas de réponse (2)">. 2</span>
        <span class="badge" title="Dispensé (1)">d 1</span>
      </div>
    </div>
  </div>
</div>

Commentaires enseignant organisés 📝

Nouvelle fonctionnalité 2025 : Affichage compact et structuré de tous les commentaires saisis par l'enseignant.

<!-- Section des commentaires par évaluation -->
<div class="comments-section">
  <h6>Commentaires (3)</h6>
  
  <!-- Regroupement par évaluation -->
  <div class="assessment-comments">
    <div class="assessment-group">
      <div class="assessment-header">
        <span class="assessment-title">Contrôle Chapitre 1 - Nombres entiers</span>
        <span class="comment-count">3 commentaire(s)</span>
      </div>
      
      <!-- Commentaires compacts sur 2 lignes -->
      <div class="comments-list">
        <div class="comment-item">
          <!-- Ligne 1: Label • Description -->
          <div class="element-info">Additions • Calculs simples</div>
          <!-- Ligne 2: [Valeur] Commentaire -->
          <div class="comment-content">
            <span class="value-badge">.</span>
            <span class="comment-text">Élève absent lors de cette question</span>
          </div>
        </div>
        
        <div class="comment-item">
          <div class="element-info">Multiplications • Tables et calculs</div>
          <div class="comment-content">
            <span class="value-badge">d</span>
            <span class="comment-text">Dispensé par décision médicale</span>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

Structure des données commentaires

# Nouvelle structure pour les commentaires
comments_by_assessments = {
    "assessments": [
        {
            "id": 1,
            "title": "Contrôle Chapitre 1 - Nombres entiers",
            "date": "2025-08-10",
            "comments": [
                {
                    "element_label": "Additions",
                    "element_description": "Calculs simples",
                    "value": ".",  # Valeur optionnelle (peut être None)
                    "comment": "Élève absent lors de cette question",
                    "exercise_title": "Exercice 1"
                }
            ]
        }
    ],
    "total_comments": 3,
    "has_comments": true
}

Avantages de l'affichage compact

  • Gain d'espace : 2 lignes par commentaire maximum
  • Contexte complet : Label, description, valeur et commentaire visibles
  • Organisation logique : Regroupement par évaluation chronologique
  • Lecture rapide : Information hiérarchisée et codes couleur cohérents
  • Positionnement optimal : Après résultats et valeurs spéciales, avant compétences

🎛️ 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

Analyse des valeurs spéciales et commentaires 📊

Nouveauté 2025 : Système complet d'analyse des valeurs spéciales (absences, dispenses) et des commentaires enseignant pour faciliter la préparation des conseils de classe.

Valeurs spéciales configurables

  • Configuration dynamique : Valeurs et couleurs modifiables via interface d'administration
  • Valeurs par défaut : . (Pas de réponse), d (Dispensé), a (Absent)
  • Comptage automatique : Calcul global et par évaluation en temps réel
  • Tooltips informatifs : Détail des éléments concernés au survol

Commentaires structurés

  • Regroupement intelligent : Organisation automatique par évaluation
  • Affichage compact : 2 lignes par commentaire (contexte + contenu)
  • Métadonnées complètes : Label, description, valeur associée
  • Tri chronologique : Évaluations les plus récentes en premier

Bénéfices pédagogiques

  • Vue d'ensemble rapide : Identification immédiate des difficultés
  • Contexte enrichi : Commentaires précédents accessibles lors des discussions
  • Suivi longitudinal : Évolution des problématiques par trimestre
  • Préparation optimisée : Toutes les informations centralisé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 Récentes et Futures

Version 2.0.1 (Août 2025) ✅

  • Valeurs spéciales : Comptage et affichage automatiques (., d, a)
  • Commentaires structurés : Organisation par évaluation avec affichage compact
  • Repository étendu : Nouvelles méthodes optimisées pour l'analyse
  • Interface enrichie : Vue détaillée expandable avec toutes les données contextuelles

Version 2.1 (Roadmap)

  • 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
  • Export enrichi : PDF avec valeurs spéciales et commentaires

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
  • 🆕 Valeurs spéciales : Comptage automatique des absences et dispenses
  • 🆕 Commentaires structurés : Historique organisé par évaluation
  • 🆕 Vue contextuelle : Toutes les données pédagogiques centralisées

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