# 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