Skip to content

README.md

Latest commit

 

History

History
353 lines (218 loc) · 11.2 KB

README.md

File metadata and controls

353 lines (218 loc) · 11.2 KB

🚀 pass Culture PRO — App Front-End

Ce dossier /pro contient l’ensemble de la configuration et les sources de l'application Web du portail professionnel du pass Culture.

Sommaire

Pré-requis

WSL 2 (Windows uniquement)

Pour les utilisateurs de Windows, il est recommandé d'utiliser WSL 2 avec une distribution Linux (Ubuntu, par exemple) pour développer sur le projet.

Installer WSL 2

Git

Installer Git

Il est recommandé pour ce repository d’utiliser la configuration suivante :

# Configurer le nom de la branche par défaut
git config --global init.defaultBranch master

# Configurer le mode de pull par défaut à "rebase"
git config --global pull.rebase true

La convention des messages de commit suit la norme Conventional Commits.

Pour s’assurer que les messages de commit respectent cette convention, il est également conseillé d’installer Commitizen qui vous guidera dans la rédaction de messages de commit conformes à la convention.

Installer Commitizen (conseillé)

Node.js (via nvm)

Il est recommandé d'utiliser nvm pour installer et gérer la version de Node.js.

Installer nvm

Une fois nvm installé, on peut installer et utiliser la bonne version de Node.js :

nvm install 24.8

nvm use 24.8

# (Conseillé : pour utiliser la version 24.8 par défaut)
nvm alias default 24.8

Yarn

Afin d’uniformiser les outils utilisés, il est recommandé d’utiliser Yarn.

Actuellement, la version de Yarn utilisée sur le projet est la version dite « classic » 1.22.22.

Avec Node.js 20, pas besoin d'installer Yarn manuellement, il suffit d'activer corepack :

corepack enable

Ceci permettra d'utiliser automatiquement la bonne version de Yarn sur le projet.

Docker

Bien qu’il soit possible d’installer le backend et tous les autres services de façon manuelle sur sa machine, il est conseillé d’utiliser Docker pour démarrer plus rapidement.

Installer Docker Desktop

Installer le projet

Commencer par cloner le projet :

Vous aurez besoin d’une clé SSH pour cloner le projet. Consultez la documentation GitHub pour effectuer la procédure.

git clone git@github.com:pass-culture/pass-culture-main.git

cd pass-culture-main

La plupart des services backend sont gérés par des scripts automatisés, disponibles dans un script nommé pc (pour pass culture).

Afin d'avoir accès à ces scripts, il est conseillé de créer un lien symbolique vers le script pc à la racine du projet :

./pc symlink

Installez ensuite l’environnement local (nécessite que Docker Desktop soit lancé) :

pc install

Une fois l’environnement installé, démarrez le backend avec la commande suivante à la racine du projet :

pc start-backend

# ou si vous avez configuré le proxy :
pc start-proxy-backend

# ⚠️ Cela peut prendre plusieurs minutes …

Cela aura pour effet de builder et lancer les conteneurs Docker permettant de faire tourner les services nécessaires, notamment :

  • l'API backend (réponds sur le port :5001)
  • la base de données (réponds sur le port :5434)
  • le back-office (réponds sur le port :5002)

Tip

Si plus tard vous souhaitez redémarrer le back-end sans rebuilder les images Docker, vous pouvez utiliser le flag --fast :

pc start-backend --fast ou pc start-proxy-backend --fast

Lancer le front-end

Le front-end se trouve dans le sous-dossier /pro, dans lequel on retrouve la structure d’une application React.

Normalement, les dépendances ont déjà été installées avec le script pc, sinon on peut le faire manuellement avec yarn install.

Pour démarrer l’application front-end, il suffit de se placer dans le sous-dossier /pro et de lancer la commande yarn start :

cd pro

yarn start

Une fenêtre s’ouvre sur le port :3001 et affiche une page de connexion.

Sandbox

Pour générer des données locales (comptes utilisateurs, structures, etc.), on peut utiliser le script pc sandbox :

pc sandbox -n industrial

# ⚠️ Peut prendre plusieurs minutes …

Une fois les données générées, on peut se connecter au portail pro avec un compte d'exemple comme :

  • Adresse email : retention_structures@example.com
  • Mot de passe : user@AZERTY123

Développer

Conseils et recommandations pour développer sur le projet.

Configurer son éditeur

L’éditeur de code recommandé est VSCode.

Installer VSCode

Tip

Pour la partie Front-End, il est recommandé d’ouvrir le projet directement à la racine du sous-dossier /pro.

