unionflow-server-api/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 ✅ COMPLÉTÉE
- [x] Créer `Adresse.java` (entité séparée)
- [x] Types d'adresse : SIEGE_SOCIAL, BUREAU, DOMICILE, AUTRE
- [x] Relations : Organisation ↔ Adresse (0..*), Membre ↔ Adresse (0..*), Evenement ↔ Adresse (0..1)
- [x] Repository : `AdresseRepository`
- [x] Service : `AdresseService`
- [x] DTO : `AdresseDTO`
- [x] Enum `TypeAdresse` dans module API

#### Étape 1.2 : Système de Rôles et Permissions ✅ COMPLÉTÉE
- [x] Créer `Role.java` (entité)
- [x] Créer `Permission.java` (entité)
- [x] Créer `MembreRole.java` (table de liaison)
- [x] Créer `RolePermission.java` (table de liaison)
- [x] Enum TypeRole dans entité
- [x] Repository : `RoleRepository`, `PermissionRepository`, `MembreRoleRepository`, `RolePermissionRepository`
- [x] Service : `RoleService`, `PermissionService`
- [ ] DTOs : `RoleDTO`, `PermissionDTO`, `MembreRoleDTO` (à créer)

---

### **PHASE 2 : SYSTÈME DE PAIEMENTS CENTRALISÉ** (Priorité CRITIQUE)
**Durée estimée** : 3-4 jours

#### Étape 2.1 : Entité Paiement ✅ COMPLÉTÉE
- [x] Créer `Paiement.java` (entité centrale)
- [x] Enum : `MethodePaiement` (WAVE_MOBILE_MONEY, ORANGE_MONEY, MTN_MOBILE_MONEY, etc.) dans module API
- [x] Enum : `StatutPaiement` (EN_ATTENTE, EN_COURS, VALIDE, ECHOUE, ANNULE, REMBOURSE) dans module API
- [x] Champs : montant, devise, datePaiement, dateValidation, validateur, references externes
- [x] Relation : Paiement → Membre (1-N)
- [x] Repository : `PaiementRepository`
- [x] Service : `PaiementService`
- [x] DTO : `PaiementDTO`
- [x] Resource REST : `PaiementResource`

#### Étape 2.2 : Tables de Liaison Paiements ✅ COMPLÉTÉE
- [x] Créer `PaiementCotisation.java` (table de liaison)
- [x] Créer `PaiementAdhesion.java` (table de liaison)
- [x] Créer `PaiementEvenement.java` (table de liaison)
- [x] Créer `PaiementAide.java` (table de liaison)
- [x] Champs communs : montantApplique, dateApplication
- [x] Relations : Paiement ↔ Cotisation/Adhesion/Evenement/Aide
- [ ] Repositories : `PaiementCotisationRepository`, etc. (à créer si nécessaire)
- [ ] Services : Logique d'application des paiements (intégrée dans PaiementService)

#### É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 ✅ COMPLÉTÉE
- [x] Créer `CompteWave.java`
  - Numéro téléphone (+225XXXXXXXX)
  - Statut : NON_VERIFIE, VERIFIE, SUSPENDU, BLOQUE (enum dans module API)
  - Relations : Organisation (1-N), Membre (0..1)
  - Identifiants API encryptés
- [x] Créer `TransactionWave.java`
  - Identifiants Wave (transactionId, requestId, reference)
  - Type : DEPOT, RETRAIT, TRANSFERT, PAIEMENT, REMBOURSEMENT (enum dans module API)
  - Statut : INITIALISE, EN_ATTENTE, EN_COURS, REUSSIE, ECHOUE, ANNULEE, EXPIRED (enum dans module API)
  - Montant, frais, montant net
  - Métadonnées JSON
  - Relation : CompteWave (1-N), Paiement (0..1)
- [x] Créer `WebhookWave.java`
  - Wave event ID
  - Type d'événement (enum dans module API)
  - Statut traitement : EN_ATTENTE, EN_TRAITEMENT, TRAITE, ECHOUE, IGNORE (enum dans module API)
  - Payload JSON
  - Relation : TransactionWave (0..1), Paiement (0..1)
- [x] Créer `ConfigurationWave.java`
  - Clé-valeur pour configuration
  - Support sandbox/production

#### Étape 3.2 : Repositories et Services Wave ✅ COMPLÉTÉE
- [x] Repositories : `CompteWaveRepository`, `TransactionWaveRepository`, `WebhookWaveRepository`, `ConfigurationWaveRepository`
- [x] Service : `WaveService` (structure de base créée)
  - [x] Méthodes : CRUD comptes, CRUD transactions, vérification
  - [ ] Méthodes : initierPaiement, verifierTransaction, traiterWebhook (à implémenter avec API réelle)
  - [ ] Gestion retry avec backoff exponentiel (à implémenter)
  - [ ] Validation de signature webhook (à implémenter)
  - [ ] Chiffrement des clés API (à implémenter)
- [x] DTOs : `CompteWaveDTO`, `TransactionWaveDTO`
- [x] Resource REST : `WaveResource`

#### É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