|
|
@@ -0,0 +1,142 @@
|
|
|
+# Mailer
|
|
|
+
|
|
|
+## Principes générales et fonctionnement actuel
|
|
|
+
|
|
|
+### Modèle de base (AbstractMailerModel)
|
|
|
+
|
|
|
+ Ce modèle sert de classe de base pour tous les modèles d'emails spécifiques.
|
|
|
+ Champs inclus:
|
|
|
+ senderId: l'identifiant de l'expéditeur de l'email.
|
|
|
+ notify: un booléen pour déterminer si une notification doit être envoyée suite à l'email.
|
|
|
+
|
|
|
+ Ils contiennent toutes les données nécessaires pour construire un email (destinataire, le sujet de l'email, le contenu)
|
|
|
+
|
|
|
+ Par exemple, SubdomainChangeModel contient des informations
|
|
|
+ spécifiques nécessaires pour informer un utilisateur d'un changement de sous-domaine
|
|
|
+ facilitant le stockage des données mais aussi la standardisation de l'envoi d'emails avec une same interface pour les builders.
|
|
|
+
|
|
|
+### Modèle spécifique (SubdomainChangeModel)
|
|
|
+
|
|
|
+ Ce modèle étend AbstractMailerModel et ajoute des champs spécifiques au contexte d'un changement de sous-domaine.
|
|
|
+ Champs en plus:
|
|
|
+ organizationId: identifiant de l'organisation concernée.
|
|
|
+ subdomainId: identifiant du sous-domaine modifié.
|
|
|
+ url: URL associée au sous-domaine après modification.
|
|
|
+
|
|
|
+### Builders
|
|
|
+
|
|
|
+ Les Builders sont des composants qui prennent les modèles préparés (comme SubdomainChangeModel) et les transforment en objets Email.
|
|
|
+ Ils utilisent des services de rendu comme Twig pour générer le contenu de l'email basé sur des templates dynamiques, et configurent les objets Email en y ajoutant les destinataires, les sujets, et autres données nécessaires.
|
|
|
+ Ces objets sont ensuite prêts à être envoyés par le service de messagerie
|
|
|
+
|
|
|
+### Builder spécifique (OnSubdomainChangeMailBuilder)
|
|
|
+
|
|
|
+ Ce builder est spécialement conçu pour construire un email au changement de sous domaine.
|
|
|
+ Il est appelé après que les modifications dans la gestion des sous-domaines soient effectuées par le service de gestion des sous-domaines (SubdomainService). Voici son processus de fonctionnement :
|
|
|
+
|
|
|
+ - Support de modèle : détermine si le modèle de données (MailerModelInterface) passé correspond à une instance de SubdomainChangeModel.
|
|
|
+ - Construction de l'email : il les informations nécessaires de la base de données avec l'em (sous-domaine, organisation, auteur de la modification) et prépare le contenu de l'email basé sur un template.
|
|
|
+ - Il définit l'expéditeur (adresse email par défaut pour les emails système) et ajoute le destinataire principal (admin de l'organisation).
|
|
|
+ - Rendu de l'email : Utilise des templates pour générer le contenu de l'email basé sur les informations fournies.
|
|
|
+
|
|
|
+### Handlers
|
|
|
+
|
|
|
+ Chaque fois que l'action d'envoi de mail est déclenché (via MailerCommand), le handlers est appelé et orchestre le processus d'envioe des emails à l'aide des builders
|
|
|
+ Le handler extrait le modèle d'email (MailerModel) de la commande. Ce modèle contient des détails tels que le type d'email (système ou non), l'identifiant de l'expéditeur, et d'autres informations spécifiques nécessaires pour l'email.
|
|
|
+ Le handler appelle ensuite un builder approprié. Les builders sont des composants spécialisés chargés de construire l'objet email à partir des données fournies par le modèle
|
|
|
+ Par exemple, si l'email concerne un changement de sous-domaine, un SubdomainChangeMailBuilder serait utilisé pour construire l'email en utilisant des templates et des données spécifiques à ce contexte.
|
|
|
+
|
|
|
+### Le cas SubdomainService - Service de Gestion des Sous-domaines (SubdomainService)
|
|
|
+
|
|
|
+ Ce service orchestre la logistique de création, modification et activation de sous-domaines pour les organisations, et utilise le système de messagerie pour notifier les changements importants :
|
|
|
+ Validation et enregistrement des noms de sous-domaines
|
|
|
+ Activation et mise à jour : Gère l'activation des sous-domaines et la synchronisation avec les systèmes externes avec typo3
|
|
|
+ Notification par email : Après un changement significatif comme l'activation d'un nouveau sous-domaine, le service construit le modèle de données pour l'email (en utilisant getMailModel) et envoie une commande (MailerCommand) au système de messagerie pour notifier l'organisation concernée.
|
|
|
+
|
|
|
+ Après la construction du modèle de l'email par SubdomainService, une MailerCommand est créée et envoyée au système de messagerie de Symfony. Cette commande est traitée par MailerHandler, qui utilise le service Mailer pour envoyer l'email préparé par le builder OnSubdomainChangeMailBuilder.
|
|
|
+
|
|
|
+ Validation et enregistrement : Il valide les noms de sous-domaines proposés contre des critères spécifiques (validation regex, vérification des sous-domaines réservés) et gère l'enregistrement de nouveaux sous-domaines dans la base de données.
|
|
|
+ Activation et mise à jour : Gère l'activation des sous-domaines et la synchronisation avec les systèmes externes (par exemple, mise à jour d'un site Typo3).
|
|
|
+ Notification par email : Après un changement significatif comme l'activation d'un nouveau sous-domaine, le service construit le modèle de données pour l'email (en utilisant getMailModel) et envoie une commande (MailerCommand) au système de messagerie pour notifier l'organisation concernée.
|
|
|
+
|
|
|
+## Flux général
|
|
|
+
|
|
|
+ +-----------------------------+ +-------------------------------+
|
|
|
+ | Action: Changement de | | Crée |
|
|
|
+ | sous-domaine +--------------->+ MailerCommand avec |
|
|
|
+ | (par utilisateur ou script)| | SubdomainChangeModel |
|
|
|
+ +-----------------------------+ +---------------+---------------+
|
|
|
+ |
|
|
|
+ v
|
|
|
+ +-------------+-------------+
|
|
|
+ | MailerHandler reçoit la |
|
|
|
+ | commande |
|
|
|
+ +-------------+-------------+
|
|
|
+ |
|
|
|
+ v
|
|
|
+ +--------------+--------------+
|
|
|
+ | Extraction du modèle |
|
|
|
+ | SubdomainChangeModel |
|
|
|
+ +--------------+--------------+
|
|
|
+ |
|
|
|
+ v
|
|
|
+ +---------------+---------------+
|
|
|
+ | Utilisation du builder |
|
|
|
+ | OnSubdomainChangeMailBuilder |
|
|
|
+ +---------------+---------------+
|
|
|
+ |
|
|
|
+ v
|
|
|
+ +----------------+----------------+
|
|
|
+ | Construction de l'email: |
|
|
|
+ | - Génération du contenu via |
|
|
|
+ | Twig |
|
|
|
+ | - Configuration des |
|
|
|
+ | destinataires |
|
|
|
+ +----------------+----------------+
|
|
|
+ |
|
|
|
+ v
|
|
|
+ +----------------+----------------+
|
|
|
+ | Envoi de l'email via le |
|
|
|
+ | service Mailer |
|
|
|
+ +----------------+----------------+
|
|
|
+ |
|
|
|
+ v
|
|
|
+ +----------------+----------------+
|
|
|
+ | Notification post-envoi (si |
|
|
|
+ | requis par getNotify()) |
|
|
|
+ +--------------------------------+
|
|
|
+
|
|
|
+### Déclenchement de l'action : Tout commence généralement par un événement dans votre application qui nécessite l'envoi d'un email. Cela pourrait être une action utilisateur, un événement programmé, etc
|
|
|
+
|
|
|
+ Commande d'envoi d'email : Un objet MailerCommand est créé et transmis au système de messagerie de Symfony. Cette commande contient les détails nécessaires pour construire et envoyer l'email, y compris l'identité du destinataire, le contenu de l'email, et d'autres métadonnées pertinentes.
|
|
|
+
|
|
|
+### Traitement de la commande par MailerHandler
|
|
|
+
|
|
|
+ L'objet MailerHandler est invoqué par le système de messagerie de Symfony en réponse à la réception d'un MailerCommand.
|
|
|
+ MailerHandler extrait le modèle d'email du MailerCommand et vérifie si l'email est un email système à travers isSystemEmail().
|
|
|
+ Il appelle ensuite la méthode main de la classe Mailer pour effectuer l'envoi de l'email.
|
|
|
+
|
|
|
+### Construction et envoi de l'email par Mailer
|
|
|
+
|
|
|
+ La méthode main de Mailer délègue la création de l'objet email spécifique de Symfony à createSymfonyEmail. Cette fonction utilise les informations fournies pour configurer les headers de l'email, définir l'expéditeur, etc.
|
|
|
+ Si l'email est un email système, une adresse générique est utilisée. Sinon, les informations spécifiques de l'email sont utilisées pour configurer l'adresse de réponse et d'autres paramètres.
|
|
|
+ Après la création de l'email, Mailer gère l'envoi de cet email via SymfonyMailer et effectue toutes les opérations de suivi nécessaires, comme la mise à jour des statuts et l'envoi de rapports.
|
|
|
+
|
|
|
+### Notification post-envoi (si applicable)
|
|
|
+
|
|
|
+ Après l'envoi de l'email, si le modèle indique qu'une notification doit être envoyée (via getNotify()), MailerHandler utilise le service Notifier pour notifier l'utilisateur ou le système concerné du succès ou de l'échec de l'envoi.
|
|
|
+
|
|
|
+ MailerHandler agit comme un coordinateur qui répond aux événements et commandes d'envoi d'email, tandis que Mailer est celui qui construit et envoie les emails, assurant que chaque aspect de l'email est correctement configuré et envoyé.
|
|
|
+
|
|
|
+## Problématiques
|
|
|
+
|
|
|
+ Dépendance à senderId: Nécessité de spécifier un expéditeur pour chaque email, même pour les emails systèmes où un expéditeur par défaut serait plus approprié.
|
|
|
+ Redondance de isSystemEmail: Stockage de l'information concernant la nature système de l'email dans chaque modèle d'email, ce qui pourrait être géré plus efficacement.
|
|
|
+ Problematique de l'abstract message : https://gitlab.2iopenservice.com/opentalent/ap2i/-/blob/develop/src/Entity/Message/Email.php?ref_type=heads#L37 - https://gitlab.2iopenservice.com/opentalent/ap2i/-/blob/develop/src/Service/Mailer/Builder/AbstractBuilder.php?ref_type=heads#L44
|
|
|
+
|
|
|
+- entité à modifier
|
|
|
+- le builder attribue un auteur que s'il y en a un
|
|
|
+- condition ternaire : isSenderId ? on retrouve l'email : email systeme : sinon on renvoie une erreur
|
|
|
+- AbstractBuilder a modifer
|
|
|
+
|
|
|
+/!\ le mailer doit etre totalement agnostique ; il faut trouver le bon endroit pour gérer l'origine du mail
|
opentalent