lionsdev/btpxpress-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
dahoud
2025-10-01 01:37:34 +00:00
commit f2bb633142
310 changed files with 86051 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

361
README.md Normal file
View File

@@ -0,0 +1,361 @@
# 🏗️ BTPXpress Backend
**Backend REST API pour la gestion complète d'entreprises BTP**
[![Quarkus](https://img.shields.io/badge/Quarkus-3.15.1-blue)](https://quarkus.io/)
[![Java](https://img.shields.io/badge/Java-17-orange)](https://openjdk.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15-blue)](https://www.postgresql.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](../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