# 🏪 CONCEPT: FOURNISSEUR

## 📌 Vue d'ensemble

Le concept **FOURNISSEUR** gère les fournisseurs de matériel et services BTP. Il inclut le catalogue produits, les comparaisons de prix, et les conditions commerciales.

**Importance**: ⭐⭐⭐⭐ (Concept stratégique)

---

## 🗂️ Fichiers concernés

### **Entités JPA** (`domain/core/entity/`)
| Fichier | Description | Lignes |
|---------|-------------|--------|
| `Fournisseur.java` | Entité principale fournisseur | ~150 |
| `FournisseurMateriel.java` | Relation fournisseur-matériel | ~80 |
| `CatalogueFournisseur.java` | Catalogue produits fournisseur | ~120 |
| `ComparaisonFournisseur.java` | Comparaison entre fournisseurs | ~100 |
| `StatutFournisseur.java` | Enum statuts (ACTIF, INACTIF, SUSPENDU, BLOQUE) | ~20 |
| `SpecialiteFournisseur.java` | Enum spécialités (MATERIAUX_GROS_OEUVRE, etc.) | ~70 |
| `ConditionsPaiement.java` | Enum conditions de paiement | ~40 |
| `CritereComparaison.java` | Enum critères de comparaison | ~25 |

### **DTOs** (`domain/shared/dto/`)
| Fichier | Description |
|---------|-------------|
| `FournisseurDTO.java` | DTO fournisseur avec enum TypeFournisseur |

### **Services** (`application/service/`)
| Fichier | Description |
|---------|-------------|
| `FournisseurService.java` | Service métier fournisseurs |
| `ComparaisonFournisseurService.java` | Service de comparaison |

---

## 📊 Modèle de données

### **Entité Fournisseur**

```java
@Entity
@Table(name = "fournisseurs")
public class Fournisseur extends PanacheEntityBase {
  
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;
  
  @NotBlank
  @Column(name = "nom", nullable = false, length = 100)
  private String nom;
  
  @Column(name = "siret", length = 20)
  private String siret;
  
  @Column(name = "numero_tva", length = 15)
  private String numeroTva;
  
  @Email
  @Column(name = "email", length = 100)
  private String email;
  
  @Column(name = "telephone", length = 20)
  private String telephone;
  
  @Column(name = "adresse", length = 200)
  private String adresse;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "statut")
  private StatutFournisseur statut = StatutFournisseur.ACTIF;
  
  @ElementCollection
  @CollectionTable(name = "fournisseur_specialites")
  @Enumerated(EnumType.STRING)
  private List<SpecialiteFournisseur> specialites;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "conditions_paiement")
  private ConditionsPaiement conditionsPaiement;
  
  @Column(name = "delai_paiement_jours")
  private Integer delaiPaiementJours;
}
```

### **Enum SpecialiteFournisseur**

```java
public enum SpecialiteFournisseur {
  // Matériaux de construction
  MATERIAUX_GROS_OEUVRE("Matériaux gros œuvre", "Béton, ciment, parpaings"),
  MATERIAUX_CHARPENTE("Matériaux charpente", "Bois de charpente"),
  MATERIAUX_COUVERTURE("Matériaux couverture", "Tuiles, ardoises"),
  MATERIAUX_ISOLATION("Matériaux isolation", "Isolants thermiques"),
  
  // Équipements techniques
  PLOMBERIE("Plomberie", "Tuyauterie, robinetterie"),
  ELECTRICITE("Électricité", "Câbles, tableaux électriques"),
  CHAUFFAGE("Chauffage", "Chaudières, radiateurs"),
  
  // Équipements et outils
  LOCATION_MATERIEL("Location matériel", "Location engins et outils"),
  OUTILLAGE("Outillage", "Outils électriques et manuels"),
  
  // Services
  TRANSPORT("Transport", "Transport de matériaux"),
  MULTI_SPECIALITES("Multi-spécialités", "Fournisseur généraliste"),
  AUTRE("Autre", "Autre spécialité")
}
```

### **Champs principaux**

