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

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

README.md

🏗️ BTPXpress Backend

📋 Table des matières

🎯 Vue d'ensemble