espace-paie-odentas/EMAIL_TEMPLATE_SYSTEM.md

Système d'Email Universel

Vue d'ensemble

Le système d'email universel permet de gérer tous les emails de l'application avec un template unique qui s'adapte automatiquement selon le type de notification.

Architecture

Fichiers principaux

• lib/emailTemplateService.ts - Service principal du système universel
• lib/emailMigrationHelpers.ts - Utilitaires de migration
• lib/emailService.ts - Service existant mis à jour pour les contrats
• templates-mails/ - Templates individuels existants (legacy)

Types d'emails supportés

Le système supporte 14 types d'emails différents, chacun avec sa propre couleur et configuration :

Type	Couleur	Usage
contract-created	Vert	Création de nouveaux contrats
contract-updated	Bleu	Modification de contrats
contract-cancelled	Rouge	Annulation de contrats
invitation	Violet	Invitation d'utilisateurs
invoice	Orange	Envoi de factures
signature-request	Indigo	Demande de signature électronique
signature-reminder	Ambre	Rappel de signature
password-reset	Cyan	Réinitialisation de mot de passe
otp	Lime	Codes de vérification
access-granted	Émeraude	Accès accordés
access-revoked	Rose	Accès révoqués
account-activation	Jaune	Invitation/activation de compte
access-updated	Orange	Modification d’habilitation (rôle)
notification	Gris	Notifications générales
reminder	Jaune	Rappels
welcome	Teal	Messages de bienvenue

Utilisation

Envoi d'un email

import { sendUniversalEmail } from '../lib/emailTemplateService';

// Email de nouveau contrat
await sendUniversalEmail({
  to: 'artiste@example.com',
  type: 'contract-created',
  data: {
    nomSalarie: 'Jean Dupont',
    nomProducteur: 'Théâtre National',
    nomSpectacle: 'Le Mariage de Figaro',
    dateDebut: '15 janvier 2025',
    dateFin: '30 mars 2025',
    cachet: '450€',
    signatureLink: 'https://example.com/sign/abc123'
  }
});

// Email d'invitation
await sendUniversalEmail({
  to: 'nouveau@example.com',
  type: 'invitation',
  data: {
    invitedUserName: 'Marie Martin',
    inviterName: 'Admin Système',
    organizationName: 'Compagnie Théâtrale',
    activationLink: 'https://example.com/activate/def456'
  }
});

Fonctions de migration

Pour faciliter la transition, des fonctions spécialisées sont disponibles :

import { 
  sendInvitationEmail,
  sendInvoiceEmail,
  sendSignatureRequestEmail,
  sendPasswordResetEmail,
  sendOTPEmail 
} from '../lib/emailMigrationHelpers';

// Utilisation simplifiée
await sendInvitationEmail({
  to: 'user@example.com',
  invitedUserName: 'Jean Dupont',
  inviterName: 'Admin',
  organizationName: 'Ma Compagnie',
  activationLink: 'https://...'
});

Exemples accès / habilitations

import { 
  sendAccountActivationEmail,
  sendAccessUpdatedEmail,
  sendAccessRevokedEmail
} from '../lib/emailMigrationHelpers';

// Activation de compte
await sendAccountActivationEmail('user@example.com', {
  firstName: 'Marie',
  organizationName: 'Compagnie Théâtrale',
  activationUrl: 'https://paie.odentas.fr/activate?token=abc'
});

// Modification d’habilitation
await sendAccessUpdatedEmail('user@example.com', {
  firstName: 'Jean',
  organizationName: 'Odentas',
  oldRole: 'AGENT',
  newRole: 'ADMIN',
  updatedBy: 'admin@odentas.fr',
  updateDate: new Date().toLocaleString('fr-FR')
});

// Révocation d’accès
await sendAccessRevokedEmail('user@example.com', {
  firstName: 'Lucie',
  organizationName: 'Odentas',
  reason: 'Accès obsolète',
  revokedBy: 'admin@odentas.fr',
  revocationDate: new Date().toLocaleString('fr-FR')
});

Avantages du système universel

1. Cohérence visuelle

• Un seul template garantit une apparence uniforme
• Design responsive automatique
• Couleurs cohérentes selon le type d'email

2. Maintenance simplifiée

• Un seul fichier à maintenir au lieu de 13+ templates
• Modifications centralisées
• Configuration type par type

3. Flexibilité

• Ajout facile de nouveaux types d'emails
• Variables dynamiques par type
• Système d'actions configurables

4. Compatibilité

• Fonctionne avec AWS SES
• HTML compatible avec tous les clients email
• Fallback texte automatique

Migration depuis l'ancien système

Étapes recommandées

1. Phase 1 ✅ - Système de contrats migré

   • sendContractNotifications
   • sendContractUpdateNotifications
   • sendContractCancellationNotifications

2. Phase 2 - Autres types d'emails

   • Remplacer les appels directs aux templates individuels
   • Utiliser les fonctions de migration disponibles

3. Phase 3 - Nettoyage (optionnel)

   • Supprimer les anciens templates après validation complète
   • Simplifier les imports

Remplacement des appels existants

// AVANT (ancien système)
await ses.sendEmail({
  Destination: { ToAddresses: [email] },
  Message: {
    Subject: { Data: subject },
    Body: { Html: { Data: htmlTemplate } }
  },
  Source: fromEmail
});

// APRÈS (système universel)
await sendUniversalEmail({
  to: email,
  type: 'contract-created',
  data: contractData
});

Configuration des types d'emails

Chaque type d'email peut être configuré dans emailTemplateService.ts :

'contract-created': {
  subject: 'Nouveau contrat CDDU créé',
  colors: {
    primary: '#059669',    // Vert
    primaryDark: '#047857',
    primaryLight: '#d1fae5'
  },
  title: 'Nouveau contrat',
  // ... autres configurations
}

Tests et validation

Le système a été testé avec :

• ✅ Build Next.js réussi
• ✅ Types TypeScript validés
• ✅ Configuration AWS SES compatible
• ✅ Templates HTML responsive

Support technique

Pour toute question ou problème avec le système d'email universel :

1. Vérifier la configuration du type d'email
2. Valider les données fournies
3. Contrôler les logs AWS SES
4. Tester avec un email de développement

---

Système créé pour unifier et simplifier la gestion des emails dans l'application de paie spectacle.