espace-paie-odentas/AVENANT_EMAIL_SYSTEM_MIGRATION.md

Migration du système d'envoi d'email pour les avenants

📋 Résumé des changements

Problèmes identifiés

1. ❌ La Lambda AWS envoyait les emails directement via SES avec un template HTML codé en dur
2. ❌ Pas d'utilisation du système universel v2 pour les emails d'avenants
3. ❌ Pas de mise à jour du statut de l'avenant dans Supabase après signature employeur
4. ❌ Logging dans Airtable au lieu du système centralisé

Solutions implémentées

✅ Création d'une route API Next.js /api/webhooks/docuseal-amendment ✅ Migration vers le système universel v2 pour les emails ✅ Mise à jour automatique du statut de l'avenant dans Supabase ✅ Logging centralisé via emailLoggingService ✅ Simplification de la Lambda (appel API au lieu de logique métier)

🔄 Nouveau flux

Avant

DocuSeal Webhook 
  ↓
Lambda postDocuSealAvenantSalarie
  ↓
AWS SES (email HTML codé en dur)
  ↓
AWS S3 (stockage email)
  ↓
Airtable (logging)

Après

DocuSeal Webhook
  ↓
Lambda postDocuSealAvenantSalarie
  ↓
API Next.js /api/webhooks/docuseal-amendment
  ↓
1. Mise à jour Supabase (statut avenant)
  ↓
2. Système universel v2 (email)
  ↓
3. AWS SES (envoi)
  ↓
4. emailLoggingService (logging centralisé)

📁 Fichiers modifiés

1. Lambda AWS

Fichier : /tmp/aws-toolkit-vscode/lambda/eu-west-3/postDocuSealAvenantSalarie/index.js

Changements :

• ✅ Ajout du parsing défensif pour event.body
• ✅ Appel à l'API Next.js au lieu d'envoyer l'email directement
• ✅ Suppression des fonctions sendSignatureEmail(), uploadEmailToS3(), logToAirtable(), findRecordIdByField(), generateEmailHtml()
• ✅ Utilisation de la variable d'environnement NEXT_API_URL

2. Route /api/staff/amendments/[id]/send-signature (MODIFIÉ)

Fichier : /Users/renaud/Projet Nouvel Espace Paie/app/api/staff/amendments/[id]/send-signature/route.ts

Changement critique :

• ✅ Insertion des données dans DynamoDB avant la création de la soumission DocuSeal
• ✅ Clé primaire : avenant.numero_avenant (ex: AVE-001)
• ✅ Données stockées : email salarié, référence contrat, nom, dates, poste, etc.

Pourquoi : La Lambda a besoin de ces données pour appeler l'API Next.js après la signature de l'employeur.

3. Route API Next.js (NOUVEAU)

Fichier : /Users/renaud/Projet Nouvel Espace Paie/app/api/webhooks/docuseal-amendment/route.ts

Fonctionnalités :

• ✅ Récupération de l'avenant par son numéro
• ✅ Mise à jour du statut : signature_status = "pending_employee"
• ✅ Envoi de l'email via sendUniversalEmailV2 avec le type signature-request-employee-amendment
• ✅ Logging automatique via emailLoggingService
• ✅ Gestion d'erreurs complète avec logs détaillés

🎨 Template email utilisé

