btpxpress-backend/DEVELOPMENT.md

🛠️ GUIDE DE DÉVELOPPEMENT - BTPXPRESS BACKEND

📋 Table des matières

• Prérequis
• Installation
• Configuration
• Lancement
• Structure du projet
• Conventions de code
• Workflow de développement
• Debugging
• 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

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

2. Installer les dépendances

./mvnw clean install

3. Configurer la base de données

Option A : PostgreSQL local

# 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

docker-compose up -d postgres

4. Configurer Keycloak

# 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 :

# 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)

./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

# Build
./mvnw clean package -Pnative

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

Avec Docker

# 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

@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

@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

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

# Tests unitaires
./mvnw test

# Tests d'intégration
./mvnw verify

# Tests avec couverture
./mvnw test jacoco:report

4. Commit et Push

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

@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

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

2. Gestion des erreurs

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

3. Pagination

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

4. Sécurité

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

5. Documentation API

@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
• Hibernate ORM Panache
• RESTEasy Reactive
• Keycloak
• MapStruct

---

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