btpxpress-backend/docs/concepts/01-CHANTIER.md

# 🏗️ CONCEPT: CHANTIER

## 📌 Vue d'ensemble

Le concept **CHANTIER** est le **cœur métier** de l'application BTPXpress. Il représente un projet de construction BTP avec toutes ses caractéristiques : localisation, dates, budget, statut, phases, et relations avec les clients, devis, factures, etc.

**Importance**: ⭐⭐⭐⭐⭐ (Concept central)

---

## 🗂️ Fichiers concernés

### **Entités JPA** (`domain/core/entity/`)
| Fichier | Description | Lignes |
|---------|-------------|--------|
| `Chantier.java` | Entité principale représentant un chantier BTP | 224 |
| `StatutChantier.java` | Enum des statuts possibles d'un chantier | 24 |
| `TypeChantier.java` | Entité type de chantier (configurable) | ~150 |
| `TypeChantierBTP.java` | Enum types BTP prédéfinis | ~50 |
| `Phase.java` | Phase générique de chantier | ~100 |
| `PhaseChantier.java` | Phase spécifique à un chantier | ~180 |
| `PhaseTemplate.java` | Template de phase réutilisable | ~120 |
| `SousPhaseTemplate.java` | Sous-phase de template | ~80 |
| `TacheTemplate.java` | Template de tâche | ~100 |
| `StatutPhaseChantier.java` | Enum statuts de phase | ~40 |
| `TypePhaseChantier.java` | Enum types de phase | ~30 |
| `PrioritePhase.java` | Enum priorités de phase | ~25 |

### **DTOs** (`domain/shared/dto/`)
| Fichier | Description |
|---------|-------------|
| `ChantierCreateDTO.java` | DTO pour créer/modifier un chantier |
| `PhaseChantierDTO.java` | DTO pour les phases de chantier |

### **Services** (`application/service/`)
| Fichier | Description |
|---------|-------------|
| `ChantierService.java` | Service métier principal pour les chantiers |
| `PhaseChantierService.java` | Service pour la gestion des phases |
| `PhaseTemplateService.java` | Service pour les templates de phases |
| `TacheTemplateService.java` | Service pour les templates de tâches |

### **Resources (API REST)** (`adapter/http/`)
| Fichier | Description |
|---------|-------------|
| `ChantierResource.java` | Endpoints REST pour les chantiers |
| `PhaseChantierResource.java` | Endpoints REST pour les phases |

---

## 📊 Modèle de données

### **Entité Chantier**

<augment_code_snippet path="btpxpress-server/src/main/java/dev/lions/btpxpress/domain/core/entity/Chantier.java" mode="EXCERPT">
````java
@Entity
@Table(name = "chantiers")
@Data
@Builder
public class Chantier extends PanacheEntityBase {
  
  @Id
  @GeneratedValue(strategy = GenerationType.UUID)
  private UUID id;
  
  @NotBlank(message = "Le nom du chantier est obligatoire")
  @Column(name = "nom", nullable = false, length = 200)
  private String nom;
  
  @Column(name = "code", unique = true, length = 50)
  private String code;
  
  @NotBlank(message = "L'adresse du chantier est obligatoire")
  @Column(name = "adresse", nullable = false, length = 500)
  private String adresse;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "statut", nullable = false)
  private StatutChantier statut = StatutChantier.PLANIFIE;
  
  @Column(name = "montant_prevu", precision = 10, scale = 2)
  private BigDecimal montantPrevu;
  
  // Relations
  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "client_id", nullable = false)
  private Client client;
  
  @OneToMany(mappedBy = "chantier", cascade = CascadeType.ALL)
  private List<Devis> devis;
  
  @OneToMany(mappedBy = "chantier", cascade = CascadeType.ALL)
  private List<Facture> factures;
  // ...
}
````
</augment_code_snippet>

### **Enum StatutChantier**

<augment_code_snippet path="btpxpress-server/src/main/java/dev/lions/btpxpress/domain/core/entity/StatutChantier.java" mode="EXCERPT">
````java
public enum StatutChantier {
  PLANIFIE("Planifié"),
  EN_COURS("En cours"),
  TERMINE("Terminé"),
  ANNULE("Annulé"),
  SUSPENDU("Suspendu");

  private final String label;
  
  StatutChantier(String label) {
    this.label = label;
  }
  
  public String getLabel() {
    return label;
  }
}
````
</augment_code_snippet>

### **Champs principaux**

