unionflow-server-api/unionflow.md

# Description Métier - UnionFlow

**Version** : 3.0 (Optimisée avec intégration Wave Mobile Money)  
**Date** : 2025-01-29  
**Domaine** : Gestion d'organisations associatives (Lions Clubs, Associations, Coopératives, etc.)

---

## 🎯 Vision et Mission

**UnionFlow** est une plateforme de gestion intégrée conçue pour les organisations (unions, associations, mutuelles et assimilées) de Côte d'Ivoire. Elle centralise et automatise la gestion administrative, financière et opérationnelle de ces organisations.

### Mission
Faciliter la gestion quotidienne des organisations associatives en automatisant les processus administratifs, financiers et événementiels, tout en favorisant la solidarité entre membres.

### Vision
Devenir la référence en matière de gestion numérique pour les organisations associatives en Afrique.

---

## 🏢 Contexte Métier

### Organisations Cibles
UnionFlow s'adresse à différents types d'organisations :
- **Associations** : Organisations à but non lucratif
- **Coopératives** : Groupements économiques
- **Fédérations** : Regroupements d'organisations
- **Mutuelles** : Organisations de solidarité
- **Syndicats** : Organisations professionnelles
- **Fondations** : Organisations philanthropiques
- **ONG** : Organisations non gouvernementales

### Problématiques Résolues
1. **Gestion dispersée** : Informations éparpillées dans des fichiers Excel, carnets, etc.
2. **Suivi financier complexe** : Difficulté à suivre les cotisations, paiements, relances
3. **Communication inefficace** : Manque de centralisation pour les événements et annonces
4. **Solidarité non structurée** : Absence de processus formalisé pour les demandes d'aide
5. **Traçabilité limitée** : Pas d'historique complet des actions et décisions
6. **Paiements manuels** : Absence d'intégration avec les solutions de mobile money

---

## 👥 Acteurs et Rôles

### 1. **SUPER_ADMIN**
- **Rôle** : Administration système complète
- **Permissions** :
  - Gestion de tous les utilisateurs et organisations
  - Configuration du système
  - Gestion du catalogue des types d'organisations
  - Configuration Wave Mobile Money
  - Accès à toutes les données et statistiques
  - Gestion des rôles et permissions
- **Cas d'usage** : Configuration initiale, maintenance, support technique

### 2. **ADMIN** (Administrateur d'Organisation)
- **Rôle** : Gestion complète d'une organisation
- **Permissions** :
  - Gestion des membres de son organisation
  - Gestion des cotisations
  - Organisation d'événements
  - Validation des adhésions
  - Traitement des demandes d'aide
  - Consultation des statistiques de son organisation
  - Gestion du compte Wave de l'organisation
  - Validation des paiements
- **Cas d'usage** : Gestion quotidienne d'un Lions Club ou d'une association

### 3. **MEMBRE**
- **Rôle** : Membre actif d'une organisation
- **Permissions** :
  - Consultation de son profil
  - Consultation de ses cotisations
  - Inscription aux événements
  - Soumission de demandes d'aide
  - Consultation des événements publics
  - Paiement via Wave Mobile Money
  - Gestion de son compte Wave personnel
- **Cas d'usage** : Participation active à la vie de l'organisation

### 4. **ORGANISATEUR_EVENEMENT**
- **Rôle** : Organisation et gestion d'événements
- **Permissions** :
  - Création et modification d'événements
  - Gestion des inscriptions
  - Suivi des participants
- **Cas d'usage** : Organisation d'assemblées générales, formations, manifestations

### 5. **TRESORIER**
- **Rôle** : Gestion financière et comptable
- **Permissions** :
  - Gestion des paiements
  - Validation des transactions
  - Gestion comptable
  - Rapprochement bancaire
  - Consultation des écritures comptables
- **Cas d'usage** : Suivi financier et comptabilité

---

## 📋 Modules Fonctionnels

### 1. 🏛️ Gestion des Organisations

#### Description
Module central permettant de gérer toutes les informations relatives aux organisations (clubs, associations, etc.).

#### Fonctionnalités Principales

**Création et Configuration**
- Enregistrement d'une nouvelle organisation avec toutes ses informations :
  - Identité : nom, nom court, type, statut
  - Contact : email, téléphones, adresse complète, coordonnées GPS
  - Web : site web, logo, réseaux sociaux
  - Finances : budget annuel, devise, cotisation obligatoire, montant
  - Métier : objectifs, activités principales, certifications, partenaires
  - Paramètres : organisation publique, accepte nouveaux membres

**Hiérarchie Organisationnelle**
- Structure hiérarchique (organisation parente)
- Niveaux hiérarchiques (0 = racine)
- Gestion des relations parent-enfant

**Statuts Organisationnels**
- **ACTIVE** : Organisation opérationnelle
- **SUSPENDUE** : Temporairement suspendue (ne peut plus accepter de membres)
- **DISSOUTE** : Organisation dissoute (archivée)
- **EN_CREATION** : Organisation en cours de création

**Gestion du Catalogue des Types**
- CRUD complet des types d'organisations
- Codes uniques (LIONS_CLUB, ASSOCIATION, etc.)
- Libellés et descriptions
- Ordre d'affichage
- Icônes pour l'interface
- Activation/désactivation

