btpxpress-backend/docs/concepts/12-MAINTENANCE.md

# 🔧 CONCEPT: MAINTENANCE

## 📌 Vue d'ensemble

Le concept **MAINTENANCE** gère la maintenance préventive et corrective du matériel BTP avec planification et historique.

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

---

## 🗂️ Fichiers concernés

### **Entités JPA**
| Fichier | Description |
|---------|-------------|
| `MaintenanceMateriel.java` | Entité principale maintenance |
| `StatutMaintenance.java` | Enum (PLANIFIEE, EN_COURS, TERMINEE, ANNULEE, REPORTEE) |
| `TypeMaintenance.java` | Enum (PREVENTIVE, CORRECTIVE, CURATIVE, PREDICTIVE) |

### **Services**
| Fichier | Description |
|---------|-------------|
| `MaintenanceService.java` | Service métier maintenance |

### **Resources**
| Fichier | Description |
|---------|-------------|
| `MaintenanceResource.java` | API REST maintenance |

---

## 📊 Modèle de données

```java
@Entity
@Table(name = "maintenances_materiel")
public class MaintenanceMateriel extends PanacheEntityBase {
  @Id
  @GeneratedValue(strategy = GenerationType.UUID)
  private UUID id;
  
  @ManyToOne
  @JoinColumn(name = "materiel_id", nullable = false)
  private Materiel materiel;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "type", nullable = false)
  private TypeMaintenance type;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "statut", nullable = false)
  private StatutMaintenance statut = StatutMaintenance.PLANIFIEE;
  
  @Column(name = "date_prevue", nullable = false)
  private LocalDate datePrevue;
  
  @Column(name = "date_realisee")
  private LocalDate dateRealisee;
  
  @Column(name = "description", length = 1000)
  private String description;
  
  @Column(name = "cout", precision = 10, scale = 2)
  private BigDecimal cout;
  
  @Column(name = "technicien", length = 100)
  private String technicien;
  
  @Column(name = "observations", length = 2000)
  private String observations;
}
```

### **Enum TypeMaintenance**

```java
public enum TypeMaintenance {
  PREVENTIVE,    // Maintenance préventive planifiée
  CORRECTIVE,    // Correction d'un dysfonctionnement
  CURATIVE,      // Réparation d'une panne
  PREDICTIVE     // Maintenance prédictive (IoT, capteurs)
}
```

### **Enum StatutMaintenance**

```java
public enum StatutMaintenance {
  PLANIFIEE,     // Planifiée
  EN_COURS,      // En cours de réalisation
  TERMINEE,      // Terminée avec succès
  ANNULEE,       // Annulée
  REPORTEE       // Reportée à une date ultérieure
}
```

---

## 🔌 API REST

### **Endpoints**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/maintenances` | Liste maintenances |
| GET | `/api/v1/maintenances/{id}` | Détails |
| POST | `/api/v1/maintenances` | Créer |
| PUT | `/api/v1/maintenances/{id}` | Modifier |
| PUT | `/api/v1/maintenances/{id}/terminer` | Terminer |
| GET | `/api/v1/maintenances/materiel/{id}` | Maintenances d'un matériel |
| GET | `/api/v1/maintenances/planifiees` | Maintenances planifiées |
| GET | `/api/v1/maintenances/stats` | Statistiques |

---

## 💻 Exemples

### **Créer une maintenance préventive**

```bash
curl -X POST http://localhost:8080/api/v1/maintenances \
  -H "Content-Type: application/json" \
  -d '{
    "materielId": "materiel-uuid",
    "type": "PREVENTIVE",
    "datePrevue": "2025-11-01",
    "description": "Révision annuelle - Vidange et contrôle général",
    "technicien": "Service Maintenance"
  }'
```

### **Terminer une maintenance**

```bash
curl -X PUT http://localhost:8080/api/v1/maintenances/{id}/terminer \
  -H "Content-Type: application/json" \
  -d '{
    "dateRealisee": "2025-11-01",
    "cout": 250.00,
    "observations": "Révision effectuée. Remplacement filtre à huile. Matériel en bon état."
  }'
```

### **Historique maintenance d'un matériel**

```bash
curl -X GET http://localhost:8080/api/v1/maintenances/materiel/{materielId}
```

**Réponse**:
```json
[
  {
    "id": "uuid",
    "type": "PREVENTIVE",
    "statut": "TERMINEE",
    "datePrevue": "2025-11-01",
    "dateRealisee": "2025-11-01",
    "description": "Révision annuelle",
    "cout": 250.00,
    "technicien": "Service Maintenance"
  },
  {
    "id": "uuid2",
    "type": "CORRECTIVE",
    "statut": "TERMINEE",
    "datePrevue": "2025-08-15",
    "dateRealisee": "2025-08-16",
    "description": "Réparation système hydraulique",
    "cout": 450.00
  }
]
```

### **Maintenances planifiées**

```bash
curl -X GET http://localhost:8080/api/v1/maintenances/planifiees
```

---

## 🔧 Services métier

**MaintenanceService - Méthodes**:
- `create(MaintenanceDTO)` - Créer maintenance
- `terminer(UUID id, MaintenanceTermineeDTO)` - Terminer
- `reporter(UUID id, LocalDate nouvelleDate)` - Reporter
- `findByMateriel(UUID materielId)` - Historique matériel
- `findPlanifiees()` - Maintenances planifiées
- `findEnRetard()` - Maintenances en retard
- `planifierPreventive(UUID materielId)` - Planifier préventive

---

## 📈 Relations

- **MATERIEL** ⬅️ Une maintenance concerne un matériel
- **EMPLOYE** ⬅️ Un technicien (employé) peut réaliser la maintenance

---

## ✅ Validations

- ✅ Matériel obligatoire
- ✅ Type obligatoire
- ✅ Date prévue obligatoire
- ✅ Coût positif
- ✅ Date réalisée >= date prévue

---

## 📚 Références

- [Concept MATERIEL](./03-MATERIEL.md)
- [Concept EMPLOYE](./11-EMPLOYE.md)

---

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