geo/api/docs/SETUP_EMAIL_QUEUE_CRON.md

Instructions de mise en place du CRON pour la queue d'emails

Problème résolu

Les emails de reçus étaient insérés dans la table email_queue mais n'étaient jamais envoyés car il manquait le script de traitement.

Fichiers créés

1. /scripts/cron/process_email_queue.php - Script principal de traitement
2. /scripts/cron/test_email_queue.php - Script de test/diagnostic
3. /scripts/sql/add_email_queue_fields.sql - Migration SQL pour les champs manquants

Installation sur les serveurs (DVA, REC, PROD)

1. Appliquer la migration SQL

Se connecter à la base de données et exécuter :

mysql -u [user] -p [database] < /path/to/api/scripts/sql/add_email_queue_fields.sql

Ou directement dans MySQL :

-- Ajouter les champs manquants
ALTER TABLE `email_queue` 
ADD COLUMN IF NOT EXISTS `sent_at` TIMESTAMP NULL DEFAULT NULL AFTER `status`;

ALTER TABLE `email_queue` 
ADD COLUMN IF NOT EXISTS `error_message` TEXT NULL DEFAULT NULL AFTER `attempts`;

-- Ajouter les index pour les performances
ALTER TABLE `email_queue` 
ADD INDEX IF NOT EXISTS `idx_status_attempts` (`status`, `attempts`);

ALTER TABLE `email_queue` 
ADD INDEX IF NOT EXISTS `idx_sent_at` (`sent_at`);

2. Tester le script

Avant de mettre en place le cron, tester que tout fonctionne :

# Vérifier l'état de la queue
php /path/to/api/scripts/cron/test_email_queue.php

# Tester l'envoi (traite jusqu'à 50 emails)
php /path/to/api/scripts/cron/process_email_queue.php

3. Configurer le CRON

Ajouter la ligne suivante dans le crontab du serveur :

# Éditer le crontab
crontab -e

# Ajouter cette ligne (exécution toutes les 5 minutes)
*/5 * * * * /usr/bin/php /path/to/api/scripts/cron/process_email_queue.php >> /var/log/email_queue.log 2>&1

Options de fréquence :

• */5 * * * * - Toutes les 5 minutes (recommandé)
• */10 * * * * - Toutes les 10 minutes
• */2 * * * * - Toutes les 2 minutes (si volume important)

4. Monitoring

Le script génère des logs via LogService. Vérifier les logs dans :

• /path/to/api/logs/ (selon la configuration)

Points à surveiller :

• Nombre d'emails traités
• Emails en échec après 3 tentatives
• Erreurs de connexion SMTP

5. Configuration SMTP

Vérifier que la configuration SMTP est correcte dans AppConfig :

• Host SMTP
• Port (587 pour TLS, 465 pour SSL)
• Username/Password
• Encryption (tls ou ssl)
• From Email/Name

Fonctionnement du script

Caractéristiques

• Batch size : 50 emails par exécution
• Max tentatives : 3 essais par email
• Lock file : Empêche l'exécution simultanée
• Nettoyage : Supprime les emails envoyés > 30 jours
• Pause : 0.5s entre chaque email (anti-spam)

Workflow

1. Récupère les emails avec status = 'pending' et attempts < 3
2. Pour chaque email :
   • Incrémente le compteur de tentatives
   • Envoie via PHPMailer avec la config SMTP
   • Si succès : status = 'sent' + mise à jour du passage
   • Si échec : réessai à la prochaine exécution
   • Après 3 échecs : status = 'failed'

Tables mises à jour

• email_queue : status, attempts, sent_at, error_message
• ope_pass : date_sent_recu, chk_email_sent

Commandes utiles

# Voir les emails en attente
mysql -e "SELECT COUNT(*) FROM email_queue WHERE status='pending'" [database]

# Voir les emails échoués
mysql -e "SELECT * FROM email_queue WHERE status='failed' ORDER BY created_at DESC LIMIT 10" [database]

# Réinitialiser un email échoué pour réessai
mysql -e "UPDATE email_queue SET status='pending', attempts=0 WHERE id=[ID]" [database]

# Voir les logs du cron
tail -f /var/log/email_queue.log

# Vérifier que le cron est actif
crontab -l | grep process_email_queue

Troubleshooting

Le cron ne s'exécute pas

• Vérifier les permissions : chmod +x process_email_queue.php
• Vérifier le chemin PHP : which php
• Vérifier les logs système : /var/log/syslog ou /var/log/cron

Emails en échec

• Vérifier la config SMTP avec test_email_queue.php
• Vérifier les logs pour les messages d'erreur
• Tester la connexion SMTP : telnet [smtp_host] [port]

Lock bloqué

Si le message "Le processus est déjà en cours" persiste :

rm /tmp/process_email_queue.lock

Contact support

En cas de problème, vérifier :

1. Les logs de l'application
2. La table email_queue pour les messages d'erreur
3. La configuration SMTP dans AppConfig