Turbo Delivery — Backend

API REST Spring Boot pour la gestion d'une plateforme de livraison : livreurs, commandes, courses, paie, charges et reporting.

---

Table des matières

• Aperçu
• Technologies
• Prérequis
• Installation
• Configuration
• Lancer l'application
• Docker
• Documentation API
• Architecture
• Domaines métier
• Tests
• Déploiement

---

Aperçu

Turbo Delivery Backend est une application Spring Boot 3.3 (Java 21) exposant une API REST pour :

• La gestion des livreurs (profils, planning, présence, performance)
• Le traitement des commandes et courses avec suivi en temps réel (WebSocket)
• Le calcul de la paie (charges fixes/variables, avances, déductions)
• La gestion des files d'attente restaurant et la coordination des livraisons
• La génération de rapports PDF/Excel via JasperReports
• L'envoi de notifications SMS (Twilio) et WebSocket
• L'intégration Google Maps pour le calcul des distances et trajets

---

Technologies

Catégorie	Technologie	Version
Langage	Java	21
Framework	Spring Boot	3.3.7
Base de données	PostgreSQL	42.7.10
Cache	Redis	(Jedis)
Authentification	JWT (jjwt)	0.11.5
ORM	Spring Data JPA / Hibernate	—
Requêtes dynamiques	QueryDSL (Jakarta)	—
Mapping	MapStruct	1.5.2
WebSocket	Netty-SocketIO	2.0.12
SMS	Twilio	10.6.4
Géolocalisation	Google Maps Services	2.2.0
Reporting	JasperReports	7.0.6
Documentation API	SpringDoc OpenAPI (Swagger)	2.3.0
Build	Maven	3.9+
Conteneurisation	Docker (multi-stage, Alpine JRE 21)	—

---

Prérequis

• Java 21 (JDK)
• Maven 3.9+
• PostgreSQL (base turbo-delivery)
• Redis (port 6379)
• (Optionnel) Docker & Docker Compose

---

Installation

git clone https://github.com/Lunion-Lab/turbo-delivery-backend.git
cd turbo-delivery-backend
mvn clean install -DskipTests

---

Configuration

Les fichiers de configuration se trouvent dans src/main/resources/ :

Fichier	Profil	Description
application.yml	défaut	Configuration principale (DB, Redis, Twilio, logs)
application-dev.properties	dev	Port 8081, base de test turbodeliverytest, logs DEBUG
application-prod.properties	production	Port 8081, base prod turbo-delivery, logs INFO

Variables clés à configurer

# PostgreSQL
spring.datasource.url=jdbc:postgresql://<host>:5432/turbo-delivery
spring.datasource.username=<user>
spring.datasource.password=<password>

# Redis
spring.data.redis.host=<host>
spring.data.redis.port=6379

# JWT
app.jwt.secret=<secret>

# Twilio (SMS)
twilio.account-sid=<sid>
twilio.auth-token=<token>
twilio.phone-number=<number>

# Google Maps
google.maps.api-key=<key>

---

Lancer l'application

Profil développement

mvn spring-boot:run -Dspring-boot.run.profiles=dev

Profil production

mvn spring-boot:run -Dspring-boot.run.profiles=production

Le serveur démarre sur le port 8080 (défaut) ou 8081 selon le profil actif.

---

Docker

Build de l'image

docker build -t turbo-delivery-backend .

Lancement

docker run -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://<host>:5432/turbo-delivery \
  -e SPRING_DATASOURCE_USERNAME=<user> \
  -e SPRING_DATASOURCE_PASSWORD=<password> \
  -e SPRING_DATA_REDIS_HOST=<host> \
  turbo-delivery-backend

Le Dockerfile utilise un build multi-étapes : compilation avec maven:3.9-eclipse-temurin-21, exécution avec eclipse-temurin:21-jre-alpine pour une image minimale.

---

Documentation API

Une fois l'application démarrée, la documentation Swagger est disponible à :

http://localhost:8080/swagger-ui.html

---

Architecture

Le projet suit une architecture en couches inspirée du Clean Architecture et du pattern Port-Adapter :

com.lunionlab.turbo/
├── adapters/       → Adaptateurs vers services externes (Twilio, Google Maps, Paiement)
├── config/         → Configuration Spring (Security, Redis, WebSocket, Swagger)
├── converters/     → Convertisseurs de types
├── dto/            → Data Transfer Objects (40+)
├── entities/       → Entités JPA (45+ tables)
├── enums/          → Énumérations métier
├── events/         → Gestion des événements applicatifs
├── exceptions/     → Gestion centralisée des erreurs
├── jobs/           → Tâches planifiées (Dépenses, Facturation, Présence)
├── mappers/        → Mappeurs MapStruct
├── objetvaleur/    → Value objects du domaine
├── port/           → Interfaces ports (21 ports)
├── queries/        → Requêtes personnalisées & logique Jasper
├── repositories/   → Repositories JPA (40+)
├── resources/      → Contrôleurs REST
│   ├── livreur/    → 18 ressources livreurs
│   ├── restaurant/ → 10 ressources restaurants
│   ├── erp/        → 31 ressources ERP
│   └── client/     → Notifications clients
├── services/       → Services métier (40+)
├── usecase/        → Cas d'utilisation
├── utilitaires/    → Fonctions utilitaires
└── vm/             → View models

---

Domaines métier

Domaine	Description
Livreur	Gestion du personnel de livraison : profil, planning, audit, performance
Commande	Commandes externes avec suivi de statut et association client
Course	Missions de livraison assignées aux livreurs, avec notifications temps réel
Paie	Calcul de salaires : charges fixes/variables, avances, déductions
Charge	Dépenses fixes et variables par période et catégorie
EmploiTemps	Plannings journaliers, suivi des heures et disponibilité
FileAttente	Gestion de la file d'attente de livraison (actif, archive, historique)
Contestation	Gestion des litiges de paiement et de livraison
Facture	Génération et suivi des factures
Notification	Notifications multi-canal : SMS (Twilio), WebSocket, Email

---

Tests

# Tous les tests
mvn test

# Profil dev (base H2 in-memory)
mvn test -Dspring.profiles.active=dev

Les tests utilisent une base H2 in-memory avec Mockito pour l'isolation des dépendances.

---

Déploiement

Voir docs/deploy.md pour les instructions complètes de déploiement en production.

Résumé

Le déploiement en production utilise un service systemd (turbobackend-prod.service) piloté par un pipeline GitHub Actions :

• Exécution sous utilisateur non-root (deployer)
• Redémarrage automatique en cas d'échec
• JVM configurée : -Xmx500m -Xms256m
• Logs via journald
• Répertoire de déploiement : /var/www/turbo/prod/backend/

---

Licence

Propriétaire — © Lunion Lab. Tous droits réservés.