**Gestion des Adresses**
- Entité dédiée pour les adresses
- Support de plusieurs adresses par organisation/membre
- Types d'adresses : siège social, bureau, domicile, autre
- Coordonnées GPS pour géolocalisation

**Statistiques**
- Nombre de membres
- Nombre d'administrateurs
- Ancienneté (années depuis la fondation)
- Budget et finances
- Transactions Wave

#### Règles Métier
- Unicité de l'email par organisation
- Unicité du numéro d'enregistrement
- Unicité du nom
- Date de fondation optionnelle mais utilisée pour calculer l'ancienneté
- Statut par défaut : ACTIVE
- Devise par défaut : XOF (Franc CFA)
- Une organisation peut avoir un compte Wave

---

### 2. 👤 Gestion des Membres et Rôles

#### Description
Gestion complète du cycle de vie des membres d'une organisation avec système de rôles et permissions granulaires.

#### Fonctionnalités Principales

**Inscription de Membres**
- Création d'un nouveau membre avec :
  - Identité : prénom, nom, email (unique), téléphone
  - Téléphone Wave : format +225XXXXXXXX
  - Dates : naissance, adhésion
  - Affiliation : organisation
  - Photo de profil
  - Adresses multiples

**Génération Automatique**
- **Numéro de membre** : Format `UF{ANNEE}-{UUID}` (ex: `UF2025-A1B2C3D4`)
  - Généré automatiquement si non fourni
  - Unique dans tout le système
- **Date d'adhésion** : Automatiquement définie à `LocalDate.now()` si non fournie
- **Date de naissance** : Par défaut à 18 ans en arrière si non fournie

**Statuts Membres**
- **ACTIF** : Membre actif et opérationnel
- **INACTIF** : Membre désactivé
- **SUSPENDU** : Membre temporairement suspendu
- **DEMISSIONNAIRE** : Membre ayant démissionné
- **EXCLU** : Membre exclu de l'organisation

**Gestion des Rôles et Permissions**
- **Rôles** : Système de rôles hiérarchiques
  - Rôles système (SUPER_ADMIN, ADMIN, MEMBRE, etc.)
  - Rôles personnalisés par organisation
  - Niveau hiérarchique pour ordre de priorité
- **Permissions** : Permissions granulaires
  - Structure : Module > Ressource > Action
  - Exemple : `ORGANISATION > MEMBRE > CREATE`
- **Attribution** : 
  - Un membre peut avoir plusieurs rôles
  - Attribution avec dates de début/fin
  - Traçabilité complète

**Recherche et Filtrage**
- Recherche par nom, prénom, email, téléphone
- Filtrage par statut, organisation, date d'adhésion, rôles
- Recherche avancée avec critères multiples :
  - Âge (min/max)
  - Période d'adhésion
  - Organisation(s)
  - Rôles
  - Compte Wave actif

**Statistiques**
- Total de membres
- Membres actifs vs inactifs
- Nouveaux membres (30 derniers jours)
- Taux d'activité
- Répartition par rôles

#### Règles Métier
- Email unique dans tout le système
- Numéro de membre unique
- Un membre appartient à une seule organisation
- Vérification de majorité (18 ans) pour certaines opérations
- Calcul automatique de l'âge à partir de la date de naissance
- Téléphone Wave au format +225XXXXXXXX
- Un membre peut avoir un compte Wave personnel

---

### 3. 💰 Gestion des Paiements (Architecture Centralisée)

#### Description
Système centralisé de gestion des paiements avec intégration stricte Wave Mobile Money et support multi-méthodes.

#### Fonctionnalités Principales

**Architecture Centralisée**
- **Entité Paiement** : Entité unique pour tous les types de paiements
  - Réutilisable pour cotisations, adhésions, événements, aides
  - Traçabilité complète
  - Support multi-méthodes
- **Tables de liaison** :
  - `PaiementCotisation` : Application d'un paiement à une cotisation
  - `PaiementAdhesion` : Application d'un paiement à une adhésion
  - `PaiementEvenement` : Application d'un paiement à un événement
  - `PaiementAide` : Application d'un paiement à une aide

**Méthodes de Paiement**
- **WAVE_MOBILE_MONEY** : Intégration stricte Wave (prioritaire)
- **ORANGE_MONEY** : Orange Money
- **MTN_MOBILE_MONEY** : MTN Mobile Money
- **MOOV_MONEY** : Moov Money
- **VIREMENT_BANCAIRE** : Virement bancaire
- **CARTE_BANCAIRE** : Carte bancaire
- **ESPECES** : Paiement en espèces
- **CHEQUE** : Chèque
- **AUTRE** : Autre méthode

**Statuts de Paiement**
- **EN_ATTENTE** : Paiement initié, en attente
- **EN_COURS** : Paiement en cours de traitement
- **VALIDE** : Paiement validé et confirmé
- **ECHOUE** : Paiement échoué
- **ANNULE** : Paiement annulé
- **REMBOURSE** : Paiement remboursé

**Gestion des Paiements**
- Numéro de référence unique
- Montant et devise
- Date de paiement
- Date de validation
- Validateur (optionnel)
- Références externes (numéro transaction, URL preuve)
- Commentaires et notes
- Traçabilité IP et User-Agent

