unionflow-mobile-apps/PLAN_IMPLEMENTATION_ARCHITECTURE_V3.md

Plan d'Implémentation - Architecture UnionFlow v3.0

Date : 2025-01-29
Objectif : Aligner le code actuel avec l'architecture cible (union-flow.puml)

---

📊 État Actuel vs Architecture Cible

✅ Entités Existantes

• ✅ BaseEntity
• ✅ Organisation
• ✅ TypeOrganisationEntity
• ✅ Membre
• ✅ Cotisation
• ✅ Adhesion
• ✅ Evenement
• ✅ InscriptionEvenement
• ✅ DemandeAide
• ✅ AuditLog

❌ Entités Manquantes

1. Paiements : Paiement, PaiementCotisation, PaiementAdhesion, PaiementEvenement, PaiementAide
2. Wave : CompteWave, TransactionWave, WebhookWave, ConfigurationWave
3. Comptabilité : CompteComptable, JournalComptable, EcritureComptable, LigneEcriture
4. Documents : Document, PieceJointe
5. Notifications : Notification, TemplateNotification
6. Rôles/Permissions : Role, Permission, MembreRole, RolePermission
7. Adresses : Adresse (séparée)

---

🎯 Plan d'Implémentation par Étapes

PHASE 1 : FONDATIONS - Adresses et Rôles (Priorité HAUTE)

Durée estimée : 2-3 jours

Étape 1.1 : Entité Adresse

• Créer Adresse.java (entité séparée)
• Types d'adresse : SIEGE_SOCIAL, BUREAU, DOMICILE, AUTRE
• Relations : Organisation ↔ Adresse (0..), Membre ↔ Adresse (0..)
• Migration : Extraire adresses de Organisation et Membre
• Repository : AdresseRepository
• Service : AdresseService
• DTO : AdresseDTO

Étape 1.2 : Système de Rôles et Permissions

• Créer Role.java (entité)
• Créer Permission.java (entité)
• Créer MembreRole.java (table de liaison)
• Créer RolePermission.java (table de liaison)
• Enums : TypeRole, TypePermission
• Repository : RoleRepository, PermissionRepository, MembreRoleRepository, RolePermissionRepository
• Service : RoleService, PermissionService
• DTOs : RoleDTO, PermissionDTO, MembreRoleDTO

---

PHASE 2 : SYSTÈME DE PAIEMENTS CENTRALISÉ (Priorité CRITIQUE)

Durée estimée : 3-4 jours

Étape 2.1 : Entité Paiement

• Créer Paiement.java (entité centrale)
• Enum : MethodePaiement (WAVE_MOBILE_MONEY, ORANGE_MONEY, MTN_MOBILE_MONEY, etc.)
• Enum : StatutPaiement (EN_ATTENTE, EN_COURS, VALIDE, ECHOUE, ANNULE, REMBOURSE)
• Champs : montant, devise, datePaiement, dateValidation, validateur, references externes
• Relation : Paiement → Membre (1-N)
• Repository : PaiementRepository
• Service : PaiementService
• DTO : PaiementDTO

Étape 2.2 : Tables de Liaison Paiements

• Créer PaiementCotisation.java (table de liaison)
• Créer PaiementAdhesion.java (table de liaison)
• Créer PaiementEvenement.java (table de liaison)
• Créer PaiementAide.java (table de liaison)
• Champs communs : montantApplique, dateApplication
• Relations : Paiement ↔ Cotisation/Adhesion/Evenement/Aide
• Repositories : PaiementCotisationRepository, etc.
• Services : Logique d'application des paiements

Étape 2.3 : Refactoring Cotisation et Adhesion

• Modifier Cotisation.java : Retirer montantPaye, utiliser PaiementCotisation
• Modifier Adhesion.java : Retirer montantPaye, utiliser PaiementAdhesion
• Mettre à jour CotisationService : Utiliser PaiementService
• Mettre à jour AdhesionService : Utiliser PaiementService
• Migration des données existantes

---

PHASE 3 : INTÉGRATION WAVE MOBILE MONEY (Priorité CRITIQUE)

