📚 Notytex - 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.

🎯 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

• Groupes classes : Organisation des élèves par classe avec gestion des années scolaires
• Évaluations par trimestre : Chaque évaluation doit être assignée à un trimestre (1, 2 ou 3)
• Structure modulaire : ClassGroup → Students → Assessment → Exercise → GradingElement → Grade
• Interface unifiée : Création d'évaluation + exercices + barème en une seule fois
• Indicateurs de progression : Visualisation temps réel de l'état de correction avec code couleur

🎯 Système de Notation Dual Unifié

2 Types de Notation Complémentaires :

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 :

• . = Pas de réponse (traité comme 0 dans les calculs)
• d = Dispensé (exclu des calculs de moyenne)
• Autres valeurs : Configuration flexible via interface d'administration

Configuration Centralisée :

• Interface d'administration : Personnalisation complète des significations et couleurs
• Règles de calcul : Logique unifiée pour tous les types avec gestion des cas particuliers
• Cohérence pédagogique : Adaptation aux différentes pratiques d'évaluation

📊 Analyse des Résultats et Statistiques

• Statistiques descriptives complètes : Moyenne, médiane, minimum, maximum, écart-type
• Visualisation graphique interactive : Histogrammes de distribution avec Chart.js
• 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)
• Git : Pour le contrôle de version

⚡ Installation (5 minutes)

# 1. Cloner et accéder au projet
git clone <repository>
cd notytex

# 2. Installer les dépendances
uv sync

# 3. Configuration obligatoire
cp .env.example .env
# Modifier .env avec SECRET_KEY (minimum 32 caractères obligatoire)

# 4. Initialiser la base de données avec données de démonstration
uv run flask --app app init-db

# 5. Lancer l'application en mode développement
uv run flask --app app run --debug

🌐 Accès à l'Application

• 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

notytex/
├── 🚀 app.py                    # Point d'entrée Flask + routes de base
├── 📊 models.py                 # Modèles SQLAlchemy + logique métier
├── ⚙️ app_config_classes.py     # Classes de configuration Flask (dev/prod/test)
├── 🔧 config/                   # Configuration sécurisée externalisé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
│   └── config.py                # Interface configuration système
├── 🎨 templates/                # Templates Jinja2 avec indicateurs UX intégrés
├── 🧪 tests/                    # Tests pytest (100 tests ✅)
└── 📋 domain/                   # Exceptions métier personnalisées

📊 Modèle de Données Hiérarchique

ClassGroup (Classes: 6ème A, 5ème B...)
    ↓
Students (Élèves de la classe)
    ↓
Assessment (Évaluations: Contrôle Chapitre 3, Trimestre obligatoire)
    ↓
Exercise (Exercices: Exercice 1, Exercice 2...)
    ↓
GradingElement (Questions: a, b, c... + type: notes|score)
    ↓
Grade (Notes attribuées à chaque élève + valeurs spéciales)

🛠️ Stack Technique

• Framework Backend : Flask (Python) avec architecture modulaire
• 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

⚙️ Configuration

🔧 Variables d'Environnement (.env)

# OBLIGATOIRE - Sécurité
SECRET_KEY=your-secret-key-here-minimum-32-characters-required

# Optionnel - Base de données
DATABASE_URL=sqlite:///school_management.db

# Optionnel - Environnement de développement
FLASK_ENV=development
DEBUG=true
LOG_LEVEL=INFO
DB_ECHO=false
WTF_CSRF_TIME_LIMIT=3600

🏭 Configuration de Production

# Variables critiques pour la production
SECRET_KEY=your-production-secret-key-min-32-chars-strong
DATABASE_URL=postgresql://user:password@localhost/notytex_prod
FLASK_ENV=production
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é

🚦 Lancer les Tests

# Tous les tests (100 tests ✅)
uv run pytest

# Tests avec rapport de couverture
uv run pytest --cov=. --cov-report=html

# Tests spécifiques par module
uv run pytest tests/test_models.py -v
uv run pytest tests/test_repositories.py -v

🎯 Organisation des Tests

• 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
• testroutes*.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

# 1. Configuration initiale
cp .env.example .env
# Éditer .env avec SECRET_KEY obligatoire
uv run flask --app app init-db

# 2. Développement avec rechargement automatique
uv run flask --app app run --debug

# 3. Validation avant commit
uv run pytest

# 4. Analyse des logs en temps réel
tail -f logs/notytex.log | jq '.'  # Pour formater le JSON

🆕 Ajouter une Nouvelle Fonctionnalité

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/

🎯 Conventions de Code

• 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
• Niveaux : DEBUG, INFO, WARNING, ERROR
• Contexte automatique : URL, méthode HTTP, IP, user-agent, timestamp
• Événements métier : Création/modification/suppression d'évaluations

📈 Métriques Disponibles

• 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

🔍 Exemple de Log Structuré

{
  "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
  }
}

🎓 Exemple d'Utilisation Complète

📝 Scénario : Création et Correction d'une Évaluation

1. 🏗️ Création de l'évaluation

   • 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

---

🌟 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.