📚 Notytex v2 - Système de Gestion Scolaire

Notytex est une application web moderne pour la gestion complète des évaluations scolaires. Version 2.0 entièrement réécrite avec FastAPI (backend) et Vue.js 3 (frontend).

🎯 Objectif Principal

Simplifier et digitaliser le processus d'évaluation scolaire, de la création des contrôles à la saisie des notes, en offrant une interface moderne et réactive.

---

🚀 Démarrage Rapide

Prérequis

• Python 3.11-3.13 avec uv (installation)
• Node.js 22 LTS avec npm
• Git

Backend (FastAPI)

cd backend
uv sync --all-extras
uv run python -m uvicorn api.main:app --reload --port 8000

Frontend (Vue.js)

cd frontend
npm install
npm run dev

Accès (Mode Développement)

• Frontend : http://localhost:3000
• API Backend : http://localhost:8000
• Documentation API : http://localhost:8000/api/v2/docs
• ReDoc : http://localhost:8000/api/v2/redoc

Déploiement avec Docker / Podman 🐳

# Configuration
cd docker
cp .env.example .env
# Éditez .env et changez SECRET_KEY

# Démarrage (Docker ou Podman)
docker compose up -d
# ou
podman-compose up -d

Accès (Mode Docker/Podman) :

• Frontend : http://localhost:8081
• API Backend : http://localhost:8080
• Documentation API : http://localhost:8080/api/v2/docs

💡 Ports sans privilèges : Les ports 8080/8081 permettent l'utilisation avec Podman sans root

📖 Documentation complète : docker/README.md

---

🏗️ Architecture Technique

Stack Technologique

Backend :

• FastAPI 0.115+ (API REST moderne avec support async)
• SQLAlchemy 2.0.36+ avec aiosqlite (ORM async)
• Pydantic 2.10+ (validation et sérialisation)
• Uvicorn 0.32+ (serveur ASGI)
• Python 3.11-3.13

Frontend :

• Vue.js 3.5+ (framework progressif)
• Vite 6.0+ (build tool ultra-rapide)
• Vue Router 4.5+ (routing SPA)
• Pinia 2.2+ (state management)
• TailwindCSS 3.4+ (styling moderne)
• Chart.js 4.4+ (graphiques interactifs)
• Axios 1.7+ (client HTTP)
• Node.js 22 LTS

Base de données :

• SQLite (développement)
• PostgreSQL recommandé (production)

---

📊 Modèle de Données

ClassGroup (Classe)
    ↓
Students (Élèves avec gestion temporelle)
    ↓
Assessment (Évaluation par trimestre)
    ↓
Exercise (Exercices)
    ↓
GradingElement (Questions/Compétences)
    ↓
Grade (Notes individuelles)

---

⭐ Fonctionnalités Principales

Gestion des Classes et Élèves

• Création et organisation de classes par année
• Inscription, transfert et départ d'élèves avec historique
• Import CSV en masse
• Statistiques par trimestre et par classe

Système d'Évaluation

• Création unifiée d'évaluations (éval + exercices + barème)
• Organisation par trimestre (1, 2, 3)
• Filtrage avancé (trimestre, classe, statut de correction)
• Indicateurs de progression de correction en temps réel

Notation Dual Configurable

2 Types de Notation :

1. notes : Valeurs numériques décimales (ex: 15.5/20)
2. score : Échelle 0-3 pour compétences (0=Non acquis → 3=Expert)

Valeurs Spéciales :

• . = Absent (compte comme 0)
• d = Dispensé (exclu des calculs)
• Configuration personnalisable via interface

Analyse et Statistiques

• Dashboard avec statistiques globales
• Résultats détaillés par évaluation
• Histogrammes de distribution des notes
• Heatmaps par compétences et domaines
• Statistiques descriptives (moyenne, médiane, écart-type)

Conseil de Classe

• Préparation automatique avec données consolidées
• Saisie et historique des appréciations
• Vue complète des performances par élève

Envoi de Bilans par Email

• Génération automatique de bilans individualisés
• Support SMTP configurable (Gmail, Outlook, etc.)
• Templates HTML responsives
• Envoi en lot avec rapport détaillé

---

🧪 Tests

Backend

cd backend

# Tous les tests
uv run pytest tests/ -v

# Tests unitaires uniquement
uv run pytest tests/unit/ -v

# Avec couverture
uv run pytest tests/ --cov=. --cov-report=html

Résultat actuel : 99/99 tests ✅

Frontend

cd frontend

# Tests unitaires (à venir)
npm run test:unit

# Tests E2E (à venir)
npm run test:e2e

