🏗️ BTPXpress Backend

Backend REST API pour la gestion complète d'entreprises BTP

---

📋 Table des matières

• Vue d'ensemble
• Technologies
• Architecture
• Installation
• Configuration
• Lancement
• API REST
• Concepts métier
• Tests
• Documentation

---

🎯 Vue d'ensemble

BTPXpress Backend est une API REST complète construite avec Quarkus pour la gestion d'entreprises du secteur BTP (Bâtiment et Travaux Publics). Elle offre :

• ✅ 22 concepts métier couvrant tous les aspects du BTP
• ✅ 95+ entités JPA avec relations complexes
• ✅ 33 services métier avec logique avancée
• ✅ 23 endpoints REST documentés avec OpenAPI/Swagger
• ✅ Architecture hexagonale (Domain-Driven Design)
• ✅ Authentification OAuth2/OIDC via Keycloak
• ✅ Gestion fine des permissions par rôle
• ✅ Base de données PostgreSQL en production
• ✅ H2 en mémoire pour le développement
• ✅ Tests unitaires et d'intégration

---

🛠️ Technologies

Framework & Runtime

• Quarkus 3.15.1 - Framework Java supersonic subatomic
• Java 17 LTS - Langage de programmation
• Maven 3.9.6 - Gestion des dépendances

Persistance

• Hibernate ORM Panache - ORM simplifié
• PostgreSQL 15 - Base de données production
• H2 Database - Base de données développement
• Flyway - Migrations de base de données

Sécurité

• Keycloak OIDC - Authentification et autorisation
• JWT - Tokens d'authentification
• BCrypt - Hachage des mots de passe

API & Documentation

• RESTEasy Reactive - Endpoints REST
• SmallRye OpenAPI - Documentation API (Swagger)
• Jackson - Sérialisation JSON

Monitoring & Observabilité

• Micrometer - Métriques applicatives
• Prometheus - Collecte de métriques
• SmallRye Health - Health checks

Utilitaires

• Lombok - Réduction du boilerplate
• MapStruct - Mapping DTO ↔ Entity
• SLF4J + Logback - Logging

---

🏛️ Architecture

Architecture Hexagonale (Ports & Adapters)

btpxpress-server/
├── src/main/java/dev/lions/btpxpress/
│   ├── domain/                    # 🔵 DOMAINE (Cœur métier)
│   │   ├── core/
│   │   │   ├── entity/           # Entités JPA (95 fichiers)
│   │   │   └── repository/       # Repositories Panache
│   │   └── shared/
│   │       └── dto/              # Data Transfer Objects
│   │
│   ├── application/               # 🟢 APPLICATION (Logique métier)
│   │   ├── service/              # Services métier (33 fichiers)
│   │   ├── mapper/               # Mappers DTO ↔ Entity
│   │   └── exception/            # Exceptions métier
│   │
│   └── adapter/                   # 🟡 ADAPTATEURS (Interfaces externes)
│       ├── http/                 # REST Resources (23 fichiers)
│       └── config/               # Configuration
│
└── src/main/resources/
    ├── application.properties     # Configuration principale
    ├── application-dev.properties # Configuration développement
    └── application-prod.properties # Configuration production

Couches de l'architecture

Couche	Responsabilité	Exemples
Domain	Modèle métier, règles business	Entités, Enums, Repositories
Application	Orchestration, logique applicative	Services, Mappers, Exceptions
Adapter	Communication externe	REST API, Configuration

---

📦 Installation

Prérequis

