notytex/README.md

📚 Notytex - Système de Gestion Scolaire

Notytex est une application web Flask conçue pour la gestion complète des évaluations. Elle permet aux enseignants de créer, organiser et noter les évaluations de leurs élèves.

Cette application a été presque entièrement vibecodé. Il ne faut donc pas s'attendre à des merveilles..! Mais elle est fonctionnelle et je l'utilise pour la gestion de mes notes!

🎯 Objectif Principal

Simplifier et digitaliser le processus d'évaluation scolaire, de la création des contrôles à la saisie des notes.

⭐ 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 : Cartes interactives
• 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 (voir modes ci-dessous)
uv run flask --app app init-db

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

🎯 Modes d'Initialisation de la Base de Données

Notytex propose 3 modes d'initialisation adaptés aux différents contextes d'usage :

🌱 Mode Minimal (par défaut) - Début d'année scolaire

uv run flask --app app init-db --mode minimal
# ou simplement
uv run flask --app app init-db

• Usage : Début d'année scolaire, base vierge
• Contenu : Configuration de base uniquement
• Idéal pour : Démarrer une nouvelle année avec ses vraies classes et élèves

📚 Mode Milieu d'Année - Données réalistes complètes

uv run flask --app app init-db --mode midyear

• Usage : Tester l'application avec des données représentatives
• Contenu :
  • 5 classes avec 142 élèves au total (25-32 élèves par classe)
  • 30 évaluations créées (6 par classe sur 2 trimestres)
  • 4 évaluations entièrement corrigées par classe (Trimestre 1)
  • 2 évaluations partiellement corrigées par classe (Trimestre 2)
  • Notes réalistes générées automatiquement
• Idéal pour : Démonstrations, formations, tests de performance
• Volumétrie : Correspond aux spécifications du CLAUDE.md (milieu de 2ème trimestre)

🧪 Mode Démonstration - Données minimales

uv run flask --app app init-db --mode demo

• Usage : Tests rapides et démonstrations simples
• Contenu : 2 classes, 5 élèves, 1 évaluation simple
• Idéal pour : Premiers pas avec l'application

🌐 Accès à l'Application

• URL de développement : http://localhost:5000
• Interface : Dashboard avec navigation intuitive et indicateurs de progression
• Données : Variables selon le mode d'initialisation choisi

🏗️ 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

# 2. Choisir le mode d'initialisation selon le contexte
uv run flask --app app init-db --mode minimal     # Début d'année
uv run flask --app app init-db --mode midyear     # Tests avec données complètes
uv run flask --app app init-db --mode demo        # Démonstration rapide

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

# 4. Validation avant commit
uv run pytest

# 5. 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

🔍 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
  }
}

🎓 Exemples d'Utilisation Complète

🌱 Scénario Début d'Année - Mode Minimal

# Initialisation pour démarrer l'année scolaire
uv run flask --app app init-db --mode minimal

Étapes typiques :

1. Configuration initiale : Année scolaire 2025-2026 automatiquement définie
2. Création des classes : Ajouter manuellement 6ème A, 5ème B, etc.
3. Import des élèves : Saisir ou importer les listes d'élèves réelles
4. Première évaluation : Créer le premier contrôle de l'année

📚 Scénario Milieu d'Année - Mode Données Complètes

# Initialisation avec données réalistes de milieu d'année
uv run flask --app app init-db --mode midyear

Contenu automatiquement généré :

• Classes : 6ème A (28 élèves), 6ème B (25 élèves), 5ème A (30 élèves), 5ème B (27 élèves), 4ème A (32 élèves)
• Évaluations Trimestre 1 (100% corrigées) :
  • Contrôle Nombres entiers (coefficient 2.0)
  • Évaluation Géométrie (coefficient 2.5)
  • Contrôle Fractions (coefficient 3.0)
  • Devoir Maison Recherche (coefficient 1.5)
• Évaluations Trimestre 2 (partiellement corrigées) :
  • Contrôle Proportionnalité (coefficient 2.5)
  • Évaluation Statistiques (coefficient 2.0)

Utilisation immédiate :

1. Dashboard : Aperçu des 142 élèves, 30 évaluations, 5 classes
2. Indicateurs de progression : Visualisation des corrections en cours
3. Analyse des résultats : Statistiques et graphiques sur les évaluations terminées
4. Saisie de notes : Continuer la correction des évaluations partielles

📝 Scénario Création d'Évaluation - Workflow Standard

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)

📚 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