btpxpress-backend/docs/concepts/22-SERVICES_TRANSVERSES.md

⚙️ 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:

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:

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:

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:

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

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

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

Réponse:

{
  "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)

# 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

# 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
• iText PDF Library
• Apache POI (Excel)

---

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