ClientGNG SDK

Getting Started

Bienvenue dans le SDK admin!

Le SDK qu'on appelle "admin" est un peu le coeur de la solution ecommerce d'Addio. Il est la seule dépendance commune à tous les autres projets du ecomm, et est installé comme dépendance dans :

• Les firebase functions gng-tb-firebase-functions
• Le SDK front gng-ecomm-sdk, rattaché à tous les sites web des clients du ecomm
• Le dashboard gng-ecomm-dash

Il est séparé en quatre grandes sections :

Les interfaces

Dossier src/Interfaces/ Contiennent toutes les interfaces de données qui nous servent de types pour la donnée enregistrée en BD. C'est ce qui nous permet de typer de façon pertinente les différents objets que nous avons à traiter à travers le ecommerce. Bien qu'il peut exister des interfaces pour un peu n'importe quel objet de données, on crée toujours au minimum une interface par classe.

Dans certains fichiers d'interface, on retrouvera aussi des fonctions ou des objets correspondant aux valeurs "par défault" de l'interface, permettant de construire des objets vides au besoin. Lorsqu'une interface contient des interfaces ou des enums secondaires, qui ne sont pas réutilisés par d'autres, ils se trouveront aussi dans le même fichier.

Les classes

Dossier src/lib/ Contient un fichier/dossier par collection en base de données. Nous utilisons la méthode orientée objet pour instancier les entrées de la base de donnée selon leur collection (une classe par collection). Chaque classe a sa propre interface pour son type, et peut extend une classe générale.

Ces fichiers contiennent les fonctions CRUD de base pour la classe, ainsi que d'autres fonctions spécifiques à la classe, qui font les transactions avec la base de données.

Les utilitaires

Dossier src/utils/ Contient plusieurs fonctions utilitaires, regroupées par "thème", qui sont utilisées dans plusieurs endroits/projets différents. La règle habituelle, c'est que si ça peut être utile à plus d'un contexte, on l'ajoute dans les utilitaires du SDK-admin. Par contre, il y a beaucoup de fonctions qui sont dédoublées en ce moment (il y a un ménage à faire!), donc simplement porter une attention particulière lorsque vous importez des utils du SDK-admin. Aussi, si vous avez besoin d'une fonction pour quelque chose, pourquoi ne pas vérifier avant si elle existe déjà dans les utils du SDK-admin!

Les autres dossiers

Dossier src/rules/ Pour les règles d'affaire spécifiques à certains clients du ecomm. En ce moment, utilisé principalement pour Groupe Richer!

Dossier src/services/ Nouveau dossier qui contient toute la logique centralisée pour le traitement des données. Permet entre autre de switch entre différentes technologies de base de données, tout en s'assurant de toujours recevoir un modèle de donnée uniforme.

Dossier src/constantes/ Semble contenir que des enums et interfaces pour MongoDB, à transférer ailleurs?

Dossier src/test/ Contient une liste de tests utilitaires, qui sont exécutés au build du projet. Utilisent Mocha et Chaï pour les tests.

IMPORTANT - Depuis les modifications pour la gestion des secrets

Il est maintenant important que, autant dans le dash que dans les firebase functions, les variables d'environnement NEXT_PUBLIC_SERVICE_DATABASE_TOKEN et NEXT_PUBLIC_SERVICE_DATABASE_URL soient définies dans le .env à partir de zoho vault.

Les branches

Le SDK admin ne contient qu'une seule branche principale, soit la branche master, puisque le SDK admin est une dépendance publiée, et on veut toujours publier à partir d'une même la branche pour avoir les versions les plus à jour.

Lorsqu'on souhaite partir une nouvelle branche pour développer, toujours partir de master :

  git checkout master
  git pull
  git checkout -b master-[num_de_tache/ticket_ici]
  yarn

Faire les modifications, et ensuite

  git add .
  git commit -m "résumé de la modification"
  git push --set-upstream origin master-GR3-T67
  // et juste git push pour les fois subséquentes

Le merge avec la branche master se fera via une pull request dans GitHub.

Tests et développement

