# 📦 CONCEPT: STOCK

## 📌 Vue d'ensemble

Le concept **STOCK** gère les stocks de matériaux et fournitures avec suivi des mouvements, alertes de rupture, et inventaires.

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

---

## 🗂️ Fichiers concernés

### **Entités JPA**
| Fichier | Description |
|---------|-------------|
| `Stock.java` | Entité principale stock |
| `CategorieStock.java` | Catégorie de stock |
| `SousCategorieStock.java` | Sous-catégorie |
| `StatutStock.java` | Enum (DISPONIBLE, RESERVE, RUPTURE, COMMANDE, PERIME) |
| `UniteMesure.java` | Enum unités (UNITE, KG, M, L, etc.) |
| `UnitePrix.java` | Enum unités de prix |

### **Services**
| Fichier | Description |
|---------|-------------|
| `StockService.java` | Service métier stock |

---

## 📊 Modèle de données

```java
@Entity
@Table(name = "stocks")
public class Stock extends PanacheEntityBase {
  @Id
  @GeneratedValue(strategy = GenerationType.UUID)
  private UUID id;
  
  @Column(name = "designation", nullable = false)
  private String designation;
  
  @Column(name = "reference", unique = true)
  private String reference;
  
  @ManyToOne
  @JoinColumn(name = "categorie_id")
  private CategorieStock categorie;
  
  @Column(name = "quantite", precision = 10, scale = 3)
  private BigDecimal quantite = BigDecimal.ZERO;
  
  @Column(name = "seuil_alerte", precision = 10, scale = 3)
  private BigDecimal seuilAlerte;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "unite")
  private UniteMesure unite;
  
  @Enumerated(EnumType.STRING)
  @Column(name = "statut")
  private StatutStock statut = StatutStock.DISPONIBLE;
  
  @Column(name = "prix_unitaire", precision = 10, scale = 2)
  private BigDecimal prixUnitaire;
}
```

### **Enum UniteMesure**

```java
public enum UniteMesure {
  UNITE, PAIRE, LOT, KIT,           // Quantité
  GRAMME, KILOGRAMME, TONNE,        // Poids
  MILLIMETRE, CENTIMETRE, METRE,    // Longueur
  METRE_CARRE, METRE_CUBE,          // Surface/Volume
  LITRE, MILLILITRE,                // Volume liquide
  AUTRE
}
```

---

## 🔌 API REST

### **Endpoints**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/stocks` | Liste stocks |
| GET | `/api/v1/stocks/{id}` | Détails stock |
| POST | `/api/v1/stocks` | Créer stock |
| PUT | `/api/v1/stocks/{id}` | Modifier stock |
| POST | `/api/v1/stocks/{id}/mouvement` | Enregistrer mouvement |
| GET | `/api/v1/stocks/alertes` | Stocks en alerte |
| GET | `/api/v1/stocks/stats` | Statistiques |

---

## 💻 Exemples

### **Créer un article en stock**

```bash
curl -X POST http://localhost:8080/api/v1/stocks \
  -H "Content-Type: application/json" \
  -d '{
    "designation": "Ciment Portland 25kg",
    "reference": "CIM-PORT-25",
    "categorieId": 1,
    "quantite": 100,
    "seuilAlerte": 20,
    "unite": "UNITE",
    "prixUnitaire": 8.50
  }'
```

### **Enregistrer un mouvement**

```bash
curl -X POST http://localhost:8080/api/v1/stocks/{id}/mouvement \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SORTIE",
    "quantite": 10,
    "motif": "Chantier Villa Moderne",
    "chantierId": "uuid"
  }'
```

### **Stocks en alerte**

```bash
curl -X GET http://localhost:8080/api/v1/stocks/alertes
```

**Réponse**:
```json
[
  {
    "id": "uuid",
    "designation": "Ciment Portland 25kg",
    "quantite": 15,
    "seuilAlerte": 20,
    "statut": "ALERTE_STOCK"
  }
]
```

---

## 🔧 Services métier

**StockService - Méthodes**:
- `findAll()` - Tous les stocks
- `ajouterStock(UUID id, BigDecimal quantite)` - Ajouter
- `retirerStock(UUID id, BigDecimal quantite)` - Retirer
- `findAlertes()` - Stocks en alerte
- `inventaire()` - Inventaire complet

---

## 📈 Relations

- **MATERIEL** ⬅️ Un stock peut être lié à du matériel
- **BON_COMMANDE** ➡️ Commandes pour réapprovisionner
- **CHANTIER** ➡️ Sorties de stock pour chantiers

---

## ✅ Validations

- ✅ Quantité ne peut pas être négative
- ✅ Seuil d'alerte positif
- ✅ Référence unique
- ✅ Unité de mesure cohérente

---

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