unionflow-server-api/unionflow/specs/001-mutuelles-anti-blanchiment/spec.md

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.