geo/api/docs/PREPA_PROD.md

PRÉPARATION PRODUCTION - Process Email Queue + Permissions Suppression Passages

📅 Date de mise en production prévue : _____________

🎯 Objectif

1. Mettre en place le système de traitement automatique de la queue d'emails pour l'envoi des reçus fiscaux de dons.
2. Ajouter le champ de permission pour autoriser les membres à supprimer des passages.

✅ Prérequis

• Backup de la base de données effectué
• Accès SSH au serveur PROD
• Accès à la base de données PROD
• Droits pour éditer le crontab

📝 Fichiers à déployer

Les fichiers suivants doivent être présents sur le serveur PROD :

• /scripts/cron/process_email_queue.php
• /scripts/cron/process_email_queue_with_daily_log.sh
• /scripts/cron/test_email_queue.php
• /src/Services/ReceiptPDFGenerator.php (nouveau)
• /src/Services/ReceiptService.php (mis à jour)
• /src/Core/MonitoredDatabase.php (mis à jour)
• /src/Controllers/EntiteController.php (mis à jour)
• /src/Controllers/LoginController.php (mis à jour)
• /scripts/sql/add_chk_user_delete_pass.sql (nouveau)

---

🔧 ÉTAPES DE MISE EN PRODUCTION

1️⃣ Mise à jour de la base de données

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

-- Vérifier d'abord la structure actuelle de email_queue
DESCRIBE email_queue;

-- Ajouter les champs manquants pour email_queue si nécessaire
ALTER TABLE `email_queue` 
ADD COLUMN IF NOT EXISTS `sent_at` TIMESTAMP NULL DEFAULT NULL 
COMMENT 'Date/heure d\'envoi effectif de l\'email'
AFTER `status`;

ALTER TABLE `email_queue` 
ADD COLUMN IF NOT EXISTS `error_message` TEXT NULL DEFAULT NULL 
COMMENT 'Message d\'erreur en cas d\'échec'
AFTER `attempts`;

-- Ajouter les index pour optimiser 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`);

-- Vérifier les modifications email_queue
DESCRIBE email_queue;

-- ⚠️ IMPORTANT : Ajouter le nouveau champ chk_user_delete_pass dans entites
source /var/www/geosector/api/scripts/sql/add_chk_user_delete_pass.sql;

2️⃣ Test du script avant mise en production

# Se connecter au serveur PROD
ssh user@prod-server

# Aller dans le répertoire de l'API
cd /var/www/geosector/api

# Rendre les scripts exécutables
chmod +x scripts/cron/process_email_queue.php
chmod +x scripts/cron/test_email_queue.php

# Tester l'état de la queue (lecture seule)
php scripts/cron/test_email_queue.php

# Si tout est OK, faire un test d'envoi sur 1 email
# (modifier temporairement BATCH_SIZE à 1 dans le script si nécessaire)
php scripts/cron/process_email_queue.php

3️⃣ Configuration du CRON avec logs journaliers

# Rendre le script wrapper exécutable
chmod +x /var/www/geosector/api/scripts/cron/process_email_queue_with_daily_log.sh

# Éditer le crontab
crontab -e

# Ajouter cette ligne pour exécution toutes les 5 minutes avec logs journaliers
*/5 * * * * /var/www/geosector/api/scripts/cron/process_email_queue_with_daily_log.sh

# Sauvegarder et quitter (:wq sous vi/vim)

# Vérifier que le cron est bien enregistré
crontab -l | grep email_queue

# Vérifier que le service cron est actif
systemctl status cron

Note : Les logs seront créés automatiquement dans /var/www/geosector/api/logs/ avec le format : email_queue_20250820.log, email_queue_20250821.log, etc. Les logs de plus de 30 jours sont supprimés automatiquement.

4️⃣ Surveillance post-déploiement

Pendant les premières heures après la mise en production :

# Surveiller les logs en temps réel (fichier du jour)
tail -f /var/www/geosector/api/logs/email_queue_$(date +%Y%m%d).log

# Vérifier le statut de la queue
php scripts/cron/test_email_queue.php

# Compter les emails traités
mysql -u geo_app_user_prod -p geo_app -e "
SELECT status, COUNT(*) as count 
FROM email_queue 
WHERE DATE(created_at) = CURDATE() 
GROUP BY status;"

# Vérifier les erreurs éventuelles
mysql -u geo_app_user_prod -p geo_app -e "
SELECT id, to_email, subject, attempts, error_message 
FROM email_queue 
WHERE status='failed' 
ORDER BY created_at DESC 
LIMIT 10;"

---

🚨 ROLLBACK (si nécessaire)

En cas de problème, voici comment revenir en arrière :

# 1. Stopper le cron
crontab -e
# Commenter la ligne du process_email_queue

# 2. Marquer les emails en attente pour traitement manuel
mysql -u geo_app_user_prod -p geo_app -e "
UPDATE email_queue 
SET status='pending', attempts=0 
WHERE status='failed' AND DATE(created_at) = CURDATE();"

# 3. Informer l'équipe pour traitement manuel si nécessaire

---

📊 VALIDATION POST-DÉPLOIEMENT

Critères de succès :

• Aucune erreur dans les logs
• Les emails sont envoyés dans les 5 minutes
• Les reçus PDF sont correctement attachés
• Le champ date_sent_recu est mis à jour dans ope_pass
• Pas d'accumulation d'emails en status 'pending'

Commandes de vérification :

# Statistiques générales
mysql -u geo_app_user_prod -p geo_app -e "
SELECT 
    status,
    COUNT(*) as count,
    MIN(created_at) as oldest,
    MAX(created_at) as newest
FROM email_queue
GROUP BY status;"

# Vérifier les passages avec reçus envoyés aujourd'hui
mysql -u geo_app_user_prod -p geo_app -e "
SELECT COUNT(*) as recus_envoyes_aujourdhui
FROM ope_pass
WHERE DATE(date_sent_recu) = CURDATE();"

# Performance du cron (dernières exécutions du jour)
tail -20 /var/www/geosector/api/logs/email_queue_$(date +%Y%m%d).log | grep "Traitement terminé"

---

📞 CONTACTS EN CAS DE PROBLÈME

• Responsable technique : _____________
• DBA : _____________
• Support O2Switch : support@o2switch.fr

---

📋 NOTES IMPORTANTES

1. Limite d'envoi : 1500 emails/heure max (limite O2Switch)
2. Batch size : 50 emails par exécution (toutes les 5 min = 600/heure max)
3. Lock file : /tmp/process_email_queue.lock empêche l'exécution simultanée
4. Nettoyage auto : Les emails envoyés > 30 jours sont supprimés automatiquement

🔒 SÉCURITÉ

• Les mots de passe SMTP ne sont jamais loggués
• Les emails en erreur conservent le message d'erreur pour diagnostic
• Le PDF est envoyé en pièce jointe encodée en base64

---

✅ CHECKLIST FINALE

Email Queue :

• Table email_queue mise à jour (sent_at, error_message, index)
• Scripts cron testés avec succès
• Cron configuré et actif
• Logs accessibles et fonctionnels
• Premier batch d'emails envoyé avec succès

Permissions Suppression Passages :

• Champ chk_user_delete_pass ajouté dans la table entites
• EntiteController.php mis à jour pour gérer le nouveau champ
• LoginController.php mis à jour pour retourner le champ dans amicale
• Test de modification de permissions via l'interface admin

Général :

• Documentation mise à jour
• Équipe informée de la mise en production

---

Date de mise en production : _______________ Validé par : _______________ Signature : _______________