# 📅 CONCEPT: RESERVATION_MATERIEL

## 📌 Vue d'ensemble

Le concept **RESERVATION_MATERIEL** gère les réservations et affectations de matériel aux chantiers. Il permet de planifier l'utilisation du matériel, éviter les conflits, et optimiser l'allocation des ressources.

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

---

## 🗂️ Fichiers concernés

### **Entités JPA** (`domain/core/entity/`)
| Fichier | Description | Lignes |
|---------|-------------|--------|
| `ReservationMateriel.java` | Entité principale de réservation | ~180 |
| `StatutReservationMateriel.java` | Enum statuts (PLANIFIEE, VALIDEE, EN_COURS, TERMINEE, REFUSEE, ANNULEE) | ~20 |
| `PrioriteReservation.java` | Enum priorités de réservation | ~25 |
| `PlanningMateriel.java` | Planning d'utilisation du matériel | ~200 |
| `StatutPlanning.java` | Enum statuts de planning | ~30 |
| `TypePlanning.java` | Enum types de planning | ~25 |

### **Services** (`application/service/`)
| Fichier | Description |
|---------|-------------|
| `ReservationMaterielService.java` | Service métier pour les réservations |
| `PlanningMaterielService.java` | Service de gestion du planning matériel |

---

## 📊 Modèle de données

### **Entité ReservationMateriel**

```java
@Entity
@Table(name = "reservations_materiel")
public class ReservationMateriel extends PanacheEntityBase {
  
  @Id
  @GeneratedValue(strategy = GenerationType.UUID)
  private UUID id;
  
  @ManyToOne
  @JoinColumn(name = "materiel_id", nullable = false)
  private Materiel materiel;
  
  @ManyToOne
  @JoinColumn(name = "chantier_id", nullable = false)
  private Chantier chantier;
  
  @Column(name = "date_debut", nullable = false)
  private LocalDate dateDebut;
  
  @Column(name = "date_fin", nullable = false)
  private LocalDate dateFin;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "statut", nullable = false)
  private StatutReservationMateriel statut = StatutReservationMateriel.PLANIFIEE;
  
  @Column(name = "quantite", precision = 10, scale = 3)
  private BigDecimal quantite;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "priorite")
  private PrioriteReservation priorite;
}
```

### **Enum StatutReservationMateriel**

```java
public enum StatutReservationMateriel {
  PLANIFIEE,    // Réservation planifiée
  VALIDEE,      // Réservation validée
  EN_COURS,     // Réservation en cours d'utilisation
  TERMINEE,     // Réservation terminée
  REFUSEE,      // Réservation refusée
  ANNULEE       // Réservation annulée
}
```

### **Champs principaux**

| Champ | Type | Obligatoire | Description |
|-------|------|-------------|-------------|
| `id` | UUID | Oui | Identifiant unique |
| `materiel` | Materiel | Oui | Matériel réservé |
| `chantier` | Chantier | Oui | Chantier destinataire |
| `dateDebut` | LocalDate | Oui | Date de début de réservation |
| `dateFin` | LocalDate | Oui | Date de fin de réservation |
| `statut` | StatutReservationMateriel | Oui | Statut actuel |
| `quantite` | BigDecimal | Non | Quantité réservée |
| `priorite` | PrioriteReservation | Non | Priorité de la réservation |
| `commentaire` | String | Non | Commentaire |

---

## 🔌 API REST

### **Base URL**: `/api/v1/reservations-materiel`

### **Endpoints disponibles**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/reservations-materiel` | Liste toutes les réservations |
| GET | `/api/v1/reservations-materiel/{id}` | Détails d'une réservation |
| POST | `/api/v1/reservations-materiel` | Créer une réservation |
| PUT | `/api/v1/reservations-materiel/{id}` | Modifier une réservation |
| DELETE | `/api/v1/reservations-materiel/{id}` | Annuler une réservation |
| GET | `/api/v1/reservations-materiel/materiel/{id}` | Réservations d'un matériel |
| GET | `/api/v1/reservations-materiel/chantier/{id}` | Réservations d'un chantier |
| GET | `/api/v1/reservations-materiel/conflits` | Détecter les conflits |

---

## 💻 Exemples d'utilisation

### **1. Créer une réservation**

```bash
curl -X POST http://localhost:8080/api/v1/reservations-materiel \
  -H "Content-Type: application/json" \
  -d '{
    "materielId": "materiel-uuid",
    "chantierId": "chantier-uuid",
    "dateDebut": "2025-10-01",
    "dateFin": "2025-10-15",
    "quantite": 2,
    "priorite": "NORMALE"
  }'
```

### **2. Vérifier les conflits**

```bash
curl -X GET "http://localhost:8080/api/v1/reservations-materiel/conflits?materielId=uuid&dateDebut=2025-10-01&dateFin=2025-10-15"
```

---

## 🔧 Services métier

### **ReservationMaterielService**

**Méthodes principales**:
- `create(ReservationDTO dto)` - Créer une réservation
- `verifierDisponibilite(UUID materielId, LocalDate debut, LocalDate fin)` - Vérifier disponibilité
- `detecterConflits(UUID materielId, LocalDate debut, LocalDate fin)` - Détecter conflits
- `valider(UUID id)` - Valider une réservation
- `annuler(UUID id)` - Annuler une réservation

---

## 📈 Relations avec autres concepts

- **MATERIEL** ⬅️ Une réservation concerne un matériel
- **CHANTIER** ⬅️ Une réservation est liée à un chantier
- **PLANNING** ➡️ Les réservations alimentent le planning
- **LIVRAISON** ➡️ Une réservation peut générer une livraison

---

## ✅ Validations

- ✅ Date de fin doit être après date de début
- ✅ Le matériel doit être disponible
- ✅ Pas de conflit avec d'autres réservations
- ✅ Quantité disponible suffisante

---

## 📚 Références

- [Concept MATERIEL](./03-MATERIEL.md)
- [Concept CHANTIER](./01-CHANTIER.md)
- [Concept PLANNING](./13-PLANNING.md)

---

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