**Paiements Multiples**
- Un paiement peut couvrir plusieurs cotisations
- Un paiement peut être partiel
- Application automatique selon ordre de priorité
- Calcul automatique des montants restants

#### Règles Métier
- Montant doit être positif
- Devise par défaut : XOF
- Validation optionnelle par administrateur
- Traçabilité complète (IP, User-Agent, dates)
- Support des paiements partiels
- Un paiement peut être lié à une transaction Wave

---

### 4. 📱 Intégration Wave Mobile Money (Stricte)

#### Description
Intégration complète et stricte de Wave Mobile Money pour tous les paiements de la plateforme.

#### Fonctionnalités Principales

**Gestion des Comptes Wave**
- **CompteWave** : Entité dédiée pour les comptes Wave
  - Comptes organisation (pour recevoir les paiements)
  - Comptes membres (pour payer)
  - Numéro de téléphone au format +225XXXXXXXX
  - Statut de vérification
  - Identifiants Wave API (encryptés)
  - Support sandbox et production
- **Vérification** :
  - Vérification automatique ou manuelle
  - Synchronisation avec Wave API
  - Statuts : NON_VERIFIE, VERIFIE, SUSPENDU, BLOQUE

**Transactions Wave**
- **TransactionWave** : Suivi complet des transactions
  - Identifiants Wave uniques (transactionId, requestId, reference)
  - Type de transaction : DÉPOT, RETRAIT, TRANSFERT, PAIEMENT, REMBOURSEMENT
  - Statuts : INITIALISE, EN_ATTENTE, EN_COURS, REUSSIE, ECHOUE, ANNULEE, EXPIRED
  - Montant, frais, montant net
  - Informations payeur et bénéficiaire
  - Métadonnées JSON
  - Réponse complète de Wave API
- **Synchronisation** :
  - Synchronisation bidirectionnelle avec Wave API
  - Retry automatique en cas d'échec
  - Suivi du nombre de tentatives
  - Gestion des erreurs

**Webhooks Wave**
- **WebhookWave** : Traitement des événements Wave
  - Réception des événements en temps réel
  - Types : TRANSACTION_CREATED, TRANSACTION_COMPLETED, TRANSACTION_FAILED, etc.
  - Validation de signature
  - Traitement asynchrone en queue
  - Retry automatique
  - Idempotence garantie
  - Statuts : EN_ATTENTE, EN_TRAITEMENT, TRAITE, ECHOUE, IGNORE

**Configuration Wave**
- **ConfigurationWave** : Paramètres d'intégration
  - URL API Wave
  - Timeout des requêtes
  - Frais de transaction (pourcentage, fixe)
  - Configuration webhook (retry, délai)
  - Support sandbox et production
  - Clés API encryptées

**Processus de Paiement via Wave**

1. **Initiation du Paiement**
   - Membre sélectionne Wave comme méthode
   - Vérification du compte Wave du membre
   - Création de TransactionWave (statut INITIALISE)

2. **Appel Wave API**
   - Génération de la requête Wave
   - Envoi à l'API Wave
   - Enregistrement de la réponse

3. **Traitement Webhook**
   - Réception du webhook Wave
   - Validation de la signature
   - Mise à jour de TransactionWave
   - Mise à jour du Paiement associé
   - Notification au membre

4. **Finalisation**
   - Validation automatique ou manuelle
   - Application aux cotisations/adhésions
   - Génération des écritures comptables
   - Notification de confirmation

**Sécurité**
- Chiffrement des clés API
- Validation de signature des webhooks
- Audit complet des transactions
- Traçabilité IP et User-Agent
- Gestion des erreurs et retry sécurisé

#### Règles Métier
- Format téléphone Wave strict : +225XXXXXXXX
- Vérification obligatoire avant utilisation
- Synchronisation automatique des statuts
- Retry automatique avec backoff exponentiel
- Idempotence des webhooks
- Validation de signature obligatoire
- Chiffrement des données sensibles

---

### 5. 💼 Gestion Comptable

#### Description
Système de comptabilité en partie double avec intégration automatique des paiements.

#### Fonctionnalités Principales

**Plan Comptable**
- **CompteComptable** : Comptes du plan comptable
  - Numéro de compte unique
  - Libellé et description
  - Type : ACTIF, PASSIF, CHARGES, PRODUITS, TRESORERIE, AUTRE
  - Classe comptable (1-7)
  - Solde initial et solde actuel
  - Devise

**Journaux Comptables**
- **JournalComptable** : Journaux comptables
  - Code unique
  - Type : ACHATS, VENTES, BANQUE, CAISSE, OD
  - Période (date début/fin)
  - Statut : OUVERT, FERME, CLOTURE

**Écritures Comptables**
- **EcritureComptable** : Écritures en partie double
  - Numéro de pièce unique
  - Date d'écriture
  - Libellé et référence
  - Lettrage et pointage
  - Commentaires
- **LigneEcriture** : Lignes d'écriture
  - Numéro de ligne
  - Compte débiteur/créditeur
  - Montant débit/crédit
  - Équilibre automatique (Débit = Crédit)

**Intégration Automatique**
- Génération automatique d'écritures pour :
  - Paiements de cotisations
  - Paiements d'adhésions
  - Paiements d'événements
  - Versements d'aides
  - Transactions Wave (frais inclus)

