diff --git a/DESCRIPTION_METIER_UNIONFLOW.md b/DESCRIPTION_METIER_UNIONFLOW.md new file mode 100644 index 0000000..24f2198 --- /dev/null +++ b/DESCRIPTION_METIER_UNIONFLOW.md @@ -0,0 +1,800 @@ +# 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 +