espace-paie-odentas/scripts

Système d'Email Universel - Guide Développeur

État actuel du système

✅ PRÊT À L'EMPLOI - Le système universel avec template centralisé et textes configurables est maintenant activé en production.

Fonctionnement

Quand tu annules/modifies/crées un CDDU :

1. Template utilisé : templates-mails/universal-template.html (Handlebars)
2. Textes : Fusion entre templates-mails/texts.json et templates intégrés
3. Rendu : Handlebars + conversion data-attributes → inline CSS
4. Envoi : SES via sendUniversalEmailV2()

Flux d'emails CDDU

• Création : contract-created → sendContractNotifications()
• Modification : contract-updated → sendContractUpdateNotifications()
• Annulation : contract-cancelled → sendContractCancellationNotifications()

Tests en développement

1. Preview local (dry-run)

# Prévisualiser l'email d'annulation
node scripts/send-test-email.js --template universal-template.html --sample annulation

# Ouvrir tmp/send-preview.html dans le navigateur

2. Envoi réel SES

# Configuration environnement (exemple)
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_REGION=eu-west-3
export FROM_EMAIL=paie@odentas.fr

# Envoi test
node scripts/send-test-email.js --template universal-template.html --sample annulation --to dev@example.com --send

3. Données personnalisées

# Créer data.json avec vos données
echo '{"employeeName":"Test User","contractReference":"TEST-123"}' > data.json

# Utiliser le fichier de données
node scripts/send-test-email.js --data data.json --sample annulation --to dev@example.com --send

Personnalisation

Modifier les textes

Éditer templates-mails/texts.json :

{
  "contract-cancelled": {
    "subject": "CDDU annulé - {{employeeName}}",
    "title": "Contrat CDDU annulé",
    "mainMessage": "Votre contrat a été annulé."
  }
}

Modifier le design

Éditer templates-mails/universal-template.html :

• Couleurs : utiliser data-attributes (ex: data-button-color="{{buttonColor}}")
• Structure : HTML + Handlebars ({{#if}}, {{#each}})

Production vs Ancien système

Aspect	Ancien	Nouveau (actuel)
Templates	Individuels (annulationCDDU.html, etc)	Universel (universal-template.html)
Textes	Hard-codés dans templates	Centralisés (texts.json)
Logique	Regex string replace	Handlebars
Styles	CSS statique	Data-attributes → inline CSS
Maintenance	3+ fichiers à synchroniser	1 template + 1 fichier textes

Notes importantes

• ⚠️ SES Sandbox : Vérifier les adresses destinataires si le compte est en sandbox
• ⚠️ FROM_EMAIL : Doit être une adresse vérifiée dans SES
• ✅ TypeScript : Le système compile sans erreurs
• ✅ Backward compatible : L'ancien sendEmail() reste disponible pour d'autres usages

Dépannage

Email non reçu

1. Vérifier les logs de la console pour les erreurs SES
2. Vérifier que FROM_EMAIL est vérifié dans AWS SES
3. Vérifier que le destinataire est vérifié (si sandbox)

Template cassé

1. Tester avec scripts/send-test-email.js en dry-run
2. Vérifier la syntaxe Handlebars dans universal-template.html
3. Vérifier que texts.json est un JSON valide

Styles incorrects

1. Les couleurs dynamiques doivent utiliser data-attributes
2. Éviter les placeholders {{...}} dans les blocs <style>
3. Le service convertit automatiquement data-* → style inline