Extensions recommandées :

VSCode vous proposera d’installer automatiquement les extensions recommandées lorsque vous ouvrirez le projet dans /pro.

La liste est disponible dans le fichier .vscode/extensions.json.

Pour les devs qui n'utilisent PAS VSCode et qui ouvrent le projet à partir du dossier racine pass-culture-main dans leur IDE :

  • Biome (Linter JS/JSON/CSS/HTML pour le Frontend)
    • npm i -g @biomejs/biome ou brew install biome
    • Installer l'extension correspondant à ton IDE si dispo
    • Prendre garde à ce que ta version Biome globale soit la même que celle déclarée dans les dev-deps pro/package.json.

Les tests

Il faut cette fois installer l'extension vitest.explorer. On aura alors accès aux tests des fichiers *.spec.tsx dans l'onglet Testing.

On peut également utiliser la commande de launch Debug current spec test file. Lorsqu'on est dans un fichier *.spec.tsx, on peut lancer la commande depuis l'onglet Run and Debug et les tests du fichier seront exécutés.

Tests unitaires / d’intégration :

Les fichiers de tests sont disponibles à côté de chaque composant ou fichier TypeScript et se terminent par .spec.ts(x).

Pour les lancer, on utilise la commande suivante :

yarn test:unit

# Lance "vitest" avec la bonne configuration

Tests end-to-end :

Nous utilisons Playwright pour Les tests E2E. Ils sont disponibles dans le sous-dossier /pro/e2e.

Plus d'informations sur les tests E2E ici

Storybook

Les composants d'interface de l'application Pro sont regroupés dans un Storybook accessible en ligne.

Il est aussi possible de lancer le Storybook localement avec la commande suivante :

yarn storybook

# Réponds sur le port :6006

Adage

Nous intégrons une sous-route du portail Pro (/adage-iframe/) dans une iframe au sein d'ADAGE, la plateforme des établissements scolaires permettant de gérer leurs activités culturelles.

Il s’agit d’une application web pour les rédacteurs de projets scolaires, leur permettant de réserver des offres sur le pass Culture pour leurs élèves.

Accès à l’iframe ADAGE

# Ouvrir la console bash
pc bash

# Générer un token
flask generate_fake_adage_token

Il suffit ensuite de suivre l’URL générée accéder à l’app

Affichage d'offres en local

Comme le local est branché sur algolia de testing, les ids qui sont remontés d'algolia sont ceux de testing, et il n’est pas certain qu'on ait les mêmes en local.

Pour récupérer les ids de certaines offres en local, on peut utiliser un index local. Pour cela, il faut :

  • Créer un nouvel index sur la sandbox algolia : <votre_nom>-collective-offers

  • Créer un fichier .env.development.local dans le dossier pro/src et renseigner le nom de l’index dans la variable VITE_ALGOLIA_COLLECTIVE_OFFERS_INDEX

  • Créer un fichier .env.local.secret dans le dossier api et renseigner les variables suivantes :

ALGOLIA_COLLECTIVE_OFFER_TEMPLATES_INDEX_NAME=<votre_nom>-collective-offers
ALGOLIA_TRIGGER_INDEXATION=1
ALGOLIA_API_KEY=<demander l’api key>
ALGOLIA_APPLICATION_ID=testingHXXTDUE7H0
SEARCH_BACKEND=pcapi.core.search.backends.algolia.AlgoliaBackend
  • Ouvrir la console bash
pc bash
  • Réindexer vos offres collectives
flask reindex_all_collective_offers

Standards de code et d’architecture

La documentation est intégrée au projet, aux travers de fichiers README à la racine des dossiers principaux.

Vous trouverez une documentation générale ainsi que des liens vers les différents README en suivant ce lien :

Dette technique

Nous utilisons SonarCloud pour monitorer la dette technique.

Annexes

Vous retrouverez dans le fichier pro/package.json des scripts Yarn utiles pour le développement.

Générer des templates de composants React et utilitaires avec Templatron

Lister les templates disponibles :

npx templatron --list

Créer un nouveau composant React :

npx templatron component MonNouveauComposant

Créer un fichier utilitaire (ex: fonction/classe JS) :

npx templatron util maFonction

Note

Les fichiers de template sont consultables dans le dossier .templatron/

Pour plus de détails sur le fonctionnement des templates, voir la documentation de Templatron.

Linter les fichiers TypeScript

yarn lint:js

Identifier du code mort

yarn lint:dead-code

Identifier des problèmes de types TS

yarn tsc -b