| Champ | Type | Obligatoire | Description |
|-------|------|-------------|-------------|
| `id` | UUID | Oui | Identifiant unique |
| `nom` | String(200) | Oui | Nom du chantier |
| `code` | String(50) | Non | Code unique du chantier |
| `description` | TEXT | Non | Description détaillée |
| `adresse` | String(500) | Oui | Adresse du chantier |
| `codePostal` | String(10) | Non | Code postal |
| `ville` | String(100) | Non | Ville |
| `dateDebut` | LocalDate | Oui | Date de début |
| `dateDebutPrevue` | LocalDate | Non | Date de début prévue |
| `dateDebutReelle` | LocalDate | Non | Date de début réelle |
| `dateFinPrevue` | LocalDate | Non | Date de fin prévue |
| `dateFinReelle` | LocalDate | Non | Date de fin réelle |
| `statut` | StatutChantier | Oui | Statut actuel (défaut: PLANIFIE) |
| `montantPrevu` | BigDecimal | Non | Montant prévu |
| `montantReel` | BigDecimal | Non | Montant réel |
| `typeChantier` | TypeChantierBTP | Non | Type de chantier |
| `actif` | Boolean | Oui | Chantier actif (défaut: true) |
| `dateCreation` | LocalDateTime | Auto | Date de création |
| `dateModification` | LocalDateTime | Auto | Date de modification |

### **Relations**

| Relation | Type | Entité cible | Description |
|----------|------|--------------|-------------|
| `client` | ManyToOne | Client | Client propriétaire (obligatoire) |
| `chefChantier` | ManyToOne | User | Chef de chantier responsable |
| `devis` | OneToMany | Devis | Liste des devis associés |
| `factures` | OneToMany | Facture | Liste des factures |

---

## 🔌 API REST

### **Base URL**: `/api/v1/chantiers`

### **Endpoints disponibles**

| Méthode | Endpoint | Description | Authentification |
|---------|----------|-------------|------------------|
| GET | `/api/v1/chantiers` | Liste tous les chantiers | Optionnelle |
| GET | `/api/v1/chantiers/actifs` | Liste chantiers actifs | Optionnelle |
| GET | `/api/v1/chantiers/{id}` | Détails d'un chantier | Optionnelle |
| POST | `/api/v1/chantiers` | Créer un chantier | Optionnelle |
| PUT | `/api/v1/chantiers/{id}` | Modifier un chantier | Optionnelle |
| DELETE | `/api/v1/chantiers/{id}` | Supprimer un chantier | Optionnelle |
| GET | `/api/v1/chantiers/statut/{statut}` | Chantiers par statut | Optionnelle |
| GET | `/api/v1/chantiers/client/{clientId}` | Chantiers d'un client | Optionnelle |
| GET | `/api/v1/chantiers/search` | Recherche de chantiers | Optionnelle |
| GET | `/api/v1/chantiers/stats` | Statistiques chantiers | Optionnelle |

### **Paramètres de requête (Query Params)**

| Paramètre | Type | Description | Exemple |
|-----------|------|-------------|---------|
| `search` | String | Terme de recherche | `?search=villa` |
| `statut` | String | Filtrer par statut | `?statut=EN_COURS` |
| `clientId` | UUID | Filtrer par client | `?clientId=uuid` |

---

## 💻 Exemples d'utilisation

### **1. Récupérer tous les chantiers**

```bash
curl -X GET http://localhost:8080/api/v1/chantiers \
  -H "Accept: application/json"
```

**Réponse** (200 OK):
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nom": "Construction Villa Moderne",
    "code": "CHANT-2025-001",
    "adresse": "123 Avenue des Champs",
    "codePostal": "75008",
    "ville": "Paris",
    "statut": "EN_COURS",
    "montantPrevu": 250000.00,
    "dateDebut": "2025-01-15",
    "dateFinPrevue": "2025-12-31",
    "actif": true
  }
]
```

### **2. Créer un nouveau chantier**

```bash
curl -X POST http://localhost:8080/api/v1/chantiers \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Rénovation Appartement",
    "adresse": "45 Rue de la Paix",
    "codePostal": "75002",
    "ville": "Paris",
    "dateDebut": "2025-10-01",
    "dateFinPrevue": "2025-12-15",
    "montantPrevu": 75000.00,
    "clientId": "client-uuid-here",
    "statut": "PLANIFIE"
  }'
