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.