Initial commit

2025-10-01 01:37:34 +00:00
commit f2bb633142
310 changed files with 86051 additions and 0 deletions
--- a/API.md
+++ b/API.md
@@ -0,0 +1,356 @@
+# 🌐 API REST - BTPXPRESS BACKEND
+
+## 📋 Table des matières
+
+- [Vue d'ensemble](#vue-densemble)
+- [Authentification](#authentification)
+- [Endpoints par concept](#endpoints-par-concept)
+- [Codes de réponse](#codes-de-réponse)
+- [Pagination](#pagination)
+- [Filtrage et tri](#filtrage-et-tri)
+- [Gestion des erreurs](#gestion-des-erreurs)
+- [Exemples complets](#exemples-complets)
+
+---
+
+## 🎯 Vue d'ensemble
+
+### **Base URL**
+
+| Environnement | URL |
+|---------------|-----|
+| **Développement** | `http://localhost:8080/api/v1` |
+| **Production** | `https://api.btpxpress.fr/api/v1` |
+
+### **Format**
+
+- **Content-Type** : `application/json`
+- **Accept** : `application/json`
+- **Charset** : `UTF-8`
+
+### **Versioning**
+
+L'API utilise le versioning dans l'URL : `/api/v1/...`
+
+### **Documentation interactive**
+
+- **Swagger UI** : http://localhost:8080/q/swagger-ui
+- **OpenAPI Spec** : http://localhost:8080/q/openapi
+
+---
+
+## 🔐 Authentification
+
+### **OAuth2 / OIDC avec Keycloak**
+
+Toutes les requêtes (sauf `/auth/login`) nécessitent un token JWT.
+
+#### **1. Obtenir un token**
+
+```bash
+curl -X POST http://localhost:8180/realms/btpxpress/protocol/openid-connect/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=password" \
+  -d "client_id=btpxpress-backend" \
+  -d "client_secret=your-secret" \
+  -d "username=admin" \
+  -d "password=admin123"
+```
+
+**Réponse** :
+```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "expires_in": 300,
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer"
+}
+```
+
+#### **2. Utiliser le token**
+
+```bash
+curl -X GET http://localhost:8080/api/v1/chantiers \
+  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+---
+
+## 📚 Endpoints par concept
+
+### **1. CHANTIERS** (`/api/v1/chantiers`)
+
+| Méthode | Endpoint | Description | Permission |
+|---------|----------|-------------|------------|
+| GET | `/chantiers` | Liste tous les chantiers | CHANTIERS_READ |
+| GET | `/chantiers/{id}` | Détails d'un chantier | CHANTIERS_READ |
+| POST | `/chantiers` | Créer un chantier | CHANTIERS_CREATE |
+| PUT | `/chantiers/{id}` | Modifier un chantier | CHANTIERS_UPDATE |
+| DELETE | `/chantiers/{id}` | Supprimer un chantier | CHANTIERS_DELETE |
+| GET | `/chantiers/search` | Rechercher des chantiers | CHANTIERS_READ |
+| GET | `/chantiers/stats` | Statistiques chantiers | CHANTIERS_READ |
+
+### **2. CLIENTS** (`/api/v1/clients`)
+
+| Méthode | Endpoint | Description | Permission |
+|---------|----------|-------------|------------|
+| GET | `/clients` | Liste tous les clients | CLIENTS_READ |
+| GET | `/clients/{id}` | Détails d'un client | CLIENTS_READ |
+| POST | `/clients` | Créer un client | CLIENTS_CREATE |
+| PUT | `/clients/{id}` | Modifier un client | CLIENTS_UPDATE |
+| DELETE | `/clients/{id}` | Supprimer un client | CLIENTS_DELETE |
+
+### **3. MATÉRIELS** (`/api/v1/materiels`)
+
+| Méthode | Endpoint | Description | Permission |
+|---------|----------|-------------|------------|
+| GET | `/materiels` | Liste tous les matériels | MATERIELS_READ |
+| GET | `/materiels/{id}` | Détails d'un matériel | MATERIELS_READ |
+| POST | `/materiels` | Créer un matériel | MATERIELS_CREATE |
+| PUT | `/materiels/{id}` | Modifier un matériel | MATERIELS_UPDATE |
+| DELETE | `/materiels/{id}` | Supprimer un matériel | MATERIELS_DELETE |
+| GET | `/materiels/disponibles` | Matériels disponibles | MATERIELS_READ |
+| GET | `/materiels/stock-faible` | Stock faible | MATERIELS_READ |
+
+### **4. RÉSERVATIONS** (`/api/v1/reservations-materiel`)
+
+| Méthode | Endpoint | Description | Permission |
+|---------|----------|-------------|------------|
+| GET | `/reservations-materiel` | Liste réservations | RESERVATIONS_READ |
+| POST | `/reservations-materiel` | Créer réservation | RESERVATIONS_CREATE |
+| GET | `/reservations-materiel/conflits` | Détecter conflits | RESERVATIONS_READ |
+
+### **5. DEVIS** (`/api/v1/devis`)
+
+| Méthode | Endpoint | Description | Permission |
+|---------|----------|-------------|------------|
+| GET | `/devis` | Liste devis | DEVIS_READ |
+| GET | `/devis/{id}` | Détails devis | DEVIS_READ |
+| POST | `/devis` | Créer devis | DEVIS_CREATE |
+| PUT | `/devis/{id}/envoyer` | Envoyer devis | DEVIS_UPDATE |
+| GET | `/devis/{id}/pdf` | Générer PDF | DEVIS_READ |
+
+### **6. EMPLOYÉS** (`/api/v1/employes`)
+
+| Méthode | Endpoint | Description | Permission |
+|---------|----------|-------------|------------|
+| GET | `/employes` | Liste employés | EMPLOYES_READ |
+| GET | `/employes/{id}` | Détails employé | EMPLOYES_READ |
+| POST | `/employes` | Créer employé | EMPLOYES_CREATE |
+| GET | `/employes/disponibles` | Employés disponibles | EMPLOYES_READ |
+
+### **7. PLANNING** (`/api/v1/planning`)
+
+| Méthode | Endpoint | Description | Permission |
+|---------|----------|-------------|------------|
+| GET | `/planning` | Liste événements | PLANNING_READ |
+| POST | `/planning` | Créer événement | PLANNING_CREATE |
+| GET | `/planning/periode` | Par période | PLANNING_READ |
+
+### **8. NOTIFICATIONS** (`/api/v1/notifications`)
+
+| Méthode | Endpoint | Description | Permission |
+|---------|----------|-------------|------------|
+| GET | `/notifications` | Liste notifications | - |
+| GET | `/notifications/non-lues` | Non lues | - |
+| PUT | `/notifications/{id}/lire` | Marquer comme lue | - |
+
+---
+
+## 📊 Codes de réponse
+
+| Code | Signification | Description |
+|------|---------------|-------------|
+| **200** | OK | Requête réussie |
+| **201** | Created | Ressource créée |
+| **204** | No Content | Suppression réussie |
+| **400** | Bad Request | Données invalides |
+| **401** | Unauthorized | Non authentifié |
+| **403** | Forbidden | Accès refusé |
+| **404** | Not Found | Ressource non trouvée |
+| **409** | Conflict | Conflit (ex: email déjà existant) |
+| **500** | Internal Server Error | Erreur serveur |
+
+---
+
+## 📄 Pagination
+
+### **Paramètres**
+
+| Paramètre | Type | Défaut | Description |
+|-----------|------|--------|-------------|
+| `page` | Integer | 0 | Numéro de page (commence à 0) |
+| `size` | Integer | 20 | Nombre d'éléments par page |
+| `sort` | String | - | Champ de tri (ex: `nom,asc`) |
+
+### **Exemple**
+
+```bash
+GET /api/v1/chantiers?page=0&size=10&sort=nom,asc
+```
+
+### **Réponse paginée**
+
+```json
+{
+  "content": [...],
+  "totalElements": 150,
+  "totalPages": 15,
+  "size": 10,
+  "number": 0,
+  "first": true,
+  "last": false
+}
+```
+
+---
+
+## 🔍 Filtrage et tri
+
+### **Filtres**
+
+```bash
+# Filtrer par statut
+GET /api/v1/chantiers?statut=EN_COURS
+
+# Filtrer par type
+GET /api/v1/materiels?type=VEHICULE
+
+# Filtrer par date
+GET /api/v1/devis?dateDebut=2025-01-01&dateFin=2025-12-31
+```
+
+### **Recherche**
+
+```bash
+# Recherche textuelle
+GET /api/v1/chantiers/search?q=villa
+
+# Recherche avancée
+GET /api/v1/clients/search?nom=Dupont&ville=Paris
+```
+
+---
+
+## ❌ Gestion des erreurs
+
+### **Format d'erreur standard**
+
+```json
+{
+  "timestamp": "2025-09-30T10:30:00",
+  "status": 400,
+  "error": "Bad Request",
+  "message": "Le nom du chantier est obligatoire",
+  "path": "/api/v1/chantiers",
+  "errors": [
+    {
+      "field": "nom",
+      "message": "Le nom est obligatoire"
+    }
+  ]
+}
+```
+
+### **Erreurs de validation**
+
+```json
+{
+  "status": 400,
+  "message": "Validation failed",
+  "errors": [
+    {
+      "field": "email",
+      "message": "Email invalide"
+    },
+    {
+      "field": "telephone",
+      "message": "Le téléphone doit contenir 10 chiffres"
+    }
+  ]
+}
+```
+
+---
+
+## 💡 Exemples complets
+
+### **Créer un chantier complet**
+
+```bash
+curl -X POST http://localhost:8080/api/v1/chantiers \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "nom": "Construction Villa Moderne",
+    "code": "CHANT-2025-001",
+    "description": "Construction d une villa moderne de 150m²",
+    "adresse": "123 Rue de la Paix",
+    "codePostal": "75001",
+    "ville": "Paris",
+    "clientId": "client-uuid",
+    "statut": "PLANIFIE",
+    "dateDebut": "2025-10-01",
+    "dateFinPrevue": "2026-03-31",
+    "montantPrevu": 250000.00,
+    "surfaceM2": 150.00
+  }'
+```
+
+### **Rechercher des chantiers**
+
+```bash
+curl -X GET "http://localhost:8080/api/v1/chantiers/search?q=villa&statut=EN_COURS&page=0&size=10" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### **Créer un devis avec lignes**
+
+```bash
+curl -X POST http://localhost:8080/api/v1/devis \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientId": "client-uuid",
+    "chantierId": "chantier-uuid",
+    "dateEmission": "2025-10-01",
+    "dateValidite": "2025-11-01",
+    "lignes": [
+      {
+        "designation": "Terrassement",
+        "quantite": 1,
+        "prixUnitaireHT": 5000.00
+      },
+      {
+        "designation": "Maçonnerie",
+        "quantite": 45,
+        "prixUnitaireHT": 120.00
+      }
+    ]
+  }'
+```
+
+### **Télécharger un PDF**
+
+```bash
+curl -X GET http://localhost:8080/api/v1/devis/{id}/pdf \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Accept: application/pdf" \
+  --output devis.pdf
+```
+
+---
+
+## 🔗 Liens utiles
+
+- [Swagger UI](http://localhost:8080/q/swagger-ui)
+- [Health Check](http://localhost:8080/q/health)
+- [Metrics](http://localhost:8080/q/metrics)
+- [OpenAPI Spec](http://localhost:8080/q/openapi)
+
+---
+
+**Dernière mise à jour**: 2025-09-30  
+**Version**: 1.0  
+**Auteur**: Équipe BTPXpress
+