Onboarding du Nouveau Développeur Marketplace

Bienvenue dans l’équipe de développement de la Marketplace ! Ce guide d’onboarding complet est conçu pour vous aider à installer, configurer et lancer l’ensemble de notre écosystème sur votre machine locale en quelques étapes simples.

💻 1. Prérequis Système

Avant de commencer l’installation, assurez-vous que votre environnement local dispose des outils suivants :

Node.js (version 18 ou supérieure) : Nous recommandons d’utiliser la version LTS (v20+). Vous pouvez vérifier votre version actuelle avec node -v.
npm (version 10 ou supérieure) : Requis pour la gestion unifiée des espaces de travail (npm workspaces).
Docker Desktop : Essentiel pour faire tourner notre instance PostgreSQL locale de manière isolée sans installation manuelle.
pgAdmin ou Client SQL (DBeaver, TablePlus, etc.) : Facultatif mais fortement recommandé pour interroger directement notre base de données locale.

📥 2. Installation Initiale

Notre projet est structuré en Monorepo géré par Turborepo. Pour que les dépendances soient correctement partagées entre nos applications, vous devez uniquement installer les paquets depuis la racine.

Exécutez les commandes suivantes dans votre terminal :


# 1. Cloner le dépôt
git clone https://gitlab.com/ernestmekontso.codevibe-group/marketplace.git
cd marketplace
 
# 2. Installer toutes les dépendances du monorepo en une seule fois
npm install

[!WARNING] Règle d’or du Monorepo : Ne lancez jamais npm install à l’intérieur des sous-dossiers /apps ou /packages. Cela briserait la gestion des dépendances partagées et les liens symboliques créés par npm. Utilisez toujours la racine pour l’installation globale.

⚙️ 3. Configuration de l’Environnement

Chaque application du monorepo s’appuie sur des variables d’environnement. Concentrons-nous sur l’API NestJS (apps/api), qui est le cœur de notre architecture de données.

Déplacez-vous dans le répertoire du backend :
```
cd apps/api
```
Créez un fichier .env :
```
touch .env
```

Ajoutez-y les variables suivantes (identifiants correspondant au conteneur Docker défini à l’étape 4 — docker-compose.yml) :


# URL de connexion à la base de données PostgreSQL exécutée sous Docker
DATABASE_URL="postgresql://marketplace_owner:conTrol123@localhost:5432/marketplace_db?schema=public"

# Clé secrète utilisée par NestJS pour signer les tokens JWT (Authentification)
JWT_SECRET="DEVELOPMENT_ONLY_SUPER_SECRET_KEY_12345!"

# Passerelle de paiement : "fake" simule un paiement immédiat pour le
# développement tant qu'aucun identifiant CinetPay réel n'est disponible.
PAYMENT_GATEWAY_MODE="fake"

[!NOTE] Voir Gestion des Paiements pour la liste complète des variables CINETPAY_* nécessaires si vous voulez tester la passerelle réelle plutôt que le mode fake.

📦 Génération du client Prisma

Le générateur du fichier schema.prisma de ce projet est laissé à sa configuration par défaut (pas de chemin output personnalisé) :


generator client {
  provider = "prisma-client-js"
}

Le client est donc généré à l’emplacement standard, node_modules/@prisma/client. Exécutez simplement :


# Générer le client Prisma typé
npx prisma generate

[!WARNING] Si l’API tourne déjà (npm run dev / nest start --watch), npx prisma generate peut échouer avec une erreur EPERM sous Windows : le moteur Prisma (query_engine-windows.dll.node) est verrouillé par le process en cours. Arrêtez le serveur API avant de régénérer le client après une modification du schéma.

🐘 4. Démarrage de la Base de Données

Notre base de données de développement est un conteneur PostgreSQL virtualisé.

Assurez-vous que votre application Docker Desktop est lancée.
Démarrez le conteneur de base de données depuis apps/api :
```
docker compose up -d
```

Appliquez nos migrations Prisma pour créer les tables nécessaires (User, Product, Order…) :


# Exécuter les scripts de structure SQL sur votre base de données locale
npx prisma migrate dev

[!NOTE] La commande prisma migrate dev va créer la base de données si elle n’existe pas, exécuter les fichiers SQL de migration dans le dossier /prisma/migrations, et regénérer automatiquement votre client Prisma pour y intégrer les derniers schémas.

🚀 5. Démarrage de l’Écosystème Applicatif

Grâce à Turborepo, vous pouvez lancer l’intégralité du projet (le backend, les deux frontends et la documentation) en une seule commande depuis la racine du monorepo.


# 1. Revenir à la racine du monorepo
cd ../..
 
# 2. Lancer toutes les applications en mode développement simultanément
npm run dev

Turborepo va orchestrer le démarrage de :

Le serveur API NestJS
L’application Store (Next.js)
L’application Dashboard (Next.js)
La documentation (Nextra)

🔍 6. Liste de Vérification (Verification Checklist)

Une fois la commande npm run dev stabilisée, ouvrez votre navigateur pour valider que chaque service fonctionne correctement :

Service / Application	Rôle principal	URL Locale	Statut attendu
⚙️ API Backend (NestJS)	API REST du monorepo	http://localhost:3000	Une requête GET vers cette adresse répond.
📊 Dashboard (Next.js)	Espace vendeur et administration	http://localhost:3001	La mire de connexion du dashboard s’affiche.
🛒 Store (Next.js)	Boutique publique acheteur	http://localhost:3002	La page d’accueil de la boutique s’affiche.
📖 Documentation (Nextra)	Ce site de documentation	http://localhost:3002	Vous lisez cette page actuellement !

[!WARNING] Conflit de port connu : apps/store et apps/docs sont tous les deux configurés par défaut sur le port 3002 (next dev --port 3002 dans leurs package.json respectifs). Avec npm run dev à la racine, l’un des deux échouera à démarrer (port déjà utilisé). Pour lancer les deux en parallèle, démarrez la doc sur un port différent : cd apps/docs && npx next dev --port 3005.

🛠️ Outil d’exploration de données (Bonus)

Pour explorer visuellement le contenu de vos tables PostgreSQL locales sans passer par un client SQL externe, vous pouvez lancer l’interface graphique de Prisma :


cd apps/api
npx prisma studio

Cela ouvrira Prisma Studio à l’adresse http://localhost:5555 .