**Rapprochement Bancaire**
- Pointage des paiements
- Lettrage automatique
- Rapprochement avec comptes bancaires
- Écarts de rapprochement

#### Règles Métier
- Équilibre obligatoire : Total Débit = Total Crédit
- Numéro de pièce unique
- Date d'écriture obligatoire
- Pointage et lettrage optionnels
- Intégration automatique avec paiements

---

### 6. 💰 Gestion des Cotisations

#### Description
Suivi complet des cotisations des membres : création, paiement via Wave, relances, statistiques.

#### Fonctionnalités Principales

**Types de Cotisations**
- **MENSUELLE** : Cotisation mensuelle récurrente
- **ANNUELLE** : Cotisation annuelle
- **ADHESION** : Frais d'adhésion initiale
- **EVENEMENT** : Participation à un événement payant
- **FORMATION** : Frais de formation
- **PROJET** : Contribution à un projet
- **SOLIDARITE** : Contribution au fonds de solidarité
- **EXTRAORDINAIRE** : Cotisation extraordinaire

**Création de Cotisation**
- Association à un membre
- Montant dû (obligatoire, positif)
- Code devise (ISO 3 lettres, défaut : XOF)
- Date d'échéance
- Période (année, mois optionnel)
- Description et observations
- Type de cotisation
- Récurrente (oui/non)

**Génération Automatique**
- **Numéro de référence** : Format `COT-{ANNEE}-{TIMESTAMP}` (ex: `COT-2025-12345678`)
  - Généré automatiquement si non fourni
  - Unique dans tout le système

**Statuts de Cotisation**
- **EN_ATTENTE** : Créée mais non payée
- **PAYEE** : Intégralement payée
- **EN_RETARD** : Date d'échéance dépassée, non payée
- **PARTIELLEMENT_PAYEE** : Paiement partiel effectué
- **ANNULEE** : Cotisation annulée
- **REMBOURSEE** : Cotisation remboursée

**Gestion des Paiements**
- **Paiements multiples** : Un paiement peut couvrir plusieurs cotisations
- **Paiements partiels** : Support des paiements partiels
- **Via Wave** : Paiement direct via Wave Mobile Money
- **Application automatique** : Calcul automatique du montant payé
- **Validation** : Validation optionnelle par administrateur

**Relances Automatiques**
- Suivi du nombre de rappels
- Date du dernier rappel
- Détection automatique des cotisations en retard
- Notifications automatiques (email, SMS)

**Recherche et Filtrage**
- Par membre
- Par statut
- Par type
- Par période (année, mois)
- Cotisations en retard
- Cotisations non payées

**Statistiques**
- Total de cotisations
- Cotisations payées
- Cotisations en retard
- Taux de paiement
- Montants collectés par période
- Répartition par méthode de paiement

#### Règles Métier
- Montant dû doit être positif
- Calcul automatique du montant restant : `montantDu - montantPaye`
- Détection automatique des cotisations en retard : `dateEcheance < aujourd'hui && !payeeIntegralement()`
- Une cotisation marquée "PAYEE" doit avoir tous les paiements validés
- Impossible de supprimer une cotisation déjà payée
- Paiement via Wave prioritaire si compte Wave disponible

---

### 7. 📅 Gestion des Événements

#### Description
Organisation complète d'événements : création, inscriptions, paiements via Wave, suivi, statistiques.

#### Fonctionnalités Principales

**Types d'Événements**
- **ASSEMBLEE_GENERALE** : Assemblée générale annuelle
- **REUNION** : Réunion régulière
- **FORMATION** : Session de formation
- **CONFERENCE** : Conférence ou séminaire
- **ATELIER** : Atelier pratique
- **SEMINAIRE** : Séminaire
- **EVENEMENT_SOCIAL** : Événement social (soirée, gala, etc.)
- **MANIFESTATION** : Manifestation publique
- **CELEBRATION** : Célébration (anniversaire, fête, etc.)
- **AUTRE** : Autre type d'événement

**Création d'Événement**
- Titre (obligatoire)
- Description détaillée
- Dates : début (obligatoire), fin (optionnelle)
- Lieu et adresse complète (entité Adresse)
- Type d'événement
- Capacité maximale (optionnelle, pour gérer les inscriptions)
- Prix de participation (optionnel)
- Instructions particulières
- Contact organisateur
- Matériel requis
- Visibilité publique

**Gestion des Inscriptions**
- Inscription requise (oui/non)
- Date limite d'inscription
- Capacité maximale
- Suivi des inscriptions :
  - **CONFIRMEE** : Inscription validée
  - **EN_ATTENTE** : En attente de validation
  - **ANNULEE** : Inscription annulée
  - **REFUSEE** : Inscription refusée

**Paiements d'Événements**
- Paiement via Wave Mobile Money
- Paiement en espèces
- Paiement par virement
- Application automatique aux inscriptions
- Génération de reçus

**Statuts d'Événement**
- **PLANIFIE** : Événement planifié (défaut)
- **CONFIRME** : Événement confirmé
- **EN_COURS** : Événement en cours
- **TERMINE** : Événement terminé
- **ANNULE** : Événement annulé
- **REPORTE** : Événement reporté

