# Thé Tip Top – Backend API ## Présentation Ce projet correspond au backend du jeu-concours organisé par **Thé Tip Top** à l'occasion de l'ouverture de sa 10ᵉ boutique à Nice. L'application permet aux clients de participer à un jeu-concours via un code présent sur leur ticket de caisse, de consulter leurs gains et de réclamer leurs lots en boutique. Le backend expose une **API** **REST** sécurisée utilisée par : - l'application client (participants) - l'espace employé en boutique - l'espace administrateur - les futurs services externes de l'écosystème Thé Tip Top --- ## Fonctionnalités ### Authentification - Inscription utilisateur - Connexion sécurisée - Authentification **JWT** - Gestion des rôles (**CLIENT**, **EMPLOYEE**, **ADMIN**) - Hachage des mots de passe avec Bcrypt - Validation des données avec **Zod** ### Jeu-concours - Génération automatique des lots - Génération des tickets gagnants - Participation via code ticket unique - Attribution automatique des gains - Historique des participations - Historique des gains remportés ### Espace Employé - Recherche d'un gain via un code ticket - Vérification du statut du gain - Validation de la remise d'un lot - Mise à jour automatique du statut du gain ### Espace Administrateur - Tableau de bord statistique - Liste des participants - Liste des contacts ayant accepté les communications marketing - Création de comptes employés - Tirage au sort du grand gagnant - Consultation du gagnant du gros lot ### Documentation API - Documentation interactive avec **Swagger UI** - Génération automatique de la documentation via **Swagger JSDoc** - Tests des endpoints directement depuis le navigateur --- ## Architecture Technique ### Backend - Node.js - Express.js ### Base de données - PostgreSQL - **Prisma **ORM** 6** - Prisma Client 6 - Prisma Migrate - Prisma Studio ### Validation des données - **Zod** - Middleware de validation personnalisé ### Sécurité - **JWT** (**JSON** Web Token) - Bcrypt - Gestion des rôles et permissions - Validation des entrées utilisateur ### Documentation - Swagger UI - Swagger JSDoc - OpenAPI 3.0 --- ## Installation ### Cloner le projet ```bash git clone cd the-tip-top-backend ``` ### Installer les dépendances ```bash npm install ``` ### Variables d'environnement Créer un fichier `.env` à la racine du projet : ```env **PORT**=**5000** DATABASE_URL="postgresql://postgres:password@localhost:**5432**/the_tip_top_db* JWT_SECRET=*your_secret_key" ``` --- ## Base de données ### Générer les migrations ```bash npx prisma migrate dev ``` ### Générer Prisma Client ```bash npx prisma generate ``` ### Exécuter le seed de la base ```bash npx prisma db seed ``` ### Générer les tickets du jeu-concours ```bash npm run generate:tickets ``` ### Ouvrir Prisma Studio ```bash npx prisma studio ``` --- ## Technologies utilisées | Technologie | Version | | ----------- | ---------------- | | Node.js | 20+ | | Express.js | 5 | | PostgreSQL | 16+ | | Prisma ORM | 6 | | JWT | Dernière version | | Bcrypt | Dernière version | | Zod | Dernière version | | Swagger UI | Dernière version | --- ## Lancement du projet ### Développement ```bash npm run dev ``` Serveur : ```txt [http://localhost:**5000**](http://localhost:**5000**) ``` --- ## Documentation API La documentation Swagger est accessible à l'adresse : ```txt [http://localhost:**5000**/api-docs](http://localhost:**5000**/api-docs) ``` Fonctionnalités disponibles : - Consultation de toutes les routes - Visualisation des schémas de données - Test des endpoints - Authentification via **JWT** avec le bouton **Authorize** --- ## Gestion des rôles ### CLIENT Peut : - Participer au jeu-concours - Consulter ses gains - Consulter son profil ### EMPLOYEE Peut : - Rechercher un gain - Vérifier les informations du gagnant - Valider la remise d'un lot ### ADMIN Peut : - Accéder aux statistiques - Créer des employés - Gérer les campagnes emailing - Effectuer le tirage au sort final - Consulter le gagnant du gros lot --- ## Routes API ### Auth | Méthode | Route | | ------- | ------------------ | | POST | /api/auth/register | | POST | /api/auth/login | | GET | /api/auth/me | ### Game | Méthode | Route | | ------- | --------------------- | | POST | /api/game/participate | | GET | /api/game/my-gains | ### Employee | Méthode | Route | | ------- | ---------------------------- | | GET | /api/employee/ticket/ | | PATCH | /api/employee/claim//deliver | ### Admin | Méthode | Route | | ------- | -------------------- | | GET | /api/admin/stats | | GET | /api/admin/users | | GET | /api/admin/emailing | | POST | /api/admin/employees | | POST | /api/admin/draw | | GET | /api/admin/draw | --- ## Validation avec Zod Toutes les données reçues par l'**API** sont validées avant traitement grâce à **Zod**. Exemples : - Inscription utilisateur - Connexion - Création d'employés - Participation au jeu-concours - Validation des paramètres de requête Cette approche garantit : - Des données cohérentes - Une meilleure sécurité - Des messages d'erreur explicites - Une maintenance facilitée --- ## Modèle de données principal ### User - **CLIENT** - **EMPLOYEE** - **ADMIN** ### Ticket - Code unique - Gain associé - Utilisé / Non utilisé ### Lot - Nom - Description - Valeur - Pourcentage de répartition ### Participation - Utilisateur - Ticket - Lot gagné ### Claim - **PENDING** - **DELIVERED** - **CANCELLED** ### GrandPrizeWinner - Gagnant du gros lot - Date du tirage - Récompense --- ## Prisma ORM 6 Le projet utilise **Prisma **ORM** 6** pour : - La modélisation des données - Les migrations de base de données - Les requêtes **SQL** typées - La génération automatique du client Prisma - L'administration de la base via Prisma Studio Commandes utiles : ```bash npx prisma migrate dev npx prisma generate npx prisma db seed npx prisma studio ``` --- ## Règles métier - Tous les tickets sont gagnants. - Un ticket ne peut être utilisé qu'une seule fois. - Les gains sont associés aux tickets dès leur génération. - Plusieurs participations n'augmentent pas les chances de remporter le gros lot. - Un seul gagnant du gros lot peut être enregistré. - Les gains non récupérés dans les délais peuvent être annulés. --- ## Auteur Projet réalisé dans le cadre de la certification : **Expert en Stratégie et Transformation Digitale** Client fictif : **Thé Tip Top**.