unionflow-client-quarkus-primefaces-freya/DESCRIPTION_METIER_UNIONFLOW.md

# Description Métier - UnionFlow

**Version** : 2.0  
**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 unions et associations Lions Club de Côte d'Ivoire. Elle centralise et automatise la gestion administrative, financière et opérationnelle de ces organisations à but non lucratif.

### 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 de l'Ouest.

---

## 🏢 Contexte Métier

### Organisations Cibles
UnionFlow s'adresse à différents types d'organisations :
- **Lions Clubs** : Clubs de service international
- **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

---

## 👥 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
  - Accès à toutes les données et statistiques
- **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
- **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
- **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

---

## 📋 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)

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

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

#### 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
- Type par défaut : ASSOCIATION
- Devise par défaut : XOF (Franc CFA)

---

### 2. 👤 Gestion des Membres

#### Description
Gestion complète du cycle de vie des membres d'une organisation.

#### Fonctionnalités Principales

**Inscription de Membres**
- Création d'un nouveau membre avec :
  - Identité : prénom, nom, email (unique), téléphone
  - Dates : naissance, adhésion
  - Affiliation : organisation
  - Rôles : chaîne de caractères pour les rôles 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 (pour éviter les contraintes @NotNull)

**Statuts Membres**
- **ACTIF** : Membre actif et opérationnel
- **INACTIF** : Membre désactivé
- **SUSPENDU** : Membre temporairement suspendu

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

**Statistiques**
- Total de membres
- Membres actifs vs inactifs
- Nouveaux membres (30 derniers jours)
- Taux d'activité

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

---

### 3. 💰 Gestion des Cotisations

#### Description
Suivi complet des cotisations des membres : création, paiement, 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é

**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

**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

**Gestion des Paiements**
- Enregistrement de paiements partiels ou complets
- Méthode de paiement (espèces, virement, mobile money, etc.)
- Référence de paiement
- Date de paiement
- Validation par un administrateur (optionnel)

**Relances Automatiques**
- Suivi du nombre de rappels
- Date du dernier rappel
- Détection automatique des cotisations en retard

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

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

#### Règles Métier
- Montant dû doit être positif
- Montant payé ne peut pas dépasser le montant dû
- Date d'échéance ne peut pas être antérieure à un an
- Une cotisation marquée "PAYEE" doit avoir montantPaye = montantDu
- Impossible de supprimer une cotisation déjà payée
- Calcul automatique du montant restant : `montantDu - montantPaye`
- Détection automatique des cotisations en retard : `dateEcheance < aujourd'hui && !payeeIntegralement()`

---

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

#### Description
Organisation complète d'événements : création, inscriptions, 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
- 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

**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é

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

---

### 5. 🤝 Gestion des Adhésions

#### Description
Processus complet de demande, validation et paiement d'adhésion à une organisation.

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

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**
- Enregistrement de paiements partiels ou complets
- Méthode de paiement
- Référence de paiement
- Date de paiement
- Calcul automatique du montant restant

**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

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

#### Règles Métier
- Frais d'adhésion doivent être positifs
- Montant payé ne peut pas dépasser les frais d'adhésion
- 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

---

### 6. ❤️ 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.

#### Fonctionnalités Principales

**Types d'Aide**
- **FINANCIERE** : Aide financière directe
- **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 (liste)
- 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
- **Score de priorité** : Calculé automatiquement selon :
  - Priorité (CRITIQUE, URGENTE, NORMALE, FAIBLE)
  - Type d'aide (urgent ou non)
  - Montant (si financière)
  - Ancienneté de la demande

**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)

10. **VERSEE**
    - Aide versée (pour aide financière)
    - Date de versement enregistré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

**Historique des Statuts**
- Traçabilité complète des changements de statut
- Date de chaque changement
- Auteur du changement
- Motif du changement
- Indication si changement automatique ou manuel

**Priorités**
- **CRITIQUE** : Intervention immédiate requise
- **URGENTE** : Intervention rapide requise
- **NORMALE** : Traitement normal
- **FAIBLE** : Traitement différé possible

**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

#### 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 score de priorité
- Détection automatique des demandes en retard
- Calcul automatique du pourcentage d'approbation
- Vérification de l'urgence pour priorisation
- Historique complet et immuable des changements

---

## 🔄 Processus Métier Principaux

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

1. **Saisie des informations**
   - Nom, prénom, email, téléphone
   - Date de naissance
   - Organisation d'affiliation

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

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

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

### Processus 2 : Gestion d'une Cotisation

1. **Création de la cotisation**
   - Association au membre
   - Définition montant, type, échéance
   - Génération numéro de référence

2. **Suivi du paiement**
   - Statut initial : EN_ATTENTE
   - Enregistrement paiements (partiels ou complets)
   - Mise à jour automatique du statut

3. **Relances**
   - Détection automatique des cotisations en retard
   - Envoi de rappels (nombre de rappels suivi)

4. **Finalisation**
   - Statut PAYEE quand intégralement payée
   - Validation par un administrateur (optionnel)

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

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

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

3. **Gestion des inscriptions**
   - Inscription des membres
   - Validation/refus des inscriptions
   - Suivi du nombre d'inscrits

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

### Processus 4 : Demande d'Adhésion

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**
   - Si approuvée, enregistrement des paiements
   - Passage automatique en PAYEE si intégral

4. **Finalisation**
   - Membre officiellement admis
   - Mise à jour de l'organisation

### Processus 5 : Demande d'Aide (Solidarité)

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

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. **Traitement**
   - Préparation de l'aide
   - Versement (si financière) ou livraison (si matérielle)

6. **Suivi**
   - 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

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

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

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

---

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

### Autorisations par Rôle
- **SUPER_ADMIN** : Accès total
- **ADMIN** : Gestion de son organisation
- **MEMBRE** : Consultation et actions limitées
- **ORGANISATEUR_EVENEMENT** : Gestion événements

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

---

## 🎨 Principes de Conception

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

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

### Séparation des Responsabilités
- **API** : Contrats et interfaces
- **Implémentation** : Logique métier et persistance
- **Client** : Interface utilisateur

### Traçabilité Complète
- Historique des modifications
- Logs d'audit
- Versioning optimiste

---

## 🚀 Évolutions Futures

### Court Terme
- Intégration paiements mobiles (Wave, Orange Money, MTN Mobile Money)
- Notifications automatiques (email, SMS)
- Export de rapports (PDF, Excel)

### Moyen Terme
- Application mobile native (Flutter)
- Tableau de bord analytique
- Gestion documentaire (upload de documents)

### Long Terme
- Intelligence artificielle pour recommandations
- Prédiction des cotisations en retard
- Optimisation automatique des événements

---

## 📞 Support et Maintenance

### Support Utilisateur
- Documentation complète
- Formation des administrateurs
- Support technique

### Maintenance
- Sauvegardes régulières
- Mises à jour de sécurité
- Monitoring des performances

---

**Document généré le** : 2025-01-29  
**Version UnionFlow** : 2.0  
**Auteur** : UnionFlow Team