btpxpress-backend/docs/concepts/05-LIVRAISON.md

# 🚚 CONCEPT: LIVRAISON

## 📌 Vue d'ensemble

Le concept **LIVRAISON** gère la logistique et le suivi des livraisons de matériel sur les chantiers. Il couvre le transport, le suivi en temps réel, et la gestion des transporteurs.

**Importance**: ⭐⭐⭐ (Concept important)

---

## 🗂️ Fichiers concernés

### **Entités JPA** (`domain/core/entity/`)
| Fichier | Description | Lignes |
|---------|-------------|--------|
| `LivraisonMateriel.java` | Entité principale de livraison | ~200 |
| `StatutLivraison.java` | Enum statuts (PLANIFIEE, EN_PREPARATION, EN_TRANSIT, LIVREE, ANNULEE, RETARDEE) | ~30 |
| `ModeLivraison.java` | Enum modes de livraison | ~25 |
| `TypeTransport.java` | Enum types de transport | ~20 |

### **Services** (`application/service/`)
| Fichier | Description |
|---------|-------------|
| `LivraisonMaterielService.java` | Service métier pour les livraisons |

---

## 📊 Modèle de données

### **Entité LivraisonMateriel**

```java
@Entity
@Table(name = "livraisons_materiel")
public class LivraisonMateriel extends PanacheEntityBase {
  
  @Id
  @GeneratedValue(strategy = GenerationType.UUID)
  private UUID id;
  
  @ManyToOne
  @JoinColumn(name = "reservation_id")
  private ReservationMateriel reservation;
  
  @Column(name = "date_livraison_prevue", nullable = false)
  private LocalDateTime dateLivraisonPrevue;
  
  @Column(name = "date_livraison_reelle")
  private LocalDateTime dateLivraisonReelle;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "statut", nullable = false)
  private StatutLivraison statut = StatutLivraison.PLANIFIEE;
  
  @Column(name = "transporteur", length = 200)
  private String transporteur;
  
  @Column(name = "numero_suivi", length = 100)
  private String numeroSuivi;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "mode_livraison")
  private ModeLivraison modeLivraison;
  
  @Column(name = "adresse_livraison", length = 500)
  private String adresseLivraison;
  
  @Column(name = "cout_livraison", precision = 10, scale = 2)
  private BigDecimal coutLivraison;
}
```

### **Enum StatutLivraison**

```java
public enum StatutLivraison {
  PLANIFIEE,        // Livraison planifiée
  EN_PREPARATION,   // En cours de préparation
  EN_TRANSIT,       // En transit
  LIVREE,           // Livrée avec succès
  ANNULEE,          // Livraison annulée
  RETARDEE          // Livraison retardée
}
```

### **Champs principaux**

| Champ | Type | Obligatoire | Description |
|-------|------|-------------|-------------|
| `id` | UUID | Oui | Identifiant unique |
| `reservation` | ReservationMateriel | Non | Réservation associée |
| `dateLivraisonPrevue` | LocalDateTime | Oui | Date/heure prévue |
| `dateLivraisonReelle` | LocalDateTime | Non | Date/heure réelle |
| `statut` | StatutLivraison | Oui | Statut actuel |
| `transporteur` | String(200) | Non | Nom du transporteur |
| `numeroSuivi` | String(100) | Non | Numéro de suivi |
| `modeLivraison` | ModeLivraison | Non | Mode de livraison |
| `adresseLivraison` | String(500) | Non | Adresse de livraison |
| `coutLivraison` | BigDecimal | Non | Coût de la livraison |

---

## 🔌 API REST

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

### **Endpoints disponibles**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/livraisons` | Liste toutes les livraisons |
| GET | `/api/v1/livraisons/{id}` | Détails d'une livraison |
| POST | `/api/v1/livraisons` | Créer une livraison |
| PUT | `/api/v1/livraisons/{id}` | Modifier une livraison |
| PUT | `/api/v1/livraisons/{id}/statut` | Changer le statut |
| GET | `/api/v1/livraisons/en-cours` | Livraisons en cours |
| GET | `/api/v1/livraisons/retardees` | Livraisons retardées |
| GET | `/api/v1/livraisons/stats` | Statistiques livraisons |

---

## 💻 Exemples d'utilisation

### **1. Créer une livraison**

```bash
curl -X POST http://localhost:8080/api/v1/livraisons \
  -H "Content-Type: application/json" \
  -d '{
    "reservationId": "reservation-uuid",
    "dateLivraisonPrevue": "2025-10-05T09:00:00",
    "transporteur": "Transport Express",
    "modeLivraison": "STANDARD",
    "adresseLivraison": "123 Rue du Chantier, 75001 Paris"
  }'
```

### **2. Mettre à jour le statut**

```bash
curl -X PUT http://localhost:8080/api/v1/livraisons/{id}/statut \
  -H "Content-Type: application/json" \
  -d '{
    "statut": "EN_TRANSIT",
    "numeroSuivi": "TRACK123456"
  }'
```

### **3. Livraisons en cours**

```bash
curl -X GET http://localhost:8080/api/v1/livraisons/en-cours
```

**Réponse**:
```json
[
  {
    "id": "uuid",
    "statut": "EN_TRANSIT",
    "transporteur": "Transport Express",
    "numeroSuivi": "TRACK123456",
    "dateLivraisonPrevue": "2025-10-05T09:00:00",
    "adresseLivraison": "123 Rue du Chantier"
  }
]
```

---

## 🔧 Services métier

### **LivraisonMaterielService**

**Méthodes principales**:
- `create(LivraisonDTO dto)` - Créer une livraison
- `changerStatut(UUID id, StatutLivraison statut)` - Changer le statut
- `findEnCours()` - Livraisons en cours
- `findRetardees()` - Livraisons retardées
- `calculerDelai(UUID id)` - Calculer le délai
- `getStatistics()` - Statistiques

---

## 📈 Relations avec autres concepts

- **RESERVATION_MATERIEL** ⬅️ Une livraison peut être liée à une réservation
- **CHANTIER** ⬅️ Une livraison est destinée à un chantier
- **MATERIEL** ⬅️ Une livraison concerne du matériel

---

## ✅ Validations

- ✅ Date de livraison prévue obligatoire
- ✅ Adresse de livraison valide
- ✅ Statut cohérent avec les transitions
- ✅ Coût de livraison positif

---

## 📚 Références

- [Concept RESERVATION_MATERIEL](./04-RESERVATION_MATERIEL.md)
- [Concept MATERIEL](./03-MATERIEL.md)
- [Concept CHANTIER](./01-CHANTIER.md)

---

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