Durée estimée : 4-5 jours

Étape 3.1 : Entités Wave

• Créer CompteWave.java
  • Numéro téléphone (+225XXXXXXXX)
  • Statut : NON_VERIFIE, VERIFIE, SUSPENDU, BLOQUE
  • Relations : Organisation (1-N), Membre (0..1)
  • Identifiants API encryptés
• Créer TransactionWave.java
  • Identifiants Wave (transactionId, requestId, reference)
  • Type : DEPOT, RETRAIT, TRANSFERT, PAIEMENT, REMBOURSEMENT
  • Statut : INITIALISE, EN_ATTENTE, EN_COURS, REUSSIE, ECHOUE, ANNULEE, EXPIRED
  • Montant, frais, montant net
  • Métadonnées JSON
  • Relation : CompteWave (1-N), Paiement (0..1)
• Créer WebhookWave.java
  • Wave event ID
  • Type d'événement
  • Statut traitement : EN_ATTENTE, EN_TRAITEMENT, TRAITE, ECHOUE, IGNORE
  • Payload JSON
  • Relation : TransactionWave (0..1), Paiement (0..1)
• Créer ConfigurationWave.java
  • Clé-valeur pour configuration
  • Support sandbox/production

Étape 3.2 : Repositories et Services Wave

• Repositories : CompteWaveRepository, TransactionWaveRepository, WebhookWaveRepository, ConfigurationWaveRepository
• Service : WaveService (intégration API Wave)
  • Méthodes : initierPaiement, verifierTransaction, traiterWebhook
  • Gestion retry avec backoff exponentiel
  • Validation de signature webhook
  • Chiffrement des clés API

Étape 3.3 : Intégration avec PaiementService

• Modifier PaiementService : Support Wave
• Workflow : Initiation → TransactionWave → Webhook → Validation
• Gestion des erreurs et retry

---

PHASE 4 : COMPTABILITÉ (Priorité MOYENNE)

Durée estimée : 3-4 jours

Étape 4.1 : Plan Comptable

• Créer CompteComptable.java
  • Numéro compte unique
  • Type : ACTIF, PASSIF, CHARGES, PRODUITS, TRESORERIE, AUTRE
  • Classe comptable (1-7)
  • Solde initial, solde actuel
• Repository : CompteComptableRepository
• Service : CompteComptableService
• DTO : CompteComptableDTO

Étape 4.2 : Journaux et Écritures

• Créer JournalComptable.java
  • Code unique
  • Type : ACHATS, VENTES, BANQUE, CAISSE, OD
  • Période, statut
• Créer EcritureComptable.java
  • Numéro pièce unique
  • Date, libellé, référence
  • Lettrage, pointage
  • Relation : JournalComptable (1-N), Organisation (1-N), Paiement (0..1)
• Créer LigneEcriture.java
  • Numéro ligne
  • Compte débiteur/créditeur
  • Montant débit/crédit
  • Relation : EcritureComptable (1-N), CompteComptable (1-N)
  • Validation : Débit = Crédit

Étape 4.3 : Service Comptable

• Service : ComptabiliteService
  • Génération automatique d'écritures pour paiements
  • Rapprochement bancaire
  • Pointage et lettrage
• Intégration avec PaiementService

---

PHASE 5 : GESTION DOCUMENTAIRE (Priorité MOYENNE)

Durée estimée : 2-3 jours

Étape 5.1 : Entités Documents

• Créer Document.java
  • Nom fichier, nom original
  • Chemin stockage
  • Type MIME, taille
  • Hash MD5, SHA256
  • Type : IDENTITE, JUSTIFICATIF_DOMICILE, PHOTO, CONTRAT, FACTURE, RECU, RAPPORT, AUTRE
• Créer PieceJointe.java
  • Ordre d'affichage
  • Libellé, commentaire
  • Relations flexibles : Membre, Organisation, Cotisation, Adhesion, DemandeAide, TransactionWave

Étape 5.2 : Services Documents

• Repositories : DocumentRepository, PieceJointeRepository
• Service : DocumentService
  • Upload sécurisé
  • Vérification intégrité (hash)
  • Contrôle d'accès
  • Audit téléchargements

