btpxpress-backend/docs/concepts/08-BON_COMMANDE.md

# 📋 CONCEPT: BON_COMMANDE

## 📌 Vue d'ensemble

Le concept **BON_COMMANDE** gère les bons de commande auprès des fournisseurs pour l'achat de matériel, fournitures et services.

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

---

## 🗂️ Fichiers concernés

### **Entités JPA**
| Fichier | Description |
|---------|-------------|
| `BonCommande.java` | Entité principale bon de commande |
| `LigneBonCommande.java` | Ligne de bon de commande |
| `StatutBonCommande.java` | Enum (BROUILLON, VALIDEE, ENVOYEE, CONFIRMEE, LIVREE, ANNULEE) |
| `StatutLigneBonCommande.java` | Enum statuts ligne |
| `TypeBonCommande.java` | Enum types (ACHAT, LOCATION, PRESTATIONS, etc.) |
| `PrioriteBonCommande.java` | Enum priorités |

### **Services**
| Fichier | Description |
|---------|-------------|
| `BonCommandeService.java` | Service métier |
| `LigneBonCommandeService.java` | Service lignes |

---

## 📊 Modèle de données

```java
@Entity
@Table(name = "bons_commande")
public class BonCommande extends PanacheEntityBase {
  @Id
  @GeneratedValue(strategy = GenerationType.UUID)
  private UUID id;
  
  @Column(name = "numero", unique = true, nullable = false)
  private String numero;
  
  @ManyToOne
  @JoinColumn(name = "fournisseur_id", nullable = false)
  private Fournisseur fournisseur;
  
  @Column(name = "date_commande", nullable = false)
  private LocalDate dateCommande;
  
  @Column(name = "date_livraison_souhaitee")
  private LocalDate dateLivraisonSouhaitee;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "statut", nullable = false)
  private StatutBonCommande statut = StatutBonCommande.BROUILLON;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "type")
  private TypeBonCommande type;
  
  @OneToMany(mappedBy = "bonCommande", cascade = CascadeType.ALL)
  private List<LigneBonCommande> lignes;
  
  @Column(name = "montant_total", precision = 10, scale = 2)
  private BigDecimal montantTotal = BigDecimal.ZERO;
  
  @Column(name = "commentaire", length = 1000)
  private String commentaire;
}
```

### **Enum StatutBonCommande**

```java
public enum StatutBonCommande {
  BROUILLON,     // En cours de rédaction
  VALIDEE,       // Validée en interne
  ENVOYEE,       // Envoyée au fournisseur
  CONFIRMEE,     // Confirmée par le fournisseur
  LIVREE,        // Livrée
  ANNULEE        // Annulée
}
```

### **Enum TypeBonCommande**

```java
public enum TypeBonCommande {
  ACHAT,         // Achat de matériel
  LOCATION,      // Location de matériel
  PRESTATIONS,   // Prestations de service
  FOURNITURES,   // Fournitures consommables
  TRAVAUX,       // Travaux sous-traités
  MAINTENANCE,   // Maintenance
  TRANSPORT,     // Transport
  AUTRE
}
```

---

## 🔌 API REST

### **Endpoints**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/bons-commande` | Liste bons de commande |
| GET | `/api/v1/bons-commande/{id}` | Détails |
| POST | `/api/v1/bons-commande` | Créer |
| PUT | `/api/v1/bons-commande/{id}` | Modifier |
| PUT | `/api/v1/bons-commande/{id}/valider` | Valider |
| PUT | `/api/v1/bons-commande/{id}/envoyer` | Envoyer |
| DELETE | `/api/v1/bons-commande/{id}` | Annuler |
| GET | `/api/v1/bons-commande/stats` | Statistiques |

---

## 💻 Exemples

### **Créer un bon de commande**

```bash
curl -X POST http://localhost:8080/api/v1/bons-commande \
  -H "Content-Type: application/json" \
  -d '{
    "fournisseurId": 1,
    "dateCommande": "2025-10-01",
    "dateLivraisonSouhaitee": "2025-10-10",
    "type": "ACHAT",
    "lignes": [
      {
        "designation": "Ciment Portland 25kg",
        "quantite": 50,
        "prixUnitaire": 8.50,
        "unite": "UNITE"
      },
      {
        "designation": "Sable 0/4 - 1 tonne",
        "quantite": 10,
        "prixUnitaire": 45.00,
        "unite": "TONNE"
      }
    ],
    "commentaire": "Livraison sur chantier Villa Moderne"
  }'
```

**Réponse**:
```json
{
  "id": "uuid",
  "numero": "BC-2025-001",
  "fournisseur": "Matériaux Pro",
  "dateCommande": "2025-10-01",
  "statut": "BROUILLON",
  "montantTotal": 875.00,
  "lignes": [
    {
      "designation": "Ciment Portland 25kg",
      "quantite": 50,
      "prixUnitaire": 8.50,
      "montant": 425.00
    },
    {
      "designation": "Sable 0/4 - 1 tonne",
      "quantite": 10,
      "prixUnitaire": 45.00,
      "montant": 450.00
    }
  ]
}
```

### **Valider un bon de commande**

```bash
curl -X PUT http://localhost:8080/api/v1/bons-commande/{id}/valider
```

### **Envoyer au fournisseur**

```bash
curl -X PUT http://localhost:8080/api/v1/bons-commande/{id}/envoyer \
  -H "Content-Type: application/json" \
  -d '{
    "emailFournisseur": "contact@materiauxpro.fr",
    "message": "Veuillez trouver ci-joint notre bon de commande"
  }'
```

---

## 🔧 Services métier

**BonCommandeService - Méthodes**:
- `create(BonCommandeDTO)` - Créer
- `valider(UUID id)` - Valider
- `envoyer(UUID id)` - Envoyer au fournisseur
- `annuler(UUID id)` - Annuler
- `calculerMontantTotal(UUID id)` - Calculer total
- `findByStatut(StatutBonCommande)` - Par statut
- `findByFournisseur(Long fournisseurId)` - Par fournisseur

---

## 📈 Relations

- **FOURNISSEUR** ⬅️ Un bon de commande est adressé à un fournisseur
- **CHANTIER** ⬅️ Un bon peut être lié à un chantier
- **STOCK** ➡️ Réception met à jour le stock

---

## ✅ Validations

- ✅ Numéro unique et obligatoire
- ✅ Fournisseur obligatoire
- ✅ Au moins une ligne
- ✅ Quantités positives
- ✅ Prix unitaires positifs
- ✅ Transitions de statut cohérentes

---

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