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 :


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

README.md Unescape Escape

Thé Tip Top – Backend API

Présentation