**Règles d'Ouverture aux Inscriptions**
Un événement est ouvert aux inscriptions si :
- `inscriptionRequise = true`
- `actif = true`
- Date limite d'inscription non dépassée
- Date de début non dépassée
- Capacité non atteinte (si définie)
- Statut = PLANIFIE ou CONFIRME

**Statistiques**
- Nombre total d'événements
- Événements actifs
- Événements à venir
- Événements en cours
- Événements passés
- Événements publics
- Taux de remplissage (inscrits / capacité)
- Taux d'activité
- Recettes par événement

#### Règles Métier
- Titre obligatoire
- Date de début obligatoire et ne peut pas être dans le passé (sauf tolérance de 1 heure)
- Date de fin ne peut pas être antérieure à la date de début
- Capacité maximale doit être positive si définie
- Prix ne peut pas être négatif
- Impossible de supprimer un événement avec des inscriptions
- Impossible de changer le statut d'un événement terminé ou annulé
- Calcul automatique de la durée en heures
- Calcul automatique des places restantes
- Vérification si un membre est déjà inscrit

---

### 8. 🤝 Gestion des Adhésions

#### Description
Processus complet de demande, validation et paiement d'adhésion à une organisation avec support Wave Mobile Money.

#### Fonctionnalités Principales

**Création de Demande d'Adhésion**
- Membre demandeur
- Organisation cible
- Date de demande (automatique si non fournie)
- Frais d'adhésion (montant)
- Code devise (défaut : XOF)

**Génération Automatique**
- **Numéro de référence** : Format `ADH-{TIMESTAMP}-{UUID}` (ex: `ADH-1706541234567-A1B2C3D4`)
  - Généré automatiquement si non fourni
  - Unique dans tout le système

**Workflow d'Adhésion**

1. **EN_ATTENTE** (Statut initial)
   - Demande soumise
   - En attente de validation par l'organisation

2. **APPROUVEE**
   - Demande approuvée par un administrateur
   - Date d'approbation enregistrée
   - Approuveur enregistré
   - Passage automatique en attente de paiement

3. **EN_PAIEMENT**
   - Paiement partiel effectué
   - Montant payé < frais d'adhésion

4. **PAYEE**
   - Paiement intégral effectué
   - Montant payé >= frais d'adhésion
   - Date de paiement enregistrée
   - Membre officiellement admis

5. **REJETEE**
   - Demande rejetée par l'organisation
   - Motif de rejet enregistré

