notytex/README.md

# 📚 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](https://docs.astral.sh/uv/))
- **Node.js 22 LTS** 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 (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** 🐳

```bash
# 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`](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**

```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**