286 lines
6.3 KiB
Markdown
286 lines
6.3 KiB
Markdown
# Thé Tip Top – Backend API
|
||
|
||
## Présentation
|
||
|
||
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’API fournit les services des espaces **CLIENT**, **EMPLOYEE** et **ADMIN** et prend notamment en charge :
|
||
|
||
- 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.
|
||
|
||
---
|
||
|
||
## Stack technique
|
||
|
||
| 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 |
|
||
|
||
## Authentification
|
||
|
||
### Email / mot de passe
|
||
|
||
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.
|
||
|
||
### Google OAuth 2.0
|
||
|
||
```text
|
||
Utilisateur
|
||
↓
|
||
Frontend
|
||
↓
|
||
API /api/auth/google
|
||
↓
|
||
Google OAuth 2.0
|
||
↓
|
||
Callback backend
|
||
↓
|
||
Création / récupération utilisateur
|
||
↓
|
||
JWT
|
||
↓
|
||
Redirection frontend
|
||
```
|
||
|
||
Les secrets OAuth restent hors du dépôt Git.
|
||
|
||
## Rôles
|
||
|
||
### CLIENT
|
||
- participer au jeu ;
|
||
- consulter ses gains ;
|
||
- gérer son profil.
|
||
|
||
### EMPLOYEE
|
||
- 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.
|
||
|
||
## Jeu-concours
|
||
|
||
Phases applicatives :
|
||
|
||
- `NOT_CONFIGURED`
|
||
- `SCHEDULED`
|
||
- `OPEN`
|
||
- `CLAIM_ONLY`
|
||
- `CLOSED`
|
||
|
||
Principales règles métier :
|
||
|
||
- 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.
|
||
|
||
## Notifications email
|
||
|
||
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.
|
||
|
||
## Sécurité
|
||
|
||
- 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.
|
||
|
||
> Ne jamais versionner les mots de passe, tokens, secrets JWT, secrets OAuth ou identifiants SMTP.
|
||
|
||
## Modèle de données principal
|
||
|
||
- `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.
|
||
|
||
## Installation locale
|
||
|
||
Prérequis : Node.js 22, npm et PostgreSQL 16.
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
Exemple de `.env` local :
|
||
|
||
```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=""
|
||
```
|
||
|
||
Ces valeurs sont uniquement des exemples.
|
||
|
||
## Prisma
|
||
|
||
```bash
|
||
npx prisma generate
|
||
npx prisma migrate dev
|
||
npx prisma migrate deploy
|
||
npx prisma db seed
|
||
npx prisma studio
|
||
```
|
||
|
||
## Lancement
|
||
|
||
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**.
|