THE-TIP-TOP/README.md

#  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**.