EduTrack IA

CELERY_BEAT_SCHEDULE = {
    'send-monthly-reports': {
        'task': 'app.tasks.reports.send_monthly_reports',
        'schedule': crontab(hour=8, minute=0, day_of_month=1),
    },
    'send-quarterly-reports': {
        'task': 'app.tasks.reports.send_quarterly_reports',
        'schedule': crontab(hour=8, minute=0, day_of_month=1, month_of_year='1,4,7,10'),
    },
}

// Réponse succès
{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

// Réponse erreur
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La note doit être entre 0 et 20",
    "field": "value"
  }
}

// Request
{
  "email": "enseignant@edutrack.fr",
  "password": "motdepasse123"
}

// Response 200
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600,
    "user": {
      "id": "uuid",
      "email": "enseignant@edutrack.fr",
      "role": "teacher",
      "first_name": "Jean",
      "last_name": "Dupont"
    }
  }
}

// Request
{
  "first_name": "Marie",
  "last_name": "Dupont",
  "date_of_birth": "2014-03-15",
  "class_name": "6A",
  "parent_phone": "+33612345678",
  "parent_email": "parent.dupont@email.com"
}

// Response 201
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Marie",
    "last_name": "Dupont",
    "full_name": "Marie Dupont",
    "date_of_birth": "2014-03-15",
    "class_name": "6A",
    "parent_phone": "+33612345678",
    "parent_email": "parent.dupont@email.com",
    "is_active": true,
    "created_at": "2026-03-25T10:30:00Z"
  }
}

// Request
{
  "student_id": "550e8400-e29b-41d4-a716-446655440000",
  "competency_id": "660e8400-e29b-41d4-a716-446655440001",
  "value": 16.5,
  "evaluation_type": "controle",
  "evaluation_date": "2026-03-25",
  "comment": "Excellent travail"
}

// Response 201
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "student_id": "550e8400-...",
    "student_name": "Marie Dupont",
    "competency_id": "660e8400-...",
    "competency_name": "Calcul mental",
    "value": 16.5,
    "evaluation_type": "controle",
    "evaluation_date": "2026-03-25",
    "comment": "Excellent travail",
    "created_at": "2026-03-25T14:00:00Z"
  }
}

// Response 200
{
  "success": true,
  "data": {
    "student_id": "550e8400-...",
    "student_name": "Marie Dupont",
    "classification": "en_progression",
    "confidence": 0.87,
    "trend_coefficient": 0.15,
    "average_grade": 14.5,
    "grade_std": 2.3,
    "num_evaluations": 12,
    "days_since_last_evaluation": 5,
    "recommendations": [
      "Continuer les exercices de français",
      "Renforcer la pratique en histoire"
    ],
    "computed_at": "2026-03-25T15:00:00Z"
  }
}

// Request
{
  "student_id": "550e8400-e29b-41d4-a716-446655440000",
  "report_type": "seance"
}

// Response 201 (async)
{
  "success": true,
  "data": {
    "report_id": "880e8400-e29b-41d4-a716-446655440003",
    "status": "generating",
    "estimated_time_seconds": 8
  }
}

// GET /api/reports/{id} après génération
{
  "success": true,
  "data": {
    "id": "880e8400-...",
    "student_id": "550e8400-...",
    "student_name": "Marie Dupont",
    "report_type": "seance",
    "status": "ready",
    "content": {
      "summary": "Marie montre une progression constante...",
      "strengths": ["Calcul mental", "Compréhension écrite"],
      "improvements": ["Expression orale"],
      "recommendations": ["Pratiquer la lecture à voix haute"]
    },
    "pdf_url": "/api/reports/880e8400-.../pdf",
    "whatsapp_sent": false,
    "created_at": "2026-03-25T16:00:00Z"
  }
}

// Request
{
  "student_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Marie participe activement en classe et aide ses camarades.",
  "category": "progres",
  "observation_date": "2026-03-25"
}

// Response 201
{
  "success": true,
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "student_id": "550e8400-...",
    "student_name": "Marie Dupont",
    "teacher_name": "Jean Dupont",
    "content": "Marie participe activement en classe...",
    "category": "progres",
    "observation_date": "2026-03-25",
    "created_at": "2026-03-25T17:00:00Z"
  }
}

