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

feat: update Readme

Browse Source
This commit is contained in:
Bertrand Benjamin
2025-08-06 20:44:21 +02:00
parent 02a60778f9
commit e5e0545b42
1 changed files with 242 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

373
README.md
View File

@@ -1,242 +1,353 @@
# 📚 Notytex - Système de Gestion Scolaire # 📚 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. **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.
## 🎯 Fonctionnalités Principales ## 🎯 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 complémentaires.
## ⭐ Fonctionnalités Clés
### 🏫 Gestion Hiérarchique Complète
### ✅ Gestion complète des évaluations
- **Groupes classes** : Organisation des élèves par classe avec gestion des années scolaires - **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) - **Évaluations par trimestre** : Chaque évaluation doit être assignée à un trimestre (1, 2 ou 3)
- **Exercices hiérarchiques** : Structure Assessment → Exercise → GradingElement - **Structure modulaire** : ClassGroup → Students → Assessment → Exercise → GradingElement → Grade
- **Interface unifiée** : Création évaluation + exercices + barème en une seule fois - **Interface unifiée** : Création d'évaluation + exercices + barème en une seule fois
- **Indicateurs de progression** : Visualisation immédiate de l'état de correction avec code couleur - **Indicateurs de progression** : Visualisation temps réel de l'état de correction avec code couleur
### 🎯 Système de notation unifié (Phase 2 - 2025) ### 🎯 Système de Notation Dual Unifié
**2 Types de Notation Fixes :** **2 Types de Notation Complémentaires :**
- **`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 1. **`notes`** : Notation classique en points décimaux (ex: 15.5/20, 2.5/4)
2. **`score`** : Évaluation par compétences sur échelle 0-3 (0=Non acquis, 1=En cours, 2=Acquis, 3=Expert)
**Valeurs Spéciales Configurables :** **Valeurs Spéciales Configurables :**
- **`.`** = Pas de réponse (traité comme 0 dans les calculs) - **`.`** = Pas de réponse (traité comme 0 dans les calculs)
- **`d`** = Dispensé (ne compte pas dans la note finale) - **`d`** = Dispensé (exclu des calculs de moyenne)
- **Autres valeurs** : Entièrement configurables via l'interface d'administration - **Autres valeurs** : Configuration flexible via interface d'administration
**Configuration Centralisée :** **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 - **Interface d'administration** : Personnalisation complète des significations et couleurs
- **Statistiques descriptives** : Moyenne, médiane, minimum, maximum, écart-type - **Règles de calcul** : Logique unifiée pour tous les types avec gestion des cas particuliers
- **Visualisation graphique** : Histogramme de distribution des notes - **Cohérence pédagogique** : Adaptation aux différentes pratiques d'évaluation
- **Tableau détaillé** : Classement alphabétique avec scores par exercice
- **Calcul intelligent** : Gestion automatique des types "points" et "compétences"
## 🚀 Installation et lancement ### 📊 Analyse des Résultats et Statistiques
### Prérequis - **Statistiques descriptives complètes** : Moyenne, médiane, minimum, maximum, écart-type
- Python 3.9+ - **Visualisation graphique interactive** : Histogrammes de distribution avec Chart.js
- uv (gestionnaire de paquets moderne Python) - **Tableau détaillé par élève** : Classement alphabétique avec scores détaillés par exercice
- **Calculs intelligents** : Gestion automatique des types "notes" et "score" avec formules spécialisées
- **Gestion des absences** : Traitement cohérent des valeurs spéciales dans les statistiques
### 🎨 Interface Utilisateur Moderne
- **Dashboard avec statistiques temps réel** : Cartes interactives avec animations et gradients
- **Navigation intuitive** : Actions principales mises en avant avec design cohérent
- **Indicateurs de progression visuels** : Cercles de progression animés avec code couleur
- **Design responsive** : Interface adaptée à tous les écrans avec TailwindCSS
- **Mode plein écran** : Visualisation optimisée pour les présentations
## 🚀 Démarrage Rapide
### 📋 Prérequis
- **Python 3.8+** (recommandé : 3.11+)
- **uv** : Gestionnaire de paquets moderne Python ([installation](https://docs.astral.sh/uv/))
- **Git** : Pour le contrôle de version
### ⚡ Installation (5 minutes)
### Installation
```bash ```bash
# 1. Cloner le projet # 1. Cloner et accéder au projet
git clone <repository> git clone <repository>
cd notytex cd notytex
# 2. Installer les dépendances # 2. Installer les dépendances
uv sync uv sync
# 3. Configurer l'environnement # 3. Configuration obligatoire
cp .env.example .env cp .env.example .env
# Modifier .env avec vos paramètres (SECRET_KEY obligatoire) # Modifier .env avec SECRET_KEY (minimum 32 caractères obligatoire)
# 4. Initialiser la base de données avec données de test # 4. Initialiser la base de données avec données de démonstration
uv run flask --app app init-db uv run flask --app app init-db
# 5. Lancer l'application # 5. Lancer l'application en mode développement
uv run flask --app app run --debug uv run flask --app app run --debug
``` ```
### Accès ### 🌐 Accès à l'Application
- **URL** : http://localhost:5000
- **Dashboard** : Statistiques temps réel
- **Interface** : Navigation intuitive entre sections
## 🏗️ Architecture Technique (Refactorisée - Phase 1) - **URL de développement** : http://localhost:5000
- **Interface** : Dashboard avec navigation intuitive
- **Données de test** : Exemples d'évaluations et élèves préchargés
## 🏗️ Architecture Technique
### 🎯 Principes Architecturaux
- **Architecture modulaire découplée** : Séparation claire des responsabilités
- **Repository Pattern** : Accès aux données abstraites et testables
- **Configuration externalisée** : Respect des principes 12 Factor App
- **Gestion d'erreurs centralisée** : Traitement uniforme des exceptions
- **Logging structuré JSON** : Traçabilité complète avec corrélation des requêtes
### 📁 Structure du Code
### Structure moderne du code
``` ```
notytex/ notytex/
├── 🚀 app.py # Application Flask + routes principales ├── 🚀 app.py # Point d'entrée Flask + routes de base
├── 📊 models.py # Modèles SQLAlchemy + logique métier ├── 📊 models.py # Modèles SQLAlchemy + logique métier
├── ⚙️ app_config_classes.py # Classes de configuration Flask ├── ⚙️ app_config_classes.py # Classes de configuration Flask (dev/prod/test)
├── 🔧 config/ # Configuration externalisée ├── 🔧 config/ # Configuration sécurisée externalisée
│ ├── __init__.py │ ├── __init__.py
│ └── settings.py # Gestion des variables d'environnement │ └── settings.py # Gestion variables d'environnement + validation
├── 🛡️ exceptions/ # Gestion d'erreurs centralisée ├── 🛡️ exceptions/ # Gestion d'erreurs centralisée
│ ├── __init__.py │ ├── __init__.py
│ └── handlers.py # Gestionnaires d'erreurs globaux │ └── handlers.py # Gestionnaires d'erreurs globaux (JSON/HTML)
├── 🔍 core/ # Utilitaires centraux ├── 🔍 core/ # Utilitaires centraux
│ ├── __init__.py │ ├── __init__.py
│ └── logging.py # Logging structuré JSON │ └── logging.py # Logging structuré JSON + corrélation requêtes
├── 📦 repositories/ # Pattern Repository (accès données) ├── 📦 repositories/ # Pattern Repository pour accès données
│ ├── __init__.py │ ├── __init__.py
│ ├── base_repository.py # Repository de base générique │ ├── base_repository.py # Repository générique CRUD
│ └── assessment_repository.py # Repository spécialisé Assessment │ └── assessment_repository.py # Repository spécialisé Assessment
├── 📁 routes/ # Blueprints organisés par fonctionnalité ├── 📁 routes/ # Blueprints organisés par fonctionnalité
│ ├── assessments.py # CRUD évaluations + création unifiée │ ├── assessments.py # CRUD évaluations (création unifiée)
│ ├── exercises.py # Gestion exercices + éléments notation │ ├── exercises.py # Gestion des exercices
│ ├── grading.py # Interface saisie des notes │ ├── grading.py # Saisie et gestion des notes
│ └── config.py # Interface configuration système │ └── config.py # Interface configuration système
├── 🎨 templates/ # Templates Jinja2 + composants réutilisables ├── 🎨 templates/ # Templates Jinja2 avec indicateurs UX intégrés
├── 🧪 tests/ # Tests pytest avec 100% de réussite ├── 🧪 tests/ # Tests pytest (100 tests ✅)
└── 📋 domain/ # Exceptions métier personnalisées └── 📋 domain/ # Exceptions métier personnalisées
``` ```
### Modèle de données hiérarchique ### 📊 Modèle de Données Hiérarchique
``` ```
ClassGroup (6ème A, 5ème B...) ClassGroup (Classes: 6ème A, 5ème B...)
↓ ↓
Students (Élèves de la classe) Students (Élèves de la classe)
↓ ↓
Assessment (Contrôle mathématiques, Trimestre 1...) Assessment (Évaluations: Contrôle Chapitre 3, Trimestre obligatoire)
↓ ↓
Exercise (Exercice 1, Exercice 2...) Exercise (Exercices: Exercice 1, Exercice 2...)
↓ ↓
GradingElement (Question a, b, c...) + grading_type (notes|score) GradingElement (Questions: a, b, c... + type: notes|score)
↓ ↓
Grade (Note attribuée à chaque élève) + valeurs spéciales configurables Grade (Notes attribuées à chaque élève + valeurs spéciales)
↓
GradingConfig (Configuration centralisée des types de notation)
``` ```
### Technologies et architecture ### 🛠️ Stack Technique
- **Backend** : Flask, SQLAlchemy, WTForms, Pydantic
- **Frontend** : TailwindCSS, Jinja2, JavaScript, Chart.js - **Framework Backend** : Flask (Python) avec architecture modulaire
- **Base de données** : SQLite avec migrations - **Base de données** : SQLite avec SQLAlchemy ORM + Repository Pattern
- **Configuration** : Variables d'environnement (.env) - **Frontend** : Templates Jinja2 + TailwindCSS + JavaScript + Chart.js
- **Logging** : Structuré JSON avec corrélation des requêtes
- **Tests** : Pytest avec couverture complète (100 tests ✅) - **Tests** : Pytest avec couverture complète (100 tests ✅)
- **Architecture** : Repository Pattern, Dependency Injection - **Configuration** : Variables d'environnement externalisées (.env)
- **Sécurité** : Configuration externalisée, validation centralisée - **Logging** : Structuré JSON avec corrélation des requêtes
- **Sécurité** : Configuration sécurisée + gestion d'erreurs centralisée
## ⚙️ Configuration ## ⚙️ Configuration
### Variables d'environnement (.env) ### 🔧 Variables d'Environnement (.env)
```bash ```bash
# Configuration obligatoire # OBLIGATOIRE - Sécurité
SECRET_KEY=your-secret-key-here-min-32-chars-dev-example-key-2025 SECRET_KEY=your-secret-key-here-minimum-32-characters-required
# Optionnel - Base de données
DATABASE_URL=sqlite:///school_management.db DATABASE_URL=sqlite:///school_management.db
# Configuration optionnelle # Optionnel - Environnement de développement
FLASK_ENV=development FLASK_ENV=development
LOG_LEVEL=INFO
DEBUG=true DEBUG=true
LOG_LEVEL=INFO
DB_ECHO=false DB_ECHO=false
WTF_CSRF_TIME_LIMIT=3600 WTF_CSRF_TIME_LIMIT=3600
``` ```
### Configuration de production ### 🏭 Configuration de Production
```bash ```bash
# Utiliser des valeurs sécurisées # Variables critiques pour la production
SECRET_KEY=your-production-secret-key-min-32-chars-prod SECRET_KEY=your-production-secret-key-min-32-chars-strong
DATABASE_URL=postgresql://user:pass@localhost/notytex_prod DATABASE_URL=postgresql://user:password@localhost/notytex_prod
FLASK_ENV=production FLASK_ENV=production
LOG_LEVEL=WARNING
DEBUG=false DEBUG=false
LOG_LEVEL=WARNING
``` ```
> ⚠️ **Important** : La variable `SECRET_KEY` est obligatoire et doit faire au minimum 32 caractères. L'application refusera de démarrer sans cette configuration.
## 🧪 Tests et Qualité ## 🧪 Tests et Qualité
### Lancer les tests ### 🚦 Lancer les Tests
```bash ```bash
# Tous les tests (100 tests ✅) # Tous les tests (100 tests ✅)
uv run pytest uv run pytest
# Tests avec couverture # Tests avec rapport de couverture
uv run pytest --cov=. --cov-report=html uv run pytest --cov=. --cov-report=html
# Tests spécifiques # Tests spécifiques par module
uv run pytest tests/test_models.py -v
uv run pytest tests/test_repositories.py -v uv run pytest tests/test_repositories.py -v
``` ```
### Architecture de tests ### 🎯 Organisation des 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 - **test_config.py** : Tests configuration externalisée + validation
- **test_error_handlers.py** : Tests gestion d'erreurs centralisée
- **test_logging.py** : Tests logging structuré JSON
- **test_repositories.py** : Tests Repository Pattern + CRUD
- **test_models.py** : Tests modèles SQLAlchemy + logique métier
- **test*routes*\*.py** : Tests routes Flask + contrôleurs
- **test_forms.py** : Tests validation WTForms
### 📊 Métriques de Qualité
- ✅ **100 tests** passent avec succès
- ✅ **Architecture découplée** avec Repository Pattern
- ✅ **Configuration sécurisée** externalisée
- ✅ **Gestion d'erreurs robuste** centralisée
## 🛠️ Guide de Développement
### 🔄 Workflow de Développement
### Workflow de développement
```bash ```bash
# 1. Environnement de développement # 1. Configuration initiale
cp .env.example .env cp .env.example .env
# Éditer .env avec SECRET_KEY obligatoire
uv run flask --app app init-db uv run flask --app app init-db
# 2. Lancement avec rechargement automatique # 2. Développement avec rechargement automatique
uv run flask --app app run --debug uv run flask --app app run --debug
# 3. Tests avant commit # 3. Validation avant commit
uv run pytest uv run pytest
# 4. Analyse des logs # 4. Analyse des logs en temps réel
tail -f logs/notytex.log tail -f logs/notytex.log | jq '.' # Pour formater le JSON
``` ```
### Ajout de nouvelles fonctionnalités ### 🆕 Ajouter une Nouvelle Fonctionnalité
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 1. **Modèles** : Définir les entités dans `models.py`
2. **Repository** : Créer l'accès données dans `repositories/`
3. **Routes** : Implémenter les contrôleurs dans `routes/`
4. **Templates** : Créer les vues dans `templates/`
5. **Forms** : Ajouter la validation dans `forms.py`
6. **Tests** : Couvrir la fonctionnalité dans `tests/`
### Logs structurés ### 🎯 Conventions de Code
- **Format** : JSON avec corrélation des requêtes
- **PEP 8** : Style Python standard
- **Type hints** : Recommandés pour les nouvelles fonctions
- **Docstrings** : Format Google pour les fonctions publiques
- **Tests** : Couverture obligatoire pour les nouvelles fonctionnalités
## 📊 Monitoring et Observabilité
### 📝 Logs Structurés JSON
- **Format** : JSON avec ID de corrélation unique par requête
- **Localisation** : `logs/notytex.log` - **Localisation** : `logs/notytex.log`
- **Niveaux** : DEBUG, INFO, WARNING, ERROR - **Niveaux** : DEBUG, INFO, WARNING, ERROR
- **Contexte** : URL, méthode, adresse IP, user-agent - **Contexte automatique** : URL, méthode HTTP, IP, user-agent, timestamp
- **Événements métier** : Création/modification/suppression d'évaluations
### Métriques disponibles ### 📈 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 - **Performance** : Temps de réponse des requêtes HTTP
- **Métier** : Événements d'évaluation, progression des corrections
- **Erreurs** : Exceptions applicatives et techniques
- **Utilisation** : Ressources système et base de données
1. **Professeur crée une évaluation** : "Contrôle Chapitre 3 - Fonctions" pour le 2ème trimestre ### 🔍 Exemple de Log Structuré
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é ```json
{
"timestamp": "2025-08-06T10:30:45.123Z",
"level": "INFO",
"correlation_id": "uuid-1234-5678-9abc",
"message": "Assessment created successfully",
"context": {
"assessment_id": 123,
"class_group_id": 45,
"trimester": 1
}
}
```
- **Configuration externalisée** : Aucune donnée sensible en dur ## 🎓 Exemple d'Utilisation Complète
- **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 ### 📝 Scénario : Création et Correction d'une Évaluation
- Enseignants du secondaire (collège/lycée) 1. **🏗️ Création de l'évaluation**
- Établissements souhaitant digitaliser leurs évaluations
- Contexte où coexistent notation classique et évaluation par compétences - Titre : "Contrôle Chapitre 3 - Fonctions"
- Paramètres : Date, **trimestre obligatoire** (ex: 2), classe, coefficient
2. **⚙️ Structure de l'évaluation**
- **Exercice 1** : "Calculs de base" (notes en points)
- Question 1a : 2 points
- Question 1b : 3 points
- **Exercice 2** : "Compétences graphiques" (score 0-3)
- Compétence "Lire un graphique" : échelle 0-3
3. **📊 Suivi de la progression**
- **Indicateur initial** : "Correction 0%" (rouge) visible sur toutes les pages
- **Saisie des notes** : Clic sur l'indicateur → accès direct à la page de notation
- **Progression temps réel** : "Correction 45%" (orange) → "Correction 100%" (vert)
4. **📈 Analyse des résultats**
- **Statistiques automatiques** : Moyenne, médiane, écart-type
- **Visualisation graphique** : Histogramme de distribution des notes
- **Tableau détaillé** : Classement alphabétique avec scores par exercice
## 🛡️ Sécurité et Bonnes Pratiques
### 🔐 Sécurité Applicative
- **Configuration externalisée** : Variables d'environnement (.env) - aucune donnée sensible en dur
- **Validation centralisée** : WTForms + validation des données en entrée
- **Gestion d'erreurs sécurisée** : Pas de fuite d'informations sensibles dans les messages
- **Logs sécurisés** : Exclusion des données personnelles/sensibles des logs
- **CSRF Protection** : Protection native Flask-WTF contre les attaques CSRF
### 🏗️ Architecture Robuste
- **Respect des principes 12 Factor App** : Configuration, logs, processus
- **Repository Pattern** : Couche d'abstraction pour l'accès aux données
- **Gestion d'erreurs centralisée** : Traitement uniforme des exceptions
- **Tests complets** : Couverture de 100% des fonctionnalités critiques
## 👥 Public Cible et Contexte d'Usage
### 🎓 Utilisateurs Principaux
- **Enseignants** du secondaire (collège, lycée)
- **Équipes pédagogiques** souhaitant harmoniser leurs pratiques d'évaluation
- **Établissements scolaires** en transition vers le numérique
### 📚 Contextes Pédagogiques
- **Coexistence des pratiques** : Notation classique ET évaluation par compétences
- **Gestion par trimestre** : Organisation structurée des évaluations scolaires
- **Diversité des exercices** : Support des différents formats de contrôles
--- ---
**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. ## 🌟 Conclusion
**Notytex** combine une **architecture technique moderne et robuste** avec une **interface utilisateur intuitive** centrée sur l'expérience enseignant. Grâce à ses indicateurs de progression intégrés, son système de notation dual et ses analyses statistiques avancées, il répond concrètement aux besoins du monde éducatif tout en respectant les meilleures pratiques du développement logiciel.