6. **ANNULEE**
   - Demande annulée (par le demandeur ou l'organisation)

**Gestion des Paiements**
- **Paiement via Wave** : Paiement direct via Wave Mobile Money
- **Paiements multiples** : Support des paiements partiels
- **Application automatique** : Calcul automatique du montant restant
- **Validation** : Validation optionnelle par administrateur

**Actions Métier**
- **Approuver** : Valide une demande en attente
- **Rejeter** : Refuse une demande avec motif
- **Enregistrer paiement** : Enregistre un paiement (partiel ou complet)
- **Annuler** : Annule une demande (si non payée)

**Recherche et Filtrage**
- Par membre
- Par organisation
- Par statut
- Adhésions en attente
- Adhésions approuvées non payées

**Statistiques**
- Total d'adhésions
- Adhésions approuvées
- Adhésions en attente
- Adhésions payées
- Taux d'approbation
- Taux de paiement
- Délai moyen de traitement

#### Règles Métier
- Frais d'adhésion doivent être positifs
- Calcul automatique du montant restant : `fraisAdhesion - montantPaye`
- Seules les adhésions EN_ATTENTE peuvent être approuvées ou rejetées
- Seules les adhésions APPROUVEE ou EN_PAIEMENT peuvent recevoir un paiement
- Impossible de supprimer une adhésion déjà payée
- Passage automatique en PAYEE si paiement intégral
- Passage automatique en EN_PAIEMENT si paiement partiel
- Paiement via Wave prioritaire si compte Wave disponible

---

### 9. ❤️ Système de Solidarité (Demandes d'Aide)

#### Description
Gestion complète du cycle de vie des demandes d'aide entre membres : soumission, évaluation, approbation, versement via Wave.

#### Fonctionnalités Principales

**Types d'Aide**
- **FINANCIERE** : Aide financière directe (versement via Wave)
- **MATERIELLE** : Fourniture de matériel
- **ALIMENTAIRE** : Aide alimentaire
- **MEDICALE** : Aide médicale
- **SCOLAIRE** : Aide scolaire (frais, fournitures)
- **LOGEMENT** : Aide au logement
- **EMPLOI** : Aide à l'emploi
- **FORMATION** : Aide à la formation
- **AUTRE** : Autre type d'aide

**Création de Demande**
- Titre et description détaillée
- Type d'aide
- Montant demandé (pour aide financière)
- Justification
- Documents fournis (via entité Document)
- Urgence (oui/non)
- Membre demandeur
- Organisation traitante

**Génération Automatique**
- **Numéro de référence** : Format `DA-{ANNEE}-{NUMERO}` (ex: `DA-2025-123456`)
  - Généré automatiquement
  - Unique dans tout le système

**Workflow de Demande d'Aide**

1. **BROUILLON** (Statut initial)
   - Demande en cours de rédaction
   - Modifiable par le demandeur

2. **SOUMISE**
   - Demande soumise à l'organisation
   - Date de soumission enregistrée

3. **EN_ATTENTE**
   - En attente d'évaluation

4. **EN_COURS_EVALUATION**
   - Évaluation en cours par un évaluateur
   - Évaluateur assigné

5. **INFORMATIONS_REQUISES**
   - Informations complémentaires demandées
   - Retour au demandeur

6. **APPROUVEE**
   - Demande approuvée intégralement
   - Montant approuvé = montant demandé
   - Date d'approbation enregistrée

7. **APPROUVEE_PARTIELLEMENT**
   - Demande approuvée partiellement
   - Montant approuvé < montant demandé

8. **EN_COURS_TRAITEMENT**
   - Traitement en cours (préparation de l'aide)

9. **EN_COURS_VERSEMENT**
   - Versement en cours (pour aide financière)
   - Initiation du paiement via Wave

10. **VERSEE**
    - Aide versée (pour aide financière)
    - Date de versement enregistrée
    - Transaction Wave confirmée

11. **LIVREE**
    - Aide livrée (pour aide matérielle)

12. **TERMINEE**
    - Processus complètement terminé

13. **REJETEE**
    - Demande rejetée
    - Commentaire d'évaluation avec motif

14. **ANNULEE**
    - Demande annulée

15. **EXPIREE**
    - Demande expirée (délai dépassé)

16. **SUSPENDUE**
    - Demande temporairement suspendue

17. **EN_SUIVI**
    - Demande en suivi post-versement

18. **CLOTUREE**
    - Demande clôturée définitivement

**Versement d'Aide Financière**
- **Via Wave Mobile Money** : Versement direct sur le compte Wave du demandeur
- **Via Virement Bancaire** : Virement bancaire
- **En Espèces** : Versement en espèces
- Traçabilité complète du versement
- Génération automatique d'écriture comptable

**Recherche et Filtrage**
- Par organisation
- Par type d'aide
- Par statut
- Par priorité
- Par demandeur
- Demandes urgentes
- Demandes en retard (délai dépassé)

**Statistiques**
- Total de demandes
- Demandes par statut
- Demandes par type
- Montants demandés vs approuvés
- Taux d'approbation
- Délais moyens de traitement
- Montants versés via Wave

#### Règles Métier
- Une demande ne peut être modifiée qu'en statut BROUILLON
- Transitions de statut validées (workflow strict)
- Calcul automatique du pourcentage d'approbation
- Détection automatique des demandes en retard
- Vérification de l'urgence pour priorisation
- Historique complet et immuable des changements
- Versement via Wave prioritaire si compte Wave disponible

---

### 10. 📄 Gestion Documentaire

#### Description
Système complet de gestion des documents avec stockage sécurisé et vérification d'intégrité.

#### Fonctionnalités Principales

**Stockage des Documents**
- **Document** : Entité centrale pour tous les documents
  - Nom de fichier et nom original
  - Chemin de stockage sécurisé
  - Type MIME
  - Taille
  - Hash MD5 et SHA256 pour vérification d'intégrité
  - Type de document
  - Description

**Types de Documents**
- **IDENTITE** : Pièce d'identité
- **JUSTIFICATIF_DOMICILE** : Justificatif de domicile
- **PHOTO** : Photo de profil
- **CONTRAT** : Contrat
- **FACTURE** : Facture
- **RECU** : Reçu de paiement
- **RAPPORT** : Rapport
- **AUTRE** : Autre type

**Pièces Jointes**
- **PieceJointe** : Association flexible des documents
  - Association à n'importe quelle entité (Membre, Organisation, Cotisation, Adhésion, DemandeAide, TransactionWave)
  - Ordre d'affichage
  - Libellé et commentaire
  - Traçabilité complète

**Sécurité**
- Stockage sécurisé (chiffrement optionnel)
- Vérification d'intégrité (hash)
- Contrôle d'accès par rôle
- Audit des téléchargements

#### Règles Métier
- Hash MD5 et SHA256 obligatoires
- Vérification d'intégrité à chaque accès
- Association flexible via PieceJointe
- Taille maximale configurable

---

### 11. 🔔 Système de Notifications

#### Description
Système multi-canaux de notifications avec templates réutilisables.

#### Fonctionnalités Principales

**Types de Notifications**
- **EMAIL** : Notification par email
- **SMS** : Notification par SMS
- **PUSH** : Notification push (mobile)
- **IN_APP** : Notification dans l'application
- **SYSTEME** : Notification système

**Templates de Notifications**
- **TemplateNotification** : Templates réutilisables
  - Code unique
  - Sujet et corps (texte et HTML)
  - Variables disponibles (JSON)
  - Canaux supportés
  - Support multi-langues

**Gestion des Notifications**
- **Notification** : Notifications individuelles
  - Type et priorité
  - Statut : EN_ATTENTE, ENVOYEE, LUE, ECHOUE, ANNULEE
  - Titre et message
  - Date d'envoi et de lecture
  - Canaux d'envoi
  - Retry automatique
  - Métadonnées JSON

**Priorités**
- **CRITIQUE** : Intervention immédiate
- **HAUTE** : Intervention rapide
- **NORMALE** : Traitement normal
- **BASSE** : Traitement différé

**Notifications Automatiques**
- Nouvelle cotisation créée
- Cotisation en retard
- Paiement reçu (via Wave)
- Transaction Wave confirmée
- Adhésion approuvée
- Demande d'aide soumise
- Événement à venir

#### Règles Métier
- Retry automatique en cas d'échec
- Priorisation selon la priorité
- Templates réutilisables
- Support multi-langues

---

## 🔄 Processus Métier Principaux

### Processus 1 : Inscription d'un Nouveau Membre

1. **Saisie des informations**
   - Nom, prénom, email, téléphone
   - Téléphone Wave (optionnel)
   - Date de naissance
   - Organisation d'affiliation
   - Adresse(s)

2. **Validation automatique**
   - Vérification unicité email
   - Génération numéro de membre
   - Définition date d'adhésion
   - Vérification format téléphone Wave

3. **Création du membre**
   - Persistance en base
   - Attribution statut ACTIF par défaut
   - Attribution rôle MEMBRE par défaut

4. **Mise à jour organisation**
   - Incrémentation nombre de membres

5. **Notification**
   - Notification de bienvenue au membre
   - Notification à l'administrateur

### Processus 2 : Paiement de Cotisation via Wave

1. **Sélection de la cotisation**
   - Membre consulte ses cotisations
   - Sélection d'une cotisation à payer

2. **Initiation du paiement Wave**
   - Vérification du compte Wave du membre
   - Création de TransactionWave (statut INITIALISE)
   - Création de Paiement (statut EN_ATTENTE)
   - Appel Wave API

3. **Traitement Webhook**
   - Réception du webhook Wave
   - Validation de la signature
   - Mise à jour TransactionWave (statut REUSSIE)
   - Mise à jour Paiement (statut VALIDE)

4. **Application au paiement**
   - Création de PaiementCotisation
   - Mise à jour du montant payé de la cotisation
   - Mise à jour du statut (PAYEE si intégral)

5. **Génération comptable**
   - Création d'écriture comptable
   - Débit compte caisse Wave
   - Crédit compte produits (cotisations)

6. **Notifications**
   - Notification de confirmation au membre
   - Notification à l'administrateur
   - Génération de reçu

### Processus 3 : Organisation d'un Événement avec Paiement

1. **Création de l'événement**
   - Saisie des informations (titre, dates, lieu, etc.)
   - Définition capacité et prix
   - Configuration inscriptions
   - Association d'une adresse

2. **Ouverture des inscriptions**
   - Vérification automatique des conditions
   - Affichage public si visible

3. **Inscription et paiement**
   - Membre s'inscrit à l'événement
   - Si payant, initiation du paiement via Wave
   - Traitement du paiement
   - Confirmation de l'inscription

4. **Gestion des inscriptions**
   - Validation/refus des inscriptions
   - Suivi du nombre d'inscrits
   - Gestion des places

5. **Exécution de l'événement**
   - Changement de statut (CONFIRME → EN_COURS → TERMINE)
   - Suivi de la participation

### Processus 4 : Demande d'Adhésion avec Paiement Wave

1. **Soumission de la demande**
   - Membre soumet une demande d'adhésion
   - Statut initial : EN_ATTENTE

2. **Évaluation**
   - Administrateur examine la demande
   - Décision : APPROUVEE ou REJETEE

3. **Paiement via Wave**
   - Si approuvée, membre paie via Wave
   - Traitement du paiement
   - Application à l'adhésion

4. **Finalisation**
   - Passage en statut PAYEE
   - Membre officiellement admis
   - Mise à jour de l'organisation
   - Notification de confirmation

### Processus 5 : Demande d'Aide avec Versement Wave

1. **Création de la demande**
   - Membre crée une demande (statut BROUILLON)
   - Saisie des informations complètes
   - Upload de documents justificatifs

2. **Soumission**
   - Passage en statut SOUMISE
   - Assignation à l'organisation

3. **Évaluation**
   - Assignation d'un évaluateur
   - Statut : EN_COURS_EVALUATION
   - Analyse de la demande

4. **Décision**
   - APPROUVEE / APPROUVEE_PARTIELLEMENT / REJETEE
   - Enregistrement du montant approuvé (si financière)

5. **Versement via Wave**
   - Si aide financière approuvée
   - Initiation du versement via Wave
   - Vérification du compte Wave du demandeur
   - Traitement de la transaction
   - Confirmation du versement

6. **Suivi**
   - Statut VERSEE
   - Statut TERMINEE ou CLOTUREE
   - Historique complet conservé

---

## 📊 Indicateurs et Statistiques

### Indicateurs Organisationnels
- Nombre total de membres
- Nombre de membres actifs
- Taux d'activité (%)
- Nouveaux membres (30 jours)
- Budget annuel
- Montant cotisations collectées
- Répartition par rôles

### Indicateurs Financiers
- Total cotisations créées
- Cotisations payées
- Cotisations en retard
- Taux de paiement (%)
- Montants collectés par période
- Adhésions payées
- Répartition par méthode de paiement
- Transactions Wave (nombre, montant)
- Taux de succès Wave (%)

### Indicateurs Wave Mobile Money
- Nombre de comptes Wave actifs
- Nombre de transactions Wave
- Montant total des transactions
- Taux de succès des transactions
- Temps moyen de traitement
- Frais de transaction totaux
- Transactions échouées

### Indicateurs Événementiels
- Total événements
- Événements à venir
- Événements en cours
- Taux de remplissage moyen
- Participation moyenne
- Recettes par événement

### Indicateurs Solidarité
- Total demandes d'aide
- Demandes urgentes
- Demandes approuvées
- Montants demandés vs approuvés
- Taux d'approbation
- Délais moyens de traitement
- Montants versés via Wave

### Indicateurs Comptables
- Nombre d'écritures
- Solde des comptes
- Écritures non pointées
- Écritures non lettrées
- Écarts de rapprochement

---

## 🔐 Sécurité et Contrôle d'Accès

### Authentification
- **Keycloak OIDC** : Authentification centralisée
- Tokens JWT pour l'accès aux APIs
- Refresh automatique des tokens
- Support SSO

### Autorisations par Rôle
- **Système de rôles hiérarchiques** : Rôles système et personnalisés
- **Permissions granulaires** : Structure Module > Ressource > Action
- **SUPER_ADMIN** : Accès total
- **ADMIN** : Gestion de son organisation
- **MEMBRE** : Consultation et actions limitées
- **ORGANISATEUR_EVENEMENT** : Gestion événements
- **TRESORIER** : Gestion financière et comptable

### Audit et Traçabilité
- **AuditLog** : Enregistrement de toutes les actions importantes
- Champs d'audit sur toutes les entités :
  - `creePar` : Créateur
  - `modifiePar` : Dernier modificateur
  - `dateCreation` : Date de création
  - `dateModification` : Date de modification
  - `version` : Version optimiste (gestion des conflits)
- Types d'actions auditées :
  - CREATE, UPDATE, DELETE, READ
  - LOGIN, LOGOUT
  - EXPORT, IMPORT
  - VALIDATION, REJECTION
- Sévérités : CRITIQUE, ELEVEE, MOYENNE, BASSE, INFO

### Sécurité Wave
- Chiffrement des clés API
- Validation de signature des webhooks
- Audit complet des transactions
- Traçabilité IP et User-Agent
- Gestion des erreurs et retry sécurisé

---

## 🎨 Principes de Conception

### DRY (Don't Repeat Yourself)
- Composants réutilisables pour l'UI
- Services partagés
- DTOs standardisés
- Entité Paiement centralisée
- Entité Document centralisée

### WOU (Write Once Use)
- Bibliothèque de composants JSF/PrimeFaces
- Fragments réutilisables
- Templates standardisés
- Templates de notifications

### Séparation des Préoccupations
- **API** : Contrats et interfaces
- **Implémentation** : Logique métier et persistance
- **Client** : Interface utilisateur
- **Wave Service** : Service dédié Wave
- **Comptabilité Service** : Service dédié comptabilité

### Normalisation
- Normalisation 3NF
- Séparation des adresses
- Tables de liaison pour relations many-to-many
- Entités dédiées pour chaque concept

### Traçabilité Complète
- Historique des modifications
- Logs d'audit
- Versioning optimiste
- Audit des transactions Wave
- Vérification d'intégrité des documents

---

## 🚀 Évolutions Futures

### Court Terme (Implémenté)
- ✅ Intégration paiements mobiles (Wave Mobile Money)
- ✅ Notifications automatiques (email, SMS)
- ✅ Gestion documentaire (upload de documents)
- ✅ Système de rôles et permissions

### Moyen Terme
- Application mobile native (Flutter)
- Tableau de bord analytique avancé
- Export de rapports (PDF, Excel)
- Intégration Orange Money et MTN Mobile Money
- API REST complète
- Webhooks personnalisés

### Long Terme
- Intelligence artificielle pour recommandations
- Prédiction des cotisations en retard
- Optimisation automatique des événements
- Analyse prédictive des demandes d'aide
- Intégration avec systèmes bancaires
- Blockchain pour traçabilité

---

## 📞 Support et Maintenance

### Support Utilisateur
- Documentation complète
- Formation des administrateurs
- Support technique
- Guide d'utilisation Wave Mobile Money

### Maintenance
- Sauvegardes régulières
- Mises à jour de sécurité
- Monitoring des performances
- Monitoring des transactions Wave
- Alertes en cas d'échec de transaction

---

## 📝 Notes Techniques

### Architecture Technique
- **Backend** : Java EE / Jakarta EE
- **Base de données** : PostgreSQL
- **Authentification** : Keycloak OIDC
- **API Wave** : Intégration REST
- **Webhooks** : Traitement asynchrone avec queue
- **Chiffrement** : AES-256 pour données sensibles

### Performance
- Indexation optimale des clés étrangères
- Cache pour configurations fréquentes
- Traitement asynchrone des webhooks
- Pagination pour grandes listes

### Conformité
- Comptabilité en partie double
- Traçabilité complète
- Audit des transactions
- Conformité RGPD (anonymisation)

---

**Document généré le** : 2025-01-29  
**Version UnionFlow** : 3.0 (Optimisée avec intégration Wave Mobile Money)  
**Auteur** : UnionFlow Team