414 lines
13 KiB
Markdown
414 lines
13 KiB
Markdown
# 🏗️ Documentation Backend - Notytex
|
|
|
|
> **Architecture & Services Backend**
|
|
> **Version**: 2.0
|
|
> **Dernière mise à jour**: 7 août 2025
|
|
|
|
## 🎯 **Vue d'Ensemble**
|
|
|
|
Cette documentation couvre l'ensemble de l'**architecture backend Notytex**, ses services, patterns architecturaux, et les bonnes pratiques pour maintenir un système robuste et évolutif.
|
|
|
|
---
|
|
|
|
## 📁 **Organisation de la Documentation**
|
|
|
|
### 🏛️ **Architecture & Patterns**
|
|
|
|
| Document | Description | Statut |
|
|
|----------|-------------|---------|
|
|
| Architecture Overview | Vue d'ensemble patterns & principes | 📋 |
|
|
| **[REPOSITORY_PATTERN.md](./REPOSITORY_PATTERN.md)** | Repository Pattern ClassGroup - complet | ✅ |
|
|
| Service Layer | Logique métier & services | 📋 |
|
|
| Error Handling | Gestion centralisée des erreurs | 📋 |
|
|
|
|
### 🔧 **Modules et Services**
|
|
|
|
| Document | Description | Statut |
|
|
|----------|-------------|---------|
|
|
| **[CLASSES_CRUD.md](./CLASSES_CRUD.md)** | Système CRUD des Classes - complet | ✅ |
|
|
| Assessment Services | Gestion des évaluations et calculs | 📋 |
|
|
| Grading System | Système de notation unifié | 📋 |
|
|
| Configuration Management | Gestion configuration dynamique | 📋 |
|
|
|
|
### 🗄️ **Base de Données & Modèles**
|
|
|
|
| Document | Description | Statut |
|
|
|----------|-------------|---------|
|
|
| Data Models | Modèles SQLAlchemy & relations | 📋 |
|
|
| Migration Strategies | Gestion des migrations DB | 📋 |
|
|
| Performance Optimization | Requêtes optimisées & indexing | 📋 |
|
|
|
|
### 🔐 **Sécurité & Authentification**
|
|
|
|
| Document | Description | Statut |
|
|
|----------|-------------|---------|
|
|
| Security Guidelines | Standards sécurité backend | 📋 |
|
|
| CSRF Protection | Implémentation & configuration | 📋 |
|
|
| Input Validation | Validation serveur & sanitization | 📋 |
|
|
|
|
---
|
|
|
|
## 🚀 **Getting Started**
|
|
|
|
### **Pour les Nouveaux Développeurs Backend**
|
|
|
|
1. **Architecture générale** : Lire CLAUDE.md pour comprendre l'ensemble
|
|
2. **Premier module** : Étudier [CLASSES_CRUD.md](./CLASSES_CRUD.md) comme exemple complet
|
|
3. **Patterns** : Comprendre Repository Pattern & Service Layer
|
|
4. **Sécurité** : Maîtriser @handle_db_errors et validation
|
|
|
|
### **Pour les Développeurs Expérimentés**
|
|
|
|
1. **Standards** : Vérifier conformité avec les patterns existants
|
|
2. **Performance** : Optimiser les requêtes et éviter N+1 queries
|
|
3. **Tests** : Maintenir couverture ≥ 90%
|
|
4. **Documentation** : Documenter toute nouvelle fonctionnalité
|
|
|
|
### **Pour les Architectes**
|
|
|
|
1. **Évolution** : Planifier les migrations et refactorings
|
|
2. **Scalabilité** : Anticiper la montée en charge
|
|
3. **Monitoring** : Métriques et observabilité
|
|
4. **Standards** : Maintenir cohérence architecturale
|
|
|
|
---
|
|
|
|
## 🏛️ **Architecture en Bref**
|
|
|
|
### **Structure du Projet**
|
|
|
|
```
|
|
notytex/
|
|
├── 📱 app.py # Point d'entrée Flask + routes principales
|
|
├── 🗄️ models.py # Modèles SQLAlchemy + logique métier
|
|
├── ⚙️ app_config_classes.py # Configuration Flask par environnement
|
|
├── 🎯 forms.py # Formulaires WTForms + validation
|
|
├── 🛠️ utils.py # Décorateurs et utilitaires
|
|
├── 📁 routes/ # Blueprints organisés par fonctionnalité
|
|
│ ├── classes.py # CRUD classes ✅
|
|
│ ├── assessments.py # CRUD évaluations
|
|
│ ├── grading.py # Saisie et gestion des notes
|
|
│ └── config.py # Interface de configuration
|
|
├── 📁 repositories/ # Pattern Repository pour accès données ✅
|
|
│ ├── base_repository.py # Repository générique
|
|
│ ├── assessment_repository.py # Repository Assessment
|
|
│ └── class_repository.py # Repository ClassGroup ✅
|
|
├── 📁 services/ # Logique métier et calculs
|
|
│ └── assessment_services.py # Services d'évaluation
|
|
├── 📁 config/ # Configuration externalisée
|
|
│ └── settings.py # Variables d'environnement
|
|
├── 📁 exceptions/ # Gestion d'erreurs centralisée
|
|
│ └── handlers.py # Gestionnaires globaux
|
|
└── 📁 core/ # Utilitaires centraux
|
|
└── logging.py # Logging structuré JSON
|
|
```
|
|
|
|
### **Patterns Architecturaux Adoptés**
|
|
|
|
#### **1. Repository Pattern**
|
|
- **Séparation** : Logique d'accès données isolée
|
|
- **Réutilisabilité** : Requêtes complexes centralisées
|
|
- **Testabilité** : Repositories mockables
|
|
|
|
#### **2. Service Layer**
|
|
- **Logique métier** : Calculs et règles business
|
|
- **Orchestration** : Coordination entre repositories
|
|
- **Transaction management** : Gestion des transactions complexes
|
|
|
|
#### **3. Error Handling Centralisé**
|
|
- **Décorateur @handle_db_errors** : Gestion automatique des erreurs DB
|
|
- **Logging structuré** : Tous les événements tracés
|
|
- **Messages utilisateur** : Conversion erreurs techniques → messages clairs
|
|
|
|
#### **4. Configuration Externalisée**
|
|
- **Variables d'environnement** : Pas de secrets en dur
|
|
- **Validation au démarrage** : Échec rapide si config incorrecte
|
|
- **Multi-environnements** : dev/test/prod avec configs séparées
|
|
|
|
---
|
|
|
|
## 🔧 **Services Principaux**
|
|
|
|
### **Classes Management (✅ Complet)**
|
|
|
|
**Responsabilité** : Gestion complète du cycle de vie des classes scolaires
|
|
|
|
- ✅ **CRUD Operations** : Create, Read, Update, Delete
|
|
- ✅ **Validation Business** : Unicité des noms, vérifications cascade
|
|
- ✅ **Relations Management** : Étudiants et évaluations associées
|
|
- ✅ **Error Handling** : Gestion robuste des cas d'erreur
|
|
|
|
**Documentation** : [CLASSES_CRUD.md](./CLASSES_CRUD.md)
|
|
|
|
### **Assessment Services (Existant)**
|
|
|
|
**Responsabilité** : Gestion des évaluations et calculs de notes
|
|
|
|
- ✅ **Assessment Management** : Création évaluations complexes
|
|
- ✅ **Grading Calculations** : Calculs unifiés notes/compétences
|
|
- ✅ **Progress Tracking** : Suivi de progression des corrections
|
|
- ✅ **Statistics** : Analyses statistiques des résultats
|
|
|
|
### **Configuration System (Existant)**
|
|
|
|
**Responsabilité** : Gestion configuration dynamique application
|
|
|
|
- ✅ **Dynamic Settings** : Configuration runtime modifiable
|
|
- ✅ **Feature Flags** : Activation/désactivation fonctionnalités
|
|
- ✅ **Business Rules** : Règles métier configurables
|
|
- ✅ **Multi-tenancy** : Support configuration par établissement
|
|
|
|
---
|
|
|
|
## 🗄️ **Modèles de Données**
|
|
|
|
### **Hiérarchie Principale**
|
|
|
|
```
|
|
ClassGroup (Classe scolaire)
|
|
↓ One-to-Many
|
|
Student (Élève)
|
|
↓ Many-to-Many (via grades)
|
|
Assessment (Évaluation)
|
|
↓ One-to-Many
|
|
Exercise (Exercice)
|
|
↓ One-to-Many
|
|
GradingElement (Élément de notation)
|
|
↓ One-to-Many
|
|
Grade (Note individuelle)
|
|
```
|
|
|
|
### **Relations Clés**
|
|
|
|
| Relation | Type | Contraintes | Cascade |
|
|
|----------|------|-------------|---------|
|
|
| ClassGroup → Student | 1:N | NOT NULL | RESTRICT |
|
|
| ClassGroup → Assessment | 1:N | NOT NULL | RESTRICT |
|
|
| Assessment → Exercise | 1:N | NOT NULL | CASCADE |
|
|
| Exercise → GradingElement | 1:N | NOT NULL | CASCADE |
|
|
| GradingElement → Grade | 1:N | NOT NULL | CASCADE |
|
|
|
|
---
|
|
|
|
## 🔐 **Sécurité**
|
|
|
|
### **Protection CSRF**
|
|
|
|
```python
|
|
# Configuration correcte (fix effectué)
|
|
WTF_CSRF_TIME_LIMIT = settings.WTF_CSRF_TIME_LIMIT # int, pas timedelta!
|
|
```
|
|
|
|
### **Validation Input**
|
|
|
|
- ✅ **WTForms** : Validation côté serveur obligatoire
|
|
- ✅ **Length limits** : Protection contre overflow DB
|
|
- ✅ **Type validation** : Coercion appropriée des types
|
|
- ✅ **Business rules** : Validation métier (unicité, contraintes)
|
|
|
|
### **Database Security**
|
|
|
|
- ✅ **SQL Injection** : Protection via SQLAlchemy ORM
|
|
- ✅ **Transaction isolation** : Rollback automatique en cas d'erreur
|
|
- ✅ **Constraint enforcement** : Contraintes DB respectées
|
|
|
|
---
|
|
|
|
## 🧪 **Tests et Qualité**
|
|
|
|
### **Couverture Actuelle**
|
|
|
|
```
|
|
Total tests: 214 ✅
|
|
Couverture: ~85%
|
|
Régression: 0 tests en échec
|
|
Performance: Tous tests < 5s
|
|
```
|
|
|
|
### **Types de Tests**
|
|
|
|
#### **Tests Unitaires**
|
|
- **Models** : Validation des modèles et relations
|
|
- **Forms** : Validation des formulaires WTForms
|
|
- **Services** : Logique métier et calculs
|
|
- **Repositories** : Accès données et requêtes
|
|
|
|
#### **Tests d'Intégration**
|
|
- **Routes** : Endpoints HTTP complets
|
|
- **Database** : Transactions et contraintes
|
|
- **Error Handling** : Gestionnaires d'erreurs
|
|
|
|
#### **Tests de Performance**
|
|
- **Query Performance** : Pas de N+1 queries
|
|
- **Memory Usage** : Pas de fuites mémoire
|
|
- **Response Time** : < 200ms pour CRUD standard
|
|
|
|
---
|
|
|
|
## 📊 **Monitoring et Observabilité**
|
|
|
|
### **Logging Structuré**
|
|
|
|
```json
|
|
{
|
|
"timestamp": "2025-08-07T19:30:45.123Z",
|
|
"level": "INFO",
|
|
"message": "Nouvelle classe créée: 6ème A",
|
|
"correlation_id": "req-uuid-1234",
|
|
"request": {
|
|
"method": "POST",
|
|
"url": "/classes/",
|
|
"remote_addr": "192.168.1.100"
|
|
},
|
|
"extra": {
|
|
"event_type": "class_created",
|
|
"class_id": 42,
|
|
"class_name": "6ème A"
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Métriques Clés**
|
|
|
|
| Métrique | Description | Seuil |
|
|
|----------|-------------|--------|
|
|
| **Response Time** | Temps réponse routes | < 200ms |
|
|
| **Error Rate** | Taux d'erreur global | < 1% |
|
|
| **DB Query Time** | Temps requêtes DB | < 50ms |
|
|
| **Memory Usage** | Utilisation mémoire | < 512MB |
|
|
|
|
---
|
|
|
|
## 📋 **Roadmap Backend**
|
|
|
|
### **Priorité Haute**
|
|
- ✅ **Repository Pattern ClassGroup** : Architecture Repository complète
|
|
- 📋 **Repository Pattern étendu** : Student, Grade, Exercise repositories
|
|
- 📋 **Service Layer complet** : Logique métier centralisée
|
|
- 📋 **API REST endpoints** : Pour intégrations externes
|
|
|
|
### **Priorité Moyenne**
|
|
- 📋 **Audit Trail système** : Traçabilité des modifications
|
|
- 📋 **Soft Delete pattern** : Archivage au lieu de suppression
|
|
- 📋 **Background Jobs** : Tâches asynchrones (exports, calculs)
|
|
- 📋 **Multi-tenancy** : Support multi-établissements
|
|
|
|
### **Priorité Basse**
|
|
- 📋 **Event Sourcing** : Historique complet des événements
|
|
- 📋 **CQRS Pattern** : Séparation lecture/écriture
|
|
- 📋 **Microservices** : Découpage en services indépendants
|
|
- 📋 **GraphQL API** : Interface query flexible
|
|
|
|
---
|
|
|
|
## 🧰 **Outils et Environnement**
|
|
|
|
### **Développement**
|
|
|
|
```bash
|
|
# Gestionnaire de paquets moderne
|
|
uv sync
|
|
|
|
# Serveur de développement avec reload
|
|
uv run flask --app app run --debug
|
|
|
|
# Tests avec couverture
|
|
uv run pytest --cov=. --cov-report=html
|
|
|
|
# Linting et formatage
|
|
uv run ruff check .
|
|
uv run black .
|
|
```
|
|
|
|
### **Base de Données**
|
|
|
|
```bash
|
|
# Initialisation avec données de test
|
|
uv run flask --app app init-db
|
|
|
|
# Console interactive
|
|
uv run flask --app app shell
|
|
|
|
# Inspection DB
|
|
sqlite3 instance/school_management.db
|
|
```
|
|
|
|
### **Stack Technologique**
|
|
|
|
- **Framework** : Flask 3.x
|
|
- **ORM** : SQLAlchemy 2.x
|
|
- **Database** : SQLite (dev) → PostgreSQL (prod)
|
|
- **Forms** : WTForms + Flask-WTF
|
|
- **Testing** : Pytest + Coverage.py
|
|
- **Config** : python-dotenv
|
|
- **Logging** : JSON structured logging
|
|
|
|
---
|
|
|
|
## 🔗 **Liens et Références**
|
|
|
|
### **Documentation Externe**
|
|
|
|
- **Flask** : [flask.palletsprojects.com](https://flask.palletsprojects.com/)
|
|
- **SQLAlchemy** : [docs.sqlalchemy.org](https://docs.sqlalchemy.org/)
|
|
- **WTForms** : [wtforms.readthedocs.io](https://wtforms.readthedocs.io/)
|
|
- **Pytest** : [docs.pytest.org](https://docs.pytest.org/)
|
|
|
|
### **Standards et Patterns**
|
|
|
|
- **12 Factor App** : [12factor.net](https://12factor.net/)
|
|
- **Repository Pattern** : [martinfowler.com](https://martinfowler.com/eaaCatalog/repository.html)
|
|
- **Domain Driven Design** : Patterns pour logique métier complexe
|
|
|
|
---
|
|
|
|
## 📝 **Contribution**
|
|
|
|
### **Ajouter un Nouveau Service**
|
|
|
|
1. **Créer le module** dans `routes/` + `services/` si nécessaire
|
|
2. **Suivre les patterns** : Repository, Service Layer, Error Handling
|
|
3. **Documenter complètement** selon structure [CLASSES_CRUD.md](./CLASSES_CRUD.md)
|
|
4. **Tests complets** : Unitaires + intégration + performance
|
|
5. **Mettre à jour** ce README.md
|
|
|
|
### **Modifier un Service Existant**
|
|
|
|
1. **Tests d'abord** : Vérifier couverture existante
|
|
2. **Backward compatibility** : Éviter les breaking changes
|
|
3. **Documentation** : Mettre à jour docs correspondantes
|
|
4. **Performance** : Vérifier impact sur métriques
|
|
|
|
### **Standards de Code**
|
|
|
|
- **PEP 8** : Respect strict du style Python
|
|
- **Type hints** : Obligatoires pour fonctions publiques
|
|
- **Docstrings** : Format Google pour toutes les fonctions
|
|
- **Error handling** : Utiliser @handle_db_errors systématiquement
|
|
- **Logging** : Événements importants avec context approprié
|
|
|
|
---
|
|
|
|
## 📈 **État de la Documentation**
|
|
|
|
### **✅ Documenté (100%)**
|
|
- Système CRUD Classes (complet avec exemples)
|
|
- Repository Pattern ClassGroup (architecture complète)
|
|
- Architecture générale et patterns
|
|
- Standards de sécurité et validation
|
|
|
|
### **🔄 En cours (20-80%)**
|
|
- Assessment Services (code existant, doc à faire)
|
|
- Configuration System (code existant, doc à faire)
|
|
- Grading System (code existant, doc à faire)
|
|
|
|
### **📋 À faire**
|
|
- Repository Pattern guide complet
|
|
- Service Layer documentation
|
|
- Performance optimization guide
|
|
- API REST documentation
|
|
- Migration strategies
|
|
|
|
---
|
|
|
|
**🎓 Cette documentation évolue avec Notytex. Chaque nouveau service ou modification significative doit être documenté selon ces standards pour maintenir la cohérence et faciliter la maintenance.** |