Initial commit
This commit is contained in:
dahoud
420
DEVELOPMENT.md
Normal file
420
DEVELOPMENT.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# 🛠️ 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
|
||||
|
||||
Reference in New Issue
Block a user