Initialisation du backend de Thé Tip Top
This commit is contained in:
347
README.md
Normal file
347
README.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# 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 <url-du-repository> 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**.
|
||||
Reference in New Issue
Block a user