add readMe Files
This commit is contained in:
781
README.md
Normal file
781
README.md
Normal file
@@ -0,0 +1,781 @@
|
||||
# Thé Tip Top – Plateforme du jeu-concours
|
||||
|
||||
## Présentation
|
||||
|
||||
**Thé Tip Top** est une application web complète développée dans le cadre d’un projet de certification **Expert en Stratégie et Transformation Digitale**.
|
||||
|
||||
Le projet simule le système d’information d’un jeu-concours organisé à l’occasion de l’ouverture de la 10ᵉ boutique Thé Tip Top à Nice.
|
||||
|
||||
La plateforme permet aux clients de participer avec un code unique présent sur leur ticket, de consulter leurs gains et de les récupérer en boutique. Elle fournit également des interfaces dédiées aux employés et aux administrateurs.
|
||||
|
||||
Au-delà de l’application, le projet met en œuvre une chaîne complète de **CI/CD**, plusieurs environnements isolés, un registre Docker privé, un reverse proxy HTTPS et une stack de supervision.
|
||||
|
||||
> **Projet étudiant — client fictif Thé Tip Top.**
|
||||
|
||||
---
|
||||
|
||||
## Fonctionnalités principales
|
||||
|
||||
### Espace client
|
||||
|
||||
- création de compte ;
|
||||
- vérification de l’adresse email ;
|
||||
- connexion email / mot de passe ;
|
||||
- connexion avec Google OAuth 2.0 ;
|
||||
- gestion du profil ;
|
||||
- saisie d’un code ticket unique ;
|
||||
- participation au jeu-concours ;
|
||||
- consultation des gains.
|
||||
|
||||
### Espace employé
|
||||
|
||||
- authentification avec rôle `EMPLOYEE` ;
|
||||
- recherche d’un gain ;
|
||||
- contrôle des informations associées au ticket ;
|
||||
- validation de la remise d’un lot.
|
||||
|
||||
### Espace administrateur
|
||||
|
||||
- authentification avec rôle `ADMIN` ;
|
||||
- tableau de bord et statistiques ;
|
||||
- consultation des participants ;
|
||||
- gestion des données nécessaires à l’administration ;
|
||||
- création de comptes employés ;
|
||||
- configuration du lancement du jeu-concours ;
|
||||
- tirage au sort final ;
|
||||
- consultation du grand gagnant.
|
||||
|
||||
### Jeu-concours
|
||||
|
||||
Le système gère plusieurs phases :
|
||||
|
||||
```text
|
||||
NOT_CONFIGURED
|
||||
↓
|
||||
SCHEDULED
|
||||
↓
|
||||
OPEN
|
||||
↓
|
||||
CLAIM_ONLY
|
||||
↓
|
||||
CLOSED
|
||||
```
|
||||
|
||||
Parmi les principales règles métier :
|
||||
|
||||
- un ticket ne peut être utilisé qu’une seule fois ;
|
||||
- les tickets du jeu sont gagnants ;
|
||||
- les gains sont associés aux tickets ;
|
||||
- seuls les clients participent au jeu ;
|
||||
- plusieurs participations d’un même client n’augmentent pas ses chances au tirage final ;
|
||||
- un seul grand gagnant peut être enregistré ;
|
||||
- le tirage final respecte les contraintes temporelles définies dans l’application.
|
||||
|
||||
---
|
||||
|
||||
# Architecture générale
|
||||
|
||||
```text
|
||||
UTILISATEURS
|
||||
│
|
||||
HTTPS
|
||||
│
|
||||
▼
|
||||
┌─────────┐
|
||||
│ Traefik │
|
||||
└────┬────┘
|
||||
│
|
||||
┌────────────┴────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
Frontend React Backend API
|
||||
Vite + Nginx Node.js + Express
|
||||
│ │
|
||||
│ ▼
|
||||
│ PostgreSQL
|
||||
│ + Prisma
|
||||
│
|
||||
└────────── API REST ─────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Stack technique
|
||||
|
||||
## Frontend
|
||||
|
||||
- React
|
||||
- Vite
|
||||
- React Router
|
||||
- Tailwind CSS
|
||||
- Vitest
|
||||
- Testing Library
|
||||
- ESLint
|
||||
- Nginx
|
||||
|
||||
## Backend
|
||||
|
||||
- Node.js 22
|
||||
- Express.js
|
||||
- Prisma ORM 6
|
||||
- PostgreSQL 16
|
||||
- JWT
|
||||
- Passport.js
|
||||
- Google OAuth 2.0
|
||||
- Bcrypt
|
||||
- Zod
|
||||
- Nodemailer
|
||||
- Helmet
|
||||
- express-rate-limit
|
||||
- Swagger / OpenAPI
|
||||
- Jest
|
||||
- Supertest
|
||||
|
||||
## DevOps
|
||||
|
||||
- Git
|
||||
- Gitea
|
||||
- Jenkins
|
||||
- Docker
|
||||
- Docker Compose
|
||||
- Docker Registry privé
|
||||
- Traefik
|
||||
- HTTPS
|
||||
- Let's Encrypt
|
||||
|
||||
## Monitoring
|
||||
|
||||
- Prometheus
|
||||
- Grafana
|
||||
- cAdvisor
|
||||
- Node Exporter
|
||||
|
||||
---
|
||||
|
||||
# Structure du dépôt
|
||||
|
||||
```text
|
||||
THE-TIP-TOP/
|
||||
│
|
||||
├── backend/
|
||||
│ ├── prisma/
|
||||
│ │ ├── migrations/
|
||||
│ │ ├── schema.prisma
|
||||
│ │ └── seed.js
|
||||
│ ├── src/
|
||||
│ ├── tests/
|
||||
│ ├── Dockerfile
|
||||
│ ├── package.json
|
||||
│ └── README.md
|
||||
│
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── components/
|
||||
│ │ ├── context/
|
||||
│ │ ├── pages/
|
||||
│ │ ├── services/
|
||||
│ │ └── test/
|
||||
│ ├── Dockerfile
|
||||
│ ├── nginx.conf
|
||||
│ ├── package.json
|
||||
│ └── README.md
|
||||
│
|
||||
├── deploy/
|
||||
│ ├── dev/
|
||||
│ │ └── docker-compose.yml
|
||||
│ ├── preprod/
|
||||
│ │ └── docker-compose.yml
|
||||
│ └── prod/
|
||||
│ └── docker-compose.yml
|
||||
│
|
||||
├── Jenkinsfile
|
||||
└── README.md
|
||||
```
|
||||
|
||||
Pour les informations spécifiques à chaque application :
|
||||
|
||||
- [`backend/README.md`](backend/README.md)
|
||||
- [`frontend/README.md`](frontend/README.md)
|
||||
|
||||
---
|
||||
|
||||
# Environnements
|
||||
|
||||
Le projet utilise trois environnements distincts.
|
||||
|
||||
| Environnement | Branche | Frontend | API |
|
||||
|---|---|---|---|
|
||||
| DEV | `develop` | `https://dev.dsp5-archi-o24a-4-5-g4.fr` | `https://api-dev.dsp5-archi-o24a-4-5-g4.fr` |
|
||||
| PREPROD | `release-*` | `https://preprod.dsp5-archi-o24a-4-5-g4.fr` | `https://api-preprod.dsp5-archi-o24a-4-5-g4.fr` |
|
||||
| PROD | `main` | `https://dsp5-archi-o24a-4-5-g4.fr` | `https://api.dsp5-archi-o24a-4-5-g4.fr` |
|
||||
|
||||
Les bases PostgreSQL et conteneurs applicatifs sont séparés entre les environnements.
|
||||
|
||||
---
|
||||
|
||||
# Stratégie Git
|
||||
|
||||
Le workflow de branches est organisé autour de plusieurs niveaux de validation.
|
||||
|
||||
```text
|
||||
feature/*
|
||||
│
|
||||
│ Pull Request / Merge
|
||||
▼
|
||||
develop
|
||||
│
|
||||
│ CI + déploiement DEV
|
||||
▼
|
||||
release-*
|
||||
│
|
||||
│ CI + déploiement PREPROD
|
||||
▼
|
||||
main
|
||||
│
|
||||
│ validation manuelle Jenkins
|
||||
▼
|
||||
PRODUCTION
|
||||
```
|
||||
|
||||
### `feature/*`
|
||||
|
||||
Branches utilisées pour le développement des fonctionnalités.
|
||||
|
||||
### `develop`
|
||||
|
||||
Branche d’intégration. Un changement validé sur cette branche est déployé automatiquement en DEV.
|
||||
|
||||
### `release-*`
|
||||
|
||||
Branches de préparation d’une version. Elles sont déployées en PREPROD pour validation avant production.
|
||||
|
||||
### `main`
|
||||
|
||||
Branche stable de production. Le déploiement PROD nécessite une validation manuelle dans Jenkins.
|
||||
|
||||
---
|
||||
|
||||
# Pipeline CI/CD
|
||||
|
||||
Le fichier `Jenkinsfile` placé à la racine du dépôt définit la chaîne d’intégration et de déploiement.
|
||||
|
||||
```text
|
||||
Push Gitea
|
||||
│
|
||||
▼
|
||||
Jenkins
|
||||
│
|
||||
├── Checkout
|
||||
│
|
||||
├── Vérification workspace
|
||||
│
|
||||
├── PostgreSQL CI temporaire
|
||||
│
|
||||
├── Prisma migrations
|
||||
│
|
||||
├── Prisma seed
|
||||
│
|
||||
├── Tests backend Jest
|
||||
│
|
||||
├── Publication JUnit
|
||||
│
|
||||
├── Frontend ESLint
|
||||
│
|
||||
├── Frontend Vite build
|
||||
│
|
||||
├── Docker build
|
||||
│
|
||||
├── Push Registry privé
|
||||
│
|
||||
└── Docker Compose deploy
|
||||
│
|
||||
▼
|
||||
DEV / PREPROD / PROD
|
||||
```
|
||||
|
||||
## Comportement selon la branche
|
||||
|
||||
### Feature
|
||||
|
||||
```text
|
||||
Push
|
||||
↓
|
||||
Tests
|
||||
↓
|
||||
Lint
|
||||
↓
|
||||
Build
|
||||
```
|
||||
|
||||
Pas de déploiement automatique.
|
||||
|
||||
### Develop
|
||||
|
||||
```text
|
||||
Push develop
|
||||
↓
|
||||
CI
|
||||
↓
|
||||
Images Docker
|
||||
↓
|
||||
Registry
|
||||
↓
|
||||
Déploiement DEV
|
||||
```
|
||||
|
||||
### Release
|
||||
|
||||
```text
|
||||
Push release-*
|
||||
↓
|
||||
CI
|
||||
↓
|
||||
Images Docker
|
||||
↓
|
||||
Registry
|
||||
↓
|
||||
Déploiement PREPROD
|
||||
```
|
||||
|
||||
### Main
|
||||
|
||||
```text
|
||||
Push main
|
||||
↓
|
||||
CI
|
||||
↓
|
||||
Images Docker
|
||||
↓
|
||||
Registry
|
||||
↓
|
||||
Validation Jenkins
|
||||
↓
|
||||
Déploiement PROD
|
||||
```
|
||||
|
||||
Cette validation constitue une barrière supplémentaire avant la mise en production.
|
||||
|
||||
---
|
||||
|
||||
# Tests automatisés
|
||||
|
||||
## Backend
|
||||
|
||||
Les tests utilisent **Jest** et **Supertest**.
|
||||
|
||||
Ils couvrent notamment :
|
||||
|
||||
- inscription ;
|
||||
- connexion ;
|
||||
- parcours E2E ;
|
||||
- autorisations ;
|
||||
- participation ;
|
||||
- phases du jeu ;
|
||||
- tirage au sort ;
|
||||
- notifications liées aux gains ;
|
||||
- notification du grand gagnant ;
|
||||
- authentification Google ;
|
||||
- gestion du mot de passe ;
|
||||
- comportements liés aux emails.
|
||||
|
||||
Commande :
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
npm test
|
||||
```
|
||||
|
||||
Dans Jenkins, PostgreSQL est lancé temporairement pour les tests. Les migrations et données initiales sont appliquées avant l’exécution des suites.
|
||||
|
||||
## Frontend
|
||||
|
||||
Les tests utilisent **Vitest** et **Testing Library**.
|
||||
|
||||
Ils couvrent notamment :
|
||||
|
||||
- connexion ;
|
||||
- inscription ;
|
||||
- formulaire d’inscription ;
|
||||
- saisie du code unique ;
|
||||
- routes protégées ;
|
||||
- contexte d’authentification ;
|
||||
- gestion des erreurs d’authentification ;
|
||||
- services ;
|
||||
- bannière de cookies.
|
||||
|
||||
Commandes :
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run lint
|
||||
npm test -- --run
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Authentification et sécurité
|
||||
|
||||
Le projet met en œuvre plusieurs mécanismes de sécurité.
|
||||
|
||||
## Authentification
|
||||
|
||||
- JWT ;
|
||||
- email / mot de passe ;
|
||||
- Google OAuth 2.0 ;
|
||||
- vérification email.
|
||||
|
||||
## Protection des mots de passe
|
||||
|
||||
Les mots de passe sont hachés avec **Bcrypt** avant stockage.
|
||||
|
||||
## Validation
|
||||
|
||||
Les données reçues par l’API sont validées avec **Zod**.
|
||||
|
||||
## Contrôle d’accès
|
||||
|
||||
Des middlewares backend contrôlent :
|
||||
|
||||
- l’authentification ;
|
||||
- le rôle ;
|
||||
- l’accès aux routes protégées.
|
||||
|
||||
## Sécurité HTTP
|
||||
|
||||
Le backend utilise notamment :
|
||||
|
||||
- Helmet ;
|
||||
- rate limiting ;
|
||||
- validation des entrées.
|
||||
|
||||
## HTTPS
|
||||
|
||||
Traefik assure le routage HTTP/HTTPS vers les différents services.
|
||||
|
||||
---
|
||||
|
||||
# Gestion des secrets
|
||||
|
||||
Les secrets ne doivent jamais être stockés directement dans le dépôt Git.
|
||||
|
||||
Sont notamment concernés :
|
||||
|
||||
```text
|
||||
JWT_SECRET
|
||||
DATABASE_URL / mots de passe PostgreSQL
|
||||
MAIL_USER
|
||||
MAIL_PASS
|
||||
GOOGLE_CLIENT_ID
|
||||
GOOGLE_CLIENT_SECRET
|
||||
FACEBOOK_APP_ID
|
||||
FACEBOOK_APP_SECRET
|
||||
identifiants du Docker Registry
|
||||
```
|
||||
|
||||
Les valeurs sensibles de déploiement sont externalisées sur le serveur ou injectées par Jenkins.
|
||||
|
||||
> Les fichiers contenant des secrets réels ne doivent jamais être ajoutés au dépôt.
|
||||
|
||||
---
|
||||
|
||||
# Docker
|
||||
|
||||
Le frontend et le backend disposent chacun de leur propre image Docker.
|
||||
|
||||
## Backend
|
||||
|
||||
```text
|
||||
Node.js 22
|
||||
↓
|
||||
npm ci
|
||||
↓
|
||||
Prisma generate
|
||||
↓
|
||||
Application Express
|
||||
```
|
||||
|
||||
## Frontend
|
||||
|
||||
Build multi-stage :
|
||||
|
||||
```text
|
||||
Node.js 22
|
||||
↓
|
||||
npm ci
|
||||
↓
|
||||
Vite build
|
||||
↓
|
||||
Nginx
|
||||
```
|
||||
|
||||
Les images sont versionnées et publiées dans le Registry privé par Jenkins.
|
||||
|
||||
---
|
||||
|
||||
# Docker Compose
|
||||
|
||||
Chaque environnement possède son propre fichier Compose :
|
||||
|
||||
```text
|
||||
deploy/dev/docker-compose.yml
|
||||
deploy/preprod/docker-compose.yml
|
||||
deploy/prod/docker-compose.yml
|
||||
```
|
||||
|
||||
Chaque stack contient notamment :
|
||||
|
||||
```text
|
||||
Frontend
|
||||
Backend
|
||||
PostgreSQL
|
||||
```
|
||||
|
||||
Les stacks sont isolées avec leurs propres conteneurs, réseaux, données et paramètres d’environnement.
|
||||
|
||||
---
|
||||
|
||||
# Reverse proxy et HTTPS
|
||||
|
||||
**Traefik** constitue le point d’entrée HTTP/HTTPS de l’infrastructure.
|
||||
|
||||
Il permet notamment :
|
||||
|
||||
- le routage par nom de domaine ;
|
||||
- l’exposition des frontends ;
|
||||
- l’exposition des APIs ;
|
||||
- la terminaison TLS ;
|
||||
- la gestion des certificats HTTPS.
|
||||
|
||||
Seuls les ports nécessaires sont exposés publiquement.
|
||||
|
||||
---
|
||||
|
||||
# Monitoring
|
||||
|
||||
La plateforme dispose d’une stack de supervision.
|
||||
|
||||
```text
|
||||
Node Exporter ──┐
|
||||
│
|
||||
cAdvisor ───────┼──► Prometheus ───► Grafana
|
||||
│
|
||||
Services ───────┘
|
||||
```
|
||||
|
||||
### Prometheus
|
||||
|
||||
Collecte les métriques.
|
||||
|
||||
### Grafana
|
||||
|
||||
Permet de construire et consulter les tableaux de bord.
|
||||
|
||||
### cAdvisor
|
||||
|
||||
Expose les métriques relatives aux conteneurs Docker.
|
||||
|
||||
### Node Exporter
|
||||
|
||||
Expose les métriques système du serveur.
|
||||
|
||||
---
|
||||
|
||||
# Documentation API
|
||||
|
||||
Le backend expose une documentation Swagger / OpenAPI.
|
||||
|
||||
En environnement local :
|
||||
|
||||
```text
|
||||
http://localhost:5000/api-docs
|
||||
```
|
||||
|
||||
Elle permet de :
|
||||
|
||||
- consulter les routes ;
|
||||
- consulter les schémas ;
|
||||
- examiner les paramètres ;
|
||||
- tester les endpoints ;
|
||||
- utiliser l’authentification prévue par l’API.
|
||||
|
||||
---
|
||||
|
||||
# Installation locale
|
||||
|
||||
## 1. Cloner le dépôt
|
||||
|
||||
```bash
|
||||
git clone <URL_DU_DEPOT>
|
||||
cd THE-TIP-TOP
|
||||
```
|
||||
|
||||
## 2. Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
npm install
|
||||
```
|
||||
|
||||
Configurer les variables d’environnement locales puis :
|
||||
|
||||
```bash
|
||||
npx prisma generate
|
||||
npx prisma migrate dev
|
||||
npx prisma db seed
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 3. Frontend
|
||||
|
||||
Dans un second terminal :
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Le frontend local est généralement accessible sur :
|
||||
|
||||
```text
|
||||
http://localhost:5173
|
||||
```
|
||||
|
||||
et l’API sur :
|
||||
|
||||
```text
|
||||
http://localhost:5000
|
||||
```
|
||||
|
||||
Consulter les README des sous-projets pour les détails de configuration.
|
||||
|
||||
---
|
||||
|
||||
# Base de données
|
||||
|
||||
Le projet utilise **PostgreSQL 16** avec **Prisma ORM 6**.
|
||||
|
||||
Commandes Prisma utiles :
|
||||
|
||||
```bash
|
||||
npx prisma generate
|
||||
npx prisma migrate dev
|
||||
npx prisma migrate deploy
|
||||
npx prisma db seed
|
||||
npx prisma studio
|
||||
```
|
||||
|
||||
En environnement déployé, les migrations sont appliquées avec `prisma migrate deploy`.
|
||||
|
||||
---
|
||||
|
||||
# Qualité logicielle
|
||||
|
||||
Le projet applique plusieurs niveaux de contrôle :
|
||||
|
||||
```text
|
||||
Code
|
||||
↓
|
||||
ESLint
|
||||
↓
|
||||
Tests unitaires / fonctionnels
|
||||
↓
|
||||
Tests backend / E2E
|
||||
↓
|
||||
Build
|
||||
↓
|
||||
Docker Build
|
||||
↓
|
||||
Déploiement
|
||||
```
|
||||
|
||||
Un échec dans une étape critique provoque l’échec du pipeline et empêche la promotion normale de la version.
|
||||
|
||||
---
|
||||
|
||||
# Infrastructure DevOps
|
||||
|
||||
Vue simplifiée :
|
||||
|
||||
```text
|
||||
┌───────────────┐
|
||||
│ Gitea │
|
||||
└───────┬───────┘
|
||||
│ Webhook
|
||||
▼
|
||||
┌───────────────┐
|
||||
│ Jenkins │
|
||||
└───────┬───────┘
|
||||
│
|
||||
Tests / Build / Docker
|
||||
│
|
||||
▼
|
||||
┌───────────────┐
|
||||
│Docker Registry│
|
||||
└───────┬───────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
▼ ▼ ▼
|
||||
DEV PREPROD PROD
|
||||
│ │ │
|
||||
└───────────────┼───────────────┘
|
||||
▼
|
||||
Traefik
|
||||
│
|
||||
HTTPS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# État du projet
|
||||
|
||||
Le projet dispose notamment de :
|
||||
|
||||
- frontend React opérationnel ;
|
||||
- backend Express opérationnel ;
|
||||
- PostgreSQL et Prisma ;
|
||||
- authentification JWT ;
|
||||
- Google OAuth 2.0 ;
|
||||
- vérification email ;
|
||||
- gestion CLIENT / EMPLOYEE / ADMIN ;
|
||||
- jeu-concours et gestion des gains ;
|
||||
- tirage final ;
|
||||
- tests automatisés ;
|
||||
- documentation Swagger ;
|
||||
- images Docker ;
|
||||
- Registry privé ;
|
||||
- pipeline Jenkins multibranch ;
|
||||
- environnements DEV / PREPROD / PROD ;
|
||||
- déploiements Docker Compose ;
|
||||
- reverse proxy Traefik ;
|
||||
- HTTPS ;
|
||||
- monitoring Prometheus / Grafana.
|
||||
|
||||
---
|
||||
|
||||
# Documentation complémentaire
|
||||
|
||||
Documentation backend :
|
||||
|
||||
```text
|
||||
backend/README.md
|
||||
```
|
||||
|
||||
Documentation frontend :
|
||||
|
||||
```text
|
||||
frontend/README.md
|
||||
```
|
||||
|
||||
Ces fichiers détaillent respectivement l’API et l’application React.
|
||||
|
||||
---
|
||||
|
||||
# Projet académique
|
||||
|
||||
Projet réalisé dans le cadre de la certification :
|
||||
|
||||
**Expert en Stratégie et Transformation Digitale**
|
||||
|
||||
Le cas **Thé Tip Top** est utilisé comme contexte métier fictif pour la conception, le développement, les tests, la sécurisation, l’industrialisation et le déploiement de l’application.
|
||||
Reference in New Issue
Block a user