Aller au contenu principal

Scheduled Exports

Système complet pour planifier des exports automatiques avec récurrence et envoi par email.

Vue d'ensemble​

Le système d'exports planifiés permet de :

  • Planifier des exports automatiques à des dates/heures spécifiques
  • Configurer des exports récurrents (quotidien, hebdomadaire, mensuel, annuel)
  • Envoyer automatiquement les exports par email
  • Sélectionner les champs à exporter
  • Utiliser des templates d'export pré-configurés

Architecture​

Backend​

Table : scheduled_exports​

Stocke les exports planifiés avec :

  • Configuration de récurrence
  • Paramètres d'envoi par email
  • Sélection de champs personnalisée
  • Référence à un template d'export (optionnel)

Service : ScheduledExportsService​

  • Fichier : backend/src/scheduled-exports/scheduled-exports.service.ts
  • Responsabilités :
    • Gestion des exports planifiés (CRUD)
    • Exécution des exports planifiés
    • Calcul des prochaines dates d'exécution

Scheduler : ScheduledExportsScheduler​

  • Fichier : backend/src/scheduled-exports/scheduled-exports.scheduler.ts
  • Fréquence : Exécution toutes les 5 minutes
  • Responsabilités :
    • Détection des exports prêts à être exécutés
    • Ajout des jobs d'export à la queue

Processor : ExportProcessor​

  • Fichier : backend/src/queue/processors/export.processor.ts
  • Responsabilités :
    • Génération de l'export
    • Envoi par email si configuré
    • Upload vers le stockage R2

API Endpoints​

Liste des exports planifiés​

Endpoint: GET /api/scheduled-exports

Response:

[
  {
    "id": "uuid",
    "owner_id": "uuid",
    "entity": "contacts",
    "format": "csv",
    "scheduled_at": "2025-01-15T10:00:00Z",
    "recurrence_pattern": {
      "frequency": "weekly",
      "interval": 1
    },
    "status": "ACTIVE",
    "send_email": true,
    "email_recipient": "user@example.com",
    "email_subject": "Weekly Contacts Export",
    "selected_fields": ["first_name", "last_name", "email"],
    "next_run_at": "2025-01-22T10:00:00Z",
    "last_run_at": "2025-01-15T10:00:00Z",
    "run_count": 5
  }
]

Créer un export planifié​

Endpoint: POST /api/scheduled-exports

Request Body:

{
  "entity": "contacts",
  "format": "csv",
  "scheduled_at": "2025-01-15T10:00:00Z",
  "recurrence_pattern": {
    "frequency": "weekly",
    "interval": 1,
    "endDate": "2025-12-31T23:59:59Z"
  },
  "send_email": true,
  "email_recipient": "user@example.com",
  "email_subject": "Weekly Contacts Export",
  "email_message": "Please find attached your weekly contacts export.",
  "selected_fields": ["first_name", "last_name", "email"],
  "export_template_id": "uuid"
}

Response: Export planifié créé

Mettre à jour un export planifié​

Endpoint: PUT /api/scheduled-exports/:id

Request Body: Même structure que la création (tous les champs sont optionnels)

Supprimer un export planifié​

Endpoint: DELETE /api/scheduled-exports/:id

Activer un export planifié​

Endpoint: POST /api/scheduled-exports/:id/activate

Change le statut à ACTIVE et calcule la prochaine date d'exécution.

Mettre en pause un export planifié​

Endpoint: POST /api/scheduled-exports/:id/pause

Change le statut à PAUSED.

Annuler un export planifié​

Endpoint: POST /api/scheduled-exports/:id/cancel

Change le statut à CANCELLED.

Récurrence​

Patterns de récurrence​

{
  "frequency": "daily" | "weekly" | "monthly" | "yearly",
  "interval": number,  // Ex: 1 = chaque jour/semaine/mois/année, 2 = tous les 2 jours/semaines/etc.
  "endDate": "2025-12-31T23:59:59Z"  // Optionnel : date de fin de récurrence
}

Exemples​

Export quotidien:

{
  "frequency": "daily",
  "interval": 1
}

Export hebdomadaire (toutes les 2 semaines):

{
  "frequency": "weekly",
  "interval": 2
}

Export mensuel avec date de fin:

{
  "frequency": "monthly",
  "interval": 1,
  "endDate": "2025-12-31T23:59:59Z"
}

Statuts​

  • PENDING : Export créé mais pas encore activé
  • ACTIVE : Export actif, sera exécuté selon la planification
  • PAUSED : Export temporairement suspendu
  • CANCELLED : Export annulé (ne sera plus exécuté)

Envoi par Email​

Quand send_email est true, l'export est automatiquement envoyé par email :

  • Pièce jointe : Le fichier d'export est attaché à l'email
  • Sujet personnalisable : Via email_subject
  • Message personnalisable : Via email_message
  • Destinataire : Spécifié dans email_recipient

Sélection de Champs​

Vous pouvez spécifier les champs à exporter via selected_fields :

{
  "selected_fields": ["first_name", "last_name", "email", "phone_number"]
}

Utilisation de Templates​

Vous pouvez référencer un template d'export existant :

{
  "export_template_id": "uuid-of-template"
}

Le template fournira les champs sélectionnés et le format.

Exemples d'Utilisation​

Export quotidien de contacts en CSV​

curl -X POST "http://localhost:3000/api/scheduled-exports" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "contacts",
    "format": "csv",
    "scheduled_at": "2025-01-15T08:00:00Z",
    "recurrence_pattern": {
      "frequency": "daily",
      "interval": 1
    },
    "send_email": true,
    "email_recipient": "user@example.com",
    "email_subject": "Daily Contacts Export"
  }'

Export mensuel de sessions en Excel avec champs sélectionnés​

curl -X POST "http://localhost:3000/api/scheduled-exports" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "sessions",
    "format": "excel",
    "scheduled_at": "2025-01-01T00:00:00Z",
    "recurrence_pattern": {
      "frequency": "monthly",
      "interval": 1
    },
    "send_email": true,
    "email_recipient": "user@example.com",
    "selected_fields": ["id", "title", "status", "start_date", "location"]
  }'

Gestion des Erreurs​

En cas d'erreur lors de l'exécution d'un export planifié :

  • L'erreur est enregistrée dans error_message
  • Le statut reste ACTIVE pour permettre une nouvelle tentative
  • Le système de queue gère automatiquement les retries

Monitoring​

Le scheduler log toutes les opérations :

  • Détection des exports prêts à être exécutés
  • Exécution des exports
  • Erreurs éventuelles

Consultez les logs pour suivre l'activité des exports planifiés.

Fichiers​

  • backend/src/scheduled-exports/scheduled-exports.service.ts - Service principal
  • backend/src/scheduled-exports/scheduled-exports-crud.service.ts - CRUD operations
  • backend/src/scheduled-exports/scheduled-exports.scheduler.ts - Scheduler
  • backend/src/scheduled-exports/scheduled-exports.controller.ts - Endpoints REST
  • infra/liquibase/changes/0139_create_scheduled_exports/ - Migration

Voir aussi​