Initial commit

2025-10-01 01:37:34 +00:00
commit f2bb633142
310 changed files with 86051 additions and 0 deletions
--- a/docs/concepts/22-SERVICES_TRANSVERSES.md
+++ b/docs/concepts/22-SERVICES_TRANSVERSES.md
@@ -0,0 +1,237 @@
+# ⚙️ 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
+