# Phase 2 - Plan de Refactorisation : Cotisations & Adhésions

**Date** : 17 novembre 2025  
**Objectif** : Refactoriser les modules Cotisations et Adhésions selon DRY/WOU

---

## 📊 ÉTAT ACTUEL DÉTAILLÉ

### Beans Existants

#### 1. `CotisationsBean` (`@Named("cotisationsBean")`)
- **Usage** : Pages `/pages/secure/cotisation/*`
- **Problèmes** :
  - ❌ Classe interne `Cotisation` duplique `CotisationDTO`
  - ❌ Données mockées : `evolutionPaiements`, `repartitionMethodes`, `rappelsEnAttente`
  - ❌ Actions non connectées : `marquerCommePaye()`, `enregistrerPaiementPartiel()`, etc.
  - ❌ Statistiques calculées côté client au lieu d'utiliser `/api/cotisations/stats`
  - ✅ Utilise déjà `CotisationService` pour charger les données

#### 2. `CotisationsGestionBean` (`@Named("cotisationsGestionBean")`)
- **Usage** : Page `/pages/admin/cotisations/gestion.xhtml`
- **Problèmes** :
  - ❌ Classe interne `CotisationAdmin` duplique `CotisationDTO`
  - ❌ Actions non connectées : toutes les actions sont juste des `LOGGER.info()`
  - ❌ Statistiques calculées côté client
  - ✅ Utilise déjà `CotisationService` pour charger les données

### Pages Existantes

#### Pages Cotisations (`/pages/secure/cotisation/`)
- ❌ `paiement.xhtml` - **PLACEHOLDER**
- ❌ `historique.xhtml` - **PLACEHOLDER**
- ❌ `relances.xhtml` - **PLACEHOLDER**
- ❌ `rapports.xhtml` - **PLACEHOLDER**
- ❌ `collect.xhtml` - **PLACEHOLDER**
- ❌ `reminders.xhtml` - **PLACEHOLDER**
- ❌ `report.xhtml` - **PLACEHOLDER**

#### Page Admin Cotisations
- ✅ `/pages/admin/cotisations/gestion.xhtml` - **EXISTE** (utilise `cotisationsGestionBean`)

### Composants Réutilisables Disponibles

✅ **Déjà créés** :
- `page-header.xhtml`
- `form-section.xhtml`
- `form-field-text.xhtml`
- `form-field-calendar.xhtml`
- `form-field-select.xhtml`
- `form-field-textarea.xhtml`
- `form-field-number.xhtml`
- `form-field-checkbox-menu.xhtml`
- `form-field-autocomplete.xhtml`
- `form-field-boolean.xhtml`
- `form-field-group.xhtml`
- `button-primary.xhtml`
- `button-secondary.xhtml`
- `button-success.xhtml`
- `button-info.xhtml`
- `button-warning.xhtml`
- `button-icon.xhtml`
- `stat-card.xhtml`

---

## 🎯 PLAN DE REFACTORISATION

### **ÉTAPE 1 : Refactoriser CotisationsBean** (Priorité 1)

#### 1.1 Supprimer la classe interne `Cotisation`
- [ ] Utiliser directement `CotisationDTO` partout
- [ ] Supprimer `convertToCotisation()` et utiliser directement les DTOs
- [ ] Adapter les propriétés dérivées (statutSeverity, etc.) dans le DTO ou créer un helper

#### 1.2 Utiliser les statistiques du backend
- [ ] Remplacer `initializeStatistiques()` pour utiliser `cotisationService.obtenirStatistiques()`
- [ ] Supprimer le calcul côté client

#### 1.3 Supprimer les données mockées
- [ ] `initializeEvolutionPaiements()` - Calculer depuis les données réelles
- [ ] `initializeRepartitionMethodes()` - Calculer depuis les données réelles
- [ ] `initializeRappels()` - Utiliser `cotisationService.obtenirEnRetard()`

#### 1.4 Connecter les actions au backend
- [ ] `enregistrerCotisation()` → `cotisationService.creer()`
- [ ] `marquerCommePaye()` → `cotisationService.modifier()` avec statut PAYEE
- [ ] `enregistrerPaiementPartiel()` → `cotisationService.modifier()` avec montant partiel
- [ ] `envoyerRappel()` → À implémenter (service de notification)
- [ ] `envoyerRappelsGroupes()` → À implémenter
- [ ] `exporterCotisations()` → À implémenter
- [ ] `genererRapportFinancier()` → Utiliser les statistiques du backend

#### 1.5 Améliorer la recherche
- [ ] Utiliser `cotisationService.rechercher()` au lieu de filtrage côté client
- [ ] Supprimer `appliquerFiltres()` et utiliser la recherche backend

---

### **ÉTAPE 2 : Refactoriser CotisationsGestionBean** (Priorité 2)

#### 2.1 Supprimer la classe interne `CotisationAdmin`
- [ ] Utiliser directement `CotisationDTO`
- [ ] Supprimer `convertToCotisationAdmin()`

#### 2.2 Utiliser les statistiques du backend
- [ ] Remplacer `initializeKPIs()` pour utiliser `cotisationService.obtenirStatistiques()`