-- Index de performance
CREATE INDEX idx_students_class ON students(class_name);
CREATE INDEX idx_students_active ON students(is_active);
CREATE INDEX idx_grades_student ON grades(student_id);
CREATE INDEX idx_grades_date ON grades(evaluation_date);
CREATE INDEX idx_grades_student_date ON grades(student_id, evaluation_date);
CREATE INDEX idx_observations_student ON observations(student_id);
CREATE INDEX idx_competencies_subject ON competencies(subject_id);
CREATE INDEX idx_reports_student ON reports(student_id);
CREATE INDEX idx_predictions_student ON ai_predictions(student_id);

-- Contraintes CHECK
ALTER TABLE grades ADD CONSTRAINT chk_grade_value
  CHECK (value >= 0 AND value <= 20);
ALTER TABLE competencies ADD CONSTRAINT chk_level
  CHECK (level >= 1 AND level <= 5);
ALTER TABLE students ADD CONSTRAINT chk_phone_format
  CHECK (parent_phone ~ '^\+?[0-9]{10,15}$');

{
  "subjects": [
    {
      "code": "MATH",
      "name_fr": "Mathématiques",
      "name_ar": "الرياضيات",
      "levels": ["college", "lycee"],
      "coefficients": {
        "sciences_math": 9,
        "sciences_exp": 7,
        "lettres": 3
      }
    },
    {
      "code": "PHYS",
      "name_fr": "Physique-Chimie",
      "name_ar": "الفيزياء والكيمياء",
      "levels": ["college", "lycee"],
      "coefficients": {
        "sciences_math": 7,
        "sciences_exp": 7,
        "lettres": 2
      }
    },
    {
      "code": "SVT",
      "name_fr": "Sciences de la Vie et de la Terre",
      "name_ar": "علوم الحياة والأرض",
      "levels": ["college", "lycee"],
      "coefficients": {
        "sciences_exp": 7,
        "sciences_math": 5
      }
    },
    {
      "code": "ARAB",
      "name_fr": "Langue Arabe",
      "name_ar": "اللغة العربية",
      "levels": ["college", "lycee"],
      "coefficients": {
        "lettres": 4,
        "sciences_exp": 2,
        "sciences_math": 2
      }
    },
    {
      "code": "FRAN",
      "name_fr": "Langue Française",
      "name_ar": "اللغة الفرنسية",
      "levels": ["college", "lycee"],
      "coefficients": {
        "lettres": 4,
        "sciences_exp": 2,
        "sciences_math": 2
      }
    },
    {
      "code": "ANGL",
      "name_fr": "Langue Anglaise",
      "name_ar": "اللغة الإنجليزية",
      "levels": ["college", "lycee"],
      "coefficients": {
        "all": 2
      }
    },
    {
      "code": "HIST",
      "name_fr": "Histoire-Géographie",
      "name_ar": "التاريخ والجغرافيا",
      "levels": ["college", "lycee"],
      "coefficients": {
        "lettres": 3,
        "sciences": 2
      }
    },
    {
      "code": "PHIL",
      "name_fr": "Philosophie",
      "name_ar": "الفلسفة",
      "levels": ["lycee"],
      "coefficients": {
        "lettres": 4,
        "sciences": 2
      }
    },
    {
      "code": "ISLA",
      "name_fr": "Éducation Islamique",
      "name_ar": "التربية الإسلامية",
      "levels": ["college", "lycee"],
      "coefficients": {
        "all": 2
      }
    }
  ]
}

{
  "subject": "MATH",
  "competencies": {
    "college": {
      "1AC": [
        {"code": "M1C1", "name": "Opérations sur les nombres entiers"},
        {"code": "M1C2", "name": "Fractions et décimaux"},
        {"code": "M1C3", "name": "Géométrie plane - triangles"},
        {"code": "M1C4", "name": "Proportionnalité"}
      ],
      "2AC": [
        {"code": "M2C1", "name": "Calcul algébrique"},
        {"code": "M2C2", "name": "Équations du 1er degré"},
        {"code": "M2C3", "name": "Théorème de Pythagore"},
        {"code": "M2C4", "name": "Statistiques descriptives"}
      ],
      "3AC": [
        {"code": "M3C1", "name": "Identités remarquables"},
        {"code": "M3C2", "name": "Systèmes d'équations"},
        {"code": "M3C3", "name": "Théorème de Thalès"},
        {"code": "M3C4", "name": "Trigonométrie dans le triangle"}
      ]
    },
    "lycee": {
      "TC": [
        {"code": "MTC1", "name": "Calcul vectoriel"},
        {"code": "MTC2", "name": "Fonctions de référence"},
        {"code": "MTC3", "name": "Polynômes du 2nd degré"}
      ],
      "1BAC": [
        {"code": "M1B1", "name": "Suites numériques"},
        {"code": "M1B2", "name": "Limites et continuité"},
        {"code": "M1B3", "name": "Dérivation"},
        {"code": "M1B4", "name": "Produit scalaire"}
      ],
      "2BAC": [
        {"code": "M2B1", "name": "Intégration"},
        {"code": "M2B2", "name": "Équations différentielles"},
        {"code": "M2B3", "name": "Nombres complexes"},
        {"code": "M2B4", "name": "Probabilités et dénombrement"}
      ]
    }
  }
}

