lionsdev/unionflow-server-impl-quarkus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0f625e5d78c3f482bcac118e6e899eeb09f92360
unionflow-server-impl-quarkus/DESCRIPTION_METIER_UNIONFLOW.md
dahoud e26ae459e4 docs: Ajout description métier complète UnionFlow 
Documentation exhaustive du point de vue métier:
- Vision et mission
- Contexte et organisations cibles
- Acteurs et rôles (SUPER_ADMIN, ADMIN, MEMBRE, ORGANISATEUR_EVENEMENT)
- 6 modules fonctionnels détaillés:
  * Gestion des Organisations
  * Gestion des Membres
  * Gestion des Cotisations
  * Gestion des Événements
  * Gestion des Adhésions
  * Système de Solidarité
- Processus métier principaux
- Indicateurs et statistiques
- Sécurité et contrôle d'accès
- Principes de conception (DRY, WOU)
- Évolutions futures

Document généré après analyse complète du code source.
2025-11-30 00:13:40 +00:00

23 KiB
Raw Blame History

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