Système de Champs pour les Templates d'Email

Vue d'ensemble

Le système d'emailing UBSI utilise deux types de champs dans les templates Handlebars (.hbs) :

1. clientFields : Champs automatiquement remplis par le système
2. dynamicFields : Champs à fournir lors de l'envoi

1. ClientFields (Auto-remplis)

Définition

Les clientFields sont des champs standardisés et automatiquement remplis par le système à partir des données du client stockées dans la base de données.

Champs disponibles

Champ	Type	Description	Exemple
userName	string	Nom complet (prénom + nom)	"Jean Dupont"
prenom	string	Prénom du client	"Jean"
nom	string	Nom de famille	"Dupont"
civilite	string	Civilité (M, Mme, Mx)	"M"
adresseMail	string	Email du client	"jean.dupont@example.com"
telephone	string	Numéro de téléphone	"0612345678"
idClient	string	Identifiant unique	"CLI_ABC1234"
pointsFidelite	number	Points de fidélité	250
niveauFidelisation	string	Niveau (Standard, Premium, Platine)	"Premium"
currentYear	string	Année en cours	"2025"

Utilisation dans un template

<h1>Bonjour {{userName}} !</h1>
<p>Vous avez actuellement {{pointsFidelite}} points de fidélité.</p>
<p>Votre niveau : {{niveauFidelisation}}</p>
<footer>© {{currentYear}} UBSI</footer>

Validation

Le système rejette automatiquement tout template utilisant un clientField non standard (ex: {{pseudo}}, {{username}}).

Exemple dans les métadonnées du template

{{!--
subject: "Joyeux anniversaire — UBSI"
category: "Fidélisation"
clientFields:
  userName: "string"
  currentYear: "string"
dynamicFields:
  birthdayOfferLink: "string"
--}}

2. DynamicFields (Fournis manuellement)

Définition

Les dynamicFields sont des champs spécifiques à une campagne qui doivent être fournis lors de l'envoi de l'email via l'API.

Exemples de dynamicFields

• birthdayOfferLink : Lien vers l'offre anniversaire
• orderNumber : Numéro de commande
• orderDate : Date de la commande
• trackingLink : Lien de suivi de colis
• verificationLink : Lien de vérification d'email

Utilisation dans un template

<p>Votre commande n°{{orderNumber}} du {{orderDate}} a été confirmée.</p>
<a href='{{orderLink}}'>Voir ma commande</a>

Fournir les dynamicFields lors de l'envoi

curl -X POST "http://localhost:649/api/publique/mail/send" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "commande",
    "parametres": {
      "orderNumber": "CMD-12345",
      "orderDate": "15/01/2025",
      "orderTotal": "99.99€",
      "orderLink": "https://ubsi.fr/orders/12345",
      "idClients": ["CLI_ABC1234"]
    }
  }'

Validation

Le système valide que tous les dynamicFields requis par le template sont fournis, sinon une erreur est retournée :

{
  "message": "Les paramètres suivants ne sont pas définis dans le template: invalidParam. Variables dynamiques disponibles: orderNumber, orderDate, orderTotal, orderLink",
  "statusCode": 400
}

3. Architecture Technique

Backend

Constantes (backend/src/mail/mail-fields.constants.ts)

export const AVAILABLE_CLIENT_FIELDS = {
  userName: {
    type: 'string',
    description: 'Nom complet du client (prénom + nom)',
    example: 'Jean Dupont',
    autoFilled: true,
  },
  // ... autres champs
};

Auto-remplissage (backend/src/mail/mail.service.ts)

if (template.clientFields) {
  Object.keys(template.clientFields).forEach((field) => {
    if (field === 'userName') {
      autoFilledClientFields[field] = `${client.prenom} ${client.nom}`;
    } else if (field === 'currentYear') {
      autoFilledClientFields[field] = new Date().getFullYear().toString();
    }
    // ... autres champs
  });
}

Validation (backend/src/mail/mail-template-sync.service.ts)

if (metadata.clientFields) {
  const invalidClientFields: string[] = [];
  Object.keys(metadata.clientFields).forEach((fieldName) => {
    if (!isStandardClientField(fieldName)) {
      invalidClientFields.push(fieldName);
    }
  });

  if (invalidClientFields.length > 0) {
    throw new Error(
      `Les clientFields suivants ne sont pas standards: ${invalidClientFields.join(', ')}`
    );
  }
}

Frontend

Endpoint des champs disponibles

GET /api/privee/mail/templates/available-fields

Retourne la liste complète des clientFields avec leurs métadonnées.

Interface utilisateur

L'interface affiche :

• Un bouton déroulant "Voir les champs disponibles"
• La liste des clientFields avec badge "AUTO"
• Un avertissement sur les dynamicFields

4. Bonnes Pratiques

✅ À FAIRE

1. Utiliser les clientFields standards pour toutes les données client
2. Déclarer tous les dynamicFields dans les métadonnées du template
3. Fournir tous les dynamicFields requis lors de l'envoi
4. Synchroniser les templates après toute modification avec POST /api/privee/mail/templates/sync

❌ À NE PAS FAIRE

1. ❌ Créer des champs client custom (ex: {{pseudo}}, {{fullName}})
2. ❌ Mélanger clientFields et dynamicFields dans les paramètres d'envoi
3. ❌ Oublier de déclarer un dynamicField dans les métadonnées
4. ❌ Hardcoder des données qui devraient être des dynamicFields

5. Exemples Complets

Template Simple

{{!--
subject: "Bienvenue {{userName}}"
category: "Onboarding"
clientFields:
  userName: "string"
  currentYear: "string"
dynamicFields:
  loginLink: "string"
--}}
<html>
  <body>
    <h1>Bienvenue {{userName}} !</h1>
    <a href='{{loginLink}}'>Accéder à mon compte</a>
    <footer>© {{currentYear}} UBSI</footer>
  </body>
</html>

Envoi de la campagne

curl -X POST "http://localhost:649/api/publique/mail/send" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "welcome",
    "parametres": {
      "loginLink": "https://ubsi.fr/login?token=xyz",
      "filtres": {
        "niveauFidelisation": "Premium"
      }
    }
  }'

Résultat

• {{userName}} → "Jean Dupont" (auto-rempli)
• {{currentYear}} → "2025" (auto-rempli)
• {{loginLink}} → "https://ubsi.fr/login?token=xyz" (fourni)

6. Endpoints API

Endpoint	Méthode	Description
/api/privee/mail/templates/available-fields	GET	Liste des clientFields disponibles
/api/privee/mail/templates/sync	POST	Synchroniser les templates depuis le filesystem
/api/publique/mail/send	POST	Envoyer une campagne d'emails

7. Résumé

• clientFields = Auto-remplis, standardisés, validation stricte
• dynamicFields = Fournis manuellement, spécifiques à chaque campagne
• Un système qui garantit la cohérence et évite les erreurs de nommage