Aller au contenu

Configuration du Traitement d'Emails

Description

Système pour récupérer automatiquement les références de documents depuis les emails de livraison et gérer leur expiration (45 jours).

Fonctionnalités Implémentées

✅ Script de traitement d'emails (app/scripts/email_processor.py) - Connexion IMAP à la boîte mail - Extraction des références ATT-XXXXXXXXX depuis les emails - Calcul automatique des dates d'expiration (45 jours) - Sauvegarde en base de données

✅ Modèle de base de données mis à jour (app/models/legacy_document.py) - Ajout des champs delivery_date et expiration_date - Migration Alembic créée

✅ Endpoint API (/souscriptions/process-emails) - Déclenche le traitement des emails via API - Paramètre limite configurable - Retourne les statistiques de traitement

✅ Endpoint de listing (/souscriptions/legacy-documents) - Liste les documents récupérés avec pagination - Statistiques d'expiration (expirés, valides, sans expiration)

✅ Vérification mise à jour (/souscriptions/verify-document) - Vérifie maintenant l'expiration des legacy documents - Messages d'erreur détaillés pour documents expirés

Configuration Requise

Ajoutez ces variables d'environnement dans votre fichier .env :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Configuration IMAP pour récupération d'emails
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
EMAIL_USERNAME=votre-email@boaz-study.com
EMAIL_PASSWORD=votre-mot-de-passe-app
IMAP_MAILBOX=INBOX

# Optionnel : si différent des paramètres SMTP
# EMAIL_USERNAME utilise SMTP_USERNAME par défaut
# EMAIL_PASSWORD utilise SMTP_PASSWORD par défaut

Utilisation

1. Via l'API (Recommandé)

1
2
3
4
5
6
7
8
# Traiter 10 emails (test)
curl -X POST "http://localhost:8000/api/souscriptions/process-emails?limit=10"

# Traiter tous les emails
curl -X POST "http://localhost:8000/api/souscriptions/process-emails"

# Lister les documents récupérés
curl -X GET "http://localhost:8000/api/souscriptions/legacy-documents"

2. Via le script direct

1
2
3
4
5
# Dans le container Docker
docker exec -it boaz-housing-mvp-backend-1 python app/scripts/email_processor.py

# Ou directement (avec l'environnement configuré)
python app/scripts/email_processor.py

3. Test de configuration

1
2
# Test des fonctionnalités
python test_email_processing.py

Migration de Base de Données

Appliquez la migration pour ajouter les nouvelles colonnes :

1
2
# Dans le container ou avec alembic installé
alembic upgrade head

Ou exécutez manuellement le SQL :

1
2
3
ALTER TABLE legacy_documents
ADD COLUMN delivery_date DATE,
ADD COLUMN expiration_date DATE;

Workflow Complet

  1. Première exécution : Récupère tous les emails existants
  2. Extraction : Trouve les références ATT-XXXXXXXXX dans les emails
  3. Dates :
    • Date de livraison = date d'envoi de l'email
    • Date d'expiration = date de livraison + 45 jours
  4. Sauvegarde : Stocke dans legacy_documents
  5. Vérification : L'endpoint /verify-document vérifie maintenant l'expiration

Formats de Référence Supportés

  • ATT-ABC123456 (standard)
  • att-xyz789012 (converti en majuscules)
  • Références multiples dans un même email

API Endpoints Ajoutés

Méthode Endpoint Description
POST /souscriptions/process-emails Traite les emails pour extraire les références
GET /souscriptions/legacy-documents Liste les documents legacy avec pagination

Réponse API Exemple

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "success": true,
  "message": "Traitement des emails terminé avec succès",
  "statistics": {
    "total_emails": 150,
    "emails_processed": 150,
    "emails_with_references": 45,
    "total_references_found": 47,
    "references_saved": 43
  }
}

Notes Importantes

  • ⚠️ Première exécution : Peut prendre du temps selon le nombre d'emails
  • 📧 Accès IMAP : Certains fournisseurs nécessitent l'activation de l'IMAP
  • 🔐 Gmail : Utilisez un "mot de passe d'application" si 2FA activé
  • 🕒 Expiration : 45 jours par défaut, configurable dans le code
  • 📊 Monitoring : Surveillez les logs pour les erreurs de connexion

Dépannage

Erreur de connexion IMAP

  • Vérifiez les paramètres IMAP_HOST, IMAP_PORT
  • Activez l'accès IMAP dans votre compte email
  • Utilisez un mot de passe d'application pour Gmail

Erreur de base de données

  • Appliquez la migration Alembic
  • Vérifiez les permissions de la base

Références non trouvées

  • Vérifiez le format ATT-XXXXXXXXX dans vos emails
  • Ajustez le pattern regex si nécessaire

Customisation

Modifiez app/scripts/email_processor.py pour : - Changer le pattern de référence - Ajuster la durée d'expiration - Modifier les critères de recherche d'emails