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