# 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)
```bash
# 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
```bash
# 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
```bash
# 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` :
```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