renaud/espace-paie-odentas
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
espace-paie-odentas/LAMBDA_EMAIL_SIGNATURE_SALARIE_GUIDE.md

357 lines
9.9 KiB
Markdown
Raw Permalink Blame History

# 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*
Reference in a new issue View git blame Copy permalink