add readMe Files
This commit is contained in:
@@ -1,368 +1,285 @@
|
||||
# Thé Tip Top – Backend API
|
||||
# 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.
|
||||
Backend REST du jeu-concours fictif **Thé Tip Top**, réalisé dans le cadre de la certification **Expert en Stratégie et Transformation Digitale**.
|
||||
|
||||
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.
|
||||
L’API fournit les services des espaces **CLIENT**, **EMPLOYEE** et **ADMIN** et prend notamment en charge :
|
||||
|
||||
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
|
||||
- inscription, vérification email et connexion ;
|
||||
- authentification JWT et Google OAuth 2.0 ;
|
||||
- rôles et autorisations ;
|
||||
- tickets, participations et gains ;
|
||||
- remise des lots ;
|
||||
- configuration des phases du jeu ;
|
||||
- tirage au sort final ;
|
||||
- notifications email ;
|
||||
- administration et statistiques.
|
||||
|
||||
---
|
||||
|
||||
## Fonctionnalités
|
||||
## Stack technique
|
||||
|
||||
### Authentification
|
||||
| Technologie | Utilisation |
|
||||
|---|---|
|
||||
| Node.js 22 | Runtime |
|
||||
| Express.js | API REST |
|
||||
| PostgreSQL 16 | Base de données |
|
||||
| Prisma ORM 6 | ORM et migrations |
|
||||
| JWT | Authentification |
|
||||
| Passport.js | Authentification externe |
|
||||
| Google OAuth 2.0 | Connexion Google |
|
||||
| Bcrypt | Hachage des mots de passe |
|
||||
| Zod | Validation |
|
||||
| Nodemailer | Emails |
|
||||
| Helmet | Sécurité HTTP |
|
||||
| express-rate-limit | Rate limiting |
|
||||
| Swagger / OpenAPI | Documentation |
|
||||
| Jest / Supertest | Tests |
|
||||
| Docker | Conteneurisation |
|
||||
|
||||
- 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**
|
||||
## Authentification
|
||||
|
||||
### Jeu-concours
|
||||
### Email / mot de passe
|
||||
|
||||
- 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
|
||||
Le parcours comprend l’inscription, le hachage Bcrypt, l’envoi d’un code de vérification par email, la validation du compte, la connexion et la génération d’un JWT.
|
||||
|
||||
### Espace Employé
|
||||
### Google OAuth 2.0
|
||||
|
||||
- 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
|
||||
```text
|
||||
Utilisateur
|
||||
↓
|
||||
Frontend
|
||||
↓
|
||||
API /api/auth/google
|
||||
↓
|
||||
Google OAuth 2.0
|
||||
↓
|
||||
Callback backend
|
||||
↓
|
||||
Création / récupération utilisateur
|
||||
↓
|
||||
JWT
|
||||
↓
|
||||
Redirection frontend
|
||||
```
|
||||
|
||||
### Installer les dépendances
|
||||
Les secrets OAuth restent hors du dépôt Git.
|
||||
|
||||
```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
|
||||
|
||||
Le projet utilise **Nodemon** afin de redémarrer automatiquement le serveur lors des modifications du code.
|
||||
|
||||
```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
|
||||
## Rôles
|
||||
|
||||
### CLIENT
|
||||
|
||||
Peut :
|
||||
|
||||
- Participer au jeu-concours
|
||||
- Consulter ses gains
|
||||
- Consulter son profil
|
||||
- participer au jeu ;
|
||||
- consulter ses gains ;
|
||||
- gérer son profil.
|
||||
|
||||
### EMPLOYEE
|
||||
|
||||
Peut :
|
||||
|
||||
- Rechercher un gain
|
||||
- Vérifier les informations du gagnant
|
||||
- Valider la remise d'un lot
|
||||
- rechercher et vérifier un gain ;
|
||||
- valider la remise d’un lot.
|
||||
|
||||
### ADMIN
|
||||
- consulter les statistiques ;
|
||||
- créer des employés ;
|
||||
- configurer le jeu ;
|
||||
- effectuer le tirage final ;
|
||||
- consulter le grand gagnant.
|
||||
|
||||
Peut :
|
||||
## Jeu-concours
|
||||
|
||||
- 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
|
||||
Phases applicatives :
|
||||
|
||||
---
|
||||
- `NOT_CONFIGURED`
|
||||
- `SCHEDULED`
|
||||
- `OPEN`
|
||||
- `CLAIM_ONLY`
|
||||
- `CLOSED`
|
||||
|
||||
## Routes API
|
||||
Principales règles métier :
|
||||
|
||||
### Auth
|
||||
- un ticket ne peut être utilisé qu’une fois ;
|
||||
- les tickets sont gagnants ;
|
||||
- les comptes EMPLOYEE et ADMIN ne participent pas comme clients ;
|
||||
- plusieurs participations d’un client n’augmentent pas ses chances au tirage final ;
|
||||
- un seul grand gagnant peut être enregistré ;
|
||||
- le tirage final respecte les contraintes temporelles du jeu.
|
||||
|
||||
| Méthode | Route |
|
||||
| ------- | ------------------ |
|
||||
| POST | /api/auth/register |
|
||||
| POST | /api/auth/login |
|
||||
| GET | /api/auth/me |
|
||||
## Notifications email
|
||||
|
||||
### Game
|
||||
Nodemailer est utilisé notamment pour la vérification des comptes et les notifications liées aux gains et au tirage final. La configuration SMTP est fournie par variables d’environnement.
|
||||
|
||||
| Méthode | Route |
|
||||
| ------- | --------------------- |
|
||||
| POST | /api/game/participate |
|
||||
| GET | /api/game/my-gains |
|
||||
## Sécurité
|
||||
|
||||
### Employee
|
||||
- Bcrypt ;
|
||||
- JWT ;
|
||||
- Google OAuth 2.0 ;
|
||||
- Zod ;
|
||||
- contrôle d’accès par rôle ;
|
||||
- Helmet ;
|
||||
- rate limiting ;
|
||||
- secrets externalisés ;
|
||||
- HTTPS via Traefik ;
|
||||
- séparation DEV / PREPROD / PROD.
|
||||
|
||||
| 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
|
||||
|
||||
---
|
||||
> Ne jamais versionner les mots de passe, tokens, secrets JWT, secrets OAuth ou identifiants SMTP.
|
||||
|
||||
## Modèle de données principal
|
||||
|
||||
### User
|
||||
- `User` : utilisateurs et rôles CLIENT / EMPLOYEE / ADMIN.
|
||||
- `Ticket` : code unique, lot associé et état d’utilisation.
|
||||
- `Lot` : lot, description, valeur et répartition.
|
||||
- `Participation` : participation d’un utilisateur avec un ticket.
|
||||
- `Claim` : gestion de la remise du gain.
|
||||
- `GameSettings` : configuration temporelle du concours.
|
||||
- `GrandPrizeWinner` : résultat du tirage final.
|
||||
|
||||
- **CLIENT**
|
||||
- **EMPLOYEE**
|
||||
- **ADMIN**
|
||||
## Installation locale
|
||||
|
||||
### Ticket
|
||||
Prérequis : Node.js 22, npm et PostgreSQL 16.
|
||||
|
||||
- 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
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
Exemple de `.env` local :
|
||||
|
||||
## Règles métier
|
||||
```env
|
||||
PORT=5000
|
||||
NODE_ENV=development
|
||||
DATABASE_URL="postgresql://postgres:password@localhost:5432/the_tip_top_db"
|
||||
JWT_SECRET="change_me"
|
||||
APP_URL="http://localhost:5000"
|
||||
FRONTEND_URL="http://localhost:5173"
|
||||
MAIL_HOST="smtp.example.com"
|
||||
MAIL_PORT=587
|
||||
MAIL_USER="user@example.com"
|
||||
MAIL_PASS="change_me"
|
||||
MAIL_FROM="Thé Tip Top <user@example.com>"
|
||||
GOOGLE_CLIENT_ID=""
|
||||
GOOGLE_CLIENT_SECRET=""
|
||||
```
|
||||
|
||||
- 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.
|
||||
Ces valeurs sont uniquement des exemples.
|
||||
|
||||
---
|
||||
## Prisma
|
||||
|
||||
## Auteur
|
||||
```bash
|
||||
npx prisma generate
|
||||
npx prisma migrate dev
|
||||
npx prisma migrate deploy
|
||||
npx prisma db seed
|
||||
npx prisma studio
|
||||
```
|
||||
|
||||
Projet réalisé dans le cadre de la certification : **Expert en Stratégie et Transformation Digitale**
|
||||
## Lancement
|
||||
|
||||
Client fictif : **Thé Tip Top**.
|
||||
Développement :
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Démarrage standard :
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
API locale généralement disponible sur `http://localhost:5000`.
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
Les tests Jest/Supertest couvrent notamment l’inscription, la connexion, les autorisations, les participations, les phases du jeu, le tirage final, les notifications, l’authentification Google et des scénarios E2E.
|
||||
|
||||
Dans Jenkins, une base PostgreSQL temporaire est créée. Les migrations et le seed sont exécutés avant les tests, puis les résultats sont publiés au format JUnit.
|
||||
|
||||
## Documentation API
|
||||
|
||||
Swagger UI est accessible localement sur :
|
||||
|
||||
```text
|
||||
http://localhost:5000/api-docs
|
||||
```
|
||||
|
||||
## CI/CD
|
||||
|
||||
Le projet utilise Gitea, Jenkins, Docker et un Registry privé.
|
||||
|
||||
```text
|
||||
feature/* → CI uniquement
|
||||
develop → DEV automatique
|
||||
release-* → PREPROD automatique
|
||||
main → validation manuelle → PROD
|
||||
```
|
||||
|
||||
Pipeline :
|
||||
|
||||
```text
|
||||
Checkout
|
||||
↓
|
||||
Tests backend + PostgreSQL temporaire
|
||||
↓
|
||||
Lint + Build frontend
|
||||
↓
|
||||
Docker Build
|
||||
↓
|
||||
Registry
|
||||
↓
|
||||
Déploiement
|
||||
↓
|
||||
Contrôle des conteneurs
|
||||
```
|
||||
|
||||
## Environnements
|
||||
|
||||
| Environnement | Frontend | API |
|
||||
|---|---|---|
|
||||
| DEV | `https://dev.dsp5-archi-o24a-4-5-g4.fr` | `https://api-dev.dsp5-archi-o24a-4-5-g4.fr` |
|
||||
| PREPROD | `https://preprod.dsp5-archi-o24a-4-5-g4.fr` | `https://api-preprod.dsp5-archi-o24a-4-5-g4.fr` |
|
||||
| PROD | `https://dsp5-archi-o24a-4-5-g4.fr` | `https://api.dsp5-archi-o24a-4-5-g4.fr` |
|
||||
|
||||
## Infrastructure
|
||||
|
||||
- Docker / Docker Compose ;
|
||||
- Gitea ;
|
||||
- Jenkins ;
|
||||
- Docker Registry ;
|
||||
- Traefik ;
|
||||
- Let's Encrypt / HTTPS ;
|
||||
- PostgreSQL ;
|
||||
- Prometheus ;
|
||||
- Grafana ;
|
||||
- cAdvisor ;
|
||||
- Node Exporter.
|
||||
|
||||
## Arborescence simplifiée
|
||||
|
||||
```text
|
||||
backend/
|
||||
├── prisma/
|
||||
│ ├── migrations/
|
||||
│ ├── schema.prisma
|
||||
│ └── seed.js
|
||||
├── src/
|
||||
│ ├── config/
|
||||
│ ├── controllers/
|
||||
│ ├── docs/
|
||||
│ ├── middlewares/
|
||||
│ ├── routes/
|
||||
│ ├── utils/
|
||||
│ ├── validations/
|
||||
│ └── app.js
|
||||
├── tests/
|
||||
├── Dockerfile
|
||||
├── package.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Projet
|
||||
|
||||
Projet étudiant fictif 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