```

**Réponse** (201 Created):
```json
{
  "id": "generated-uuid",
  "nom": "Rénovation Appartement",
  "statut": "PLANIFIE",
  "dateCreation": "2025-09-30T10:30:00"
}
```

### **3. Rechercher des chantiers**

```bash
# Par nom
curl -X GET "http://localhost:8080/api/v1/chantiers?search=villa"

# Par statut
curl -X GET "http://localhost:8080/api/v1/chantiers?statut=EN_COURS"

# Par client
curl -X GET "http://localhost:8080/api/v1/chantiers?clientId=uuid-client"
```

### **4. Obtenir les statistiques**

```bash
curl -X GET http://localhost:8080/api/v1/chantiers/stats
```

**Réponse**:
```json
{
  "totalChantiers": 45,
  "chantiersActifs": 38,
  "enCours": 12,
  "planifies": 8,
  "termines": 15,
  "suspendus": 2,
  "annules": 1,
  "montantTotalPrevu": 5250000.00,
  "montantTotalReel": 4890000.00
}
```

---

## 🔧 Services métier

### **ChantierService**

**Méthodes principales**:

| Méthode | Description | Retour |
|---------|-------------|--------|
| `findAll()` | Récupère tous les chantiers | `List<Chantier>` |
| `findActifs()` | Récupère chantiers actifs | `List<Chantier>` |
| `findById(UUID id)` | Récupère par ID | `Optional<Chantier>` |
| `create(ChantierCreateDTO dto)` | Crée un chantier | `Chantier` |
| `update(UUID id, ChantierCreateDTO dto)` | Met à jour | `Chantier` |
| `delete(UUID id)` | Supprime (soft delete) | `void` |
| `findByStatut(StatutChantier statut)` | Filtre par statut | `List<Chantier>` |
| `findByClient(UUID clientId)` | Chantiers d'un client | `List<Chantier>` |
| `search(String term)` | Recherche textuelle | `List<Chantier>` |
| `getStatistics()` | Statistiques globales | `Object` |

---

## 🔐 Permissions requises

| Permission | Description | Rôles autorisés |
|------------|-------------|-----------------|
| `CHANTIERS_READ` | Lecture des chantiers | ADMIN, MANAGER, CHEF_CHANTIER, COMPTABLE, OUVRIER |
| `CHANTIERS_CREATE` | Création de chantiers | ADMIN, MANAGER |
| `CHANTIERS_UPDATE` | Modification de chantiers | ADMIN, MANAGER, CHEF_CHANTIER |
| `CHANTIERS_DELETE` | Suppression de chantiers | ADMIN, MANAGER |
| `CHANTIERS_PHASES` | Gestion des phases | ADMIN, MANAGER, CHEF_CHANTIER |
| `CHANTIERS_BUDGET` | Gestion du budget | ADMIN, MANAGER, COMPTABLE |

---

## 📈 Relations avec autres concepts

### **Dépendances directes**:
- **CLIENT** ⬅️ Un chantier appartient à un client (obligatoire)
- **USER** ⬅️ Un chantier peut avoir un chef de chantier
- **DEVIS** ➡️ Un chantier peut avoir plusieurs devis
- **FACTURE** ➡️ Un chantier peut avoir plusieurs factures
- **PHASE** ➡️ Un chantier est divisé en phases
- **BUDGET** ➡️ Un chantier a un budget associé
- **PLANNING** ➡️ Un chantier a un planning
- **DOCUMENT** ➡️ Un chantier peut avoir des documents (plans, photos, etc.)

---

## 🧪 Tests

### **Tests unitaires**
- Fichier: `ChantierServiceTest.java`
- Couverture: Logique métier, validations, calculs

### **Tests d'intégration**
- Fichier: `ChantierResourceTest.java`
- Couverture: Endpoints REST, sérialisation JSON

### **Commande pour exécuter les tests**:
```bash
cd btpxpress-server
./mvnw test -Dtest=ChantierServiceTest
./mvnw test -Dtest=ChantierResourceTest
```

---

## 📚 Références

- [API Documentation complète](../API.md#chantiers)
- [Schéma de base de données](../DATABASE.md#table-chantiers)
- [Guide d'architecture](../architecture/domain-model.md#chantier)
- [Service ChantierService](../../src/main/java/dev/lions/btpxpress/application/service/ChantierService.java)
- [Resource ChantierResource](../../src/main/java/dev/lions/btpxpress/adapter/http/ChantierResource.java)

---

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