| Champ | Type | Obligatoire | Description |
|-------|------|-------------|-------------|
| `id` | Long | Oui | Identifiant unique |
| `nom` | String(100) | Oui | Nom du fournisseur |
| `siret` | String(20) | Non | Numéro SIRET |
| `numeroTva` | String(15) | Non | Numéro TVA |
| `email` | String(100) | Non | Email de contact |
| `telephone` | String(20) | Non | Téléphone |
| `adresse` | String(200) | Non | Adresse |
| `statut` | StatutFournisseur | Oui | Statut (défaut: ACTIF) |
| `specialites` | List<SpecialiteFournisseur> | Non | Spécialités |
| `conditionsPaiement` | ConditionsPaiement | Non | Conditions de paiement |
| `delaiPaiementJours` | Integer | Non | Délai de paiement en jours |

---

## 🔌 API REST

### **Base URL**: `/api/v1/fournisseurs`

### **Endpoints disponibles**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/fournisseurs` | Liste tous les fournisseurs |
| GET | `/api/v1/fournisseurs/{id}` | Détails d'un fournisseur |
| POST | `/api/v1/fournisseurs` | Créer un fournisseur |
| PUT | `/api/v1/fournisseurs/{id}` | Modifier un fournisseur |
| DELETE | `/api/v1/fournisseurs/{id}` | Supprimer un fournisseur |
| GET | `/api/v1/fournisseurs/specialite/{specialite}` | Par spécialité |
| GET | `/api/v1/fournisseurs/comparer` | Comparer des fournisseurs |
| GET | `/api/v1/fournisseurs/stats` | Statistiques |

---

## 💻 Exemples d'utilisation

### **1. Créer un fournisseur**

```bash
curl -X POST http://localhost:8080/api/v1/fournisseurs \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Matériaux Pro",
    "siret": "12345678901234",
    "email": "contact@materiauxpro.fr",
    "telephone": "+33 1 23 45 67 89",
    "adresse": "10 Rue de l Industrie, 75001 Paris",
    "specialites": ["MATERIAUX_GROS_OEUVRE", "MATERIAUX_ISOLATION"],
    "conditionsPaiement": "NET_30",
    "delaiPaiementJours": 30
  }'
```

### **2. Rechercher par spécialité**

```bash
curl -X GET "http://localhost:8080/api/v1/fournisseurs/specialite/MATERIAUX_GROS_OEUVRE"
```

### **3. Comparer des fournisseurs**

```bash
curl -X GET "http://localhost:8080/api/v1/fournisseurs/comparer?materielId=uuid&fournisseurIds=id1,id2,id3"
```

**Réponse**:
```json
{
  "materiel": "Ciment Portland 25kg",
  "comparaisons": [
    {
      "fournisseur": "Matériaux Pro",
      "prix": 8.50,
      "delaiLivraison": 2,
      "conditionsPaiement": "NET_30",
      "note": 4.5
    },
    {
      "fournisseur": "BTP Discount",
      "prix": 7.90,
      "delaiLivraison": 5,
      "conditionsPaiement": "NET_45",
      "note": 4.2
    }
  ]
}
```

---

## 🔧 Services métier

### **FournisseurService**

**Méthodes principales**:
- `findAll()` - Tous les fournisseurs
- `findBySpecialite(SpecialiteFournisseur)` - Par spécialité
- `findActifs()` - Fournisseurs actifs
- `create(FournisseurDTO)` - Créer
- `update(Long id, FournisseurDTO)` - Modifier

### **ComparaisonFournisseurService**

**Méthodes principales**:
- `comparerPrix(UUID materielId, List<Long> fournisseurIds)` - Comparer prix
- `getMeilleurFournisseur(UUID materielId, CritereComparaison)` - Meilleur fournisseur

---

## 📈 Relations avec autres concepts

- **MATERIEL** ➡️ Un fournisseur propose du matériel (catalogue)
- **BON_COMMANDE** ➡️ Un fournisseur reçoit des bons de commande
- **FACTURE** ➡️ Un fournisseur émet des factures

---

## ✅ Validations

- ✅ Nom obligatoire
- ✅ Email au format valide
- ✅ SIRET 14 caractères si renseigné
- ✅ Au moins une spécialité

---

## 📚 Références

- [Concept MATERIEL](./03-MATERIEL.md)
- [Concept BON_COMMANDE](./08-BON_COMMANDE.md)

---

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