---

📂 Structure du Projet

notytex/
├── backend/                    # API FastAPI
│   ├── api/                   # Routes et endpoints
│   │   ├── main.py           # Application principale
│   │   └── routes/           # Routes organisées par fonctionnalité
│   ├── domain/               # Logique métier pure
│   │   ├── services/         # Services de calcul
│   │   └── value_objects/    # Objets valeur
│   ├── infrastructure/       # Couche d'infrastructure
│   │   ├── database/         # Modèles SQLAlchemy + repositories
│   │   └── external/         # Services externes (email)
│   ├── schemas/              # Modèles Pydantic (validation I/O)
│   ├── core/                 # Configuration
│   └── tests/                # Tests unitaires et d'intégration
├── frontend/                  # SPA Vue.js
│   ├── src/
│   │   ├── components/       # Composants réutilisables
│   │   ├── views/            # Pages de l'application
│   │   ├── stores/           # State management Pinia
│   │   ├── services/         # Clients API
│   │   ├── router/           # Configuration routing
│   │   └── assets/           # Assets statiques
│   └── public/               # Fichiers publics
├── docs/                      # Documentation complète
├── school_management.db       # Base de données SQLite
└── README.md                  # Ce fichier

---

⚙️ Configuration

Backend (backend/.env)

# Base de données
DATABASE_URL=sqlite+aiosqlite:///../school_management.db

# Sécurité
SECRET_KEY=your-secret-key-here-min-32-chars

# CORS (origines autorisées)
CORS_ORIGINS=["http://localhost:3000","http://localhost:5173"]

# Logging
LOG_LEVEL=INFO

# Email (optionnel)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
EMAIL_FROM=your-email@gmail.com

Frontend

Le frontend utilise un proxy Vite configuré dans vite.config.js pour rediriger /api vers le backend.

---

📖 Documentation Complète

• Architecture détaillée : REWRITE.md - Historique de la réécriture v1 → v2
• Backend : backend/README.md - Documentation API
• Parité fonctionnelle : backend/docs/PARITY_CHECKLIST.md
• Documentation API : http://localhost:8000/api/v2/docs (Swagger)

---

🔧 Commandes Utiles

Backend

# Démarrer l'API en mode développement
cd backend && uv run python -m uvicorn api.main:app --reload --port 8000

# Exécuter les tests
cd backend && uv run pytest tests/ -v

# Formater le code
cd backend && uv run black .

# Linter
cd backend && uv run ruff check .

Frontend

# Démarrer en développement
cd frontend && npm run dev

# Build pour production
cd frontend && npm run build

# Preview du build
cd frontend && npm run preview

---

📊 État du Projet

Fonctionnalités Implémentées (100%)

Module	Fonctionnalités	Status
Classes	CRUD, stats, dashboard	✅
Élèves	CRUD, inscriptions, import CSV	✅
Évaluations	Création unifiée, filtres, progression	✅
Notation	Grille interactive, valeurs spéciales	✅
Résultats	Statistiques, graphiques, heatmaps	✅
Conseil	Préparation, appréciations	✅
Configuration	Compétences, domaines, échelle, SMTP	✅
Email	Envoi bilans individualisés	✅

Tests

• Backend : 99/99 tests unitaires ✅
• API : 45 routes opérationnelles ✅
• Frontend : 14 vues complètes ✅

---

🎓 Public Cible

• Enseignants du secondaire (collège/lycée)
• Établissements souhaitant digitaliser leurs évaluations
• Contexte de coexistence notation classique / évaluation par compétences

---

📝 Notes de Version

Version 2.0.0 (Actuelle)

• ✨ Réécriture complète en FastAPI + Vue.js
• ⚡ Architecture moderne avec séparation backend/frontend
• 🚀 API REST JSON pure avec documentation OpenAPI
• 🎨 Interface utilisateur réactive avec Vue 3
• 📊 Graphiques interactifs avec Chart.js
• 🔒 Validation Pydantic sur toutes les entrées
• 🧪 99 tests unitaires avec 100% de succès

Version 1.0.0 (Legacy)

• Application Flask monolithique
• Code disponible dans l'historique Git (branche main avant migration)

---

🤝 Contribution

Ce projet a été développé avec l'aide d'assistants IA (principalement Claude). Les contributions sont bienvenues !

---

📄 Licence

MIT

---

🔗 Liens Utiles

• FastAPI Documentation
• Vue.js 3 Documentation
• SQLAlchemy 2.0
• Pydantic
• TailwindCSS

---

Développé avec ❤️ pour simplifier la vie des enseignants