# 💵 CONCEPT: BUDGET

## 📌 Vue d'ensemble

Le concept **BUDGET** gère les budgets prévisionnels et réels des chantiers avec suivi des dépenses et écarts.

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

---

## 🗂️ Fichiers concernés

### **Entités JPA**
| Fichier | Description |
|---------|-------------|
| `Budget.java` | Entité principale budget |

### **Services**
| Fichier | Description |
|---------|-------------|
| `BudgetService.java` | Service métier budget |

### **Resources**
| Fichier | Description |
|---------|-------------|
| `BudgetResource.java` | API REST budget |

---

## 📊 Modèle de données

```java
@Entity
@Table(name = "budgets")
public class Budget extends PanacheEntityBase {
  @Id
  @GeneratedValue(strategy = GenerationType.UUID)
  private UUID id;
  
  @OneToOne
  @JoinColumn(name = "chantier_id", nullable = false)
  private Chantier chantier;
  
  @Column(name = "montant_prevu", precision = 12, scale = 2)
  private BigDecimal montantPrevu;
  
  @Column(name = "montant_depense", precision = 12, scale = 2)
  private BigDecimal montantDepense = BigDecimal.ZERO;
  
  @Column(name = "montant_restant", precision = 12, scale = 2)
  private BigDecimal montantRestant;
  
  @Column(name = "pourcentage_utilise", precision = 5, scale = 2)
  private BigDecimal pourcentageUtilise = BigDecimal.ZERO;
}
```

---

## 🔌 API REST

### **Endpoints**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/budgets` | Liste budgets |
| GET | `/api/v1/budgets/{id}` | Détails |
| GET | `/api/v1/budgets/chantier/{id}` | Budget d'un chantier |
| POST | `/api/v1/budgets` | Créer |
| PUT | `/api/v1/budgets/{id}` | Modifier |
| POST | `/api/v1/budgets/{id}/depense` | Enregistrer dépense |
| GET | `/api/v1/budgets/{id}/ecarts` | Analyse écarts |

---

## 💻 Exemples

### **Créer un budget**

```bash
curl -X POST http://localhost:8080/api/v1/budgets \
  -H "Content-Type: application/json" \
  -d '{
    "chantierId": "chantier-uuid",
    "montantPrevu": 250000.00
  }'
```

### **Enregistrer une dépense**

```bash
curl -X POST http://localhost:8080/api/v1/budgets/{id}/depense \
  -H "Content-Type: application/json" \
  -d '{
    "montant": 5000.00,
    "categorie": "MATERIAUX",
    "description": "Achat ciment et sable"
  }'
```

### **Analyse des écarts**

```bash
curl -X GET http://localhost:8080/api/v1/budgets/{id}/ecarts
```

**Réponse**:
```json
{
  "montantPrevu": 250000.00,
  "montantDepense": 180000.00,
  "montantRestant": 70000.00,
  "pourcentageUtilise": 72.00,
  "ecart": -70000.00,
  "statut": "DANS_BUDGET",
  "alertes": []
}
```

---

## 🔧 Services métier

**BudgetService - Méthodes**:
- `create(BudgetDTO)` - Créer
- `enregistrerDepense(UUID id, BigDecimal montant)` - Dépense
- `calculerEcarts(UUID id)` - Calculer écarts
- `getStatutBudget(UUID id)` - Statut

---

## 📈 Relations

- **CHANTIER** ⬅️ Un budget est lié à un chantier (OneToOne)
- **DEVIS** ⬅️ Le budget initial vient du devis
- **FACTURE** ➡️ Les factures impactent le budget

---

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