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

```typescript
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 :

```typescript
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

```typescript
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

```typescript
// 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` :

```typescript
'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.*