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** :

```sql
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** :
```json
{
  "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

- [x] Créer route API Next.js
- [x] Ajouter templates emails (employer + employee)
- [x] 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