# 🏗️ 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