Pour tester les modifications apportées dans le SDK-admin, ou pour voir des logs ajoutés, cela dépend du projet qui a le SDK admin en dépendance. Par contre, dans tous les cas, il faut s'assurer de toujours faire yarn build après avoir apporté des modifications dans le sSDK-admin, pour qu'elles soient compilées en local et appliquées dans le projet rattaché.

Dans des fonctions appelées par le gng-ecomm-dash :

On peut lier le sdk-admin en local directement dans le dashboard afin de voir les modifiactions en temps réel dans la version locale du dashboard. Voir la procédure exacte dans le README du dashboard. Les logs apparaitront alors dans la console du navigateur, sur la version locale du dashboard.

Dans des fonctions appelées par le gng-ecomm-sdk ou un des sites front :

On doit lier le SDK-admin en local dans le SDK-front (gng-ecomm-sdk), puis lier le SDK-front dans le site souhaité. Voir la procédure exacte dans le README du SDK-front. Les logs apparaitront alors dans la console du navigateur, sur la version locale du site.

Dans des fonctions appelées par les gng-tb-firebase-functions :

On ne peut PAS lier le SDK-admin en local dans ce cas là, puisque les firebase functions ne peuvent pas rouler en local. Il faudra alors créer et publier un canary pour le SDK-admin, et mettre à jour la dépendances dans les firebase functions pour pouvoir voir la modification. Les logs dans les firebase se trouveront dans la console des cloud functions de Firebase directement (voir le README des firebase functions pour les détails).

Publication de versions stables et de canary

Le SDK-admin est une dépendance publiée sur NPM, puis importée dans les projets où elle est nécessaire. On doit donc toujours publier une nouvelle version lorsqu'on veut mettre à jour le SDK sur l'une des branches d'un autre projet. La publication se fait de façon manuelle (n'est pas automatique au déploiement).

Pour faire une publication du SDK, il faut d'abord s'assurer qu'on soit connecté à NPM, et qu'on a les accès nécessaires pour publier le package. Pour vérifier si vous êtes connectés, faites la commande npm whoami dans le terminal, ce qui vous donnera votre compte si connecté.

Une fois connecté, assurez vous d'être dans un terminal bash (surtout important pour les utilisateurs de PC), puis faites les commandes suivantes dans le terminal :

  yarn
  yarn build
  yarn pub

Suivez les indications dans le terminal pour publier votre version. Si vous vous posez la question à savoir si vous devez créer une version stable ou un canary :

Quand publier un canary

Un canary est une version temporaire du SDK-admin, utilisée soit pour des tests lorsqu'on ne peut pas tester en liant le SDK localement, ou encore, lorsqu'on développe sur des branches parallèles qui doivent être maintenue à long terme avant d'être ré-intégrées avec la branche principale.

Lorsqu'on se trouve sur une branche secondaire du SDK-admin (autre que master), vous n'aurez que le choix de créer un canary en faisant yarn pub. La règle générale, c'est qu'il ne devrait jamais y avoir de canary sur la branche master, ou sur des branches en production dans les différents projets!

Lorsqu'on génère un canary, on le fait en ajoutant -canary + -1, ou le 1 est incrémenté à chaque nouveau canary. Si la version stable de laquelle vous partez est la version 1.0.0, le canary qu'on vous proposera sera alors 1.0.0-canary-1. Ou encore, si vous partez de la version 1.0.0-canary-45, on vous proposera 1.0.0-canary-46.

ATTENTION - Il ne peut y avoir qu'un seul canary par itération (donc un seul canary-46 par version stable, par exemple). Ce que cela veut dire, c'est qu'on doit toujours s'assurer d'être à jour avec la branche principale de développement lorsqu'on a l'intention de créer un nouveau canary, pour être synchronisé avec les versions actuellement déployées.

Par contre, il est possible que deux branches parallèles aient besoin de canary en même temps. Dans ce temps là, la commande yarn pub s'occupera de vérifier si la version que vous tentez de créer existe déjà. Si oui, elle affichera un message en console, et passera au canary suivant, jusqu'à ce qu'il tombe sur un canary disponible. Si jamais vous voyez que la logique roule depuis un moment, et que votre canary s'incrémente à l'infini, c'est probablement que vous n'êtes pas à jour!