{
  "levels": {
    "college": {
      "name_fr": "Collège (Secondaire Collégial)",
      "name_ar": "الثانوي الإعدادي",
      "classes": [
        {"code": "1AC", "name": "1ère Année Collège", "age": 12},
        {"code": "2AC", "name": "2ème Année Collège", "age": 13},
        {"code": "3AC", "name": "3ème Année Collège", "age": 14, "exam": "Brevet"}
      ]
    },
    "lycee": {
      "name_fr": "Lycée (Secondaire Qualifiant)",
      "name_ar": "الثانوي التأهيلي",
      "classes": [
        {"code": "TC", "name": "Tronc Commun", "age": 15},
        {"code": "1BAC", "name": "1ère Année Bac", "age": 16, "exam": "Régional"},
        {"code": "2BAC", "name": "2ème Année Bac", "age": 17, "exam": "Baccalauréat"}
      ],
      "filieres": [
        {"code": "SM", "name": "Sciences Mathématiques"},
        {"code": "PC", "name": "Sciences Physiques"},
        {"code": "SVT", "name": "Sciences de la Vie et de la Terre"},
        {"code": "SE", "name": "Sciences Économiques"},
        {"code": "SH", "name": "Sciences Humaines"},
        {"code": "LA", "name": "Lettres et Arts"}
      ]
    }
  }
}

ML_CONFIG = {
    "model": {
        "type": "RandomForestClassifier",
        "params": {
            "n_estimators": 100,
            "max_depth": 10,
            "min_samples_split": 5,
            "min_samples_leaf": 2,
            "random_state": 42,
            "n_jobs": -1  # Utiliser tous les CPU
        }
    },
    "features": [
        "avg_grade",
        "std_grade",
        "trend_coefficient",
        "num_evaluations",
        "last_grade",
        "days_since_last",
        "competency_coverage",
        "improvement_rate"
    ],
    "target_classes": {
        0: "en_difficulte",    # Score < 10 ou tendance négative forte
        1: "stable",           # Score entre 10-14, tendance neutre
        2: "en_progression"    # Score > 14 ou tendance positive
    },
    "thresholds": {
        "alert_confidence": 0.75,     # Seuil pour déclencher alerte
        "min_evaluations": 3,         # Minimum évaluations requises
        "difficulty_grade": 10.0     # Seuil de difficulté
    },
    "huggingface": {
        "model_name": "mistralai/Mistral-7B-Instruct-v0.2",
        "max_new_tokens": 500,
        "temperature": 0.7,
        "top_p": 0.9,
        "repetition_penalty": 1.1
    }
}

WHATSAPP_CONFIG = {
    "account_sid": "${TWILIO_ACCOUNT_SID}",     # Variable d'environnement
    "auth_token": "${TWILIO_AUTH_TOKEN}",       # Variable d'environnement
    "from_number": "whatsapp:+14155238886",    # Numéro Sandbox Twilio

    "message_templates": {
        "report_ready": """
🎓 *EduTrack IA - Rapport de Progression*

Bonjour,

Le rapport de progression de {student_name} est disponible.

📊 Résumé:
• Moyenne: {avg_grade}/20
• Classification: {classification}
• Tendance: {trend}

📎 Consultez le rapport complet: {pdf_url}

Cordialement,
L'équipe pédagogique
""",
        "alert": """
⚠️ *Alerte EduTrack IA*

Concernant {student_name}:

{alert_message}

Nous vous invitons à consulter le tableau de bord
pour plus de détails.

📞 Contactez l'établissement si nécessaire.
""",
        "weekly_summary": """
📅 *Résumé Hebdomadaire - {student_name}*

Cette semaine:
• Notes ajoutées: {new_grades_count}
• Moyenne: {weekly_avg}/20
• Évolution: {evolution}

Détails sur le portail parent.
"""
    }
}

