btpxpress-frontend/LAZY_LOADING_IMPLEMENTATION_SPEC.md

📋 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 :

/**
 * 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 :

/**
 * 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 :

@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