espace-paie-odentas/LAMBDA_MIGRATION_AVENANT_COMPLETION.md

Migration Lambda → Next.js API - Avenant Completion

📋 Context

Migration de la Lambda AWS postDocuSealFinalEmailsAvenant vers une route API Next.js intégrée au système d'emails universel v2.

🎯 Objectifs

1. ✅ Remplacer la Lambda AWS par une route Next.js
2. ✅ Utiliser le système d'emails universel v2 (templates Handlebars)
3. ✅ Logger les emails dans Supabase (email_logs)
4. ✅ Supprimer la dépendance à Airtable
5. ✅ Supprimer le HTML inline hardcodé

🔧 Fichiers Créés/Modifiés

✅ Nouveau Webhook Handler

Fichier : app/api/webhooks/docuseal-amendment-completed/route.ts

Fonction : Traite la complétion d'un avenant (toutes parties signées)

Flow :

1. Reçoit webhook DocuSeal avec submissionId
2. Recherche l'avenant par docuseal_submission_id
3. Met à jour signature_status → 'completed'
4. Envoie email à l'employeur (amendment-completed-employer)
5. Envoie email au salarié (amendment-completed-employee)
6. Logs les emails dans email_logs

Sécurité :

• Utilise createRouteHandlerClient (Supabase Auth)
• Clé API DocuSeal en Authorization header

✅ Templates d'Emails Ajoutés

Fichier : lib/emailTemplateService.ts

Templates créés :

1. amendment-completed-employer

• Sujet : "Avenant n°X signé - [Organisation]"
• CTA : "Voir les documents"
• Info : Salarié, matricule, détails avenant
• Message : Confirmation signature par toutes les parties

2. amendment-completed-employee

• Sujet : "Votre avenant n°X est signé - [Organisation]"
• CTA : "Télécharger l'avenant"
• Info : Employeur, matricule, détails avenant
• Message : Téléchargement de l'exemplaire signé

✅ Types Ajoutés

Fichiers :

• lib/emailTemplateService.ts (EmailTypeV2)
• lib/emailLoggingService.ts (EmailType)

Types :

• amendment-completed-employer
• amendment-completed-employee

🔄 Flux Complet Avenant

Étape 1 : Signature Employeur

Webhook : /api/webhooks/docuseal-amendment Action :

1. Employeur signe l'avenant sur DocuSeal
2. Webhook reçu avec submissionId
3. Update avenant : signature_status → 'pending_employee'
4. Envoi email au salarié (signature-request-employee-amendment)

Étape 2 : Signature Salarié (Complétion)

Webhook : /api/webhooks/docuseal-amendment-completed Action :

1. Salarié signe l'avenant sur DocuSeal
2. Webhook reçu avec submissionId
3. Update avenant : signature_status → 'completed'
4. Envoi email employeur (amendment-completed-employer)
5. Envoi email salarié (amendment-completed-employee)

📊 Comparaison Lambda vs Next.js

Aspect	Lambda (Avant)	Next.js (Après)
Localisation	iad1 (US-Est) ❌	cdg1 (Paris) ✅
Templates	HTML inline hardcodé	Handlebars universel v2
Logging	Airtable ❌	Supabase email_logs ✅
Auth	Clé API custom	Supabase Auth
Maintenance	Code séparé	Code intégré au projet
Réutilisabilité	Zéro	Composants réutilisables

⚠️ Migration SQL Requise

Exécuter dans Supabase SQL Editor :

ALTER TYPE email_type ADD VALUE IF NOT EXISTS 'amendment-completed-employer';
ALTER TYPE email_type ADD VALUE IF NOT EXISTS 'amendment-completed-employee';
ALTER TYPE email_type ADD VALUE IF NOT EXISTS 'signature-request-employee-amendment';

Voir : MIGRATION_SQL_EMAIL_TYPES.md pour le script complet.

🧪 Tests à Effectuer

Test 1 : Signature Employeur → Email Salarié

