espace-paie-odentas/SIGNATURE_SALARIE_PRENOM_FEATURE.md

📧 Personnalisation Email Signature Salarié avec Prénom

Date: 16 octobre 2025

🎯 Objectif

Personnaliser l'email de signature électronique envoyé aux salariés en utilisant leur prénom dans la salutation "Bonjour [Prénom]". Le prénom est récupéré depuis la colonne prenom de la table salaries dans Supabase.

---

✨ Fonctionnalité

Comportement

Lorsqu'un email de signature électronique est envoyé à un salarié :

1. Si la Lambda fournit le prénom → Utilisé directement
2. Si le prénom n'est pas fourni → Recherche dans la table salaries de Supabase
   • Recherche par matricule (priorité) ou adresse_mail
   • Filtre par employer_id si disponible
3. Si aucun prénom trouvé → Fallback sur "Salarié"

Email généré

Bonjour Jean,

Nous vous invitons à signer votre contrat de travail ci-dessous...

---

🔧 Implémentation

Fichier modifié

/app/api/emails/signature-salarie/route.ts

Étape 1 : Renommer le paramètre firstName

const {
  employeeEmail,
  signatureLink,
  reference,
  firstName: providedFirstName,  // ← Renommé pour clarté
  organizationName,
  matricule,
  // ...
} = data;

Étape 2 : Récupération depuis Supabase

// 3. Récupération du prénom depuis Supabase si non fourni
let firstName = providedFirstName;

if (!firstName && (matricule || employeeEmail)) {
  console.log('🔍 Récupération du prénom depuis la table salaries...');
  try {
    const supabase = createSbServiceRole();
    
    // Recherche par matricule ou email
    let query = supabase
      .from('salaries')
      .select('prenom')
      .limit(1);
    
    if (organizationId) {
      query = query.eq('employer_id', organizationId);
    }
    
    // Priorité au matricule
    if (matricule) {
      query = query.or(`code_salarie.eq.${matricule},num_salarie.eq.${matricule}`);
    } else if (employeeEmail) {
      query = query.eq('adresse_mail', employeeEmail);
    }
    
    const { data: salaryData, error: salaryError } = await query;
    
    if (!salaryError && salaryData && salaryData[0]?.prenom) {
      firstName = salaryData[0].prenom;
      console.log('✅ Prénom trouvé dans Supabase:', firstName);
    } else {
      console.warn('⚠️ Prénom non trouvé dans Supabase');
    }
  } catch (err) {
    console.error('⚠️ Erreur lors de la récupération du prénom:', err);
  }
}

Étape 3 : Utilisation du prénom

// 4. Préparation des données de l'email
const emailData: EmailDataV2 = {
  firstName: firstName || 'Salarié',  // ← Fallback si toujours vide
  organizationName: organizationName,
  // ...
};

Étape 4 : Logging amélioré

console.log('📧 Préparation de l\'envoi de l\'email:', {
  to: employeeEmail,
  type: 'signature-request-salarie',
  subject: `Signez votre contrat ${organizationName}`,
  firstName: emailData.firstName  // ← Affiche le prénom utilisé
});

---

🔄 Flux de données

Cas 1 : Lambda fournit le prénom (DynamoDB)

Lambda AWS (DynamoDB)
  ↓ firstName: "Jean"
API /api/emails/signature-salarie
  ↓ Utilise "Jean"
Email envoyé avec "Bonjour Jean,"

Cas 2 : Lambda ne fournit pas le prénom

Lambda AWS (DynamoDB)
  ↓ firstName: null/undefined
API /api/emails/signature-salarie
  ↓ Recherche dans Supabase
Supabase table salaries
  ↓ prenom: "Marie"
API utilise "Marie"
  ↓
Email envoyé avec "Bonjour Marie,"

Cas 3 : Aucun prénom disponible

Lambda AWS (DynamoDB)
  ↓ firstName: null
API /api/emails/signature-salarie
  ↓ Recherche dans Supabase
Supabase table salaries
  ↓ Aucun résultat
API utilise fallback "Salarié"
  ↓
Email envoyé avec "Bonjour Salarié,"

---

📊 Table Supabase utilisée

Table: salaries

Colonnes consultées

Colonne	Type	Description	Utilisation
prenom	text	Prénom du salarié	✅ Récupéré pour personnalisation
code_salarie	text	Code matricule	🔍 Critère de recherche
num_salarie	text	Numéro salarié	🔍 Critère de recherche (alternative)
adresse_mail	text	Email du salarié	🔍 Critère de recherche (fallback)
employer_id	uuid	ID de l'employeur	🔍 Filtre (si disponible)

Requête SQL équivalente

SELECT prenom 
FROM salaries
WHERE employer_id = 'uuid-org-id'
  AND (code_salarie = 'MAT123' OR num_salarie = 'MAT123')
LIMIT 1;

---

🧪 Tests

Test 1 : Prénom fourni par Lambda

Payload envoyé à l'API :

{
  "employeeEmail": "jean.dupont@example.com",
  "signatureLink": "https://...",
  "reference": "CDDU-2025-001",
  "firstName": "Jean",
  "organizationName": "Théâtre National",
  "matricule": "SAL001"
}

