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
```bash
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
```sql
-- 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)
```sql
-- 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 ?
   ```bash
   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