from twilio.rest import Client
from config.whatsapp_config import WHATSAPP_CONFIG

class WhatsAppService:
    def __init__(self):
        self.client = Client(
            WHATSAPP_CONFIG['account_sid'],
            WHATSAPP_CONFIG['auth_token']
        )
        self.from_number = WHATSAPP_CONFIG['from_number']

    def send_report(self, parent_phone: str, student_name: str,
                     avg_grade: float, classification: str,
                     trend: str, pdf_url: str) -> dict:
        """Envoie un rapport de progression via WhatsApp."""

        message = WHATSAPP_CONFIG['message_templates']['report_ready'].format(
            student_name=student_name,
            avg_grade=avg_grade,
            classification=classification,
            trend=trend,
            pdf_url=pdf_url
        )

        response = self.client.messages.create(
            from_=self.from_number,
            body=message,
            to=f'whatsapp:{parent_phone}'
        )

        return {
            'message_sid': response.sid,
            'status': response.status,
            'sent_at': response.date_sent
        }

    def send_alert(self, parent_phone: str, student_name: str,
                    alert_message: str) -> dict:
        """Envoie une alerte urgente via WhatsApp."""

        message = WHATSAPP_CONFIG['message_templates']['alert'].format(
            student_name=student_name,
            alert_message=alert_message
        )

        response = self.client.messages.create(
            from_=self.from_number,
            body=message,
            to=f'whatsapp:{parent_phone}'
        )

        return {
            'message_sid': response.sid,
            'status': response.status
        }

# Scénario 1: Connexion réussie
Given un utilisateur avec email "prof@edutrack.ma" et mot de passe valide
When il soumet le formulaire de connexion
Then il reçoit un token JWT valide
And il est redirigé vers le dashboard
And son dernier login est mis à jour en BDD

# Scénario 2: Connexion échouée (mauvais mot de passe)
Given un utilisateur avec email valide mais mauvais mot de passe
When il soumet le formulaire de connexion
Then il reçoit une erreur 401
And le message "Email ou mot de passe incorrect" s'affiche
And aucun token n'est généré

# Scénario 3: Compte désactivé
Given un utilisateur avec is_active = false
When il soumet le formulaire de connexion
Then il reçoit une erreur 403
And le message "Compte désactivé" s'affiche

# Scénario 1: Saisie réussie
Given un enseignant connecté
And un élève "Ahmed Benali" de la classe "3AC-A"
And une compétence "Équations du 1er degré"
When il saisit la note 15/20 pour l'évaluation "Contrôle" du 2025-03-20
Then la note est enregistrée en BDD
And les features ML de l'élève sont recalculées
And un message de succès s'affiche
And le graphique de progression est mis à jour

# Scénario 2: Note invalide
Given un enseignant connecté
When il saisit une note de 25/20 (hors limite)
Then une erreur de validation s'affiche
And la note n'est pas enregistrée

# Scénario 3: Élève non trouvé
Given un student_id invalide
When l'enseignant tente de saisir une note
Then une erreur 404 est retournée

# Scénario 1: Classification réussie
Given un élève avec au moins 3 notes enregistrées
When le système calcule sa classification
Then il retourne une des 3 classes: "en_difficulte", "stable", "en_progression"
And un score de confiance entre 0 et 1
And la prédiction est sauvegardée dans ai_predictions

# Scénario 2: Données insuffisantes
Given un élève avec moins de 3 notes
When le système tente de classifier
Then il retourne None
And un message "Données insuffisantes" est loggé

# Scénario 3: Précision du modèle
Given le jeu de données de test
When le modèle est évalué
Then la précision est >= 75%

# Scénario 1: Génération réussie
Given un enseignant connecté
And un élève avec des notes et une classification ML
When il clique sur "Générer rapport"
Then le rapport PDF est généré en moins de 10 secondes
And le rapport contient: infos élève, graphique radar, texte IA bienveillant
And le rapport est sauvegardé dans la table reports

