btpxpress-backend/DEVELOPMENT.md

# 🛠️ GUIDE DE DÉVELOPPEMENT - BTPXPRESS BACKEND

## 📋 Table des matières

- [Prérequis](#prérequis)
- [Installation](#installation)
- [Configuration](#configuration)
- [Lancement](#lancement)
- [Structure du projet](#structure-du-projet)
- [Conventions de code](#conventions-de-code)
- [Workflow de développement](#workflow-de-développement)
- [Debugging](#debugging)
- [Bonnes pratiques](#bonnes-pratiques)

---

## 🔧 Prérequis

### **Logiciels requis**

| Logiciel | Version minimale | Recommandée | Vérification |
|----------|------------------|-------------|--------------|
| **Java JDK** | 17 | 17 LTS | `java -version` |
| **Maven** | 3.8.1 | 3.9.6 | `mvn -version` |
| **PostgreSQL** | 14 | 15 | `psql --version` |
| **Docker** | 20.10 | 24.0 | `docker --version` |
| **Git** | 2.30 | 2.40+ | `git --version` |

### **IDE recommandés**

- **IntelliJ IDEA** (Ultimate ou Community)
- **VS Code** avec extensions Java
- **Eclipse** avec plugin Quarkus

### **Extensions IntelliJ IDEA recommandées**

- Quarkus Tools
- Lombok
- MapStruct Support
- Database Navigator
- SonarLint

---

## 📦 Installation

### **1. Cloner le repository**

```bash
git clone https://github.com/votre-org/btpxpress.git
cd btpxpress/btpxpress-server
```

### **2. Installer les dépendances**

```bash
./mvnw clean install
```

### **3. Configurer la base de données**

#### **Option A : PostgreSQL local**

```bash
# Créer la base de données
createdb btpxpress_dev

# Créer l'utilisateur
psql -c "CREATE USER btpxpress WITH PASSWORD 'btpxpress123';"
psql -c "GRANT ALL PRIVILEGES ON DATABASE btpxpress_dev TO btpxpress;"
```

#### **Option B : Docker Compose**

```bash
docker-compose up -d postgres
```

### **4. Configurer Keycloak**

```bash
# Lancer Keycloak avec Docker
docker-compose up -d keycloak

# Accéder à l'admin console
# URL: http://localhost:8180
# User: admin
# Password: admin
```

---

## ⚙️ Configuration

### **Fichiers de configuration**

```
src/main/resources/
├── application.properties          # Configuration principale
├── application-dev.properties      # Configuration développement
├── application-prod.properties     # Configuration production
└── application-test.properties     # Configuration tests
```

### **Variables d'environnement**

Créer un fichier `.env` à la racine :

```bash
# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=btpxpress_dev
DB_USER=btpxpress
DB_PASSWORD=btpxpress123

# Keycloak
KEYCLOAK_URL=http://localhost:8180
KEYCLOAK_REALM=btpxpress
KEYCLOAK_CLIENT_ID=btpxpress-backend
KEYCLOAK_CLIENT_SECRET=your-secret-here

# Application
QUARKUS_PROFILE=dev
LOG_LEVEL=DEBUG
```

### **Configuration IntelliJ IDEA**

1. **Importer le projet Maven**
   - File → Open → Sélectionner `pom.xml`
   - Cocher "Import Maven projects automatically"

2. **Configurer le JDK**
   - File → Project Structure → Project SDK → Java 17

3. **Activer Lombok**
   - Settings → Plugins → Installer "Lombok"
   - Settings → Build → Compiler → Annotation Processors → Enable annotation processing

4. **Configurer Quarkus Dev Mode**
   - Run → Edit Configurations → Add New → Maven
   - Command line: `quarkus:dev`
   - Working directory: `$PROJECT_DIR$`

---

## 🚀 Lancement

### **Mode développement (Dev Mode)**

```bash
./mvnw quarkus:dev
```

**Fonctionnalités Dev Mode** :
- ✅ Hot reload automatique
- ✅ Dev UI : http://localhost:8080/q/dev
- ✅ Swagger UI : http://localhost:8080/q/swagger-ui
- ✅ Health checks : http://localhost:8080/q/health
- ✅ Metrics : http://localhost:8080/q/metrics

### **Mode production**

```bash
# Build
./mvnw clean package -Pnative

# Run
java -jar target/quarkus-app/quarkus-run.jar
```

### **Avec Docker**

```bash
# Build image
docker build -t btpxpress-server .

# Run container
docker run -p 8080:8080 btpxpress-server
```

---

## 📁 Structure du projet

```
btpxpress-server/
├── src/
│   ├── main/
│   │   ├── java/dev/lions/btpxpress/
│   │   │   ├── adapter/              # Couche Adapter (Hexagonal)
│   │   │   │   ├── http/             # REST Resources (Controllers)
│   │   │   │   └── config/           # Configurations
│   │   │   ├── application/          # Couche Application
│   │   │   │   ├── service/          # Services métier
│   │   │   │   └── mapper/           # MapStruct mappers
│   │   │   └── domain/               # Couche Domain
│   │   │       ├── core/
│   │   │       │   └── entity/       # Entités JPA
│   │   │       └── shared/
│   │   │           └── dto/          # DTOs
│   │   └── resources/
│   │       ├── application.properties
│   │       └── db/migration/         # Scripts Flyway
│   └── test/
│       ├── java/                     # Tests unitaires et intégration
│       └── resources/
├── docs/                             # Documentation
│   ├── concepts/                     # Documentation par concept
│   ├── architecture/                 # Architecture
│   └── guides/                       # Guides
├── pom.xml                           # Configuration Maven
├── README.md                         # README principal
├── DEVELOPMENT.md                    # Ce fichier
└── docker-compose.yml                # Docker Compose
```

---

## 📝 Conventions de code

### **Nommage**

| Élément | Convention | Exemple |
|---------|------------|---------|
| **Classes** | PascalCase | `ChantierService` |
| **Méthodes** | camelCase | `findById()` |
| **Variables** | camelCase | `montantTotal` |
| **Constantes** | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
| **Packages** | lowercase | `dev.lions.btpxpress.domain` |
| **Enum** | PascalCase | `StatutChantier` |
| **Enum values** | UPPER_SNAKE_CASE | `EN_COURS` |

### **Architecture Hexagonale**

```
┌─────────────────────────────────────────────┐
│           ADAPTER LAYER (HTTP)              │
│  ChantierResource, ClientResource, etc.     │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│        APPLICATION LAYER (Services)         │
│  ChantierService, ClientService, etc.       │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│         DOMAIN LAYER (Entities/DTOs)        │
│  Chantier, Client, ChantierDTO, etc.        │
└─────────────────────────────────────────────┘
```

### **Annotations Lombok**

```java
@Data                    // Génère getters, setters, toString, equals, hashCode
@Builder                 // Pattern Builder
@NoArgsConstructor       // Constructeur sans arguments
@AllArgsConstructor      // Constructeur avec tous les arguments
@Slf4j                   // Logger SLF4J
```

### **Validation**

```java
@NotNull(message = "Le nom est obligatoire")
@NotBlank(message = "Le nom ne peut pas être vide")
@Email(message = "Email invalide")
@Size(min = 2, max = 100, message = "Le nom doit contenir entre 2 et 100 caractères")
@Pattern(regexp = "^[0-9]{14}$", message = "SIRET invalide")
```

---

## 🔄 Workflow de développement

### **1. Créer une branche**

```bash
git checkout -b feature/nom-de-la-fonctionnalite
```

### **2. Développer**

1. Créer l'entité JPA (`domain/core/entity/`)
2. Créer le DTO (`domain/shared/dto/`)
3. Créer le Mapper MapStruct (`application/mapper/`)
4. Créer le Service (`application/service/`)
5. Créer le Resource REST (`adapter/http/`)
6. Écrire les tests

### **3. Tester**

```bash
# Tests unitaires
./mvnw test

# Tests d'intégration
./mvnw verify

# Tests avec couverture
./mvnw test jacoco:report
```

### **4. Commit et Push**

```bash
git add .
git commit -m "feat: ajout de la fonctionnalité X"
git push origin feature/nom-de-la-fonctionnalite
```

### **5. Pull Request**

- Créer une PR sur GitHub/GitLab
- Demander une revue de code
- Corriger les remarques
- Merger après validation

---

## 🐛 Debugging

### **Logs**

```java
@Slf4j
public class ChantierService {
  public Chantier create(ChantierDTO dto) {
    log.debug("Création d'un chantier: {}", dto);
    // ...
    log.info("Chantier créé avec succès: {}", chantier.getId());
  }
}
```

### **Debug IntelliJ IDEA**

1. Placer des breakpoints (clic gauche dans la marge)
2. Run → Debug 'Quarkus Dev Mode'
3. Utiliser F8 (Step Over), F7 (Step Into), F9 (Resume)

### **Quarkus Dev UI**

Accéder à http://localhost:8080/q/dev pour :
- Voir les endpoints REST
- Tester les requêtes
- Consulter les logs
- Gérer la base de données

---

## ✅ Bonnes pratiques

### **1. Gestion des transactions**

```java
@Transactional
public Chantier create(ChantierDTO dto) {
  // Code transactionnel
}
```

### **2. Gestion des erreurs**

```java
public Chantier findById(UUID id) {
  return Chantier.findByIdOptional(id)
    .orElseThrow(() -> new NotFoundException("Chantier non trouvé"));
}
```

### **3. Pagination**

```java
public List<Chantier> findAll(int page, int size) {
  return Chantier.findAll()
    .page(page, size)
    .list();
}
```

### **4. Sécurité**

```java
@RolesAllowed({"ADMIN", "MANAGER"})
@Path("/chantiers")
public class ChantierResource {
  // ...
}
```

### **5. Documentation API**

```java
@Operation(summary = "Créer un chantier")
@APIResponse(responseCode = "201", description = "Chantier créé")
@APIResponse(responseCode = "400", description = "Données invalides")
public Response create(ChantierDTO dto) {
  // ...
}
```

---

## 📚 Ressources

- [Documentation Quarkus](https://quarkus.io/guides/)
- [Hibernate ORM Panache](https://quarkus.io/guides/hibernate-orm-panache)
- [RESTEasy Reactive](https://quarkus.io/guides/resteasy-reactive)
- [Keycloak](https://www.keycloak.org/documentation)
- [MapStruct](https://mapstruct.org/)

---

**Dernière mise à jour**: 2025-09-30  
**Version**: 1.0  
**Auteur**: Équipe BTPXpress