# ⚙️ CONCEPT: SERVICES_TRANSVERSES

## 📌 Vue d'ensemble

Le concept **SERVICES_TRANSVERSES** regroupe les services utilitaires et techniques utilisés par l'ensemble de l'application.

**Importance**: ⭐⭐⭐ (Concept technique)

---

## 🗂️ Fichiers concernés

### **Services** (`application/service/`)
| Fichier | Description |
|---------|-------------|
| `EmailService.java` | Service d'envoi d'emails |
| `PdfGeneratorService.java` | Génération de PDF |
| `ExportService.java` | Export de données (Excel, CSV) |
| `ImportService.java` | Import de données |

---

## 📊 Services disponibles

### **1. EmailService**

Service d'envoi d'emails transactionnels et notifications.

**Méthodes principales**:
```java
public class EmailService {
  void sendEmail(String to, String subject, String body);
  void sendEmailWithAttachment(String to, String subject, String body, File attachment);
  void sendTemplateEmail(String to, String templateName, Map<String, Object> variables);
}
```

**Exemples d'utilisation**:
- Envoi de devis par email
- Notifications de livraison
- Alertes de stock faible
- Rappels de maintenance

---

### **2. PdfGeneratorService**

Service de génération de documents PDF.

**Méthodes principales**:
```java
public class PdfGeneratorService {
  byte[] genererDevisPdf(UUID devisId);
  byte[] genererFacturePdf(UUID factureId);
  byte[] genererBonCommandePdf(UUID bonCommandeId);
  byte[] genererRapportChantierPdf(UUID chantierId);
}
```

**Technologies utilisées**:
- iText ou Apache PDFBox
- Templates HTML/CSS convertis en PDF
- Génération de graphiques et tableaux

---

### **3. ExportService**

Service d'export de données vers différents formats.

**Méthodes principales**:
```java
public class ExportService {
  byte[] exportToExcel(List<?> data, String sheetName);
  byte[] exportToCsv(List<?> data);
  byte[] exportToJson(List<?> data);
}
```

**Cas d'usage**:
- Export liste de chantiers
- Export inventaire matériel
- Export historique factures
- Export planning mensuel

---

### **4. ImportService**

Service d'import de données depuis fichiers externes.

**Méthodes principales**:
```java
public class ImportService {
  ImportResult importFromExcel(MultipartFile file, String entityType);
  ImportResult importFromCsv(MultipartFile file, String entityType);
  ValidationResult validateImportData(List<?> data);
}
```

**Fonctionnalités**:
- Import en masse de matériel
- Import de clients
- Import de fournisseurs
- Validation des données avant import

---

## 🔌 API REST

### **Endpoints Export**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/export/chantiers/excel` | Export chantiers Excel |
| GET | `/api/v1/export/materiels/csv` | Export matériel CSV |
| GET | `/api/v1/export/factures/pdf` | Export factures PDF |

### **Endpoints Import**

| Méthode | Endpoint | Description |
|---------|----------|-------------|
| POST | `/api/v1/import/materiels` | Import matériel |
| POST | `/api/v1/import/clients` | Import clients |
| POST | `/api/v1/import/validate` | Valider données |

---

## 💻 Exemples

### **Export Excel**

```bash
curl -X GET http://localhost:8080/api/v1/export/chantiers/excel \
  -H "Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  --output chantiers.xlsx
```

### **Import matériel**

```bash
curl -X POST http://localhost:8080/api/v1/import/materiels \
  -F "file=@materiels.xlsx" \
  -F "validateOnly=false"
```

**Réponse**:
```json
{
  "success": true,
  "totalRows": 150,
  "imported": 145,
  "errors": 5,
  "errorDetails": [
    {
      "row": 12,
      "error": "Référence déjà existante"
    },
    {
      "row": 45,
      "error": "Type de matériel invalide"
    }
  ]
}
```

---

## 🔧 Configuration

### **Email (application.properties)**

```properties
# Configuration SMTP
quarkus.mailer.host=smtp.gmail.com
quarkus.mailer.port=587
quarkus.mailer.username=noreply@btpxpress.fr
quarkus.mailer.password=${SMTP_PASSWORD}
quarkus.mailer.from=noreply@btpxpress.fr
quarkus.mailer.tls=true
```

### **PDF Generator**

```properties
# Configuration PDF
pdf.generator.font.path=/fonts/
pdf.generator.logo.path=/images/logo.png
pdf.generator.template.path=/templates/pdf/
```

---

## 📈 Utilisation

Ces services sont utilisés par de nombreux concepts :

- **DEVIS** ➡️ PdfGeneratorService, EmailService
- **FACTURE** ➡️ PdfGeneratorService, EmailService
- **BON_COMMANDE** ➡️ PdfGeneratorService, EmailService
- **MATERIEL** ➡️ ExportService, ImportService
- **CHANTIER** ➡️ ExportService, PdfGeneratorService
- **NOTIFICATION** ➡️ EmailService

---

## ✅ Bonnes pratiques

### **Gestion des erreurs**
- Validation des données avant traitement
- Logs détaillés des erreurs
- Retry automatique pour les emails

### **Performance**
- Génération asynchrone des PDF volumineux
- Cache des templates
- Compression des exports

### **Sécurité**
- Validation des fichiers uploadés
- Limitation de la taille des fichiers
- Scan antivirus des uploads

---

## 📚 Références

- [Configuration Quarkus Mailer](https://quarkus.io/guides/mailer)
- [iText PDF Library](https://itextpdf.com/)
- [Apache POI (Excel)](https://poi.apache.org/)

---

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