Quand publier une version stable

On publie une version stable du SDK-admin SEULEMENT à partir de la branche master. Et seulement lorsqu'on est prêt à ce que nos modifiactions soient disponibles à d'autres projets que celui où nous travaillons présentement.

La version stable du SDK-admin s'incrémentera automatiquement elle aussi avec la commande yarn pub, en ajoutant 1 au troisième élément de la version ("patch release"). Ex. Si la version courrante est 1.0.0, la version qui vous sera proposée sera 1.0.1. Si jamais vos modifications sont plus de l'ordre de la "minor relase" ou du "major release", vous devrez utiliser la commande yarn publish plutôt, et entrer votre version manuellement. Nous recommandons que cela soit fait en ayant consulté les autres membres de l'équipe avant!

Ajout du SDK admin dans d'autres projets

Après avoir publié votre nouvelle version du SDK-admin, pour le mettre à jour dans les projets :

• Pour mettre à jour avec la version stable la plus récente :

   yarn update-sdk

• Pour mettre à jour avec le canary le plus récent :

   yarn update-canary

Dans les deux cas, cela ira chercher la version la plus récente de la dépendance, et l'ajoutera au package.json du projet, en y préfixant le symbole ^. Le ^ veut dire que cela ira toujours chercher la plus récente version lorsqu'un build est effectué. Par exemple, si dans le package.json on voit

"gng-ecomm-admin-sdk": "^1.0.3",

mais qu'une version 1.0.4 a été publiée depuis, au prochain yarn, cela téléchargera la version 1.0.4 du package, sans changer ce qui affiche dans le package.json. Pour savoir la version réelle du package qui est installée, vérifier dans le yarn.lock.

Notre NPM a été configuré pour que, si c'est un canary qui est installé en ce moment, on va seulement chercher les canary les plus récents, et idem pour les versions stables. Par contre, cela peut évidemment causer des problèmes avec le développement, si deux canary coexistent par exemple.

Pour éviter cela, lorsque vous voulez forcer la version du sdk-admin à télécharger, aller simplement retirer le ^ dans le package.json devant la version. Sauvegardez le fichier, puis refaites la commande yarn dans le terminal, ce qui installera une version "figée" de la dépendance. Règle générale, pour les version stables, on laisse toujours le ^ devant la version. Donc c'est surtout une manipulation qui est faite avec les canary.

Tests unitaires

Quelques tests unitaires existent déjà pour certaines classes et utilitaires du SDK-admin. Nous utilisons Mocha et Chai pour construire ces tests. Ils peuvent être déclanchés localement en utilisant les différentes commandes énoncées dans le package.json :

• yarn class-tests : Déclenche les tests trouvés dans les classes (dossier src/lib)
• yarn local-tests : Déclenche les tests trouvés dans le dossier courrant où vous êtes (naviger dans le bon dossier via le terminal avant)
• yarn rules-gr-tests : Déclenche les tests au niveau des règles d'affaire de GR (dossier src/rules/GR/utils)
• yarn test : Déclenche les test du dossier src/test, avec affichage réduit des résultats en console
• yarn test:with-spec-reporter : Déclenche les test du dossier src/test, avec affichage détaillé des résultats en console.

Documentation générée automatiquement

Pour le SDK admin, nous tentons d'utiliser le plus possible la documentation en début de fonctions avec la nomenclature jsdoc. Cela nous permet non seulement de garder une meilleur trace du but des fonctions, des propriétés reçues et de la valeur retournée, mais aussi de générer de la documentation "papier" à partir de ces entêtes.

Pour générer la doc, faire la commande suivante dans le terminal :

yarn build:doc

NOTE - Si jamais des erreurs de type sont trouvées, elles afficheront en console, et vous devrez les corriger pour que le document se produise.

Le fichier généré se trouve à la racine du projet : addio-sdk-doc.md