6.8 KiB
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
git clone <url-du-repository>
cd the-tip-top-backend
Installer les dépendances
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
npx prisma migrate dev
Générer Prisma Client
npx prisma generate
Exécuter le seed de la base
npx prisma db seed
Générer les tickets du jeu-concours
npm run generate:tickets
Ouvrir Prisma Studio
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
Le projet utilise Nodemon afin de redémarrer automatiquement le serveur lors des modifications du code.
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 :
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.