Type : signature-request-employee-amendment Système : Universel v2 (templates-mails/universal-template.html) Couleurs : Standards Odentas (header #171424, bouton #efc543)

Contenu :

• Greeting personnalisé avec prénom du salarié
• Message explicatif sur la signature de l'avenant
• Bouton CTA "Signer l'avenant" avec lien DocuSeal
• Carte d'info : employeur + matricule
• Carte détails : référence contrat, type, profession, date début, production
• Footer légal standard

🚀 Déploiement

Étape 1 : Déployer Next.js sur Vercel

cd "/Users/renaud/Projet Nouvel Espace Paie"
git add app/api/webhooks/docuseal-amendment/route.ts
git commit -m "feat: Ajouter route webhook avenant avec système universel v2"
git push origin main

Étape 2 : Mettre à jour la Lambda AWS

1. Ouvrir AWS Lambda Console
2. Aller dans postDocuSealAvenantSalarie
3. Copier le contenu de /tmp/aws-toolkit-vscode/lambda/eu-west-3/postDocuSealAvenantSalarie/index.js
4. Ajouter la variable d'environnement :
   • NEXT_API_URL = https://paie.odentas.fr (production)
   • ou https://staging.paie.odentas.fr (staging)
5. Déployer la Lambda

Étape 3 : Tester le flux complet

1. Créer un avenant test dans /staff/avenants/nouveau
2. Envoyer en signature à l'employeur
3. Signer en tant qu'employeur via DocuSeal
4. Vérifier dans les logs :
   • Lambda CloudWatch : appel API Next.js
   • Vercel : route webhook appelée
   • Supabase : statut avenant mis à jour
   • Email reçu par le salarié (boîte mail)

📊 Vérifications

Dans Supabase

-- Vérifier le statut de l'avenant
SELECT 
  numero_avenant,
  signature_status,
  last_employee_notification_at
FROM avenants
WHERE numero_avenant = 'AVE-XXX';

Attendu : signature_status = 'pending_employee' après signature employeur

Dans les logs Vercel

Chercher : [WEBHOOK AVENANT]

• ✅ Avenant trouvé
• ✅ Statut mis à jour
• ✅ Email envoyé

Dans email_logs (Supabase)

-- Vérifier l'envoi de l'email
SELECT 
  email_type,
  to_emails,
  email_status,
  created_at
FROM email_logs
WHERE email_type = 'signature-request-employee-amendment'
ORDER BY created_at DESC
LIMIT 10;

⚙️ Variables d'environnement requises

Lambda AWS

• DOCUSEAL_API_TOKEN - Token API DocuSeal
• NEXT_API_URL - URL de l'API Next.js (ex: https://paie.odentas.fr)
• AWS credentials (automatique via IAM Role)

Next.js (Vercel)

• DOCUSEAL_TOKEN - Token API DocuSeal
• NEXT_PUBLIC_SUPABASE_URL - URL Supabase
• SUPABASE_SERVICE_ROLE_KEY - Service role key
• AWS_REGION - Région AWS (eu-west-3)
• AWS_ACCESS_KEY_ID - Credentials AWS SES
• AWS_SECRET_ACCESS_KEY - Credentials AWS SES

🐛 Debugging

Si l'email n'est pas envoyé

1. Vérifier DynamoDB : Les données sont-elles présentes pour le numéro d'avenant ?

   aws dynamodb get-item \
     --table-name DocuSealNotification \
     --key '{"submission_id":{"S":"AVE-001"}}'
   

2. Vérifier les logs Lambda CloudWatch : postDocuSealAvenantSalarie
3. Vérifier les logs Vercel : /api/webhooks/docuseal-amendment
4. Vérifier email_logs dans Supabase
5. Vérifier que le type signature-request-employee-amendment existe dans emailTemplateService.ts

Si les données ne sont pas dans DynamoDB

• Cause : Échec de l'insertion lors de l'envoi en signature
• Solution : Vérifier les credentials AWS dans les variables d'environnement Vercel
• Vérifier : Logs de /api/staff/amendments/[id]/send-signature pour l'erreur DynamoDB

Si le statut n'est pas mis à jour

1. Vérifier que l'avenant existe avec le bon numero_avenant
2. Vérifier les permissions Supabase (service role)
3. Vérifier les logs de la route webhook

Si la Lambda échoue

1. Vérifier event.body dans les logs CloudWatch
2. Vérifier que NEXT_API_URL est définie
3. Vérifier que l'API Next.js est accessible (pas de firewall/CORS)

📝 Notes importantes

• ⚠️ Ne pas supprimer la table DynamoDB DocuSealNotification (encore utilisée par la Lambda)
• ⚠️ Ne pas supprimer les fonctions Airtable dans la Lambda (encore dans le code mais non utilisées)
• ✅ Le logging Airtable est remplacé par emailLoggingService
• ✅ Le stockage S3 des emails est remplacé par le logging centralisé
• ✅ Les emails utilisent maintenant le template universel v2 cohérent avec le reste de l'application

🎯 Prochaines étapes (optionnel)

1. Migrer complètement vers webhook DocuSeal direct (sans Lambda)
2. Supprimer DynamoDB et Airtable du flux
3. Ajouter un webhook pour la signature du salarié (mise à jour finale du statut)
4. Ajouter des tests automatisés pour le flux complet

✅ Checklist de déploiement

• Code Next.js déployé sur Vercel
• Lambda mise à jour avec nouveau code
• Variable NEXT_API_URL ajoutée à la Lambda
• Test complet du flux (création → signature employeur → email salarié)
• Vérification dans Supabase (statut mis à jour)
• Vérification email reçu avec bon template
• Logs vérifiés (Lambda + Vercel + email_logs)

---

Date de migration : 23 octobre 2025 Auteur : GitHub Copilot Statut : ✅ Prêt pour déploiement