Initial commit

2025-10-01 01:37:34 +00:00
commit f2bb633142
310 changed files with 86051 additions and 0 deletions
--- a/docs/concepts/10-BUDGET.md
+++ b/docs/concepts/10-BUDGET.md
@@ -0,0 +1,142 @@
+# 💵 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
+