# Scénario 2: Texte IA généré
Given les données de l'élève formatées dans le prompt
When HuggingFace génère le texte
Then le texte fait 3-4 paragraphes
And le ton est bienveillant et constructif
And des recommandations concrètes sont incluses

# Sprint 1 - Fondations (pas de dépendances)
US-DATA-1 (BDD) ──────────────────────────────────────┐
US-DATA-2 (Migrations) ───────────────────────────────┤
US-DATA-3 (Fixtures matières) ────────────────────────┼──→ Sprint 2 peut commencer
US-DATA-4 (Fixtures compétences collège) ─────────────┤
US-DATA-5 (Fixtures compétences lycée) ───────────────┘

# Sprint 1 → Sprint 2
US-AUTH-1 (Login) ────────────────────────────────────┐
US-AUTH-2 (Logout) ───────────────────────────────────┼──→ US-STU-* (CRUD élèves)
US-AUTH-3 (Créer comptes) ────────────────────────────┘    US-GRD-* (CRUD notes)

# Sprint 2 → Sprint 3
US-STU-1 (Créer élève) ───────────────────────────────┐
US-GRD-1 (Saisir note) ───────────────────────────────┼──→ US-ML-1 (Features ML)
US-CMP-1 (Créer compétence) ──────────────────────────┘    US-ML-2 (Classification)

# Sprint 3 → Sprint 4
US-ML-1 (Features ML) ────────────────────────────────┐
US-ML-2 (Classification) ─────────────────────────────┼──→ US-DASH-* (Dashboard)
US-ML-3 (Voir prédiction) ────────────────────────────┘    US-DASH-5 (Alertes)

# Sprint 4 → Sprint 5
US-DASH-1 (Dashboard) ────────────────────────────────┐
US-DASH-3 (Radar) ────────────────────────────────────┼──→ US-RPT-1 (Rapport PDF)
US-ML-2 (Classification) ─────────────────────────────┘    US-RPT-2 (WhatsApp)

# Stories Indépendantes (peuvent être faites en parallèle)
US-STU-5 (Import CSV) ← indépendant après US-DATA-*
US-OBS-1 (Observations) ← indépendant après US-STU-1
US-AUTH-5 (Reset password) ← indépendant après US-AUTH-1

tests/
├── unit/
│   ├── test_models.py          # Tests modèles SQLAlchemy
│   ├── test_schemas.py         # Tests validation Marshmallow
│   ├── test_ml_features.py     # Tests calcul features ML
│   └── test_classification.py  # Tests pipeline ML
├── integration/
│   ├── test_api_students.py    # Tests CRUD élèves
│   ├── test_api_grades.py      # Tests CRUD notes
│   ├── test_api_analytics.py   # Tests endpoints analytics
│   ├── test_api_reports.py     # Tests génération rapports
│   └── test_whatsapp.py        # Tests intégration Twilio
├── e2e/
│   ├── test_teacher_flow.py    # Parcours enseignant complet
│   ├── test_parent_flow.py     # Parcours parent
│   └── test_report_flow.py     # Génération + envoi rapport
├── fixtures/
│   ├── students.json           # Données test élèves
│   ├── grades.json             # Données test notes
│   └── competencies.json       # Données test compétences
├── conftest.py                 # Fixtures pytest partagées
└── pytest.ini                  # Configuration pytest

import pytest
from app.services.ml_features import calculate_features

class TestMLFeatures:
    def test_calculate_features_minimum_grades(self, student_with_grades):
        """Test: minimum 3 notes requises pour calcul"""
        student_id = student_with_grades[0].id

        features = calculate_features(student_id)

        assert features is not None
        assert 'avg_grade' in features
        assert 'trend_coefficient' in features

    def test_calculate_features_insufficient_data(self, student_one_grade):
        """Test: retourne None si moins de 3 notes"""
        student_id = student_one_grade.id

        features = calculate_features(student_id)

        assert features is None

    def test_trend_coefficient_positive(self, improving_student):
        """Test: coefficient positif pour élève en progression"""
        features = calculate_features(improving_student.id)

        assert features['trend_coefficient'] > 0

    def test_avg_grade_accuracy(self, student_with_known_grades):
        """Test: moyenne calculée correctement"""
        # Élève avec notes: 10, 12, 14 → moyenne = 12
        features = calculate_features(student_with_known_grades.id)

        assert features['avg_grade'] == pytest.approx(12.0, rel=0.01)