Bertrand Benjamin
1f17b1e982
- Correction commande: python -m uvicorn au lieu de uvicorn seul
- Copie de la base de données depuis instance/ vers racine
- README mis à jour avec la bonne commande
- Backend vérifié: /api/v2/health répond healthy ✅
350 lines
8.8 KiB
Markdown
350 lines
8.8 KiB
Markdown
# 📚 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+** avec `uv` ([installation](https://docs.astral.sh/uv/))
|
|
- **Node.js 18+** avec `npm`
|
|
- **Git**
|
|
|
|
### **Backend (FastAPI)**
|
|
|
|
```bash
|
|
cd backend
|
|
uv sync --all-extras
|
|
uv run python -m uvicorn api.main:app --reload --port 8000
|
|
```
|
|
|
|
### **Frontend (Vue.js)**
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
### **Accès**
|
|
|
|
- **Frontend** : http://localhost:3000
|
|
- **API Backend** : http://localhost:8000
|
|
- **Documentation API** : http://localhost:8000/api/v2/docs
|
|
- **ReDoc** : http://localhost:8000/api/v2/redoc
|
|
|
|
---
|
|
|
|
## 🏗️ **Architecture Technique**
|
|
|
|
### **Stack Technologique**
|
|
|
|
**Backend :**
|
|
- FastAPI 0.109+ (API REST moderne avec support async)
|
|
- SQLAlchemy 2.0+ avec aiosqlite (ORM async)
|
|
- Pydantic 2.0+ (validation et sérialisation)
|
|
- Uvicorn (serveur ASGI)
|
|
|
|
**Frontend :**
|
|
- Vue.js 3.4+ (framework progressif)
|
|
- Vite (build tool ultra-rapide)
|
|
- Vue Router 4 (routing SPA)
|
|
- Pinia (state management)
|
|
- TailwindCSS 3 (styling moderne)
|
|
- Chart.js 4 (graphiques interactifs)
|
|
- Axios (client HTTP)
|
|
|
|
**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**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```bash
|
|
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`)**
|
|
|
|
```bash
|
|
# 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`](REWRITE.md) - Historique de la réécriture v1 → v2
|
|
- **Backend** : [`backend/README.md`](backend/README.md) - Documentation API
|
|
- **Parité fonctionnelle** : [`backend/docs/PARITY_CHECKLIST.md`](backend/docs/PARITY_CHECKLIST.md)
|
|
- **Documentation API** : http://localhost:8000/api/v2/docs (Swagger)
|
|
|
|
---
|
|
|
|
## 🔧 **Commandes Utiles**
|
|
|
|
### **Backend**
|
|
|
|
```bash
|
|
# 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**
|
|
|
|
```bash
|
|
# 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](https://fastapi.tiangolo.com/)
|
|
- [Vue.js 3 Documentation](https://vuejs.org/)
|
|
- [SQLAlchemy 2.0](https://docs.sqlalchemy.org/en/20/)
|
|
- [Pydantic](https://docs.pydantic.dev/)
|
|
- [TailwindCSS](https://tailwindcss.com/)
|
|
|
|
---
|
|
|
|
**Développé avec ❤️ pour simplifier la vie des enseignants**
|