300 lines
11 KiB
Markdown
300 lines
11 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Xpeditis is a Spring Boot-based logistics/shipping application built with a modular Maven architecture. The project follows Hexagonal Architecture (Clean Architecture) principles with clear separation of concerns.
|
|
|
|
## Architecture
|
|
|
|
### Modular Structure
|
|
The project is organized into Maven modules:
|
|
|
|
- **bootstrap**: Main application entry point and configuration (XpeditisApplication.java)
|
|
- **application**: REST controllers and web layer (AuthenticationRestController, UserRestController)
|
|
- **domain**: Core business logic split into:
|
|
- **api**: Service interfaces (UserService, AuthenticationService, etc.)
|
|
- **data**: DTOs and exceptions (UserAccount, AuthenticationRequest/Response)
|
|
- **service**: Service implementations (UserServiceImpl, AuthenticationServiceImpl)
|
|
- **spi**: Repository interfaces (UserRepository, AuthenticationRepository)
|
|
- **infrastructure**: Data access layer with JPA entities, repositories, and external integrations
|
|
- **common**: Shared utilities (CommonUtil)
|
|
|
|
### Key Technologies
|
|
- Spring Boot 3.4.1 with Java 23
|
|
- Spring Security with JWT authentication
|
|
- JPA/Hibernate for data persistence
|
|
- MapStruct for entity mapping
|
|
- Lombok for boilerplate reduction
|
|
- Flyway for database migrations
|
|
- MySQL (prod) / H2 (dev) databases
|
|
|
|
## Development Commands
|
|
|
|
### Build and Test
|
|
```bash
|
|
# Clean build and install all modules
|
|
./mvnw clean install
|
|
|
|
# Run tests
|
|
./mvnw test
|
|
|
|
# Run single test class
|
|
./mvnw test -Dtest=UserServiceImplTest
|
|
|
|
# Run specific test method
|
|
./mvnw test -Dtest=UserServiceImplTest#shouldCreateUser
|
|
```
|
|
|
|
### Database Management
|
|
```bash
|
|
# Development (H2) - migrate database
|
|
./mvnw clean install flyway:migrate '-Dflyway.configFiles=flyway-h2.conf' -Pdev
|
|
|
|
# Production (MySQL) - migrate database
|
|
./mvnw clean install flyway:migrate -Pprod
|
|
|
|
# Start application with dev profile (default)
|
|
./mvnw spring-boot:run
|
|
|
|
# Start with production profile
|
|
./mvnw spring-boot:run -Pprod
|
|
```
|
|
|
|
### Docker Operations
|
|
```bash
|
|
# Build and start services with Docker Compose
|
|
docker-compose up --build
|
|
|
|
# Start database only
|
|
docker-compose up db
|
|
|
|
# View logs
|
|
docker-compose logs -f back
|
|
```
|
|
|
|
## Development Profiles
|
|
|
|
- **dev** (default): Uses H2 in-memory database, simplified configuration
|
|
- **prod**: Uses MySQL database, includes Flyway migrations, production-ready settings
|
|
|
|
## Key Configuration Files
|
|
|
|
- `bootstrap/src/main/resources/application.yml`: Main configuration
|
|
- `bootstrap/src/main/resources/application-dev.yml`: Development overrides
|
|
- `bootstrap/src/main/resources/application-prod.yml`: Production overrides
|
|
- `infrastructure/flyway.conf`: Database migration configuration
|
|
- `compose.yml`: Docker services configuration
|
|
|
|
## API Documentation
|
|
|
|
Swagger UI is available at: http://localhost:8080/swagger-ui.html
|
|
|
|
## Security Implementation
|
|
|
|
The application uses JWT-based authentication with:
|
|
- JWT token generation and validation (JwtUtil)
|
|
- Security configuration (SecurityConfiguration)
|
|
- Authentication filter (JwtAuthenticationFilter)
|
|
- Logout service (LogoutService)
|
|
- Role-based access control with Permission enum
|
|
|
|
## Testing Strategy
|
|
|
|
- Unit tests for service layer implementations (AddressServiceImplTest, etc.)
|
|
- Repository tests for data access layer (AddressJpaRepositoryTest, etc.)
|
|
- Integration tests in bootstrap module (LeBlrApplicationTests)
|
|
- Use AssertJ for fluent assertions
|
|
|
|
## Database Schema
|
|
|
|
Database migrations are in `infrastructure/src/main/resources/db/migration/`:
|
|
- `structure/V1__INIT_DB_SCHEMA.sql`: Initial schema
|
|
- `data/V1.1__INIT_DB_DATA.sql`: Initial data
|
|
|
|
## Logging
|
|
|
|
Structured logging configuration in `logback-spring.xml` with:
|
|
- Production logs written to `./logs/prod/`
|
|
- Request logging via CommonsRequestLoggingFilter
|
|
- Configurable log levels per package
|
|
|
|
## 🏗️ Checklist Architecture Hexagonale - Étapes de Validation Pré-Codage
|
|
|
|
### 📋 Phase 1 : Analyse et Compréhension du Contexte
|
|
|
|
#### ✅ 1.1 Identification du Domaine Métier
|
|
- [ ] Clarifier le domaine d'activité : Quel est le métier principal ?
|
|
- [ ] Identifier les entités métier principales : Quels sont les objets centraux ?
|
|
- [ ] Définir les règles de gestion : Quelles sont les contraintes business ?
|
|
- [ ] Mapper les cas d'usage : Que doit faire l'application ?
|
|
|
|
#### ✅ 1.2 Analyse des Besoins d'Intégration
|
|
- [ ] Identifier les acteurs externes : Qui utilise l'application ?
|
|
- [ ] Répertorier les services externes : BDD, APIs, systèmes de fichiers ?
|
|
- [ ] Définir les interfaces d'entrée : REST, GraphQL, CLI ?
|
|
- [ ] Spécifier les interfaces de sortie : Persistance, notifications, etc.
|
|
|
|
### 📐 Phase 2 : Conception Architecturale
|
|
|
|
#### ✅ 2.1 Structure des Modules Maven
|
|
- [ ] Valider la structure 4 modules :
|
|
- `domain` (cœur hexagonal)
|
|
- `application` (couche application)
|
|
- `infrastructure` (couche infrastructure)
|
|
- `bootstrap` (module de lancement)
|
|
|
|
#### ✅ 2.2 Définition des Ports
|
|
- [ ] Identifier les Ports API (interfaces exposées par le domaine) :
|
|
- Services métier que le domaine expose
|
|
- Interfaces appelées par les adaptateurs d'entrée
|
|
- [ ] Identifier les Ports SPI (interfaces requises par le domaine) :
|
|
- Repositories pour la persistance
|
|
- Services externes (notifications, intégrations)
|
|
- Interfaces que le domaine définit mais n'implémente pas
|
|
|
|
#### ✅ 2.3 Conception des Adaptateurs
|
|
- [ ] Adaptateurs d'Entrée (Driving) :
|
|
- Contrôleurs REST
|
|
- Interfaces utilisateur
|
|
- Tests automatisés
|
|
- [ ] Adaptateurs de Sortie (Driven) :
|
|
- Implémentations des repositories
|
|
- Clients pour services externes
|
|
- Systèmes de fichiers/messaging
|
|
|
|
### 🏛️ Phase 3 : Architecture en Couches
|
|
|
|
#### ✅ 3.1 Module Domain (Cœur)
|
|
- [ ] Vérifier l'isolation complète : Aucune dépendance externe
|
|
- [ ] Structure du package :
|
|
```
|
|
com.{project}.domain/
|
|
├── model/ # Entités métier
|
|
├── service/ # Services du domaine
|
|
├── port/
|
|
│ ├── in/ # Ports d'entrée (API)
|
|
│ └── out/ # Ports de sortie (SPI)
|
|
└── exception/ # Exceptions métier
|
|
```
|
|
|
|
#### ✅ 3.2 Module Application
|
|
- [ ] Responsabilités claires : Exposition des services
|
|
- [ ] Structure du package :
|
|
```
|
|
com.{project}.application/
|
|
├── controller/ # Contrôleurs REST
|
|
├── dto/ # Data Transfer Objects
|
|
├── mapper/ # Mappers DTO ↔ Domain
|
|
└── config/ # Configuration Spring
|
|
```
|
|
|
|
#### ✅ 3.3 Module Infrastructure
|
|
- [ ] Implémentation des SPI : Tous les ports de sortie
|
|
- [ ] Structure du package :
|
|
```
|
|
com.{project}.infrastructure/
|
|
├── adapter/
|
|
│ ├── in/ # Adaptateurs d'entrée (si applicable)
|
|
│ └── out/ # Adaptateurs de sortie
|
|
├── repository/ # Implémentations JPA
|
|
├── entity/ # Entités JPA
|
|
└── mapper/ # Mappers JPA ↔ Domain
|
|
```
|
|
|
|
#### ✅ 3.4 Module bootstrap
|
|
- [ ] Point d'entrée unique : Classe @SpringBootApplication
|
|
- [ ] Assemblage des dépendances : Configuration complète
|
|
- [ ] Dépendances vers tous les modules
|
|
|
|
### 🔧 Phase 4 : Validation Technique
|
|
|
|
#### ✅ 4.1 Gestion des Dépendances
|
|
- [ ] Module domain : Aucune dépendance externe (sauf tests)
|
|
- [ ] Module application : Dépend uniquement de domain
|
|
- [ ] Module infrastructure : Dépend uniquement de domain
|
|
- [ ] Module bootstrap : Dépend de tous les autres modules
|
|
|
|
#### ✅ 4.2 Respect des Patterns
|
|
- [ ] Domain-Driven Design : Entités, Value Objects, Aggregates
|
|
- [ ] SOLID Principles : SRP, DIP, ISP appliqués
|
|
- [ ] Repository Pattern : Abstraction de la persistance
|
|
- [ ] Clean Architecture : Règle de dépendance respectée
|
|
|
|
#### ✅ 4.3 Configuration Spring
|
|
- [ ] Injection de dépendance : Utilisation de @Configuration
|
|
- [ ] Éviter @Component dans le domaine
|
|
- [ ] Gestion des transactions : @Transactional dans l'application
|
|
|
|
### 🧪 Phase 5 : Stratégie de Test
|
|
|
|
#### ✅ 5.1 Tests par Couche
|
|
- [ ] Tests unitaires du domaine : Sans dépendances externes
|
|
- [ ] Tests d'intégration : Par adaptateur spécifique
|
|
- [ ] Tests end-to-end : Flux complets
|
|
- [ ] Mocking strategy : Interfaces bien définies
|
|
|
|
#### ✅ 5.2 Testabilité
|
|
- [ ] Isolation du domaine : Tests sans Spring Context
|
|
- [ ] Adaptateurs mockables : Interfaces clairement définies
|
|
- [ ] Données de test : Jeux de données cohérents
|
|
|
|
### 📝 Phase 6 : Naming et Conventions
|
|
|
|
#### ✅ 6.1 Conventions de Nommage
|
|
- [ ] Ports : Suffixe "Port" ou noms explicites d'interfaces
|
|
- [ ] Adaptateurs : Suffixe "Adapter"
|
|
- [ ] Services : Suffixe "Service"
|
|
- [ ] Repositories : Suffixe "Repository"
|
|
|
|
#### ✅ 6.2 Structure des Packages
|
|
- [ ] Cohérence : Nommage uniforme entre modules
|
|
- [ ] Lisibilité : Structure claire et intuitive
|
|
- [ ] Séparation : Concerns bien séparés
|
|
|
|
### 🎯 Phase 7 : Questions de Validation Finale
|
|
|
|
#### ✅ 7.1 Questions Critiques à Se Poser
|
|
- [ ] Le domaine est-il complètement isolé ?
|
|
- [ ] Les dépendances pointent-elles vers l'intérieur ?
|
|
- [ ] Peut-on tester le domaine sans Spring ?
|
|
- [ ] Peut-on changer de base de données sans impact sur le domaine ?
|
|
- [ ] Peut-on ajouter une nouvelle interface (GraphQL) facilement ?
|
|
|
|
#### ✅ 7.2 Validation des Flux
|
|
- [ ] Flux d'entrée : HTTP → Contrôleur → Service → Port API
|
|
- [ ] Flux de sortie : Port SPI → Adaptateur → Base/Service externe
|
|
- [ ] Mapping : DTO ↔ Domain ↔ JPA entities clairement défini
|
|
|
|
### 🚦 Phase 8 : Checklist Pré-Codage
|
|
|
|
#### ✅ 8.1 Avant de Commencer
|
|
- [ ] Architecture validée avec le demandeur
|
|
- [ ] Modules Maven structure approuvée
|
|
- [ ] Ports et Adaptateurs identifiés et documentés
|
|
- [ ] Stack technique confirmée (Spring Boot, H2, MapStruct)
|
|
- [ ] Stratégie de tests définie
|
|
|
|
#### ✅ 8.2 Ordre de Développement Recommandé
|
|
1. Module domain : Entités, services, ports
|
|
2. Module infrastructure : Adaptateurs de sortie, repositories
|
|
3. Module application : Contrôleurs, DTOs, mappers
|
|
4. Module bootstrap : Configuration, assemblage
|
|
5. Tests : Unitaires → Intégration → E2E
|
|
|
|
### 💡 Points d'Attention Spéciaux
|
|
|
|
#### ⚠️ Pièges à Éviter
|
|
- Dépendances circulaires entre modules
|
|
- Logique métier dans les adaptateurs
|
|
- Annotations Spring dans le domaine
|
|
- Couplage fort entre couches
|
|
- Tests qui nécessitent le contexte Spring pour le domaine
|
|
|
|
#### 🎯 Objectifs à Atteindre
|
|
- Domaine pur et testable isolément
|
|
- Flexibilité pour changer d'adaptateurs
|
|
- Maintenabilité et évolutivité
|
|
- Séparation claire des responsabilités
|
|
- Code réutilisable et modulaire |