lafrite/notytex
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
ac2762218e57e5c2f7cd078a5c76720a4072c65e
notytex/docs/backend/README.md

14 KiB
Raw Blame History

🏗️ 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 ClassGroup - complet ✅
Service Layer Logique métier & services 📋
Error Handling Gestion centralisée des erreurs 📋

🔧 Modules et Services

Document Description Statut
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 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

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 (✅ 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

🗄️ 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

# 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é

{
  "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

# 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

# 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

Standards et Patterns

📝 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
  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)
  • Système d'échelles et dégradés (notes, scores, valeurs spéciales)
  • Architecture générale et patterns
  • Standards de sécurité et validation

🔄 En cours (20-80%)

  • Assessment Services (code existant, doc à faire)
  • Configuration System général (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.