#### 2.3 Connecter toutes les actions au backend
- [ ] `enregistrerPaiement()` → `cotisationService.modifier()`
- [ ] `genererRecu()` → À implémenter (génération PDF)
- [ ] `envoyerRappel()` → À implémenter
- [ ] `marquerPayeesGroupees()` → Boucle sur sélection + `cotisationService.modifier()`
- [ ] `envoyerRelancesGroupees()` → À implémenter
- [ ] `genererRecusGroupes()` → À implémenter
- [ ] `annulerCotisationsGroupees()` → `cotisationService.supprimer()`
- [ ] `creerCampagne()` → Créer plusieurs cotisations via `cotisationService.creer()`

---

### **ÉTAPE 3 : Créer les Pages Cotisations** (Priorité 3)

#### 3.1 Page Paiement (`paiement.xhtml`)
- [ ] Utiliser `page-header.xhtml`
- [ ] Formulaire avec `form-field-*` components
- [ ] Sélection méthode paiement (Wave, Orange, etc.)
- [ ] Connexion à `cotisationService.modifier()` pour enregistrer le paiement
- [ ] Utiliser composants boutons réutilisables

#### 3.2 Page Historique (`historique.xhtml`)
- [ ] Utiliser `page-header.xhtml`
- [ ] Tableau avec `p:dataTable`
- [ ] Filtres avec composants réutilisables
- [ ] Connexion à `cotisationService.obtenirParMembre()` ou `cotisationService.rechercher()`
- [ ] Pagination

#### 3.3 Page Relances (`relances.xhtml`)
- [ ] Utiliser `page-header.xhtml`
- [ ] Liste des cotisations en retard via `cotisationService.obtenirEnRetard()`
- [ ] Actions groupées pour envoi de rappels
- [ ] Utiliser composants réutilisables

#### 3.4 Page Rapports (`rapports.xhtml`)
- [ ] Utiliser `page-header.xhtml`
- [ ] Statistiques via `cotisationService.obtenirStatistiques()`
- [ ] Graphiques d'évolution
- [ ] Export Excel/PDF

#### 3.5 Pages Collect, Reminders, Report
- [ ] Déterminer si nécessaire ou fusionner avec autres pages
- [ ] Si nécessaire, créer avec composants réutilisables

---

### **ÉTAPE 4 : Créer Module Adhésions Backend** (Priorité 4)

#### 4.1 Créer `AdhesionDTO` dans `unionflow-server-api`
- [ ] Structure complète avec validations
- [ ] Champs : membreId, typeAdhesion, dateDemande, dateValidation, statut, etc.

#### 4.2 Créer `Adhesion` Entity dans `unionflow-server-impl-quarkus`
- [ ] Entité JPA avec UUID
- [ ] Relations avec Membre et Association

#### 4.3 Créer `AdhesionRepository`
- [ ] Repository Panache
- [ ] Méthodes de recherche

#### 4.4 Créer `AdhesionService`
- [ ] Logique métier complète
- [ ] Méthodes CRUD
- [ ] Validation, Renouvellement, Rejet

#### 4.5 Créer `AdhesionResource`
- [ ] REST API complète
- [ ] Tous les endpoints nécessaires

---

### **ÉTAPE 5 : Créer Module Adhésions Frontend** (Priorité 5)

#### 5.1 Créer `AdhesionService` (RestClient)
- [ ] Interface complète correspondant au backend

#### 5.2 Créer `AdhesionsBean`
- [ ] Bean JSF
- [ ] Connexion complète au backend
- [ ] Utiliser directement `AdhesionDTO` (pas de classe interne)

#### 5.3 Créer les pages Adhésions
- [ ] `demande.xhtml` - Formulaire avec composants réutilisables
- [ ] `validation.xhtml` - Liste + actions avec composants réutilisables
- [ ] `renouvellement.xhtml` - Formulaire avec composants réutilisables
- [ ] `liste.xhtml` - Tableau avec composants réutilisables
- [ ] `pending.xhtml` - Liste en attente
- [ ] `history.xhtml` - Historique

---

## 🔄 ORDRE D'EXÉCUTION

1. **Étape 1** : Refactoriser `CotisationsBean` (1-2 semaines)
2. **Étape 2** : Refactoriser `CotisationsGestionBean` (1 semaine)
3. **Étape 3** : Créer pages Cotisations (2-3 semaines)
4. **Étape 4** : Créer module Adhésions Backend (1-2 semaines)
5. **Étape 5** : Créer module Adhésions Frontend (2-3 semaines)

**Durée totale** : 7-11 semaines

---

## ✅ PRINCIPES À RESPECTER

### DRY (Don't Repeat Yourself)
- ❌ Pas de duplication de DTOs (supprimer classes internes)
- ❌ Pas de calculs dupliqués (utiliser backend)
- ❌ Pas de code répétitif (utiliser composants)

### WOU (Write Once, Use Everywhere)
- ✅ Utiliser composants réutilisables créés
- ✅ Utiliser `CotisationDTO` directement
- ✅ Centraliser la logique dans les services

### Connexion Backend
- ✅ Toutes les actions doivent appeler le backend
- ✅ Utiliser les statistiques du backend
- ✅ Gérer les erreurs proprement

---

**Document créé le** : 17 novembre 2025