242 lines
9.2 KiB
Markdown
242 lines
9.2 KiB
Markdown
# 📚 Notytex - Système de Gestion Scolaire
|
|
|
|
**Notytex** est une application web Flask moderne et robuste 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.
|
|
|
|
## 🎯 Fonctionnalités Principales
|
|
|
|
### ✅ Gestion complète des évaluations
|
|
- **Groupes classes** : Organisation des élèves par classe avec gestion des années scolaires
|
|
- **Évaluations par trimestre** : Organisation structurée des contrôles (trimestre obligatoire)
|
|
- **Exercices hiérarchiques** : Structure Assessment → Exercise → GradingElement
|
|
- **Interface unifiée** : Création évaluation + exercices + barème en une seule fois
|
|
- **Indicateurs de progression** : Visualisation immédiate de l'état de correction avec code couleur
|
|
|
|
### 🎯 Système de notation unifié (Phase 2 - 2025)
|
|
|
|
**2 Types de Notation Fixes :**
|
|
- **`notes`** : Valeurs numériques décimales (ex: 15.5/20, 2.5/4 points)
|
|
- **`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
|
|
|
|
### 📊 Analyse des résultats avancée
|
|
- **Statistiques descriptives** : Moyenne, médiane, minimum, maximum, écart-type
|
|
- **Visualisation graphique** : Histogramme de distribution des notes
|
|
- **Tableau détaillé** : Classement alphabétique avec scores par exercice
|
|
- **Calcul intelligent** : Gestion automatique des types "points" et "compétences"
|
|
|
|
## 🚀 Installation et lancement
|
|
|
|
### Prérequis
|
|
- Python 3.9+
|
|
- uv (gestionnaire de paquets moderne Python)
|
|
|
|
### Installation
|
|
```bash
|
|
# 1. Cloner le projet
|
|
git clone <repository>
|
|
cd notytex
|
|
|
|
# 2. Installer les dépendances
|
|
uv sync
|
|
|
|
# 3. Configurer l'environnement
|
|
cp .env.example .env
|
|
# Modifier .env avec vos paramètres (SECRET_KEY obligatoire)
|
|
|
|
# 4. Initialiser la base de données avec données de test
|
|
uv run flask --app app init-db
|
|
|
|
# 5. Lancer l'application
|
|
uv run flask --app app run --debug
|
|
```
|
|
|
|
### Accès
|
|
- **URL** : http://localhost:5000
|
|
- **Dashboard** : Statistiques temps réel
|
|
- **Interface** : Navigation intuitive entre sections
|
|
|
|
## 🏗️ Architecture Technique (Refactorisée - Phase 1)
|
|
|
|
### Structure moderne du code
|
|
```
|
|
notytex/
|
|
├── 🚀 app.py # Application Flask + routes principales
|
|
├── 📊 models.py # Modèles SQLAlchemy + logique métier
|
|
├── ⚙️ app_config_classes.py # Classes de configuration Flask
|
|
├── 🔧 config/ # Configuration externalisée
|
|
│ ├── __init__.py
|
|
│ └── settings.py # Gestion des variables d'environnement
|
|
├── 🛡️ exceptions/ # Gestion d'erreurs centralisée
|
|
│ ├── __init__.py
|
|
│ └── handlers.py # Gestionnaires d'erreurs globaux
|
|
├── 🔍 core/ # Utilitaires centraux
|
|
│ ├── __init__.py
|
|
│ └── logging.py # Logging structuré JSON
|
|
├── 📦 repositories/ # Pattern Repository (accès données)
|
|
│ ├── __init__.py
|
|
│ ├── base_repository.py # Repository de base générique
|
|
│ └── assessment_repository.py # Repository spécialisé Assessment
|
|
├── 📁 routes/ # Blueprints organisés par fonctionnalité
|
|
│ ├── assessments.py # CRUD évaluations + création unifiée
|
|
│ ├── exercises.py # Gestion exercices + éléments notation
|
|
│ ├── grading.py # Interface saisie des notes
|
|
│ └── config.py # Interface configuration système
|
|
├── 🎨 templates/ # Templates Jinja2 + composants réutilisables
|
|
├── 🧪 tests/ # Tests pytest avec 100% de réussite
|
|
└── 📋 domain/ # Exceptions métier personnalisées
|
|
```
|
|
|
|
### Modèle de données hiérarchique
|
|
```
|
|
ClassGroup (6ème A, 5ème B...)
|
|
↓
|
|
Students (Élèves de la classe)
|
|
↓
|
|
Assessment (Contrôle mathématiques, Trimestre 1...)
|
|
↓
|
|
Exercise (Exercice 1, Exercice 2...)
|
|
↓
|
|
GradingElement (Question a, b, c...) + grading_type (notes|score)
|
|
↓
|
|
Grade (Note attribuée à chaque élève) + valeurs spéciales configurables
|
|
↓
|
|
GradingConfig (Configuration centralisée des types de notation)
|
|
```
|
|
|
|
### Technologies et architecture
|
|
- **Backend** : Flask, SQLAlchemy, WTForms, Pydantic
|
|
- **Frontend** : TailwindCSS, Jinja2, JavaScript, Chart.js
|
|
- **Base de données** : SQLite avec migrations
|
|
- **Configuration** : Variables d'environnement (.env)
|
|
- **Logging** : Structuré JSON avec corrélation des requêtes
|
|
- **Tests** : Pytest avec couverture complète (100 tests ✅)
|
|
- **Architecture** : Repository Pattern, Dependency Injection
|
|
- **Sécurité** : Configuration externalisée, validation centralisée
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Variables d'environnement (.env)
|
|
```bash
|
|
# Configuration obligatoire
|
|
SECRET_KEY=your-secret-key-here-min-32-chars-dev-example-key-2025
|
|
DATABASE_URL=sqlite:///school_management.db
|
|
|
|
# Configuration optionnelle
|
|
FLASK_ENV=development
|
|
LOG_LEVEL=INFO
|
|
DEBUG=true
|
|
DB_ECHO=false
|
|
WTF_CSRF_TIME_LIMIT=3600
|
|
```
|
|
|
|
### Configuration de production
|
|
```bash
|
|
# Utiliser des valeurs sécurisées
|
|
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
|
|
```
|
|
|
|
## 🧪 Tests et Qualité
|
|
|
|
### Lancer les tests
|
|
```bash
|
|
# Tous les tests (100 tests ✅)
|
|
uv run pytest
|
|
|
|
# Tests avec couverture
|
|
uv run pytest --cov=. --cov-report=html
|
|
|
|
# Tests spécifiques
|
|
uv run pytest tests/test_repositories.py -v
|
|
```
|
|
|
|
### Architecture de tests
|
|
- **test_config.py** : Tests configuration externalisée
|
|
- **test_error_handlers.py** : Tests gestion d'erreurs
|
|
- **test_logging.py** : Tests logging structuré
|
|
- **test_repositories.py** : Tests Repository pattern
|
|
- **test_models.py** : Tests modèles et logique métier
|
|
- **test_routes_*.py** : Tests routes et contrôleurs
|
|
- **test_services.py** : Tests couche service
|
|
|
|
## 🚀 Développement
|
|
|
|
### Workflow de développement
|
|
```bash
|
|
# 1. Environnement de développement
|
|
cp .env.example .env
|
|
uv run flask --app app init-db
|
|
|
|
# 2. Lancement avec rechargement automatique
|
|
uv run flask --app app run --debug
|
|
|
|
# 3. Tests avant commit
|
|
uv run pytest
|
|
|
|
# 4. Analyse des logs
|
|
tail -f logs/notytex.log
|
|
```
|
|
|
|
### Ajout de nouvelles fonctionnalités
|
|
1. **Créer les modèles** dans `models.py`
|
|
2. **Implémenter le repository** dans `repositories/`
|
|
3. **Créer les routes** dans `routes/`
|
|
4. **Ajouter les templates** dans `templates/`
|
|
5. **Écrire les tests** dans `tests/`
|
|
|
|
## 📊 Monitoring
|
|
|
|
### Logs structurés
|
|
- **Format** : JSON avec corrélation des requêtes
|
|
- **Localisation** : `logs/notytex.log`
|
|
- **Niveaux** : DEBUG, INFO, WARNING, ERROR
|
|
- **Contexte** : URL, méthode, adresse IP, user-agent
|
|
|
|
### Métriques disponibles
|
|
- Temps de réponse des requêtes
|
|
- Événements métier (création évaluation, etc.)
|
|
- Erreurs et exceptions
|
|
- Utilisation des ressources
|
|
|
|
## 🎓 Cas d'Usage Typique
|
|
|
|
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
|
|
|
|
## 🛡️ Sécurité
|
|
|
|
- **Configuration externalisée** : Aucune donnée sensible en dur
|
|
- **Validation centralisée** : Pydantic pour la validation des données
|
|
- **Gestion d'erreurs** : Pas de fuite d'informations sensibles
|
|
- **Logs sécurisés** : Pas de données personnelles dans les logs
|
|
- **CSRF Protection** : Protection contre les attaques CSRF
|
|
|
|
## 👥 Public Cible
|
|
|
|
- Enseignants du secondaire (collège/lycée)
|
|
- Établissements souhaitant digitaliser leurs évaluations
|
|
- Contexte où coexistent notation classique et évaluation par compétences
|
|
|
|
---
|
|
|
|
**Notytex** présente une architecture solide et moderne, 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 robustesse technique. |