362 lines
11 KiB
Markdown
362 lines
11 KiB
Markdown
# 🏗️ BTPXpress Backend
|
|
|
|
**Backend REST API pour la gestion complète d'entreprises BTP**
|
|
|
|
[](https://quarkus.io/)
|
|
[](https://openjdk.org/)
|
|
[](https://www.postgresql.org/)
|
|
[](../LICENSE)
|
|
|
|
---
|
|
|
|
## 📋 Table des matières
|
|
|
|
- [Vue d'ensemble](#-vue-densemble)
|
|
- [Technologies](#-technologies)
|
|
- [Architecture](#-architecture)
|
|
- [Installation](#-installation)
|
|
- [Configuration](#-configuration)
|
|
- [Lancement](#-lancement)
|
|
- [API REST](#-api-rest)
|
|
- [Concepts métier](#-concepts-métier)
|
|
- [Tests](#-tests)
|
|
- [Documentation](#-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](https://openjdk.org/))
|
|
- ✅ **Maven 3.9+** ([Apache Maven](https://maven.apache.org/))
|
|
- ✅ **PostgreSQL 15** (production) ou H2 (dev)
|
|
- ✅ **Keycloak** (pour l'authentification)
|
|
|
|
### **Vérifier les prérequis**
|
|
|
|
```bash
|
|
java -version # Doit afficher Java 17+
|
|
mvn -version # Doit afficher Maven 3.9+
|
|
psql --version # Doit afficher PostgreSQL 15+
|
|
```
|
|
|
|
### **Cloner le projet**
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd btpxpress/btpxpress-server
|
|
```
|
|
|
|
### **Installer les dépendances**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```properties
|
|
# 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)**
|
|
|
|
```properties
|
|
# 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)
|
|
|
|
```bash
|
|
./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**
|
|
|
|
```bash
|
|
# Compiler
|
|
./mvnw package
|
|
|
|
# Lancer
|
|
java -jar target/quarkus-app/quarkus-run.jar
|
|
```
|
|
|
|
### **Mode natif** (GraalVM)
|
|
|
|
```bash
|
|
./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](./API.md)
|
|
|
|
---
|
|
|
|
## 📚 Concepts métier
|
|
|
|
Le backend BTPXpress est organisé autour de **22 concepts métier** :
|
|
|
|
| # | Concept | Description | Documentation |
|
|
|---|---------|-------------|---------------|
|
|
| 1 | **CHANTIER** | Projets de construction | [📄](./docs/concepts/01-CHANTIER.md) |
|
|
| 2 | **CLIENT** | Gestion des clients | [📄](./docs/concepts/02-CLIENT.md) |
|
|
| 3 | **MATERIEL** | Équipements et matériel | [📄](./docs/concepts/03-MATERIEL.md) |
|
|
| 4 | **RESERVATION_MATERIEL** | Réservations matériel | [📄](./docs/concepts/04-RESERVATION_MATERIEL.md) |
|
|
| 5 | **LIVRAISON** | Logistique et livraisons | [📄](./docs/concepts/05-LIVRAISON.md) |
|
|
| 6 | **FOURNISSEUR** | Gestion fournisseurs | [📄](./docs/concepts/06-FOURNISSEUR.md) |
|
|
| 7 | **STOCK** | Gestion des stocks | [📄](./docs/concepts/07-STOCK.md) |
|
|
| 8 | **BON_COMMANDE** | Bons de commande | [📄](./docs/concepts/08-BON_COMMANDE.md) |
|
|
| 9 | **DEVIS** | Devis et facturation | [📄](./docs/concepts/09-DEVIS.md) |
|
|
| 10 | **BUDGET** | Gestion budgétaire | [📄](./docs/concepts/10-BUDGET.md) |
|
|
| 11 | **EMPLOYE** | Ressources humaines | [📄](./docs/concepts/11-EMPLOYE.md) |
|
|
| 12 | **MAINTENANCE** | Maintenance matériel | [📄](./docs/concepts/12-MAINTENANCE.md) |
|
|
| 13 | **PLANNING** | Planning et événements | [📄](./docs/concepts/13-PLANNING.md) |
|
|
| 14 | **DOCUMENT** | Gestion documentaire | [📄](./docs/concepts/14-DOCUMENT.md) |
|
|
| 15 | **MESSAGE** | Messagerie interne | [📄](./docs/concepts/15-MESSAGE.md) |
|
|
| 16 | **NOTIFICATION** | Notifications | [📄](./docs/concepts/16-NOTIFICATION.md) |
|
|
| 17 | **USER** | Utilisateurs et auth | [📄](./docs/concepts/17-USER.md) |
|
|
| 18 | **ENTREPRISE** | Profils entreprises | [📄](./docs/concepts/18-ENTREPRISE.md) |
|
|
| 19 | **DISPONIBILITE** | Gestion disponibilités | [📄](./docs/concepts/19-DISPONIBILITE.md) |
|
|
| 20 | **ZONE_CLIMATIQUE** | Zones climatiques | [📄](./docs/concepts/20-ZONE_CLIMATIQUE.md) |
|
|
| 21 | **ABONNEMENT** | Abonnements | [📄](./docs/concepts/21-ABONNEMENT.md) |
|
|
| 22 | **SERVICES_TRANSVERSES** | Services utilitaires | [📄](./docs/concepts/22-SERVICES_TRANSVERSES.md) |
|
|
|
|
---
|
|
|
|
## 🧪 Tests
|
|
|
|
### **Exécuter tous les tests**
|
|
|
|
```bash
|
|
./mvnw test
|
|
```
|
|
|
|
### **Tests unitaires uniquement**
|
|
|
|
```bash
|
|
./mvnw test -Dtest=*ServiceTest
|
|
```
|
|
|
|
### **Tests d'intégration uniquement**
|
|
|
|
```bash
|
|
./mvnw test -Dtest=*ResourceTest
|
|
```
|
|
|
|
### **Couverture de code**
|
|
|
|
```bash
|
|
./mvnw verify jacoco:report
|
|
# Rapport: target/site/jacoco/index.html
|
|
```
|
|
|
|
**Voir**: [Guide des tests](./TESTING.md)
|
|
|
|
---
|
|
|
|
## 📖 Documentation
|
|
|
|
### **Documentation disponible**
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [README.md](./README.md) | Ce fichier - Vue d'ensemble |
|
|
| [DEVELOPMENT.md](./DEVELOPMENT.md) | Guide de développement |
|
|
| [DATABASE.md](./DATABASE.md) | Schéma de base de données |
|
|
| [API.md](./API.md) | Documentation API REST complète |
|
|
| [TESTING.md](./TESTING.md) | Guide des tests |
|
|
| [docs/concepts/](./docs/concepts/) | Documentation par concept (22 fichiers) |
|
|
| [docs/architecture/](./docs/architecture/) | Architecture détaillée |
|
|
| [docs/guides/](./docs/guides/) | Guides pratiques |
|
|
|
|
---
|
|
|
|
## 🤝 Contribution
|
|
|
|
Voir le [Guide de contribution](../CONTRIBUTING.md)
|
|
|
|
---
|
|
|
|
## 📄 Licence
|
|
|
|
MIT License - Voir [LICENSE](../LICENSE)
|
|
|
|
---
|
|
|
|
## 👥 Auteurs
|
|
|
|
**BTPXpress Team**
|
|
|
|
---
|
|
|
|
## 🔗 Liens utiles
|
|
|
|
- [Quarkus Documentation](https://quarkus.io/guides/)
|
|
- [Hibernate ORM Panache](https://quarkus.io/guides/hibernate-orm-panache)
|
|
- [Keycloak Documentation](https://www.keycloak.org/documentation)
|
|
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
|
|
|
|
---
|
|
|
|
**Dernière mise à jour**: 2025-09-30
|
|
**Version**: 1.0.0
|
|
|