238 lines
5.2 KiB
Markdown
238 lines
5.2 KiB
Markdown
# ⚙️ 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
|
|
|