---

PHASE 6 : SYSTÈME DE NOTIFICATIONS (Priorité MOYENNE)

Durée estimée : 2-3 jours

Étape 6.1 : Entités Notifications

• Créer TemplateNotification.java
  • Code unique
  • Sujet, corps (texte et HTML)
  • Variables disponibles (JSON)
  • Canaux supportés
  • Support multi-langues
• Créer Notification.java
  • Type : EMAIL, SMS, PUSH, IN_APP, SYSTEME
  • Priorité : CRITIQUE, HAUTE, NORMALE, BASSE
  • Statut : EN_ATTENTE, ENVOYEE, LUE, ECHOUE, ANNULEE
  • Relations : Membre (1-N), Organisation (0..1), TemplateNotification (0..1)

Étape 6.2 : Service Notifications

• Repositories : NotificationRepository, TemplateNotificationRepository
• Service : NotificationService
  • Envoi multi-canaux
  • Retry automatique
  • Priorisation
  • Templates réutilisables

---

PHASE 7 : MISE À JOUR MEMBRE (Priorité HAUTE)

Durée estimée : 1-2 jours

Étape 7.1 : Ajout Champs Membre

• Ajouter telephoneWave (String, format +225XXXXXXXX)
• Ajouter photoUrl (String)
• Relation : Membre → CompteWave (0..1)
• Relation : Membre → Adresse (0..*)
• Relation : Membre → MembreRole (1-N)

Étape 7.2 : Migration Données

• Script de migration pour extraire adresses
• Attribution rôles par défaut
• Validation format téléphone Wave

---

PHASE 8 : MISE À JOUR ORGANISATION (Priorité MOYENNE)

Durée estimée : 1 jour

Étape 8.1 : Relations Organisation

• Relation : Organisation → CompteWave (1-N)
• Relation : Organisation → Adresse (0..*)
• Migration : Extraire adresses vers entité Adresse

---

PHASE 9 : MISE À JOUR ÉVÉNEMENT (Priorité MOYENNE)

Durée estimée : 1 jour

Étape 9.1 : Relations Evenement

• Relation : Evenement → Adresse (0..1)
• Relation : Evenement → PaiementEvenement (0..*)
• Migration : Extraire adresse vers entité Adresse

---

PHASE 10 : RESSOURCES REST ET DTOs (Priorité HAUTE)

Durée estimée : 3-4 jours

Étape 10.1 : DTOs API

• Créer tous les DTOs manquants dans unionflow-server-api
• Enums dans unionflow-server-api

Étape 10.2 : Resources REST

• PaiementResource
• WaveResource (CompteWave, TransactionWave, WebhookWave)
• ComptabiliteResource (CompteComptable, JournalComptable, EcritureComptable)
• DocumentResource
• NotificationResource
• RoleResource, PermissionResource
• AdresseResource

---

PHASE 11 : TESTS ET VALIDATION (Priorité HAUTE)

Durée estimée : 2-3 jours

Étape 11.1 : Tests Unitaires

• Tests pour toutes les nouvelles entités
• Tests pour tous les services
• Tests d'intégration Wave (mock)

Étape 11.2 : Tests d'Intégration

• Tests de workflow complet paiement
• Tests webhooks Wave
• Tests génération écritures comptables

---

📋 Ordre d'Implémentation Recommandé

1. PHASE 1 : Adresses et Rôles (fondations)
2. PHASE 2 : Système de Paiements (critique)
3. PHASE 7 : Mise à jour Membre (dépend de Phase 1)
4. PHASE 3 : Intégration Wave (dépend de Phase 2)
5. PHASE 4 : Comptabilité (dépend de Phase 2)
6. PHASE 5 : Documents
7. PHASE 6 : Notifications
8. PHASE 8-9 : Mises à jour Organisation/Evenement
9. PHASE 10 : Resources REST
10. PHASE 11 : Tests

---

🚀 Démarrage de l'Implémentation

Prochaine étape : Commencer par la PHASE 1 - Étape 1.1 : Création de l'entité Adresse