Files
notytex/docs/features/CONSEIL_DE_CLASSE.md

644 lines
22 KiB
Markdown

# 📋 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
# 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)
```python
# 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
```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'
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)
```python
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
```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é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
```html
<!-- 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.
```html
<!-- 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
```python
# 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
```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
### 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
```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 Récentes et Futures
### Version 2.0.1 (Août 2025) ✅
- [x] **Valeurs spéciales** : Comptage et affichage automatiques (`.`, `d`, `a`)
- [x] **Commentaires structurés** : Organisation par évaluation avec affichage compact
- [x] **Repository étendu** : Nouvelles méthodes optimisées pour l'analyse
- [x] **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**