Cash-in agent — État actuel vs prévu et roadmap

Ce qui est implémenté aujourd'hui, ce qui est prévu mais non encore implémenté, plan de remédiation. Pour la vue d'ensemble, voir Cash-in agent — overview.

⚠️ État Actuel vs Prévu

✅ Ce Qui Est Implémenté

1. Configuration des Règles ✅

   • CRUD configurations
   • Validation total = 100%
   • Simulateur de distribution
   • Historique

2. Collecte des Frais ✅

   • Débit client
   • Crédit FEE_COLLECTION
   • Ledger entries

3. Calcul des Montants ✅

   • Service de simulation
   • Calcul par pourcentage

⚠️ Ce Qui Est Prévu Mais Non Implémenté

1. Distribution Automatique ❌

   • Service CommissionDistributionService manquant
   • Pas d'intégration dans TransactionCreationOrchestrator

2. Résolution Wallets ❌

   • Logique prévue mais non codée
   • Pas de service TransactionEntitiesService

3. Sauvegarde Distributions ❌

   • Table commission_distributions créée
   • Pas de service pour l'utiliser

---

🔧 Ce Qui Doit Être Fait

Phase 1: Service Transaction Entities (1 jour)

Créer:

services/ledger-wallets/src/transaction-entities/
├── transaction-entities.module.ts
├── transaction-entities.service.ts
└── entities/transaction-entity.entity.ts

Fonctionnalité:

• Sauvegarder contexte transaction (merchant_id, corporate_id, etc.)
• Récupérer entités pour résolution wallets

---

Phase 2: Service Commission Distributions (1 jour)

Créer:

services/ledger-wallets/src/commission-distributions/
├── commission-distributions.module.ts
├── commission-distributions.service.ts
└── entities/commission-distribution.entity.ts

Fonctionnalité:

• Sauvegarder distributions
• Gérer status (pending/completed/failed)
• Retry pour comptes manquants

---

Phase 3: Service Distribution Orchestrator (2 jours)

Créer:

services/orchestrator/src/application/services/
└── commission-distribution.service.ts

Fonctionnalité:

1. Récupérer règles depuis Configuration Service
2. Résoudre entités depuis transaction_entities
3. Résoudre wallets/comptes bénéficiaires
4. Créer transferts depuis FEE_COLLECTION
5. Sauvegarder dans commission_distributions

---

Phase 4: Intégration (1 jour)

Modifier:

services/ledger-wallets/src/transactions/orchestrators/
└── transaction-creation.orchestrator.ts

Ajouter après ligne 116:

// ÉTAPE 5: Distribuer commissions (si frais)
if (feeAmount > 0 && savedTransaction.status === TransactionStatus.COMPLETED) {
  await this.commissionDistributionService.distribute({
    transactionId: savedTransaction.id,
    transactionTypeId: dto.transactionTypeId,
    feeAmount: feeAmount,
    currencyCode: dto.currencyCode || 'XAF',
  });
}

---

📝 Exemple Complet de Flux

Scénario: Cash-In 10,000 XAF avec frais 200 XAF

1. Transaction Créée

{
  "id": "tx-123",
  "amount": 10000,
  "feeAmount": 200,
  "transactionTypeId": "deposit-cashin-uuid"
}

2. Frais Collectés

FEE_COLLECTION.balance: 0 → 200 XAF

3. Règles Appliquées

{
  "platform": { "percentage": 30, "amount": 60 },
  "corporate": { "percentage": 20, "amount": 40 },
  "merchant": { "percentage": 50, "amount": 100 }
}

4. Distribution (Prévue)

FEE_COLLECTION: 200 → 0 XAF
Nex Wallet: 0 → 60 XAF
Corporate Wallet: 0 → 40 XAF
Merchant Wallet: 0 → 100 XAF

5. Enregistrements

-- commission_distributions
INSERT INTO commission_distributions VALUES
  ('dist-1', 'tx-123', 'rule-platform', 'platform', 'account-nxpay', 60, 30, 'completed'),
  ('dist-2', 'tx-123', 'rule-corporate', 'corporate', 'account-corp', 40, 20, 'completed'),
  ('dist-3', 'tx-123', 'rule-merchant', 'merchant', 'account-merchant', 100, 50, 'completed');

---

🎯 Conclusion

État Actuel:

• ✅ Configuration: 100%
• ✅ Collecte: 100%
• ⚠️ Distribution: 0%

L'argent est collecté mais pas encore distribué automatiquement.

Pour activer la distribution:

1. Implémenter les services manquants (4-5 jours)
2. Intégrer dans le flux de transaction
3. Tester avec transactions réelles

---

Document créé le: 2026-01-29
Version: 1.0.0