1. Créer un avenant via staff/contrats
2. Envoyer pour signature employeur
3. Signer en tant qu'employeur
4. ✅ Vérifier email reçu par salarié
5. ✅ Vérifier log dans email_logs (type: signature-request-employee-amendment)

Test 2 : Signature Salarié → Emails Confirmation

1. Reprendre avenant de Test 1 (pending_employee)
2. Signer en tant que salarié
3. ✅ Vérifier email reçu par employeur (type: amendment-completed-employer)
4. ✅ Vérifier email reçu par salarié (type: amendment-completed-employee)
5. ✅ Vérifier logs dans email_logs (2 entrées)
6. ✅ Vérifier signature_status = 'completed' dans avenants

Test 3 : Liens de Téléchargement

1. Cliquer sur CTA dans email employeur
2. ✅ Vérifier accès aux documents
3. Cliquer sur CTA dans email salarié
4. ✅ Vérifier téléchargement avenant signé

🗑️ Nettoyage Lambda (Après Tests)

Une fois les tests validés :

1. AWS Lambda Console :

   • Désactiver trigger DocuSeal
   • Supprimer fonction postDocuSealFinalEmailsAvenant
   • Supprimer layer Node.js si non utilisé ailleurs

2. DocuSeal :

   • Vérifier webhook configuré sur nouvelle route Next.js
   • URL : https://espacepaieodentas.com/api/webhooks/docuseal-amendment-completed

3. Airtable :

   • ✅ Déjà supprimé (variables d'environnement retirées)

4. Documentation :

   • Mettre à jour DOCUSEAL_SIGNATURE_CONFIG.md
   • Archiver code Lambda dans repo si backup souhaité

📝 Configuration DocuSeal

Webhook à Configurer :

• Event : form.completed (toutes parties signées)
• URL : https://espacepaieodentas.com/api/webhooks/docuseal-amendment-completed
• Method : POST
• Headers :
  • Authorization: Bearer [DOCUSEAL_API_KEY]
  • Content-Type: application/json

Payload Attendu :

{
  "event_type": "form.completed",
  "data": {
    "id": "submission_123456",
    "template": {
      "name": "AVENANT_REF_CONTRACT"
    },
    "created_at": "2025-01-XX",
    "submitters": [
      {
        "email": "employer@company.com",
        "role": "Employeur"
      },
      {
        "email": "employee@example.com", 
        "role": "Salarié"
      }
    ]
  }
}

🎯 Avantages de la Migration

1. RGPD : Région Paris (cdg1) → données EU uniquement
2. Maintenance : Code centralisé dans le projet Next.js
3. Réutilisabilité : Templates Handlebars pour tous les emails
4. Logging : Traçabilité complète dans Supabase
5. Performance : Moins de latence (cdg1 vs iad1)
6. Coûts : Réduction coûts AWS Lambda
7. Cohérence : Système unifié pour tous les emails

🔗 Références

• Webhook avenant étape 1 : /api/webhooks/docuseal-amendment
• Webhook avenant étape 2 : /api/webhooks/docuseal-amendment-completed
• Email templates : lib/emailTemplateService.ts
• Email logging : lib/emailLoggingService.ts
• Migration SQL : MIGRATION_SQL_EMAIL_TYPES.md
• Lambda original : LAMBDA_EMAIL_SIGNATURE_SALARIE_GUIDE.md (contrats initiaux)

✅ Checklist Déploiement

• Créer route API Next.js
• Ajouter templates emails (employer + employee)
• Ajouter types TypeScript
• Exécuter migration SQL Supabase
• Configurer webhook DocuSeal
• Tester flux complet (étape 1 + étape 2)
• Vérifier logs dans email_logs
• Valider emails reçus (contenu + design)
• Désactiver Lambda AWS
• Mettre à jour documentation
• Commit + push code

📅 Status

Date : 2025-01-XX Status : ✅ Code prêt, en attente SQL + tests Bloquants : Migration SQL à exécuter dans Supabase Prochaine étape : Exécuter SQL puis tester avec avenant réel