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

clean v1 artifacts

Browse Source
This commit is contained in:
Bertrand Benjamin
2026-02-09 17:57:02 +01:00
parent ba25dd19db
commit a30dd4af19
6 changed files with 346 additions and 1739 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
.coverage
View File

Binary file not shown.

17
.env.example
View File

@@ -1,17 +0,0 @@
# Configuration de développement
SECRET_KEY=your-secret-key-here-min-32-chars-dev-example-key-2025
DATABASE_URL=sqlite:///school_management.db
FLASK_ENV=development
LOG_LEVEL=INFO
DEBUG=true
# Configuration de production (décommentez et ajustez pour la production)
# SECRET_KEY=your-production-secret-key-min-32-chars-prod
# DATABASE_URL=postgresql://user:pass@localhost/notytex_prod
# FLASK_ENV=production
# LOG_LEVEL=WARNING
# DEBUG=false
# Configuration optionnelle
# DB_ECHO=false
# WTF_CSRF_TIME_LIMIT=3600

4
.gitignore vendored
View File

@@ -82,7 +82,3 @@ htmlcov/
# Docker data
data/
!data/.gitkeep
# Flask legacy
instance/
.webassets-cache

923
CLAUDE.md
View File

@@ -1,628 +1,397 @@
# 📚 Notytex - Système de Gestion Scolaire
# Notytex v2 - Système de Gestion Scolaire
**Notytex** est une application web Flask moderne conçue pour la gestion complète des évaluations scolaires. Elle permet aux enseignants de créer, organiser et noter les évaluations de leurs élèves avec une interface intuitive et des fonctionnalités avancées.
**Notytex** est une application web moderne pour la gestion complète des évaluations scolaires. Version 2.0 entièrement réécrite avec **FastAPI** (backend) et **Vue.js 3** (frontend).
## 🎯 **Objectif Principal**
## Objectif Principal
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.
Simplifier et digitaliser le processus d'évaluation scolaire, de la création des contrôles à la saisie des notes, en offrant une interface moderne, réactive et une API REST documentée.
## 🏗️ **Architecture Technique **
---
**Framework :** Flask (Python) avec architecture modulaire découplée
**Base de données :** SQLite avec SQLAlchemy ORM + Repository Pattern
**Frontend :** Templates Jinja2 + TailwindCSS + JavaScript + Chart.js
**Tests :** Pytest avec couverture complète (100 tests ✅)
**Configuration :** Variables d'environnement externalisées (.env)
**Logging :** Structuré JSON avec corrélation des requêtes
**Sécurité :** Configuration sécurisée + gestion d'erreurs centralisée
## Architecture Technique
## 📊 **Modèle de Données Hiérarchique**
| Couche | Technologie |
|--------|-------------|
| **Backend** | FastAPI 0.115+ (Python 3.11-3.13) |
| **ORM** | SQLAlchemy 2.0.36+ avec aiosqlite (async) |
| **Validation** | Pydantic 2.10+ / pydantic-settings |
| **Serveur** | Uvicorn 0.32+ (ASGI) |
| **Frontend** | Vue.js 3.5+ (Composition API) + Vite 6.0+ |
| **State** | Pinia 2.2+ |
| **CSS** | TailwindCSS 3.4+ |
| **Graphiques** | Chart.js 4.4+ (vue-chartjs) |
| **HTTP client** | Axios 1.7+ |
| **Base de données** | SQLite (dev/prod), PostgreSQL possible |
| **Déploiement** | Docker / Podman avec Nginx |
| **Tests** | pytest + pytest-asyncio (99/99 tests) |
| **Qualité** | Black, Ruff, ESLint |
---
## Modèle de Données (12 tables)
### Entités principales (7)
```
ClassGroup (6ème A, 5ème B...)
↓ StudentEnrollment (inscription temporelle : arrivée/départ)
Student (élèves)
↓
Students (Élèves de la classe)
Assessment (évaluation, rattachée à un trimestre 1/2/3)
↓
Assessment (Contrôle de mathématiques, Trimestre 1...)
Exercise (exercices ordonnés)
↓
Exercise (Exercice 1, Exercice 2...)
GradingElement (question/compétence, type "notes" ou "score", domaine optionnel)
↓
GradingElement (Question a, b, c...)
↓
Grade (Note attribuée à chaque élève)
Grade (note individuelle par élève : valeur string + commentaire)
```
## ⭐ **Fonctionnalités Clés**
- **CouncilAppreciation** : appréciation de conseil de classe (élève + classe + trimestre, statut draft/finalized)
### **Gestion des Évaluations**
### Tables de configuration (5)
- Création d'évaluations complètes avec exercices multiples
- **Organisation par trimestre** : Chaque évaluation doit être assignée à un trimestre (1, 2 ou 3)
- Structure hiérarchique : Assessment → Exercise → GradingElement
- Interface unifiée pour créer évaluation + exercices + barème en une fois
- Modification et suppression avec gestion des cascades
- **AppConfig** : clé-valeur (ex: `context.school_year`, `grading.special_values`)
- **CompetenceScaleValue** : échelle de notation (0=Non acquis → 3=Expert, couleurs, `.`, `d`, `a`)
- **Competence** : compétences pédagogiques (Calculer, Raisonner...) avec couleur et icône
- **Domain** : domaines/tags pour les éléments de notation
### **Système de Notation Unifié **
**2 Types de Notation Fixes :**
1. **`notes`** : Valeurs numériques décimales (ex: 2.5/4, 18/20, 15.5/20)
2. **`score`** : Échelle fixe de 0 à 3 pour l'évaluation par compétences
**Valeurs Spéciales Configurables :**
- **`.`** = Pas de réponse (traité comme 0 dans les calculs)
- **`d`** = Dispensé (ne compte pas dans la note finale)
- **Autres valeurs** : Entièrement configurables via l'interface d'administration
**Configuration Centralisée :**
- **Signification des scores** : 0=Non acquis, 1=En cours, 2=Acquis, 3=Expert (modifiable)
- **Couleurs associées** : Chaque niveau peut avoir sa couleur personnalisée
- **Règles de calcul** : Logique unifiée pour tous les types de notation
- **Interface d'administration** : Gestion complète des paramètres de notation
### **Filtrage Avancé des Évaluations**
**Filtres Dynamiques Disponibles :**
- **Trimestre** : Filtrage par trimestre (1, 2, 3) pour organiser par période scolaire
- **Classe** : Filtrage par groupe de classe pour se concentrer sur une classe spécifique
- **Statut de Correction** : **NOUVEAU** - Filtre essentiel pour la gestion des corrections :
- **Non terminées** : Évaluations partiellement corrigées ou non commencées (idéal pour mode midyear)
- **Terminées** : Évaluations 100% corrigées
- **Non commencées** : Évaluations sans aucune note saisie
- **Tri** : Organisation par date (récent/ancien), titre alphabétique, ou classe
**JavaScript Dynamique :**
- **Filtrage temps réel** : Les filtres s'appliquent automatiquement au changement
- **Persistence des filtres** : État maintenu dans l'URL pour navigation intuitive
- **Interface responsive** : Adaptée aux appareils mobiles et desktop
### **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
- **Navigation intuitive** : Actions principales mises en avant avec boutons colorés et icônes
- **Templates responsive** avec TailwindCSS et animations fluides
- **Page de présentation d'évaluation repensée** :
- Hero section avec gradient et informations clés
- Actions principales (Noter, Résultats, Modifier, Supprimer) en cards colorées
- Indicateur de progression central avec visualisation circulaire animée
- Structure d'évaluation en cards compactes avec compétences visibles
- **Suppression des pages intermédiaires** : Plus de pages de détail d'exercices, navigation directe
- **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 **
**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
- **Rapport détaillé** : Statistiques complètes (importés, ignorés, erreurs) avec détail ligne par ligne
- **Validation robuste** : Contrôle format CSV, taille fichier, types de données
- **Interface intuitive** : Modal avec drag & drop, instructions du format attendu
**Points d'Accès Multiples :**
- **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
### **Analyse des Résultats Avancée**
- **Page de résultats complète** : Vue d'ensemble des performances de l'évaluation
- **Statistiques descriptives** : Moyenne, médiane, minimum, maximum, écart-type
- **Visualisation graphique** : Histogramme de distribution des notes (groupes de 1 point, de 0 au maximum)
- **Tableau détaillé** : Classement alphabétique avec scores par exercice au format "score/total"
- **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 **
```
app.py # Application Flask principale + routes de base
models.py # Modèles SQLAlchemy (5 entités principales + calcul progression)
app_config_classes.py # Classes de configuration Flask (dev/prod/test)
🔧 config/ # Configuration externalisée sécurisée
├── __init__.py
└── settings.py # Gestion variables d'environnement + validation
🛡️ exceptions/ # Gestion d'erreurs centralisée
├── __init__.py
└── handlers.py # Gestionnaires d'erreurs globaux (JSON/HTML)
🔍 core/ # Utilitaires centraux
├── __init__.py
└── logging.py # Logging structuré JSON + corrélation requêtes
📦 repositories/ # Pattern Repository pour accès données
├── __init__.py
├── base_repository.py # Repository générique CRUD
└── assessment_repository.py # Repository spécialisé Assessment
📁 routes/ # Blueprints organisés par fonctionnalité
├── assessments.py # CRUD évaluations (création unifiée)
├── exercises.py # Gestion des exercices
├── grading.py # Saisie et gestion des notes
├── classes.py # Gestion classes + import CSV élèves
└── config.py # Interface configuration système
forms.py # Formulaires WTForms pour validation (+ CSVImportForm)
📋 services/ # Services métier modulaires
├── csv_import_service.py # Service d'import CSV élèves
└── assessment_services.py # Logique métier évaluations
utils.py # Utilitaires existants
commands.py # Commandes CLI Flask (init-db)
templates/ # Templates Jinja2 avec indicateurs UX intégrés
📋 domain/ # Exceptions métier personnalisées
🧪 tests/ # Tests pytest (100 tests ✅)
```
## 🚀 **Installation & Lancement **
```bash
# Installation avec uv (gestionnaire moderne)
uv sync
# Configuration obligatoire (.env)
cp .env.example .env
# Modifier .env avec SECRET_KEY (obligatoire, min 32 caractères)
# Initialisation base de données + données de démo
uv run flask --app app init-db
# Lancement développement avec logging structuré
uv run flask --app app run --debug
# Lancement des tests (100 tests ✅)
uv run pytest
# Consultation des logs structurés JSON
tail -f logs/notytex.log
```
## 🧪 **Qualité du Code **
- **Tests pytest avec 100% de réussite** (100 tests ✅)
- **Architecture découplée** : Repository Pattern + Dependency Injection
- **Gestion d'erreurs centralisée** : Gestionnaires globaux JSON/HTML
- **Logging structuré JSON** : Corrélation des requêtes + contexte complet
- **Configuration sécurisée** : Variables d'environnement externalisées
- **Validation robuste** : WTForms + Pydantic + services métier
- **Séparation des responsabilités** : Modèles/Repositories/Services/Controllers
## 📝 **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"
4. **Définit le barème** : Question 1a (2 pts), Question 1b (3 pts), Compétence graphique (score 0-3)
5. **Voit l'indicateur de progression** : "Correction 0%" en rouge sur toutes les pages
6. **Saisit les notes** pour chaque élève sur chaque élément via clic sur l'indicateur
7. **Suit la progression** : L'indicateur passe à "Correction 45%" en orange, puis "Correction 100%" en vert
8. **Consulte les résultats détaillés** : Accès direct à la page de résultats avec statistiques et histogramme
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 `;`
4. **Glisse le fichier** dans la zone de drag & drop ou sélectionne via le bouton
5. **Configure l'import** : Date d'inscription, option "ignorer doublons" activée
6. **Lance l'import** : Validation automatique format + extraction intelligente des noms
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
- 5 classes d'entre 25 et 35 élèves
- Les évaluations sont constitués d'entre 10 et 20 éléments de notations
- 4 évaluations corrigées par classes pour le premier trimestre
- 2 évaluations non corrigée ou partiellement corrigée par classe
## 🎓 **Public Cible**
- Enseignants du secondaire (collège/lycée)
- Établissements souhaitant digitaliser leurs évaluations
- Contexte où coexistent notation classique et évaluation par compétences
Ce projet présente une architecture solide, une interface soignée avec des **indicateurs UX avancés** pour le suivi de progression, et répond à un besoin concret du monde éducatif en combinant praticité et modernité technique.
## 🎨 **Dernières Améliorations UX**
### **Indicateurs de Progression Intégrés**
- **Calcul automatique** : Propriété `grading_progress` dans le modèle Assessment
- **Affichage multi-pages** : Présent sur index, liste évaluations, détail évaluation
- **Code couleur intuitif** :
- 🔴 Rouge : "Correction 0%" (non commencée)
- 🟠 Orange : "Correction XX%" (en cours avec cercle de progression)
- 🟢 Vert : "Correction 100%" (terminée)
- **Actions directes** : Clic sur l'indicateur → redirection vers page de notation
- **Informations détaillées** : "X/Y notes saisies (Z élèves)"
- **Responsive design** : Version complète sur liste évaluations, version compacte sur index
### **Système de Résultats et Statistiques**
- **Calculs automatisés** : Méthodes `calculate_student_scores()`, `get_assessment_statistics()` dans le modèle Assessment
- **Double logique de scoring** :
- **Points** : Sommation directe des valeurs
- **Compétences** : Formule `1/3 * score * pointMax` (score 0-3)
- **Gestion des cas particuliers** : Les scores "." comptent comme 0 mais incluent les points maximum
- **Arrondi intelligent** : Notes totales arrondies à 2 décimales pour la précision
- **Interface graphique** : Chart.js pour histogrammes interactifs avec bins de 1 point
- **Tri alphabétique** : Classement automatique par nom de famille puis prénom
Cette évolution transforme Notytex en un outil **véritablement centré utilisateur** où l'état de correction est **visible et actionnable depuis n'importe quelle page**, avec une **analyse statistique complète** des résultats.
Tous les modèles sont dans `backend/infrastructure/database/models.py`.
---
# 🚀 **Guide de Démarrage pour Nouveaux Développeurs**
## Fonctionnalités Clés
## 📋 **Prérequis**
### Gestion des Classes et Élèves
### **Environnement de Développement**
- CRUD classes avec année scolaire
- Inscription temporelle (bitemporal) : dates d'arrivée/départ, transferts, historique
- Import CSV en masse (séparateur `;`, format "NOM Prénoms", gestion doublons)
- Statistiques par trimestre et par classe
- **Python 3.8+** : Version recommandée 3.11+
- **uv** : Gestionnaire de paquets moderne Python ([installation](https://docs.astral.sh/uv/))
- **Git** : Pour le contrôle de version
- **IDE recommandé** : VSCode avec extensions Python, Flask, Jinja2
### Système d'Évaluation
### **Connaissances Requises**
- Création unifiée (évaluation + exercices + barème en une fois)
- Organisation par trimestre (1, 2, 3)
- Filtrage avancé (trimestre, classe, statut de correction, tri)
- Indicateurs de progression : rouge (0%), orange (en cours), vert (100%)
- **Python** : Classes, décorateurs, gestion d'erreurs
- **Flask** : Routes, templates, blueprints, contexte d'application
- **SQLAlchemy** : ORM, relations, requêtes
- **HTML/CSS** : TailwindCSS de préférence
- **JavaScript** : Manipulation DOM, événements
### Notation Dual Configurable
## ⚡ **Démarrage Rapide (5 minutes)**
**2 types de notation (par GradingElement) :**
```bash
# 1. Cloner et installer
git clone <repository>
cd notytex
uv sync
1. **`notes`** : valeurs numériques décimales (ex: 15.5/20) — calcul direct
2. **`score`** : échelle fixe 0-3 — converti en points : `(value / 3) * max_points`
# 2. Initialiser la base de données avec données de test
uv run flask --app app init-db
**Valeurs spéciales (configurables via interface) :**
- `.` = pas de réponse (compte comme 0 dans le total)
- `d` = dispensé (exclu des calculs)
- `a` = absent (compte comme 0)
# 3. Lancer l'application
uv run flask --app app run --debug
### Analyse et Statistiques
# 4. Ouvrir http://localhost:5000
```
- Statistiques descriptives (moyenne, médiane, écart-type, min/max, quartiles)
- Histogrammes de distribution (bins de 1 point, Chart.js)
- Heatmaps par compétences et par domaines
- Classement alphabétique avec scores par exercice
## 🏗️ **Architecture Détaillée**
### Conseil de Classe
### **Structure des Fichiers**
- Préparation automatique avec données consolidées par trimestre
- Saisie et historique des appréciations (brouillon → finalisé)
- Vue complète des performances par élève
### Envoi de Bilans par Email
- Génération automatique de bilans individualisés (HTML Jinja2)
- SMTP configurable (Gmail, Outlook, serveur perso)
- Envoi en lot avec rapport détaillé succès/erreurs
- Prévisualisation avant envoi
---
## Structure du Code
```
notytex/
├── 📱 app.py # Point d'entrée Flask + routes principales
├── 🗄️ models.py # Modèles SQLAlchemy + logique métier
├── ⚙️ app_config.py # Gestionnaire de configuration SQLite
├── 🔧 config.py # Configuration Flask (dev/prod/test)
├── 🎯 forms.py # Formulaires WTForms + validation
├── 🛠️ utils.py # Fonctions utilitaires + gestion erreurs
├── 📜 commands.py # Commandes CLI Flask
├── 📁 routes/ # Blueprints organisés par fonctionnalité
│ ├── assessments.py # CRUD évaluations + création unifiée
│ ├── exercises.py # Gestion exercices + éléments de notation
│ ├── grading.py # Interface de saisie des notes
│ └── config.py # Interface de configuration système
├── 📁 templates/ # Templates Jinja2 + composants réutilisables
│ ├── base.html # Layout principal + navigation
│ ├── components/ # Composants réutilisables
│ └── config/ # Interface de configuration
├── 📁 static/ # Assets statiques (CSS, JS, images)
├── 🧪 tests/ # Tests pytest + fixtures
└── 📝 pyproject.toml # Configuration uv + dépendances
├── backend/ # API FastAPI
│ ├── api/
│ │ ├── main.py # App FastAPI + CORS + lifespan
│ │ ├── dependencies.py # DI (AsyncSessionDep)
│ │ └── routes/
│ │ ├── assessments.py # CRUD évaluations + notation + résultats + email
│ │ ├── classes.py # CRUD classes + import CSV + stats dashboard
│ │ ├── students.py # CRUD élèves + inscriptions
│ │ ├── config.py # Configuration système + compétences + domaines
│ │ └── council.py # Appréciations de conseil de classe
│ │
│ ├── schemas/ # Modèles Pydantic (validation I/O)
│ │ ├── common.py # BaseSchema, PaginationParams
│ │ ├── assessment.py # AssessmentRead, AssessmentCreate...
│ │ ├── student.py # StudentRead, StudentCreate...
│ │ ├── grading.py # GradeRead, BulkGradeCreate
│ │ ├── class_group.py # ClassGroupRead, ClassDashboardStats
│ │ ├── config.py # ConfigRead, CompetenceCreate
│ │ ├── council.py # CouncilAppreciationRead
│ │ └── csv_import.py # CSVImportResponse
│ │
│ ├── domain/ # Logique métier pure (aucune dépendance framework)
│ │ ├── services/
│ │ │ ├── grading_calculator.py # Strategy Pattern (Notes/Score)
│ │ │ ├── statistics_service.py # Statistiques descriptives
│ │ │ ├── score_calculator.py # Calcul scores élèves
│ │ │ ├── config_service.py # Valeurs spéciales, signification scores
│ │ │ ├── student_report_service.py # Génération bilans email
│ │ │ └── class_statistics_service.py # Stats par classe
│ │ └── value_objects/
│ │ ├── progress.py # ProgressResult, ProgressStatus
│ │ ├── score.py # GradeValue, ExerciseScore, StudentScore
│ │ └── statistics.py # StatisticsResult, HistogramBin
│ │
│ ├── infrastructure/
│ │ ├── database/
│ │ │ ├── models.py # 12 modèles SQLAlchemy
│ │ │ └── session.py # AsyncSession factory
│ │ └── external/
│ │ └── email_service.py # Service SMTP
│ │
│ ├── core/
│ │ └── config.py # pydantic-settings (Settings)
│ │
│ ├── tests/ # 99 tests
│ │ ├── conftest.py # Fixtures (SQLite in-memory, AsyncClient)
│ │ ├── unit/ # Tests services domaine
│ │ ├── integration/ # Tests endpoints API
│ │ └── comparison/ # Tests parité v1 ↔ v2
│ │
│ ├── pyproject.toml # Dépendances + config Black/Ruff/pytest
│ └── uv.lock
│
├── frontend/ # SPA Vue.js 3
│ ├── src/
│ │ ├── main.js # Initialisation app
│ │ ├── App.vue # Composant racine
│ │ ├── router/index.js # 14 routes Vue Router
│ │ ├── stores/ # Pinia (classes, assessments, config, notifications)
│ │ ├── services/api.js # Instance Axios (/api/v2)
│ │ ├── views/ # 14 pages (Dashboard, Grading, Results...)
│ │ ├── components/ # 16+ composants réutilisables
│ │ └── assets/
│ ├── vite.config.js # Proxy dev /api → localhost:8000
│ ├── tailwind.config.js
│ └── package.json
│
├── docker/
│ ├── docker-compose.yaml # Production (ports 8080/8081)
│ ├── docker-compose.dev.yaml # Développement avec hot reload
│ └── .env.example # Template variables Docker
│
├── school_management.db # Base SQLite partagée
├── CLAUDE.md # Ce fichier
└── README.md # Documentation utilisateur
```
### **Flux de Données Typique**
```
1. Route Flask (routes/*.py)
↓
2. Validation Form (forms.py)
↓
3. Logique Métier (models.py)
↓
4. Accès Base de Données (SQLAlchemy)
↓
5. Rendu Template (templates/*.html)
```
## 🎯 **Points d'Entrée pour Contribuer**
### **🌟 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
3. **Ajouter une validation de formulaire**
- Fichier : `forms.py`
- Technologie : WTForms
- Exemple : Validation format email étudiant
### **🔥 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
3. **Étendre le système de configuration**
- Nouveau modèle dans `models.py`
- Interface dans `routes/config.py`
- Template de configuration
### **⚡ 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
3. **Système de notifications**
- Modèles de notifications
- Interface utilisateur
- Système de stockage
## 📚 **Concepts Clés à Maîtriser**
### **Configuration Dynamique**
```python
# Configuration stockée en base SQLite
from app_config import config_manager
# Lecture
school_year = config_manager.get('context.school_year')
competences = config_manager.get_competences_list()
# Écriture
config_manager.set('context.school_year', '2025-2026')
config_manager.save()
```
### **Calcul de Progression**
```python
# Dans models.py - Assessment
@property
def grading_progress(self):
# Calcul automatique du % de correction
# Utilisé partout dans l'interface
return {
'percentage': 75,
'status': 'in_progress',
'completed': 45,
'total': 60
}
```
### **Système de Notation Unifié**
```python
# Type "notes" - Valeurs numériques
grade.value = "15.5" # Points décimaux
grade.grading_element.grading_type = "notes"
grade.grading_element.max_points = 20
# Type "score" - Échelle 0-3 fixe
grade.value = "2" # 0=Non acquis, 1=En cours, 2=Acquis, 3=Expert
grade.grading_element.grading_type = "score"
grade.grading_element.max_points = 3 # Toujours 3 pour les scores
# Valeurs spéciales configurables
grade.value = "." # Pas de réponse (= 0)
grade.value = "d" # Dispensé (ne compte pas)
# Configuration centralisée
from app_config import config_manager
score_meanings = config_manager.get('grading.score_meanings')
special_values = config_manager.get('grading.special_values')
```
## 🧪 **Tests et Débogage**
### **Lancer les Tests**
```bash
# Tous les tests
uv run pytest
# Tests avec couverture
uv run pytest --cov=. --cov-report=html
# Test spécifique de l'import CSV
uv run python -c "
from services.csv_import_service import CSVImportService
service = CSVImportService()
print('✅ Test extraction:', service.extract_name_parts('DUPONT Marie Claire'))
"
# Tests spécifiques
uv run pytest tests/test_models.py -v
```
### **Débogage**
```bash
# Mode debug avec rechargement auto
uv run flask --app app run --debug
# Console interactive
uv run flask --app app shell
# Logs détaillés
tail -f logs/school_management.log
```
### **Base de Données**
```bash
# Réinitialiser complètement
rm school_management.db
uv run flask --app app init-db
# Inspecter la DB
sqlite3 school_management.db
.tables
.schema assessment
```
## 🎨 **Conventions de Code**
### **Style Python**
- **PEP 8** : Formatage automatique avec black
- **Type hints** : Recommandés pour les nouvelles fonctions
- **Docstrings** : Format Google pour les fonctions publiques
- **Noms explicites** : `calculate_student_scores()` plutôt que `calc()`
### **Templates Jinja2**
- **Indentation** : 4 espaces
- **Noms de variables** : snake_case
- **Blocs réutilisables** : Utiliser les includes et macros
- **Classes CSS** : TailwindCSS avec composition
### **Base de Données**
- **Noms de tables** : Pluriel en anglais (`students`, `assessments`)
- **Relations** : Toujours avec `backref` explicite
- **Cascades** : Définir explicitement le comportement
## 🐛 **Problèmes Courants**
### **Erreur : Template Not Found**
```python
# ❌ Mauvais
return render_template('config.html')
# ✅ Correct
return render_template('config/index.html')
```
### **Erreur : SQLAlchemy Session**
```python
# ❌ Oublier de commit
db.session.add(new_student)
# ✅ Correct
db.session.add(new_student)
db.session.commit()
```
### **Erreur : Import Circulaire**
```python
# ❌ Import direct dans models.py
from app import app
# ✅ Import dans fonction
def get_current_app():
from flask import current_app
return current_app
```
## 📖 **Ressources Utiles**
### **Documentation Officielle**
- [Flask](https://flask.palletsprojects.com/) - Framework web
- [SQLAlchemy](https://docs.sqlalchemy.org/) - ORM Python
- [TailwindCSS](https://tailwindcss.com/) - Framework CSS
- [Jinja2](https://jinja.palletsprojects.com/) - Moteur de templates
### **Outils de Développement**
- [uv](https://docs.astral.sh/uv/) - Gestionnaire de paquets
- [pytest](https://docs.pytest.org/) - Framework de tests
- [Flask-Shell](https://flask.palletsprojects.com/en/2.3.x/shell/) - Console interactive
---
## 📧 **Système d'Envoi de Bilans par Email**
## Installation et Lancement
**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.
### Prérequis
### **🎯 Fonctionnalités Principales**
- Python 3.11-3.13 avec [uv](https://docs.astral.sh/uv/)
- Node.js 22 LTS avec npm
- Git
- ✅ **Configuration SMTP flexible** via interface web (Gmail, Outlook, serveurs personnalisés)
- ✅ **Génération automatique** de bilans individualisés avec analyses détaillées
- ✅ **Templates HTML responsives** optimisés pour tous clients email
- ✅ **Analyses par compétences et domaines** avec visualisations graphiques
- ✅ **Serveur de test intégré** (`debug_smtp_server.py`) pour développement
- ✅ **Gestion d'erreurs robuste** avec logs structurés et rapports détaillés
### Backend
### **🏗️ Architecture**
```
services/
├── email_service.py # Service d'envoi SMTP
└── student_report_service.py # Génération de bilans
templates/email/
├── base_email.html # Template de base responsive
└── student_report.html # Template de bilan détaillé
```bash
cd backend
uv sync --all-extras
uv run python -m uvicorn api.main:app --reload --port 8000
```
### **📊 Contenu des Bilans**
- API : http://localhost:8000/api/v2/docs (Swagger)
- ReDoc : http://localhost:8000/api/v2/redoc
Chaque bilan inclut :
### Frontend
- **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
- **Performances par domaines** avec codes couleur
- **Statistiques de classe** (moyenne, médiane, écart-type)
- **Message personnalisé** du professeur (optionnel)
```bash
cd frontend
npm install
npm run dev
```
### **📧 Workflow d'Envoi**
- Application : http://localhost:3000 (proxy automatique `/api` vers le backend)
1. **Configuration SMTP** via `Configuration > Email`
2. **Sélection d'élèves** depuis la page de résultats d'évaluation
3. **Prévisualisation** des bilans via `/preview-report`
4. **Envoi groupé** avec rapport détaillé des succès/erreurs
5. **Réception professionnelle** par les élèves et familles
### Docker / Podman
**📖 Documentation complète** : [docs/features/EMAIL_REPORTS.md](docs/features/EMAIL_REPORTS.md)
```bash
cd docker
cp .env.example .env
# Modifier SECRET_KEY dans .env
docker compose up -d # ou podman-compose up -d
```
- Frontend : http://localhost:8081
- API : http://localhost:8080/api/v2/docs
---
## Tests
```bash
cd backend
# Tous les tests
uv run pytest tests/ -v
# Tests unitaires
uv run pytest tests/unit/ -v
# Tests de parité v1 ↔ v2
uv run pytest tests/comparison/ -v
# Avec couverture
uv run pytest tests/ --cov=. --cov-report=html
```
**Résultat actuel : 99/99 tests**
Les tests utilisent une base SQLite in-memory avec `AsyncClient` + `ASGITransport` pour tester les endpoints sans serveur.
---
## Configuration
### pydantic-settings (`backend/core/config.py`)
```python
class Settings(BaseSettings):
# Base de données
database_url: Optional[str] # URL complète SQLAlchemy async
database_path: Optional[str] # Chemin simple vers le .db
# API
api_v2_prefix: str = "/api/v2"
# CORS
cors_origins: list[str] = ["http://localhost:3000", "http://localhost:5173"]
# Logging
log_level: str = "INFO"
# Email (optionnel)
smtp_server, smtp_port, smtp_username, smtp_password, email_from
model_config = SettingsConfigDict(env_file=".env")
```
Toute la config est lue depuis `backend/.env` et validée par Pydantic au démarrage.
### Configuration dynamique (table AppConfig)
Paramètres modifiables à chaud via l'interface web :
- `context.school_year` — année scolaire en cours
- `grading.special_values` — valeurs spéciales (`.`, `d`, `a`)
- `grading.score_meanings` — signification des scores 0-3
- Configuration SMTP pour l'envoi d'emails
---
## Patterns Architecturaux
### Strategy Pattern — Calcul de notation
`domain/services/grading_calculator.py` : `GradingStrategy` (ABC) avec `NotesStrategy` et `ScoreStrategy`, sélectionnées par `GradingStrategyFactory` selon le `grading_type` du GradingElement.
### Value Objects — Objets immuables du domaine
`domain/value_objects/` : `ProgressResult`, `GradeValue`, `StudentScore`, `StatisticsResult`, `HistogramBin`. Représentent des résultats de calcul sans identité propre.
### Dependency Injection — FastAPI natif
```python
AsyncSessionDep = Annotated[AsyncSession, Depends(get_async_session)]
```
Injection de la session DB dans chaque route, facilitant le remplacement en tests.
### Service Layer — Logique métier découplée
Les services dans `domain/services/` n'ont aucune dépendance sur FastAPI ou SQLAlchemy. Ils reçoivent des données brutes et retournent des Value Objects.
### Clean Architecture — Séparation en couches
`api/` (routes) → `schemas/` (validation) → `domain/` (métier) → `infrastructure/` (DB, email). Les dépendances pointent toujours vers l'intérieur.
---
## Conventions de Code
### Backend (Python)
- **Formatage** : `black` (line-length 88, target py311)
- **Linting** : `ruff` (pycodestyle, pyflakes, isort, bugbear, comprehensions)
- **Types** : `mypy` recommandé pour les nouvelles fonctions
- **Async** : toutes les routes et accès DB sont `async/await`
- **Noms** : snake_case, noms explicites (`calculate_student_scores`, pas `calc`)
### Frontend (JavaScript/Vue)
- **Composition API** avec `<script setup>`
- **Pinia** stores en style composition (pas Options API)
- **TailwindCSS** pour le styling (pas de CSS custom sauf nécessité)
- **Axios** via `services/api.js` pour tous les appels API
### Base de données
- Noms de tables : pluriel anglais (`students`, `assessments`)
- Relations avec `relationship()` et cascade explicite
- Modèles identiques à v1 pour compatibilité de la base partagée
---
## Volumétrie (milieu d'année)
- 5 classes de 25 à 35 élèves
- 10 à 20 éléments de notation par évaluation
- 4 évaluations corrigées par classe pour le 1er trimestre
- 2 évaluations non corrigées ou partiellement corrigées par classe
---
## Public Cible
- Enseignants du secondaire (collège/lycée)
- Établissements souhaitant digitaliser leurs évaluations
- Contexte de coexistence notation classique et évaluation par compétences
---
## Workflow Développeur
### Ajouter un endpoint API
1. Créer le schéma Pydantic dans `backend/schemas/`
2. Ajouter la route dans `backend/api/routes/`
3. Utiliser `AsyncSessionDep` pour l'accès DB
4. Écrire les tests dans `backend/tests/`
### Ajouter une page frontend
1. Créer le composant Vue dans `frontend/src/views/`
2. Ajouter la route dans `frontend/src/router/index.js`
3. Créer un store Pinia si nécessaire dans `frontend/src/stores/`
4. Réutiliser les composants existants de `frontend/src/components/`
### Modifier la logique de notation
1. Modifier `backend/domain/services/grading_calculator.py`
2. Mettre à jour les tests dans `backend/tests/unit/test_grading_calculator.py`
3. Lancer les tests de parité (`tests/comparison/`) pour vérifier la compatibilité v1
### Débogage
```bash
# Backend avec rechargement auto
cd backend && uv run python -m uvicorn api.main:app --reload --port 8000
# Inspecter la base
sqlite3 school_management.db ".schema assessment"
# Console interactive
cd backend && uv run python -c "from infrastructure.database.models import *; print('OK')"
```

37
pyproject.toml
View File

@@ -1,37 +0,0 @@
[project]
name = "school-management"
version = "0.1.0"
description = "Application web de gestion scolaire"
requires-python = ">=3.9"
dependencies = [
"Flask>=2.3.3",
"Flask-SQLAlchemy>=3.0.5",
"Flask-WTF>=1.1.1",
"WTForms>=3.0.1",
"python-dotenv>=1.0.0",
"pydantic>=2.0.0",
"Flask-Mail>=0.9.1",
"premailer>=3.10.0",
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["."]
[tool.uv]
dev-dependencies = [
"pytest>=7.4.0",
"pytest-flask>=1.2.0",
"pytest-cov>=4.1.0",
]
[tool.poetry.group.dev.dependencies]
aiosmtpd = "^1.4.6"
[dependency-groups]
dev = [
"psutil>=7.0.0",
]

1104
uv.lock generated
View File

File diff suppressed because it is too large Load Diff