chore(quarkus-327): bump to Quarkus 3.27.3 LTS, rename deprecated config keys
This commit is contained in:
221
LAZY_LOADING_IMPLEMENTATION_SPEC.md
Normal file
221
LAZY_LOADING_IMPLEMENTATION_SPEC.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 📋 Spécification Technique - Implémentation Lazy Loading Production
|
||||
|
||||
## 🎯 Objectif
|
||||
Implémenter le lazy loading pour les factures avec une solution **production-ready** incluant :
|
||||
- Gestion d'erreurs robuste
|
||||
- Logging approprié
|
||||
- Tests unitaires et d'intégration
|
||||
- Documentation complète
|
||||
- Compatibilité backend/frontend
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### Composants à Créer/Modifier
|
||||
|
||||
#### Frontend (btpxpress-client)
|
||||
1. **FactureLazyDataModel** - Nouveau
|
||||
2. **FactureService** - Modifier (ajouter méthodes lazy)
|
||||
3. **BtpXpressApiClient** - Modifier (ajouter endpoints lazy)
|
||||
4. **FactureView** - Modifier (utiliser LazyDataModel)
|
||||
5. **factures.xhtml** - Modifier (activer lazy loading)
|
||||
|
||||
#### Backend (btpxpress-server)
|
||||
1. **FactureResource** - Modifier (ajouter endpoints lazy)
|
||||
2. **FactureService** - Modifier (ajouter méthodes paginées)
|
||||
3. **FactureRepository** - Modifier (ajouter requêtes paginées)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Flux de Données
|
||||
|
||||
```
|
||||
[factures.xhtml]
|
||||
↓ (lazy=true, rows=10)
|
||||
[FactureView + LazyDataModel]
|
||||
↓ (load(first, pageSize, sortBy, filterBy))
|
||||
[FactureService]
|
||||
↓ (getFacturesLazy(params))
|
||||
[BtpXpressApiClient]
|
||||
↓ (HTTP GET /api/v1/factures/lazy?offset=0&limit=10&...)
|
||||
[Backend FactureResource]
|
||||
↓ (getFacturesLazy(offset, limit, ...))
|
||||
[Backend FactureService]
|
||||
↓ (findFacturesLazy(offset, limit, ...))
|
||||
[Backend FactureRepository]
|
||||
↓ (Panache query with pagination)
|
||||
[Database]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Détails d'Implémentation
|
||||
|
||||
### 1. Backend - FactureRepository
|
||||
|
||||
**Méthodes à ajouter** :
|
||||
```java
|
||||
/**
|
||||
* Compte le nombre total de factures avec filtres optionnels
|
||||
*/
|
||||
public long countFactures(String filtreNumero, String filtreClient, String filtreStatut);
|
||||
|
||||
/**
|
||||
* Récupère les factures avec pagination, tri et filtres
|
||||
*/
|
||||
public List<Facture> findFacturesLazy(
|
||||
int offset,
|
||||
int limit,
|
||||
String sortField,
|
||||
String sortOrder,
|
||||
String filtreNumero,
|
||||
String filtreClient,
|
||||
String filtreStatut
|
||||
);
|
||||
```
|
||||
|
||||
### 2. Backend - FactureService
|
||||
|
||||
**Méthodes à ajouter** :
|
||||
```java
|
||||
/**
|
||||
* Récupère les factures avec pagination
|
||||
* @return DTO contenant les factures et le total
|
||||
*/
|
||||
public FacturePageDTO getFacturesLazy(FactureFilterDTO filters);
|
||||
|
||||
/**
|
||||
* Compte les factures avec filtres
|
||||
*/
|
||||
public long countFactures(FactureFilterDTO filters);
|
||||
```
|
||||
|
||||
### 3. Backend - FactureResource
|
||||
|
||||
**Endpoints à ajouter** :
|
||||
```java
|
||||
@GET
|
||||
@Path("/lazy")
|
||||
@Produces(MediaType.APPLICATION_JSON)
|
||||
public Response getFacturesLazy(
|
||||
@QueryParam("offset") @DefaultValue("0") int offset,
|
||||
@QueryParam("limit") @DefaultValue("10") int limit,
|
||||
@QueryParam("sortField") String sortField,
|
||||
@QueryParam("sortOrder") @DefaultValue("ASC") String sortOrder,
|
||||
@QueryParam("filter_numero") String filtreNumero,
|
||||
@QueryParam("filter_client") String filtreClient,
|
||||
@QueryParam("filter_statut") String filtreStatut
|
||||
);
|
||||
|
||||
@GET
|
||||
@Path("/count")
|
||||
@Produces(MediaType.APPLICATION_JSON)
|
||||
public Response countFactures(
|
||||
@QueryParam("filter_numero") String filtreNumero,
|
||||
@QueryParam("filter_client") String filtreClient,
|
||||
@QueryParam("filter_statut") String filtreStatut
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Critères d'Acceptation
|
||||
|
||||
### Fonctionnels
|
||||
- [ ] La liste des factures charge seulement 10-50 items par page
|
||||
- [ ] La pagination fonctionne correctement (première, précédente, suivante, dernière page)
|
||||
- [ ] Le tri fonctionne sur toutes les colonnes triables
|
||||
- [ ] Les filtres fonctionnent et sont appliqués côté serveur
|
||||
- [ ] Le compteur total affiche le bon nombre de factures
|
||||
- [ ] Les performances sont améliorées (temps de chargement <500ms)
|
||||
|
||||
### Techniques
|
||||
- [ ] Gestion d'erreurs complète (try-catch, logging)
|
||||
- [ ] Validation des paramètres (offset >= 0, limit > 0, etc.)
|
||||
- [ ] Logs appropriés (DEBUG, INFO, WARN, ERROR)
|
||||
- [ ] Code commenté et documenté
|
||||
- [ ] Tests unitaires (couverture >80%)
|
||||
- [ ] Tests d'intégration
|
||||
- [ ] Pas de régression sur les fonctionnalités existantes
|
||||
|
||||
### Sécurité
|
||||
- [ ] Validation côté serveur de tous les paramètres
|
||||
- [ ] Protection contre SQL injection
|
||||
- [ ] Vérification des droits d'accès
|
||||
- [ ] Limitation du nombre max d'items par page (ex: 100)
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Plan de Tests
|
||||
|
||||
### Tests Unitaires
|
||||
|
||||
#### Frontend
|
||||
- `FactureLazyDataModel.load()` - Cas nominal
|
||||
- `FactureLazyDataModel.load()` - Avec filtres
|
||||
- `FactureLazyDataModel.load()` - Avec tri
|
||||
- `FactureLazyDataModel.count()` - Cas nominal
|
||||
- `FactureLazyDataModel` - Gestion d'erreurs
|
||||
|
||||
#### Backend
|
||||
- `FactureRepository.findFacturesLazy()` - Pagination
|
||||
- `FactureRepository.findFacturesLazy()` - Tri
|
||||
- `FactureRepository.findFacturesLazy()` - Filtres
|
||||
- `FactureRepository.countFactures()` - Avec/sans filtres
|
||||
- `FactureService.getFacturesLazy()` - Cas nominal
|
||||
- `FactureService.getFacturesLazy()` - Gestion d'erreurs
|
||||
|
||||
### Tests d'Intégration
|
||||
- Chargement de la première page
|
||||
- Navigation entre les pages
|
||||
- Tri par différentes colonnes
|
||||
- Application de filtres multiples
|
||||
- Gestion d'erreurs réseau
|
||||
- Performance (temps de réponse <500ms)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Checklist d'Implémentation
|
||||
|
||||
### Phase 1 : Backend (Priorité 1)
|
||||
- [ ] Créer DTOs (FactureFilterDTO, FacturePageDTO)
|
||||
- [ ] Implémenter FactureRepository.findFacturesLazy()
|
||||
- [ ] Implémenter FactureRepository.countFactures()
|
||||
- [ ] Implémenter FactureService.getFacturesLazy()
|
||||
- [ ] Implémenter FactureResource endpoints
|
||||
- [ ] Tests unitaires backend
|
||||
- [ ] Tests d'intégration backend
|
||||
|
||||
### Phase 2 : Frontend (Priorité 2)
|
||||
- [ ] Créer FactureLazyDataModel
|
||||
- [ ] Modifier BtpXpressApiClient
|
||||
- [ ] Modifier FactureService
|
||||
- [ ] Modifier FactureView
|
||||
- [ ] Modifier factures.xhtml
|
||||
- [ ] Tests unitaires frontend
|
||||
|
||||
### Phase 3 : Tests & Documentation (Priorité 3)
|
||||
- [ ] Tests end-to-end
|
||||
- [ ] Tests de performance
|
||||
- [ ] Documentation technique
|
||||
- [ ] Documentation utilisateur
|
||||
- [ ] Revue de code
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Risques et Mitigation
|
||||
|
||||
| Risque | Impact | Probabilité | Mitigation |
|
||||
|--------|--------|-------------|------------|
|
||||
| Incompatibilité backend | Élevé | Faible | Vérifier version Panache, tester avec données réelles |
|
||||
| Performance dégradée | Élevé | Moyen | Indexer colonnes de tri/filtre, optimiser requêtes |
|
||||
| Régression fonctionnelle | Moyen | Moyen | Tests complets avant déploiement |
|
||||
| Erreurs réseau | Moyen | Faible | Gestion d'erreurs robuste, retry logic |
|
||||
|
||||
---
|
||||
|
||||
**Version** : 1.0
|
||||
**Date** : 2025-12-29
|
||||
**Statut** : Prêt pour implémentation
|
||||
|
||||
Reference in New Issue
Block a user