Résultat attendu :

• ✅ Email envoyé avec "Bonjour Jean,"
• 📝 Log : firstName: emailData.firstName → "Jean"

---

Test 2 : Prénom non fourni, recherche réussie

Payload envoyé à l'API :

{
  "employeeEmail": "marie.martin@example.com",
  "signatureLink": "https://...",
  "reference": "CDDU-2025-002",
  "firstName": null,
  "organizationName": "Opéra de Paris",
  "matricule": "SAL002",
  "organizationId": "uuid-org"
}

Logs attendus :

🔍 Récupération du prénom depuis la table salaries...
✅ Prénom trouvé dans Supabase: Marie
📧 Préparation de l'envoi de l'email: { firstName: "Marie", ... }

Résultat attendu :

• ✅ Email envoyé avec "Bonjour Marie,"

---

Test 3 : Aucun prénom disponible

Payload envoyé à l'API :

{
  "employeeEmail": "nouveau@example.com",
  "signatureLink": "https://...",
  "reference": "CDDU-2025-003",
  "firstName": null,
  "organizationName": "Comédie Française",
  "matricule": "UNKNOWN"
}

Logs attendus :

🔍 Récupération du prénom depuis la table salaries...
⚠️ Prénom non trouvé dans Supabase
📧 Préparation de l'envoi de l'email: { firstName: "Salarié", ... }

Résultat attendu :

• ✅ Email envoyé avec "Bonjour Salarié,"
• ⚠️ Message générique mais email toujours envoyé

---

📝 Template Email

Le template utilise Handlebars pour la personnalisation :

lib/emailTemplateService.ts

'signature-request-salarie': {
  subject: 'Signez votre contrat {{organizationName}}',
  title: 'Demande de signature électronique',
  greeting: '{{#if firstName}}Bonjour {{firstName}},{{/if}}',  // ← Utilise firstName
  mainMessage: 'Nous vous invitons à signer votre contrat de travail ci-dessous...',
  // ...
}

---

🔒 Sécurité

Authentification

L'API /api/emails/signature-salarie est protégée par API Key :

const apiKey = request.headers.get('X-API-Key');
const validApiKey = ENV.LAMBDA_API_KEY;

if (!apiKey || apiKey !== validApiKey) {
  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}

Permissions Supabase

Utilise createSbServiceRole() pour accéder à la table salaries avec des permissions élevées :

const supabase = createSbServiceRole();

---

📋 Checklist de déploiement

• Modification de /app/api/emails/signature-salarie/route.ts
• Ajout de la récupération du prénom depuis Supabase
• Gestion du fallback "Salarié"
• Logging amélioré avec firstName affiché
• Aucune modification nécessaire dans la Lambda (rétrocompatible)
• Aucune modification nécessaire dans le template email (déjà configuré)

---

✅ Avantages

1. Rétrocompatible : Si la Lambda envoie déjà le prénom, il est utilisé directement
2. Fallback automatique : Recherche dans Supabase si le prénom n'est pas fourni
3. Robuste : Gestion des erreurs sans bloquer l'envoi d'email
4. Logging détaillé : Suivi clair du prénom utilisé dans les logs
5. Personnalisation améliorée : Meilleure expérience utilisateur pour les salariés

---

🐛 Dépannage

Le prénom n'apparaît pas dans l'email

Vérifier :

1. Les logs de l'API :

   📦 Données reçues: { firstName: null, matricule: "SAL001", ... }
   🔍 Récupération du prénom depuis la table salaries...
   ✅ Prénom trouvé dans Supabase: Jean
   

2. La table salaries dans Supabase :

   • Le salarié existe avec ce matricule ?
   • La colonne prenom est bien remplie ?
   • L'employer_id correspond ?

3. Le template email :

   greeting: '{{#if firstName}}Bonjour {{firstName}},{{/if}}'
   

Erreur de requête Supabase

⚠️ Erreur lors de la récupération du prénom: [Error details]

Actions :

• Vérifier que SUPABASE_SERVICE_ROLE_KEY est bien configuré
• Vérifier les permissions RLS sur la table salaries
• Vérifier que createSbServiceRole() utilise bien le service role

---

📚 Fichiers liés

Fichier	Rôle
/app/api/emails/signature-salarie/route.ts	API recevant la demande d'envoi email
/lib/emailTemplateService.ts	Configuration du template avec greeting
/templates-mails/signature-electronique-salarie.html	Template HTML (utilise Handlebars)
/LAMBDA_SIGNATURE_SALARIE_UPDATED.js	Code de la Lambda AWS
Table salaries (Supabase)	Source de données pour le prénom

---

🎉 Résultat

Les emails de signature électronique sont maintenant personnalisés avec le prénom du salarié :

Objet : Signez votre contrat Théâtre National

Bonjour Jean,

Nous vous invitons à signer votre contrat de travail ci-dessous.

[Signer le contrat]

Au lieu de :

Objet : Signez votre contrat Théâtre National

Un document nécessite votre signature électronique.

[Signer le contrat]