# Configuration Lambda → Espace Paie : Email Signature Salarié

## 📋 Vue d'ensemble

Cette documentation détaille la configuration nécessaire pour faire communiquer la Lambda AWS `postDocuSealSalarie` avec l'Espace Paie pour l'envoi d'emails de signature aux salariés.

### Architecture

```
DocuSeal Webhook → Lambda postDocuSealSalarie → API Espace Paie → Système Email Universel v2 → AWS SES
                                                                           ↓
                                                                   Logs emails (Supabase)
```

### Avantages de cette architecture

✅ **Centralisation** : Tous les emails passent par le système universel v2  
✅ **Logs automatiques** : Tous les envois sont enregistrés dans `email_logs`  
✅ **Cohérence** : Même template et même système que les autres emails  
✅ **Maintenance simplifiée** : Un seul endroit pour gérer les emails  
✅ **Debugging facilité** : Logs accessibles dans l'interface Staff

---

## 🔧 Configuration AWS Lambda

### Variables d'environnement à ajouter/modifier

Dans la configuration de la Lambda `postDocuSealSalarie` :

```env
# Existantes (à conserver)
DOCUSEAL_API_TOKEN=xxxxx
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_SERVICE_ROLE=xxxxx
ZAPIER_WEBHOOK_URL=https://hooks.zapier.com/xxxxx

# NOUVELLES variables à ajouter
ESPACE_PAIE_URL=https://paie.odentas.fr
ESPACE_PAIE_API_KEY=<générer une clé secrète forte>
```

### ⚠️ Variables à SUPPRIMER

Les variables suivantes ne sont plus nécessaires car l'envoi d'email est géré par l'Espace Paie :

```env
# À SUPPRIMER
AWS_SES_FROM=paie@odentas.fr
S3_BUCKET_NAME_EMAILS=odentas-emails
AIRTABLE_API_KEY=xxxxx
```

### Génération de l'API Key

Pour générer une API Key sécurisée :

```bash
# Méthode 1 : OpenSSL
openssl rand -hex 32

# Méthode 2 : Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Méthode 3 : Python
python3 -c "import secrets; print(secrets.token_hex(32))"
```

**Important** : Utilisez la même clé dans AWS Lambda et dans l'Espace Paie.

---

## 🌐 Configuration Espace Paie

### Variables d'environnement à ajouter

Dans `.env.local` (dev) et dans Vercel (production) :

```env
# API Key pour authentifier les appels depuis la Lambda
LAMBDA_API_KEY=<même clé que ESPACE_PAIE_API_KEY de la Lambda>
```

### Déploiement de la variable sur Vercel

```bash
# Ajouter la variable d'environnement sur Vercel
vercel env add LAMBDA_API_KEY

# Saisir la valeur : <la même que dans AWS Lambda>
# Environnements : Production, Preview, Development

# Redéployer pour prendre en compte la nouvelle variable
vercel --prod
```

---

## 📝 Fichiers modifiés/créés

### 1. Espace Paie (Next.js)

#### ✨ Nouveau fichier créé
- **`app/api/emails/signature-salarie/route.ts`**
  - Route API POST pour recevoir les demandes d'envoi d'email
  - Authentification par API Key
  - Utilise `sendUniversalEmailV2()`
  - Logs automatiques dans `email_logs`

#### 📝 Fichiers modifiés
- **`lib/emailTemplateService.ts`**
  - Ajout du type `'signature-request-salarie'` dans `EmailTypeV2`
  - Ajout des champs `matricule` et `typecontrat` dans `EmailDataV2`
  - Configuration du template email avec cartes info et détails

- **`lib/cleanEnv.ts`**
  - Ajout de `LAMBDA_API_KEY` dans l'objet `ENV`

### 2. Lambda AWS

