lafrite/notytex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Checkpoint avant migration v1 (Flask) -> v2 (FastAPI + Vue.js)

Browse Source
This commit is contained in:
Bertrand Benjamin
2025-11-25 21:04:47 +01:00
parent 75b03c24ed
commit 60c60c1605
4015 changed files with 441464 additions and 446 deletions
Download Patch File Download Diff File Expand all files Collapse all files

264
CLAUDE.md
View File

@@ -6,7 +6,7 @@
Simplifier et digitaliser le processus d'évaluation scolaire, de la création des contrôles à la saisie des notes, en offrant une structure hiérarchique flexible et deux modes de notation.
## 🏗️ **Architecture Technique (Phase 1 - Refactorisée)**
## 🏗️ **Architecture Technique **
**Framework :** Flask (Python) avec architecture modulaire découplée
**Base de données :** SQLite avec SQLAlchemy ORM + Repository Pattern
@@ -42,7 +42,7 @@ Grade (Note attribuée à chaque élève)
- Interface unifiée pour créer évaluation + exercices + barème en une fois
- Modification et suppression avec gestion des cascades
### **Système de Notation Unifié (Phase 2 - 2025)**
### **Système de Notation Unifié **
**2 Types de Notation Fixes :**
@@ -80,7 +80,7 @@ Grade (Note attribuée à chaque élève)
- **Persistence des filtres** : État maintenu dans l'URL pour navigation intuitive
- **Interface responsive** : Adaptée aux appareils mobiles et desktop
### **Interface Utilisateur & UX Moderne (Phase 2 - Décembre 2024)**
### **Interface Utilisateur & UX Moderne **
- **Dashboard avec statistiques en temps réel** : Cartes cliquables avec animations et gradients
- **Pages hero modernisées** : Sections d'accueil avec gradients colorés et informations contextuelles
@@ -95,15 +95,17 @@ Grade (Note attribuée à chaque élève)
- **Indicateurs de progression de correction** : Visualisation immédiate avec cercles de progression et actions intégrées
- **Interface cohérente** : Design system unifié avec espacements, couleurs et animations harmonieux
### **Gestion des Élèves et Import CSV (Nouvelle Fonctionnalité - 2025)**
### **Gestion des Élèves et Import CSV **
**Gestion Individuelle des Élèves :**
- **Inscription manuelle** : Création d'élèves un par un avec prénom, nom, email optionnel
- **Système d'inscription temporel** : Historique complet avec dates d'arrivée/départ
- **Gestion des mouvements** : Transferts entre classes, départs, réintégrations
- **Interface moderne** : Modal avec onglets (nouvel élève / élève existant)
**Import en Lot depuis CSV :**
- **Format CSV supporté** : Séparateur `;`, première colonne "NOM Prénoms"
- **Extraction intelligente** : Reconnaissance automatique nom/prénom ("DUPONT Marie Claire" → nom: "DUPONT", prénom: "Marie Claire")
- **Gestion des doublons** : Option pour ignorer ou échouer en cas d'élève existant
@@ -112,7 +114,8 @@ Grade (Note attribuée à chaque élève)
- **Interface intuitive** : Modal avec drag & drop, instructions du format attendu
**Points d'Accès Multiples :**
- **Dashboard de classe** : Carte d'action violette "Import CSV"
- **Dashboard de classe** : Carte d'action violette "Import CSV"
- **Page gestion élèves** : Bouton "Import CSV" dans la barre d'actions
- **Navigation cohérente** : Accès contextuel selon le workflow utilisateur
@@ -125,7 +128,7 @@ Grade (Note attribuée à chaque élève)
- **Calcul intelligent des scores** : Gestion des types "points" et "compétences" avec formules spécialisées
- **Traitement des absences** : Score "." = 0 point mais compte dans le total possible
## 🔧 **Structure du Code (Phase 1 - Architecture Refactorisée)**
## 🔧 **Structure du Code **
```
app.py # Application Flask principale + routes de base
@@ -167,7 +170,7 @@ templates/ # Templates Jinja2 avec indicateurs UX intégrés
🧪 tests/ # Tests pytest (100 tests ✅)
```
## 🚀 **Installation & Lancement (Phase 1)**
## 🚀 **Installation & Lancement **
```bash
# Installation avec uv (gestionnaire moderne)
@@ -190,7 +193,7 @@ uv run pytest
tail -f logs/notytex.log
```
## 🧪 **Qualité du Code (Phase 1 - Renforcée)**
## 🧪 **Qualité du Code **
- **Tests pytest avec 100% de réussite** (100 tests ✅)
- **Architecture découplée** : Repository Pattern + Dependency Injection
@@ -203,6 +206,7 @@ tail -f logs/notytex.log
## 📝 **Cas d'Usage Typiques**
### **Scénario A : Évaluation Complète**
1. **Professeur crée une évaluation** : "Contrôle Chapitre 3 - Fonctions" pour le 2ème trimestre
2. **Définit les paramètres** : Date, trimestre (obligatoire), classe, coefficient
3. **Ajoute des exercices** : "Exercice 1: Calculs", "Exercice 2: Graphiques"
@@ -214,6 +218,7 @@ tail -f logs/notytex.log
9. **Analyse les performances** : Statistiques descriptives, distribution des notes et classement alphabétique
### **Scénario B : Import d'Élèves en Masse (Nouveau)**
1. **Professeur accède au dashboard** de la classe "6ème A"
2. **Clique sur "Import CSV"** depuis la carte d'action violette ou la page des élèves
3. **Prépare le fichier CSV** : Export depuis le logiciel administratif avec colonnes séparées par `;`
@@ -223,7 +228,7 @@ tail -f logs/notytex.log
7. **Consulte le rapport** : "15 élèves importés, 2 ignorés (doublons), 0 erreur"
8. **Vérifie la liste** : Redirection automatique vers la page des élèves mise à jour
## Volumétrie de milieu d'année (milieu du 2e trimestre)
## Volumétrie de milieu d'année
- 5 classes d'entre 25 et 35 élèves
- Les évaluations sont constitués d'entre 10 et 20 éléments de notations
@@ -349,13 +354,11 @@ notytex/
### **🌟 Débutant - Familiarisation**
1. **Ajouter un champ à un modèle existant**
- Fichier : `models.py`
- Exemple : Ajouter un champ "commentaire" à Student
- Impact : Migration DB + template + form
2. **Modifier l'apparence d'une page**
- Fichiers : `templates/*.html`
- Technologie : TailwindCSS
- Exemple : Changer les couleurs du dashboard
@@ -368,14 +371,12 @@ notytex/
### **🔥 Intermédiaire - Nouvelles Fonctionnalités**
1. **Créer une nouvelle page**
- Blueprint dans `routes/`
- Template correspondant
- Formulaire si nécessaire
- Tests
2. **Ajouter un système d'export**
- Route d'export (PDF, Excel, CSV)
- Template de génération
- Boutons dans l'interface
@@ -388,13 +389,11 @@ notytex/
### **⚡ Avancé - Architecture**
1. **Optimiser les performances**
- Requêtes SQLAlchemy (N+1 queries)
- Cache des calculs coûteux
- Lazy loading intelligent
2. **Ajouter des API REST**
- Endpoints JSON
- Authentification
- Documentation OpenAPI
@@ -580,30 +579,9 @@ def get_current_app():
- [pytest](https://docs.pytest.org/) - Framework de tests
- [Flask-Shell](https://flask.palletsprojects.com/en/2.3.x/shell/) - Console interactive
### **Extensions Recommandées VSCode**
- Python
- Flask Snippets
- Jinja2
- SQLite Viewer
- TailwindCSS IntelliSense
## 🚀 **Prochaines Étapes**
Après avoir lu ce guide :
1. **Installer et lancer** l'application
2. **Explorer l'interface** en créant une évaluation test
3. **Lire le code** des modèles principaux (`models.py`)
4. **Faire une petite modification** (ex: changer une couleur)
5. **Lancer les tests** pour vérifier que tout fonctionne
6. **Choisir une tâche** dans les points d'entrée selon votre niveau
**Bienvenue dans l'équipe Notytex ! 🎓**
---
## 📧 **Système d'Envoi de Bilans par Email (Nouvelle Fonctionnalité - 2025)**
## 📧 **Système d'Envoi de Bilans par Email**
**Notytex** intègre désormais un système complet d'envoi automatique des bilans d'évaluation individuels par email aux élèves et à leurs familles.
@@ -631,6 +609,7 @@ templates/email/
### **📊 Contenu des Bilans**
Chaque bilan inclut :
- **Note globale** avec visualisation colorée et position dans la classe
- **Détail par exercice** et questions individuelles
- **Analyses par compétences** avec système d'étoiles visuelles
@@ -647,214 +626,3 @@ Chaque bilan inclut :
5. **Réception professionnelle** par les élèves et familles
**📖 Documentation complète** : [docs/features/EMAIL_REPORTS.md](docs/features/EMAIL_REPORTS.md)
---
# 🚀 **Améliorations Phase 1 - Architecture Refactorisée (2025)**
## ✅ **Refactoring Complet Selon les Principes 12 Factor App**
La **Phase 1** de refactoring a transformé Notytex en une application **robuste, sécurisée et prête pour la production**, en appliquant les meilleures pratiques d'architecture logicielle.
### 🔧 **1. Configuration Externalisée Sécurisée**
**Avant** : Configuration en dur avec clés secrètes dans le code
```python
# ❌ Ancien : Sécurité compromise
SECRET_KEY = os.urandom(32) # Différent à chaque redémarrage
```
**Après** : Configuration robuste avec validation
```python
# ✅ Nouveau : Configuration sécurisée
# config/settings.py
class Settings:
@property
def SECRET_KEY(self) -> str:
key = os.environ.get('SECRET_KEY')
if not key or len(key) < 32:
raise ValueError("SECRET_KEY invalide")
return key
```
**🎯 Bénéfices :**
- **Sécurité renforcée** : Plus de données sensibles en dur
- **Configuration flexible** : Variables d'environnement (.env)
- **Validation au démarrage** : Échec rapide si configuration incorrecte
- **Conformité 12 Factor App** : Séparation strict config/code
### 🛡️ **2. Gestion d'Erreurs Centralisée**
**Avant** : Gestion d'erreurs dispersée et incohérente
```python
# ❌ Ancien : Gestion ad-hoc
try:
# logique métier
except Exception as e:
flash("Erreur") # Gestion incohérente
```
**Après** : Gestionnaires d'erreurs globaux
```python
# ✅ Nouveau : Gestion centralisée
# exceptions/handlers.py
@app.errorhandler(ValidationError)
def handle_validation_error(error):
if request.is_json:
return jsonify({'success': False, 'error': str(error)}), 400
return render_template('error.html', error=str(error)), 400
```
**🎯 Bénéfices :**
- **Gestion unifiée** : Toutes les erreurs traitées de manière cohérente
- **Support JSON/HTML** : API et interface web harmonisées
- **Logs automatiques** : Traçabilité complète des erreurs
- **Expérience utilisateur** : Messages d'erreur clairs et uniformes
### 🔍 **3. Logging Structuré JSON**
**Avant** : Logs textuels basiques difficiles à analyser
```python
# ❌ Ancien : Logs non structurés
app.logger.info(f'Utilisateur {user} a créé évaluation {assessment}')
```
**Après** : Logs JSON avec corrélation des requêtes
```python
# ✅ Nouveau : Logs structurés
# core/logging.py
{
"timestamp": "2025-08-05T10:30:45.123Z",
"level": "INFO",
"message": "Événement métier : assessment_created",
"correlation_id": "uuid-1234-5678",
"request": {
"method": "POST",
"url": "/assessments/create",
"remote_addr": "192.168.1.100"
},
"extra": {
"event_type": "assessment_created",
"assessment_id": 123
}
}
```
**🎯 Bénéfices :**
- **Traçabilité complète** : ID de corrélation pour suivre les requêtes
- **Analyse facilitée** : Logs exploitables par des outils (ELK, Splunk)
- **Contexte riche** : URL, IP, user-agent automatiquement capturés
- **Debugging avancé** : Stack traces structurées
### 📦 **4. Repository Pattern pour l'Accès aux Données**
**Avant** : Accès direct aux modèles dans les contrôleurs
```python
# ❌ Ancien : Couplage fort
def assessments_list():
assessments = Assessment.query.filter_by(trimester=1).all()
return render_template('assessments.html', assessments=assessments)
```
**Après** : Couche Repository découplée
```python
# ✅ Nouveau : Accès découplé
# repositories/assessment_repository.py
class AssessmentRepository:
def find_by_filters(self, trimester=None, class_id=None, sort_by='date_desc'):
query = Assessment.query.options(joinedload(Assessment.class_group))
# Logique de filtrage réutilisable
return query.all()
# Dans le contrôleur
def assessments_list():
repo = AssessmentRepository()
assessments = repo.find_by_filters(trimester=1)
return render_template('assessments.html', assessments=assessments)
```
**🎯 Bénéfices :**
- **Séparation des responsabilités** : Logique d'accès données isolée
- **Réutilisabilité** : Requêtes complexes réutilisables
- **Testabilité** : Repositories mockables indépendamment
- **Maintenabilité** : Évolution facilitée des requêtes
## 🏆 **Résultats de la Phase 1**
### 📊 **Métriques de Qualité**
- **100 tests passent** ✅ (vs 79 avant refactoring)
- **0 régression fonctionnelle** ✅
- **Architecture découplée** ✅
- **Sécurité renforcée** ✅
### 🎯 **Prêt pour la Production**
- **Configuration externalisée** : Variables d'environnement
- **Logs exploitables** : JSON structuré avec corrélation
- **Gestion d'erreurs robuste** : Gestionnaires centralisés
- **Architecture évolutive** : Repository Pattern + DI
### 🚀 **Prochaines Phases**
**Phase 2 - Performance & Architecture** (En cours)
- Services découplés avec injection de dépendances
- Validation centralisée avec Pydantic
- Cache layer pour optimiser les performances
- Pagination des listes longues
- **Import CSV d'élèves** ✅ **NOUVEAU** - Fonctionnalité complète avec extraction intelligente des noms
- Métriques et monitoring avancés
**Phase 3 - Finalisation**
- Tests d'intégration complets
- Documentation API complète
- Pipeline CI/CD
---
**Notytex v2.1** est maintenant une application **moderne, robuste et sécurisée**, respectant les meilleures pratiques de l'industrie et prête pour un déploiement professionnel ! 🎓✨
---
## 🚀 **Dernières Améliorations - Janvier 2025**
### **✨ Import CSV d'Élèves - Fonctionnalité Complète**
**Architecture Technique :**
```
📋 services/csv_import_service.py # Service d'import avec extraction intelligente
📁 routes/classes.py # Route POST /classes/<id>/import-students-csv
📝 forms.py # CSVImportForm avec validation fichier
🖥️ templates/ # Modals d'import dans dashboard et page élèves
```
**Logique d'Extraction Avancée :**
- **Reconnaissance patterns** : "MARTIN Marie" → (nom: "MARTIN", prénom: "Marie")
- **Noms composés** : "AABIDA LAHDILI Fatima Zahra" → (nom: "AABIDA LAHDILI", prénom: "Fatima Zahra")
- **Validation robuste** : Format CSV, taille fichier, encodage UTF-8 avec BOM
- **Rapport d'import détaillé** : Ligne par ligne avec gestion des erreurs et doublons
**Interface Utilisateur :**
- **Accès contextuel** : Dashboard classe (carte violette) + page élèves (bouton navigation)
- **Modal moderne** : Drag & drop, instructions claires, paramétrage flexible
- **UX optimisée** : Messages de succès/erreur, redirection intelligente, state management
**Impact :**
- **Gain de temps considérable** : Import de 30 élèves en 1 action vs 30 saisies manuelles
- **Réduction d'erreurs** : Extraction automatisée vs saisie manuelle sujette aux fautes de frappe
- **Compatibilité exports scolaires** : Supporte le format standard des logiciels administratifs