From a7b3baa89ef64d48eb230b428e8ec3ee696407ea Mon Sep 17 00:00:00 2001 From: Adrien Burgun Date: Mon, 6 Feb 2023 23:08:31 +0100 Subject: [PATCH] :sparkles: Finish email section --- figures/mailingnest-2.dot | 72 ++++++++++++++++++++++++++++++++++ figures/mailingnest.dot | 2 +- references.bib | 7 ++++ report.tex | 82 ++++++++++++++++++++++++++++++++++++++- 4 files changed, 160 insertions(+), 3 deletions(-) create mode 100644 figures/mailingnest-2.dot diff --git a/figures/mailingnest-2.dot b/figures/mailingnest-2.dot new file mode 100644 index 0000000..7e3e05d --- /dev/null +++ b/figures/mailingnest-2.dot @@ -0,0 +1,72 @@ +digraph nestjs1 { + rankdir=LR; + + subgraph cluster_generator { + { + rank=same + PrintGenerator + TemplateGenerator + } + PrintGenerator -> TemplateGenerator + + label="handlebars-generator" + style="filled" + color="#e0e0f0" + } + + subgraph cluster_mailing_nest { + subgraph cluster_generatormodule { + GeneratorService -> PrintGenerator + label="GeneratorModule" + style="dotted" + } + + subgraph cluster_SenderModule { + { + rank=same + SenderService + AmazonSenderService [color=dimgrey,fontcolor=dimgrey] + } + SenderService -> AmazonSenderService [color=dimgrey] + SenderService -> GeneratorService + label="SenderModule" + style="dotted" + } + + label="mailing-nest" + style="filled" + color="#e0f0e0" + } + + subgraph cluster_mint { + subgraph cluster_MintMailingModule { + MintMailingService -> SenderService + + label="MintMailingModule" + style="dotted" + } + + subgraph cluster_OrderService { + { + rank=same + OrderService + OrderController [shape=rectangle] + } + OrderController -> OrderService + OrderService -> MintMailingService + + style="dotted" + } + + subgraph cluster_Rest { + Rest [label="..."] + Rest -> MintMailingService + + style="dotted" + } + + label="mint-service" + style="filled" + color="#f0e0e0" + } +} diff --git a/figures/mailingnest.dot b/figures/mailingnest.dot index 01c385a..367ede7 100644 --- a/figures/mailingnest.dot +++ b/figures/mailingnest.dot @@ -39,7 +39,7 @@ digraph nestjs1 { SenderService AmazonSenderService [color=dimgrey,fontcolor=dimgrey] } - SenderService -> AmazonSenderService + SenderService -> AmazonSenderService [color=dimgrey] label="SenderModule" style="dotted" } diff --git a/references.bib b/references.bib index 41b245a..cff55e8 100644 --- a/references.bib +++ b/references.bib @@ -183,3 +183,10 @@ howpublished="\url{https://mjml.io/}", note="[En ligne; accédé le 06 Février 2023]" } + +@article{mdncontentcategories, + title={Content Categories}, + author={Mozilla Developer Network}, + howpublished="\url{https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories}", + note="[En ligne; accédé le 06 Février 2023]" +} diff --git a/report.tex b/report.tex index 6ee66c4..871afc8 100644 --- a/report.tex +++ b/report.tex @@ -93,7 +93,11 @@ \IfFontExistsTF{Source Sans Pro SemiBold}{ \newfontfamily{\SourceSansSB}[UprightFont={* SemiBold}]{Source Sans Pro} }{ - \newfontfamily{\SourceSansSB}[UprightFont={* Semi-Bold}]{Source Sans Pro} + \IfFontExistsTF{Source Sans Pro Semi-Bold}{ + \newfontfamily{\SourceSansSB}[UprightFont={* Semi-Bold}]{Source Sans Pro} + }{ + \newfontfamily{\SourceSansSB}[UprightFont={* Semibold}]{Source Sans Pro} + } } \setmainfont{Source Sans Pro} % \newfontfamily{\ossb}[UprightFont={* Semibold}]{Open Sans} @@ -423,6 +427,8 @@ et propose de nombreux outils pour gérer les requêtes, les bases de données e % Agile, poker planning % Backlog, recettes, versioning +\subsection{Planning} + \section{Travail réalisé sur Mint Service} Mint Service est une application construite avec \entity{NestJS}. @@ -599,13 +605,85 @@ J'ai choisi la librairie \entity{MJML} \cite{mjml}, qui utilise un langage resse \inputfig{email} -\subsection{Refactor du système de mails} +\subsection{Rétrospective sur le système d'envoi de mails} % - [ ] parler des désavantages de cette méthode % - [ ] parler de ce qu'on prévoyait de faire % - [ ] parler de comment on l'a fait (pour showcase l'avantage du monorepo), et des étapes prises % - [ ] parler des améliorations futures qui pourront être faites % (ajouter plus de providers, simplifier la logique pour choisir les providers, react.email, svelte, etc.) +% - [ ] Comparer la maintenabilité + +Après avoir fini l'implémentation du système de mail, j'ai pu l'observer alors qu'il est passé par la vérification de qualité, +des déploiements et recettes sur un serveur local, et enfin des déploiements chez les clients. + +Les deux librairies ont vu peu de changements, et ont fonctionné comme voulu. +L'organisation du code au sein de \entity{Mint Service} a pris deux essais pour arriver à un format satisfaisant: +le premier essai plaçait l'envoi des mails dans un service dédié à la gestion des utilisateurs (\texttt{GuestModule}), +mais il s'averrait qu'il fallait assez de code pour préparer les informations des mails qu'il était préférable de déplacer la logique d'envoi des mails dans un module à part, \texttt{MintMailingModule}. + +Malgré \entity{MJML} et le système de composants, écrire des templates d'emails reste plus compliqué à écrire que du code React: + +\begin{itemize} + \item La différence de format entre les templates Handlebars/MJML et les composants React fait qu'il est difficile d'appliquer les intuitions valables pour le React lorsqu'on écrit ou réécrit des templates d'emails. + \\ + Ceci est en grande partie dû au fonctionnement de MJML, + qui requiet une structure stricte dans le code (\texttt{mj-body} $\rightarrow$ \texttt{mj-section} $\rightarrow$ \texttt{mj-column} $\rightarrow$ texte). + \\ + HTML lui a une structure plus flexible, + permettant d'imbriquer la pluspart des éléments disponibles dans un ordre arbitraire. \cite{mdncontentcategories} + + \item Le choix de faire le rendu final des templates via les templates d'\entity{Amazon SES} rend l'écriture des emails plus compliquée + (il faut mixer ensemble deux différents formats handlebars, l'un étant interprété de notre côté, et l'autre étant interprété du côté d'\entityb{Amazon SES} \figref{emailsrchbs}). + \\ + Ce choix rend aussi le débuggage de toute erreur lors du deuxième rendu très compliqué, + car le seul moyen pour accéder aux erreurs d'envoi de mails sur \entityb{Amason SES} est de mettre en place un système + de transfert de messages, puis de l'activer en envoyant les mails avec un paramètre précis. +\end{itemize} + +Pour palier à la deuxième difficulté, j'ai décidé vers la fin de mon stage de modifier l'implémentation du système d'envoi de mails, +afin de faire l'entièreté du rendu de notre côté, et d'uniquement utiliser \entity{Amazon SES} pour l'envoi pur des mails. + +J'avais également comme but secondaire de rendre ce système plus robuste, +en permettant notamment l'insertion de code pour vérifier la validité des données insérées dans les emails lorsqu'on est dans un environnement de développement. + +Les modifications ont été faites dans l'ordre suivant, qui permettait de progressivement appliquer les changements nécessaires: + +\begin{enumerate} + \item Suppression de la transformation des balises secondaires (\texttt{[[} et \texttt{]]}) et des options associées + \item Marquage de différents types comme dépréciés, et ajout de types pour l'envoi pur d'emails + \item Dépréciation des méthodes d'envoi d'email via les templates SES (\texttt{sendTemplatedEmail}), et ajout des méthodes pour l'envoi pur d'emails (\texttt{sendEmail}) + \item Modification des templates pour ne plus utiliser les balises secondaires + \item Modification de l'application de prévisionage des emails pour utiliser le nouveau format des informations substituées dans les mails + \item Modification de \entity{Mint Service} pour utiliser \texttt{sendEmail} au lieu de \texttt{sendTemplatedEmail} + \item Suppression de \texttt{UploadModule} et de \texttt{sendTemplatedEmail} + \item Suppression des types inutilisés +\end{enumerate} + +À la suite de ces modifications, les emails s'affichent de la même manière qu'avant, +et le système d'envoi de mails est désormais plus simple à utiliser +et plus simple à étendre avec différents services d'envoi de mail. + +Je n'ai pas pu implémenter le système de validation des données, par soucis de difficulté d'implémentation: +il aurait fallu étendre le système de chargement de composants pour également charger du code Javascript, +et transformer le format des données utilisé par Handlebars en un format facilement vérifiable. +\\ +Il est par contre maintenant possible d'écrire dans \entityb{Mint Service} des tests pour s'assurer que la logique de transformation des données reste compatible avec les emails. + +À la suite de cette modification, +je pense qu'il est encore possible d'améliorer de différentes manières ce système d'envoi de mails: + +\begin{itemize} + \item En ajoutant plus de tests automatisés dans le système, notamment des tests d'intégration + \item En rendant les différents modules plus simples d'utilisation + \item En permettant d'utiliser une syntaxe plus proche de celle de React pour appeler des composants (\texttt{} au lieu de \texttt{\{\{>Composant\}\}}) + \item En utilisant un système comme \href{https://react.email/}{React Email} ou \href{https://astro.build/}{Astro} pour écrire les templates en Javascript, ce qui permetterait aussi de faire de la vérification des données et des types. +\end{itemize} + +\begin{figure}[H] + \includegraphics[width=\textwidth]{mailingnest-2} + \caption{Organisation finale du système d'envoi de mail dans Mint-Service} +\end{figure} \section{Travail sur Mood TV}