#### 📝 Fichier modifié
- **`index.js`** (version mise à jour fournie : `LAMBDA_SIGNATURE_SALARIE_UPDATED.js`)
  - ❌ Suppression de `sendSignatureEmail()` (envoi direct SES)
  - ❌ Suppression de `uploadEmailToS3()` (stockage S3)
  - ❌ Suppression de `logToAirtable()` (logging Airtable)
  - ❌ Suppression de `generateEmailHtml()` (template HTML)
  - ✅ Ajout de l'appel API vers l'Espace Paie
  - ✅ Headers d'authentification avec API Key
  - ✅ Gestion d'erreurs améliorée

---

## 🚀 Déploiement

### Étape 1 : Déployer l'Espace Paie

```bash
# En local, vérifier que la variable existe
grep LAMBDA_API_KEY .env.local

# Si absente, l'ajouter
echo "LAMBDA_API_KEY=votre_cle_secrete_ici" >> .env.local

# Sur Vercel (production)
vercel env add LAMBDA_API_KEY
# Puis redéployer
vercel --prod
```

### Étape 2 : Mettre à jour la Lambda AWS

1. **Via AWS Console** :
   - Aller dans AWS Lambda → `postDocuSealSalarie`
   - Onglet "Configuration" → "Environment variables"
   - Ajouter :
     - `ESPACE_PAIE_URL` = `https://paie.odentas.fr`
     - `ESPACE_PAIE_API_KEY` = `<votre clé générée>`
   - Supprimer les anciennes variables (optionnel mais recommandé)

2. **Mettre à jour le code** :
   - Remplacer le contenu de `index.js` par celui de `LAMBDA_SIGNATURE_SALARIE_UPDATED.js`
   - Cliquer sur "Deploy"

### Étape 3 : Tester

```bash
# Test depuis la Lambda (déclencher un webhook DocuSeal)
# Vérifier les logs CloudWatch pour :
# - "📤 Appel de l'API Espace Paie pour envoi email..."
# - "✅ E-mail envoyé via l'API Espace Paie"

# Vérifier dans l'Espace Paie
# - Aller sur /staff/email-logs
# - Chercher le type "signature-request-salarie"
# - Vérifier le statut "sent"
```

---

## 🔍 Debug & Monitoring

### Logs Lambda (CloudWatch)

```
📤 Appel de l'API Espace Paie pour envoi email...
✅ E-mail envoyé via l'API Espace Paie: { success: true, messageId: '...' }
```

### Logs Espace Paie (Console serveur)

```
=== API Email Signature Salarié ===
✅ Authentication successful
📦 Données reçues: { employeeEmail: '...', reference: '...', ... }
📧 Préparation de l'envoi de l'email: { to: '...', type: 'signature-request-salarie' }
✅ Email envoyé avec succès: { messageId: '...', recipient: '...', reference: '...' }
```

### Vérification dans l'interface

1. **Interface Staff** : `/staff/email-logs`
   - Filtrer par type : `signature-request-salarie`
   - Vérifier le statut et le contenu HTML

2. **Base de données** : Table `email_logs`
   ```sql
   SELECT * FROM email_logs 
   WHERE email_type = 'signature-request-salarie' 
   ORDER BY created_at DESC 
   LIMIT 10;
   ```

---

## 🛡️ Sécurité

### API Key

- ✅ Utilisez une clé de minimum 32 caractères hexadécimaux (256 bits)
- ✅ Ne commitez JAMAIS la clé dans le code
- ✅ Utilisez des variables d'environnement différentes par environnement
- ✅ Renouvelez la clé périodiquement (tous les 6 mois)

### HTTPS

- ✅ L'API Espace Paie doit être en HTTPS uniquement
- ✅ Vérifiez le certificat SSL (fait automatiquement par axios)

### Rate Limiting

À considérer pour le futur :
- Limiter le nombre de requêtes par minute depuis une IP
- Implémenter un système de throttling

---

## 📊 Données envoyées

### Payload de la Lambda vers l'API