• ✅ Java 17 ou supérieur (OpenJDK)
• ✅ Maven 3.9+ (Apache Maven)
• ✅ PostgreSQL 15 (production) ou H2 (dev)
• ✅ Keycloak (pour l'authentification)

Vérifier les prérequis

java -version    # Doit afficher Java 17+
mvn -version     # Doit afficher Maven 3.9+
psql --version   # Doit afficher PostgreSQL 15+

Cloner le projet

git clone <repository-url>
cd btpxpress/btpxpress-server

Installer les dépendances

mvn clean install

---

⚙️ Configuration

Fichiers de configuration

Fichier	Environnement	Description
application.properties	Commun	Configuration de base
application-dev.properties	Développement	H2, logs debug
application-prod.properties	Production	PostgreSQL, optimisations

Variables d'environnement principales

# Base de données
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=btpxpress
quarkus.datasource.password=your-password
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/btpxpress

# Keycloak
quarkus.oidc.auth-server-url=https://security.lions.dev/realms/btpxpress
quarkus.oidc.client-id=btpxpress-backend
quarkus.oidc.credentials.secret=your-client-secret

# Application
quarkus.http.port=8080
quarkus.http.cors=true

Configuration H2 (Développement)

# Activé par défaut en mode dev
quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:mem:btpxpress
quarkus.hibernate-orm.database.generation=drop-and-create

---

🚀 Lancement

Mode développement (avec hot reload)

./mvnw quarkus:dev

L'application démarre sur http://localhost:8080

Fonctionnalités du mode dev:

• ✅ Hot reload automatique
• ✅ Dev UI: http://localhost:8080/q/dev
• ✅ Swagger UI: http://localhost:8080/q/swagger-ui
• ✅ H2 Console: http://localhost:8080/q/h2-console

Mode production

# Compiler
./mvnw package

# Lancer
java -jar target/quarkus-app/quarkus-run.jar

Mode natif (GraalVM)

./mvnw package -Pnative
./target/btpxpress-server-1.0.0-SNAPSHOT-runner

---

🔌 API REST

Base URL: http://localhost:8080/api/v1

Documentation interactive

• Swagger UI: http://localhost:8080/q/swagger-ui
• OpenAPI JSON: http://localhost:8080/q/openapi

Endpoints principaux

Ressource	Endpoint	Description
Chantiers	/api/v1/chantiers	Gestion des chantiers
Clients	/api/v1/clients	Gestion des clients
Matériel	/api/v1/materiels	Gestion du matériel
Employés	/api/v1/employes	Gestion RH
Planning	/api/v1/planning	Planning et événements
Documents	/api/v1/documents	Gestion documentaire
Messages	/api/v1/messages	Messagerie interne
Devis	/api/v1/devis	Devis et facturation
Stock	/api/v1/stocks	Gestion des stocks
Maintenance	/api/v1/maintenances	Maintenance matériel

Voir: Documentation API complète

---

📚 Concepts métier

Le backend BTPXpress est organisé autour de 22 concepts métier :

#	Concept	Description	Documentation
1	CHANTIER	Projets de construction	📄
2	CLIENT	Gestion des clients	📄
3	MATERIEL	Équipements et matériel	📄
4	RESERVATION_MATERIEL	Réservations matériel	📄
5	LIVRAISON	Logistique et livraisons	📄
6	FOURNISSEUR	Gestion fournisseurs	📄
7	STOCK	Gestion des stocks	📄
8	BON_COMMANDE	Bons de commande	📄
9	DEVIS	Devis et facturation	📄
10	BUDGET	Gestion budgétaire	📄
11	EMPLOYE	Ressources humaines	📄
12	MAINTENANCE	Maintenance matériel	📄
13	PLANNING	Planning et événements	📄
14	DOCUMENT	Gestion documentaire	📄
15	MESSAGE	Messagerie interne	📄
16	NOTIFICATION	Notifications	📄
17	USER	Utilisateurs et auth	📄
18	ENTREPRISE	Profils entreprises	📄
19	DISPONIBILITE	Gestion disponibilités	📄
20	ZONE_CLIMATIQUE	Zones climatiques	📄
21	ABONNEMENT	Abonnements	📄
22	SERVICES_TRANSVERSES	Services utilitaires	📄

---

🧪 Tests

Exécuter tous les tests

./mvnw test

Tests unitaires uniquement

./mvnw test -Dtest=*ServiceTest

Tests d'intégration uniquement

./mvnw test -Dtest=*ResourceTest

Couverture de code

./mvnw verify jacoco:report
# Rapport: target/site/jacoco/index.html

Voir: Guide des tests

---

📖 Documentation

Documentation disponible

Document	Description
README.md	Ce fichier - Vue d'ensemble
DEVELOPMENT.md	Guide de développement
DATABASE.md	Schéma de base de données
API.md	Documentation API REST complète
TESTING.md	Guide des tests
docs/concepts/	Documentation par concept (22 fichiers)
docs/architecture/	Architecture détaillée
docs/guides/	Guides pratiques

---

🤝 Contribution

Voir le Guide de contribution

---

📄 Licence

MIT License - Voir LICENSE

---

👥 Auteurs

BTPXpress Team

---

🔗 Liens utiles

• Quarkus Documentation
• Hibernate ORM Panache
• Keycloak Documentation
• PostgreSQL Documentation

---

Dernière mise à jour: 2025-09-30
Version: 1.0.0