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

# 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)

# 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

# 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

# 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

# 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

Créer les modèles dans models.py
Implémenter le repository dans repositories/
Créer les routes dans routes/
Ajouter les templates dans templates/
É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

Professeur crée une évaluation : "Contrôle Chapitre 3 - Fonctions" pour le 2ème trimestre
Définit les paramètres : Date, trimestre (obligatoire), classe, coefficient
Ajoute des exercices : "Exercice 1: Calculs", "Exercice 2: Graphiques"
Définit le barème : Question 1a (2 pts), Question 1b (3 pts), Compétence graphique (score 0-3)
Voit l'indicateur de progression : "Correction 0%" en rouge sur toutes les pages
Saisit les notes pour chaque élève sur chaque élément via clic sur l'indicateur
Suit la progression : L'indicateur passe à "Correction 45%" en orange, puis "Correction 100%" en vert
Consulte les résultats détaillés : Accès direct à la page de résultats avec statistiques et histogramme
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.