# Spécification : Gestion des mutuelles orientée anti-blanchiment (LCB-FT) **Feature Branch** : `001-mutuelles-anti-blanchiment` **Créé** : 2026-02-28 **Statut** : Spécification **Type** : Extension métier (alignement LCB-FT / BCEAO/OHADA) ## Contexte UnionFlow gère des mutuelles d'épargne et de crédit. Les flux de fonds (dépôts, retraits, transferts, crédits) doivent être traçables et conformes aux exigences de **lutte contre le blanchiment des capitaux et le financement du terrorisme (LCB-FT)** et aux bonnes pratiques BCEAO/OHADA. Ce document décrit l’état actuel du backend (API + impl) pour les mutuelles, puis les extensions proposées pour une gestion orientée anti-blanchiment, **sans données fictives**. --- ## 1. État actuel (inventaire) ### 1.1 API – unionflow-server-api **Mutuelles épargne** - **dto.mutuelle.epargne** - `CompteEpargneRequest` : membreId, organisationId, typeCompte, notesOuverture - `CompteEpargneResponse` : id, membreId, organisationId, numeroCompte, typeCompte, soldeActuel, soldeBloque, statut, dateOuverture, dateDerniereTransaction, description - `TransactionEpargneRequest` : compteId, typeTransaction, montant, compteDestinationId, **motif** - `TransactionEpargneResponse` : compteId, type, montant, soldeAvant/Apres, motif, dateTransaction, operateurId, referenceExterne, statutExecution - **enums.mutuelle.epargne** : TypeTransactionEpargne (DEPOT, RETRAIT, TRANSFERT_ENTRANT/SORTANT, PAIEMENT_INTERETS, etc.), StatutCompteEpargne, TypeCompteEpargne **Mutuelles crédit** - **dto.mutuelle.credit** - `DemandeCreditRequest` : membreId, typeCredit, montantDemande, dureeMois, compteLieId, **justificationDetaillee**, documentIds, garantiesProposees - `DemandeCreditResponse` : numeroDossier, membreId, montantDemande/Approuve, echeancier, statut, notesComite, etc. - `GarantieDemandeDTO`, `EcheanceCreditDTO` - **enums.mutuelle.credit** : StatutDemandeCredit, TypeCredit, TypeGarantie, StatutEcheanceCredit **Paiements / intentions** - **dto.paiement** : CreatePaiementRequest (numeroReference, montant, codeDevise, methodePaiement, commentaire, membreId), Wave DTOs - **intentions_paiement** (V2.3) : utilisateur_id, organisation_id, montant_total, code_devise, type_objet, statut, objets_cibles, wave_* — pas de champ dédié « origine des fonds » ou « justification LCB-FT » **Membres (KYC)** - `CreateMembreRequest` : **typeIdentite**, **numeroIdentite** (déjà présents), nom, prénom, email, téléphone, dateNaissance, profession, nationalite, statutMatrimonial **Audit** - V2.9 : audit_logs avec organisation_id, portee (ORGANISATION | PLATEFORME), conservation 10 ans (BCEAO/OHADA/Fiscalité) ### 1.2 Base de données (migrations) - **paiements** : reference, montant, devise, methode_paiement, statut, membre_id, organisation_id — pas d’origine des fonds ni de seuil LCB-FT - **intentions_paiement** : type_objet (COTISATION, ADHESION, EVENEMENT, ABONNEMENT_UNIONFLOW) — pas d’EPARGNE ni CREDIT ni champs LCB-FT - **membres** : pas de niveau de vigilance (KYC simplifié / renforcé) ni de date de vérification d’identité - **audit_logs** : portee, organisation_id — adapté pour traçabilité ### 1.3 Mobile (unionflow-mobile-apps) - Pas de feature dédiée « mutuelles » (épargne/crédit) dans les écrans listés ; contributions, adhesions, solidarité, dashboard existent. - Les écrans mutuelles (s’ils sont ajoutés) devront afficher uniquement des données réelles (API), avec champs obligatoires pour origine des fonds / justification lorsque le backend les exigera. --- ## 2. Objectifs orientés anti-blanchiment 1. **Traçabilité** : chaque opération significative (dépôt, retrait, transfert, déblocage crédit) liée à un membre identifié, avec origine des fonds ou motif explicite. 2. **Seuils** : au-dessus d’un montant configurable (ex. 500 000 XOF / 1 000 000 XOF), renforcement des contrôles (justification obligatoire, validation, éventuelle déclaration). 3. **Vigilance** : niveau KYC membre (simplifié / renforcé), date de vérification d’identité, lien avec éligibilité aux opérations. 4. **Alertes** : transactions inhabituelles (montant, fréquence, motif) et dépassement de seuil en vue d’un contrôle manuel ou déclaration. 5. **Conservation** : conservation des justificatifs et journaux conforme aux exigences (déjà 10 ans pour audit_logs ; à étendre aux pièces et champs LCB-FT). --- ## 3. Propositions d’extension (sans données fictives) ### 3.1 API – Nouveaux champs et contrats **TransactionEpargneRequest (extension)** - `origineFonds` (String, optionnel) : libellé court de l’origine des fonds (ex. « Salaire », « Vente », « Héritage ») — obligatoire au-dessus du seuil configuré. - `pieceJustificativeId` (UUID, optionnel) : référence vers une pièce jointe (document) pour les opérations au-dessus du seuil. **TransactionEpargneResponse (extension)** - Conserver les champs existants ; ajouter éventuellement `origineFonds`, `pieceJustificativeId` en lecture pour traçabilité. **DemandeCreditRequest (déjà bien orienté)** - Déjà : justificationDetaillee, documentIds, garantiesProposees. - Optionnel : `origineFondsRemboursement` (String) pour indiquer la source prévue du remboursement (cohérence LCB-FT). **Intentions de paiement / Paiements** - Étendre `type_objet` (ou équivalent API) pour inclure **EPARGNE_DEPOT**, **EPARGNE_RETRAIT**, **CREDIT_REMBOURSEMENT** si les flux passent par le hub Wave. - Ajouter dans le DTO d’intention ou de paiement : `origineFonds` (String, optionnel), `justificationLcbFt` (String, optionnel) — obligatoires au-dessus du seuil. **Membre / KYC** - Ajouter en API (et en base) : - `niveauVigilanceKyc` : enum (SIMPLIFIE | RENFORCE). - `dateVerificationIdentite` (LocalDate, optionnel). - `statutKyc` : enum (NON_VERIFIE | EN_COURS | VERIFIE | REFUSE) pour piloter l’éligibilité aux opérations. **Configuration organisation / plateforme** - Seuils LCB-FT configurables (par organisation ou globaux) : montant au-dessus duquel justification obligatoire, montant au-dessus duquel validation manuelle obligatoire (ex. 500k / 1M XOF). À exposer via config ou table `parametres_organisation` / `parametres_plateforme`. ### 3.2 Base de données - **membres** (ou table dédiée `membre_kyc`) : colonnes `niveau_vigilance_kyc`, `date_verification_identite`, `statut_kyc`. - **transaction_epargne** (si table dédiée) ou table des mouvements : colonnes `origine_fonds`, `piece_justificative_id`, `seuil_lcb_ft_atteint` (booléen). - **intentions_paiement** : colonnes `origine_fonds`, `justification_lcb_ft` (TEXT). - **parametres** : table ou colonnes pour seuils LCB-FT (montant_seuil_justification, montant_seuil_validation_manuelle, code_devise). ### 3.3 Règles métier (impl Quarkus) - Lors de la création d’une transaction épargne (dépôt, retrait, transfert) : si montant >= seuil configuré, exiger `origineFonds` (et éventuellement `pieceJustificativeId`) ; sinon rejet (400) avec message clair. - Crédit : conserver justification détaillée + documents ; optionnellement exiger `dateVerificationIdentite` à jour pour le membre avant déblocage. - Enregistrement systématique dans `audit_logs` des opérations mutuelles (épargne/crédit) avec portee ORGANISATION et détails (montant, type, membre, seuil franchi). - Alertes : création d’événements ou entrées « alerte LCB-FT » (table dédiée ou type d’audit) pour dépassement de seuil, motif vide au-dessus du seuil, ou éventuellement pattern inhabituel (à définir en phase 2). ### 3.4 Mobile - Formulaires de dépôt/retrait/transfert épargne : champs **Origine des fonds** et **Pièce justificative** (upload) rendus obligatoires lorsque le montant saisi dépasse le seuil (seuil fourni par l’API ou la config). - Pas d’affichage de données fictives : listes et détails mutuelles = appels API uniquement. - Fiche membre : affichage du statut KYC et de la date de vérification d’identité (lecture seule si pas de droit de modification). --- ## 4. Conformité et références - **BCEAO** : directives sur les systèmes financiers décentralisés et la lutte contre le blanchiment. - **OHADA** : conservation des preuves et traçabilité des opérations. - **LCB-FT** : identification, vigilance, traçabilité, déclaration des opérations suspectes (la déclaration aux autorités reste hors scope applicatif direct ; le système prépare les données et alertes). --- ## 5. Livrables proposés (ordre recommandé) 1. **Spec + inventaire** (ce document) — fait. 2. **API (unionflow-server-api)** : ajout des champs et enums (origineFonds, niveauVigilanceKyc, statutKyc, dateVerificationIdentite, seuils) dans les DTOs existants ; nouveaux DTOs ou champs pour paramètres LCB-FT. 3. **Migrations Flyway** : nouvelles colonnes membres/KYC, transaction_epargne/intentions_paiement, table paramètres LCB-FT. 4. **Impl Quarkus** : règles de validation (seuils), enregistrement audit, éventuelle table/ressource « alertes LCB-FT ». 5. **Mobile** : écrans mutuelles (épargne/crédit) avec champs obligatoires selon seuil, sans données fictives. --- ## 6. Règle anti-hallucination - Toute nouvelle classe, colonne ou endpoint doit être ajoutée d’abord dans **unionflow-server-api** (ou dans ce spec avec référence explicite au fichier), puis reflétée dans l’inventaire `.specify/memory/inventaire-code.md`. - Aucune donnée fictive en production : pas de listes en dur, pas de mock de données métier dans les écrans ou les réponses API.