```json
{
  "employeeEmail": "salarie@example.com",
  "signatureLink": "https://paie.odentas.fr/signature-salarie/?docuseal_id=abc123",
  "reference": "CDDU-2025-001",
  "firstName": "Jean",
  "organizationName": "Théâtre National",
  "matricule": "SAL001",
  "typecontrat": "CDDU",
  "startDate": "15/01/2025",
  "profession": "Comédien",
  "productionName": "Le Mariage de Figaro",
  "organizationId": "uuid-org",
  "contractId": "uuid-contract"
}
```

### Réponse de l'API

```json
{
  "success": true,
  "messageId": "01000192...",
  "recipient": "salarie@example.com",
  "reference": "CDDU-2025-001"
}
```

---

## ❌ Gestion des erreurs

### Erreurs possibles

| Code | Erreur | Cause | Solution |
|------|--------|-------|----------|
| 401 | Unauthorized | API Key invalide ou manquante | Vérifier `LAMBDA_API_KEY` et `ESPACE_PAIE_API_KEY` |
| 400 | Bad Request | Champs requis manquants | Vérifier le payload envoyé |
| 500 | Server Error | Erreur lors de l'envoi SES | Vérifier les credentials AWS SES |
| 500 | Configuration Error | `LAMBDA_API_KEY` non définie | Ajouter la variable dans Vercel |

### En cas d'échec

La Lambda retourne une erreur 500 mais **ne bloque pas** :
- Le contrat reste signé par l'employeur dans Supabase
- Le webhook Zapier est appelé quand même
- L'erreur est loggée dans CloudWatch

---

## 🔄 Rollback

Si vous devez revenir en arrière :

1. **Restaurer l'ancien code Lambda**
   - Utiliser le fichier `/tmp/aws-toolkit-vscode/lambda/eu-west-3/postDocuSealSalarie/index.js`

2. **Rétablir les variables d'environnement**
   - Réajouter `AWS_SES_FROM`, `S3_BUCKET_NAME_EMAILS`, `AIRTABLE_API_KEY`
   - Supprimer `ESPACE_PAIE_URL` et `ESPACE_PAIE_API_KEY`

3. **L'Espace Paie reste compatible**
   - La route API peut rester en place (elle ne sera simplement pas appelée)
   - Le nouveau type d'email `signature-request-salarie` ne causera pas d'erreur

---

## 📚 Ressources

- [Système Email Universel v2](./EMAIL_TEMPLATE_SYSTEM.md)
- [Logs Emails](./DEBUG_EMAIL_LOGS.md)
- [DocuSeal API](https://docs.docuseal.co/)
- [AWS Lambda Configuration](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html)

---

## ✅ Checklist de déploiement

### Avant déploiement

- [ ] Générer une API Key sécurisée (32 caractères hex minimum)
- [ ] Tester localement la route API avec un faux payload
- [ ] Vérifier que le template email s'affiche correctement

### Espace Paie

- [ ] Ajouter `LAMBDA_API_KEY` dans `.env.local`
- [ ] Ajouter `LAMBDA_API_KEY` sur Vercel (tous les environnements)
- [ ] Déployer sur Vercel
- [ ] Vérifier que la route `/api/emails/signature-salarie` répond

### Lambda AWS

- [ ] Ajouter `ESPACE_PAIE_URL` dans les variables d'env
- [ ] Ajouter `ESPACE_PAIE_API_KEY` dans les variables d'env (même valeur que `LAMBDA_API_KEY`)
- [ ] Mettre à jour le code de la Lambda
- [ ] Déployer

### Tests

- [ ] Déclencher un webhook DocuSeal (signature employeur)
- [ ] Vérifier les logs CloudWatch de la Lambda
- [ ] Vérifier les logs de l'API Espace Paie
- [ ] Vérifier que l'email a été reçu par le salarié
- [ ] Vérifier l'entrée dans `/staff/email-logs`
- [ ] Vérifier le contenu HTML de l'email

### Post-déploiement

- [ ] Monitorer les logs pendant 24h
- [ ] Vérifier le taux de succès des emails
- [ ] Documenter tout problème rencontré
- [ ] Célébrer ! 🎉

---

*Dernière mise à jour : 15 octobre 2025*