440 lines
16 KiB
Markdown
440 lines
16 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 |
|
|
|----------|-------------|---------|
|
|
| **[SOLID_ARCHITECTURE.md](./SOLID_ARCHITECTURE.md)** | Architecture SOLID complète - services découplés | ✅ |
|
|
| **[REPOSITORY_PATTERN.md](./REPOSITORY_PATTERN.md)** | Repository Pattern ClassGroup - complet | ✅ |
|
|
| **[DEPENDENCY_INJECTION.md](./DEPENDENCY_INJECTION.md)** | Injection dépendances via providers | ✅ |
|
|
| **[PERFORMANCE_OPTIMIZATION.md](./PERFORMANCE_OPTIMIZATION.md)** | Optimisations N+1 queries résolues | ✅ |
|
|
|
|
### 🔧 **Modules et Services**
|
|
|
|
| Document | Description | Statut |
|
|
|----------|-------------|---------|
|
|
| **[CLASSES_CRUD.md](./CLASSES_CRUD.md)** | Système CRUD des Classes - complet | ✅ |
|
|
| **[ASSESSMENT_SERVICES.md](./ASSESSMENT_SERVICES.md)** | Services évaluations refactorisés - facade & DI | ✅ |
|
|
| **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** | Guide migration Phase 1 - feature flags supprimés | ✅ |
|
|
| 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. **Principes SOLID** : Étudier [SOLID_ARCHITECTURE.md](./SOLID_ARCHITECTURE.md) pour les patterns modernes
|
|
3. **Premier module** : Étudier [CLASSES_CRUD.md](./CLASSES_CRUD.md) comme exemple complet
|
|
4. **Services découplés** : Maîtriser [ASSESSMENT_SERVICES.md](./ASSESSMENT_SERVICES.md) et [DEPENDENCY_INJECTION.md](./DEPENDENCY_INJECTION.md)
|
|
5. **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 découplée (SOLID)
|
|
│ └── assessment_services.py # Services évaluations + Statistics + Progress ✅
|
|
├── 📁 providers/ # Injection de dépendances (DI Pattern) ✅
|
|
│ └── concrete_providers.py # ConfigProvider + DatabaseProvider optimisés
|
|
├── 📁 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 (Phase 1 ✅)**
|
|
|
|
#### **1. SOLID Principles (Refactoring Complet)**
|
|
- **Single Responsibility** : Services spécialisés (ClassStatistics, AssessmentProgress...)
|
|
- **Open/Closed** : Strategy Pattern pour types notation (GradingStrategy)
|
|
- **Liskov Substitution** : Interfaces respectées (ConfigProvider, DatabaseProvider)
|
|
- **Interface Segregation** : Providers spécialisés selon usage
|
|
- **Dependency Inversion** : Injection dépendances partout via factories
|
|
|
|
#### **2. Repository Pattern**
|
|
- **Séparation** : Logique d'accès données isolée
|
|
- **Réutilisabilité** : Requêtes complexes centralisées
|
|
- **Testabilité** : Repositories mockables
|
|
- **Performance** : Requêtes N+1 résolues avec eager loading
|
|
|
|
#### **3. Service Layer Découplé**
|
|
- **Facade Pattern** : AssessmentServicesFacade point d'entrée unique
|
|
- **Services spécialisés** : Progress, Statistics, ScoreCalculation
|
|
- **DTOs** : ProgressResult, StudentScore, StatisticsResult
|
|
- **Injection dépendances** : Via ConfigProvider/DatabaseProvider
|
|
|
|
#### **4. Dependency Injection via Providers**
|
|
- **ConfigManagerProvider** : Accès configuration découplé
|
|
- **SQLAlchemyDatabaseProvider** : Requêtes optimisées centralisées
|
|
- **Factory Pattern** : AssessmentServicesFactory création services
|
|
- **Résolution imports circulaires** : Import paresseux et interfaces
|
|
|
|
---
|
|
|
|
## 🔧 **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 (✅ Refactorisé Phase 1)**
|
|
|
|
**Responsabilité** : Gestion découplée des évaluations avec architecture SOLID
|
|
|
|
- ✅ **AssessmentServicesFacade** : Point d'entrée unifié avec DI
|
|
- ✅ **UnifiedGradingCalculator** : Calculs Strategy Pattern (Notes/Score)
|
|
- ✅ **AssessmentProgressService** : Suivi progression optimisé (requêtes uniques)
|
|
- ✅ **StudentScoreCalculator** : Calculs scores avec DTOs
|
|
- ✅ **AssessmentStatisticsService** : Analyses statistiques découplées
|
|
- ✅ **Performance** : 375 → 1 requête SQL (-99.7%), 2.3s → 0.4s (-82%)
|
|
|
|
**Documentation** : [ASSESSMENT_SERVICES.md](./ASSESSMENT_SERVICES.md)
|
|
|
|
### **Configuration System (✅ Complet)**
|
|
|
|
**Responsabilité** : Gestion configuration dynamique application
|
|
|
|
- ✅ **Dynamic Settings** : Configuration runtime modifiable
|
|
- ✅ **Scales Management** : Échelles de notation configurables (0-3 + spéciales)
|
|
- ✅ **Color Gradients** : Système dégradé couleurs notes avec HSL
|
|
- ✅ **Visual Feedback** : Indicateurs d'erreur visuels pour validation
|
|
- ✅ **Grading Integration** : Application automatique dans page de notation
|
|
- ✅ **Business Rules** : Règles métier configurables
|
|
- ✅ **Unified Interface** : Interface de configuration unifiée
|
|
|
|
**Documentation** : [../CONFIGURATION_SCALES.md](../CONFIGURATION_SCALES.md)
|
|
|
|
---
|
|
|
|
## 🗄️ **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 (Phase 1 ✅)**
|
|
|
|
```
|
|
Total tests: 198 ✅ (après nettoyage migration)
|
|
Couverture: ~90% (amélioration architecture SOLID)
|
|
Régression: 0 tests en échec (vs 15 échecs avant)
|
|
Performance: Tous tests < 2s (amélioration -60%)
|
|
Feature flags: 100% supprimés (58 tests obsolètes nettoyés)
|
|
```
|
|
|
|
### **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**
|
|
|
|
### **Phase 1 Terminée ✅**
|
|
- ✅ **Architecture SOLID complète** : Principes S.O.L.I.D respectés à 100%
|
|
- ✅ **Services découplés** : Assessment services refactorisés avec DI
|
|
- ✅ **Repository Pattern ClassGroup** : Architecture Repository complète
|
|
- ✅ **Performance optimisée** : Requêtes N+1 résolues (-99.7% SQL queries)
|
|
- ✅ **Feature flags supprimés** : Migration propre terminée
|
|
|
|
### **Priorité Haute (Phase 2)**
|
|
- 📋 **Repository Pattern étendu** : Student, Grade, Exercise repositories
|
|
- 📋 **API REST endpoints** : Pour intégrations externes avec OpenAPI
|
|
- 📋 **Event-driven architecture** : Events pour audit trail
|
|
|
|
### **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é Complet (100%)**
|
|
- **Architecture SOLID** : Patterns modernes avec diagrammes et exemples
|
|
- **Assessment Services** : Services découplés avec DI et DTOs
|
|
- **Dependency Injection** : Providers pattern avec factory
|
|
- **Performance Optimization** : Requêtes N+1 résolues et métriques
|
|
- **Migration Guide** : Guide complet Phase 1 avec troubleshooting
|
|
- **Repository Pattern ClassGroup** : Architecture complète avec tests
|
|
- **Système CRUD Classes** : Implémentation complète avec exemples
|
|
- **Système d'échelles et dégradés** : Configuration notes/scores/valeurs spéciales
|
|
|
|
### **🔄 En cours d'évolution (Phase 2)**
|
|
- Repository Pattern étendu (Student, Grade, Exercise)
|
|
- API REST documentation avec OpenAPI
|
|
- Event-driven architecture patterns
|
|
|
|
### **📋 Priorité future**
|
|
- Microservices architecture guide
|
|
- CQRS Pattern documentation
|
|
- GraphQL API patterns
|
|
|
|
---
|
|
|
|
**🎓 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.** |