lionsdev/btpxpress-backend

Fork 0

Files

dahoud f2bb633142 Initial commit

2025-10-01 01:37:34 +00:00

10 KiB

Raw Blame History

🛠️ 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

Importer le projet Maven
- File → Open → Sélectionner pom.xml
- Cocher "Import Maven projects automatically"
Configurer le JDK
- File → Project Structure → Project SDK → Java 17
Activer Lombok
- Settings → Plugins → Installer "Lombok"
- Settings → Build → Compiler → Annotation Processors → Enable annotation processing
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

Créer l'entité JPA (domain/core/entity/)
Créer le DTO (domain/shared/dto/)
Créer le Mapper MapStruct (application/mapper/)
Créer le Service (application/service/)
Créer le Resource REST (adapter/http/)
É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

Placer des breakpoints (clic gauche dans la marge)
Run → Debug 'Quarkus Dev Mode'
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

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

10 KiB Raw Blame History