unionflow-server-api/PHASE2_REFACTORING_PLAN.md

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