Repayment_doc.md

SYSTÈME DE REMBOURSEMENTS - DOCUMENTATION COMPLÈTE

STRUCTURE DES TABLES

1. Table Remboursements (MODIFIÉE)

Nouvelles colonnes à ajouter dans Google Sheets :

| Colonne                | Type    | Description                                        |
|------------------------|---------|---------------------------------------------------|
| ID_Transaction         | Texte   | TRX-2026-0001                                    |
| ID_Pret                | Texte   | PRT-2026-0002                                    |
| ID_Client              | Texte   | CLI-2026-0003 (nouveau)                          |
| Date_Paiement          | Date    | 2026-01-15                                       |
| Montant_Verse          | Nombre  | Montant total payé par le client                 |
| Montant_Principal      | Nombre  | Part du capital remboursé (nouveau)              |
| Montant_Interets       | Nombre  | Part des intérêts (nouveau)                      |
| Penalites_Retard       | Nombre  | Montant des pénalités (nouveau)                  |
| Solde_Avant            | Nombre  | Dette totale avant ce paiement (nouveau)         |
| Solde_Apres            | Nombre  | Dette restante après ce paiement (nouveau)       |
| Numero_Echeance        | Texte   | Format "3/10" (nouveau)                          |
| Date_Echeance_Prevue   | Date    | Date attendue pour ce paiement (nouveau)         |
| Jours_Retard           | Nombre  | Peut être négatif si anticipé (nouveau)          |
| Statut_Paiement        | Texte   | PONCTUEL/EN_RETARD/ANTICIPE/PARTIEL (nouveau)    |
| Moyen_Paiement         | Texte   | Wave, Espèces, etc.                              |
| Reference_Externe      | Texte   | N° transaction Wave/OM (nouveau)                 |
| Commentaire            | Texte   | Notes complémentaires                            |
| Recu_Emis              | Texte   | OUI/NON (nouveau)                                |
| Numero_Recu            | Texte   | REC-2026-0042 (nouveau)                          |
| Timestamp              | Texte   | 2026-01-15 14:23:10                              |

2. Table Ajustements_Echeances (NOUVELLE)

À créer dans Google Sheets :

| Colonne              | Type    | Description                                     |
|---------------------|---------|------------------------------------------------|
| ID_Ajustement       | Texte   | ADJ-2026-0001                                 |
| ID_Pret             | Texte   | PRT-2026-0002                                 |
| Numero_Echeance     | Nombre  | 4 (numéro de l'échéance ajustée)             |
| Montant_Additionnel | Nombre  | 3600 (montant à ajouter)                      |
| Raison              | Texte   | PAIEMENT_PARTIEL                              |
| Date_Creation       | Date    | 2026-01-18                                    |
| Timestamp           | Texte   | 2026-01-18 14:23:10                           |

Cette table est automatiquement créée par le code si elle n'existe pas.

---

INSTALLATION

1. Dépendances Python

Ajouter à votre requirements.txt :

reportlab>=4.0.0

Installer :

pip install reportlab

2. Structure des Dossiers

Vérifier que vous avez cette structure :

project/
├── src/
│   ├── streamlit_app.py
│   ├── modules/
│   │   └── repayments.py          # Interface utilisateur
│   ├── Analytics/
│   │   └── AnalyseRepayment.py    # Logique métier
│   └── DocumentGen/
│       └── InvoiceRepayment.py    # Génération PDF

3. Configuration Google Sheets

1. Ouvrir votre Google Sheet
2. Créer une nouvelle feuille Ajustements_Echeances avec les colonnes listées ci-dessus
3. Modifier la feuille Remboursements pour ajouter les nouvelles colonnes

---

UTILISATION

Workflow Standard

1. Sélection du prêt

   • Rechercher le client par nom ou ID
   • Sélectionner le prêt actif

2. Analyse automatique

   • Le système détecte l'échéance en cours
   • Calcule automatiquement les retards éventuels

3. Choix du scénario (si retard)

   • Option 1 : Pénalités réglementaires (5%)
   • Option 2 : Geste commercial (0%)
   • Option 3 : Taux personnalisé (slider)

4. Validation du paiement

   • Saisir le montant versé
   • Choisir le moyen de paiement
   • Ajouter une référence externe
   • Valider

5. Génération du reçu (optionnel)

   • Cliquer sur "Générer le Reçu"
   • Télécharger le PDF

---

LOGIQUE MÉTIER

Calcul des Pénalités

Formule : Montant_Echéance × Taux_Hebdo × Semaines_Entamées

Exemple :
- Échéance : 10 600 XOF
- Retard : 7 jours = 1 semaine entamée
- Taux : 5%
- Pénalités = 10 600 × 0.05 × 1 = 530 XOF

Ordre de Priorité des Paiements

1. Pénalités (prélevées en priorité)
2. Intérêts
3. Principal

Exemple :

Montant versé : 12 000 XOF
- Pénalités : 530 XOF
- Reste : 11 470 XOF
  ├─ Intérêts : 600 XOF
  └─ Principal : 10 870 XOF

Gestion des Paiements Partiels

Si le montant versé < montant échéance (avec tolérance de 1%) :

1. Le statut devient PARTIEL
2. Le montant manquant est calculé
3. Une ligne est ajoutée dans Ajustements_Echeances
4. L'échéance suivante est automatiquement ajustée

Exemple :

Échéance 3 : 10 600 XOF
Client paie : 7 000 XOF
Manque : 3 600 XOF

→ Échéance 4 devient : 10 600 + 3 600 = 14 200 XOF

Détermination du Statut

# Tolérance de 1%
montant_min_accepte = montant_echeance × 0.99

if jours_retard > 0:
    statut = "EN_RETARD"
elif montant_verse < montant_min_accepte:
    statut = "PARTIEL"
elif jours_retard < 0:
    statut = "ANTICIPE"
else:
    statut = "PONCTUEL"

---

EXEMPLES CONCRETS

Exemple 1 : Paiement Ponctuel

Contexte :
- Prêt : PRT-2026-0002 (100 000 XOF capital, 106 000 XOF total)
- Échéance 3/10 attendue le 15/01/2026
- Client paie 10 600 XOF le 15/01/2026

Résultat :
- Statut : PONCTUEL
- Pénalités : 0 XOF
- Principal : 10 000 XOF
- Intérêts : 600 XOF
- Solde après : 84 800 XOF

Exemple 2 : Paiement en Retard avec Pénalités

Contexte :
- Même prêt
- Échéance 3/10 attendue le 15/01/2026
- Client paie 11 130 XOF le 22/01/2026 (7 jours de retard)

Calculs :
- Retard : 7 jours = 1 semaine
- Pénalités : 10 600 × 5% × 1 = 530 XOF
- Montant pour dette : 11 130 - 530 = 10 600 XOF
  ├─ Intérêts : 600 XOF
  └─ Principal : 10 000 XOF

Résultat :
- Statut : EN_RETARD
- Pénalités : 530 XOF
- Principal : 10 000 XOF
- Intérêts : 600 XOF
- Solde après : 84 800 XOF

Exemple 3 : Paiement Partiel

Contexte :
- Même prêt
- Échéance 3/10 attendue le 15/01/2026
- Client paie 7 000 XOF le 15/01/2026

Calculs :
- Manque : 10 600 - 7 000 = 3 600 XOF
- Décomposition :
  ├─ Intérêts : 600 XOF (priorité)
  └─ Principal : 6 400 XOF

Résultat :
- Statut : PARTIEL
- Pénalités : 0 XOF
- Principal : 6 400 XOF
- Intérêts : 600 XOF
- Solde après : 92 000 XOF

Action :
- Ajout dans Ajustements_Echeances :
  * ID_Pret : PRT-2026-0002
  * Numero_Echeance : 4
  * Montant_Additionnel : 3 600 XOF
  * Raison : PAIEMENT_PARTIEL

- Échéance 4 devient : 10 600 + 3 600 = 14 200 XOF

---

DÉPANNAGE

Erreur : "Table Ajustements_Echeances non trouvée"

Solution : La table sera créée automatiquement au premier ajustement. Vous pouvez aussi la créer manuellement avec les colonnes spécifiées.

Erreur : "Impossible de déterminer l'échéance"

Vérifications :

1. La colonne Dates_Versements est-elle remplie correctement ?
2. Le format est-il correct ? (DD/MM/YYYY,DD/MM/YYYY,...)
3. Le prêt a-t-il un statut ACTIF ?

Les pénalités ne s'affichent pas

Vérifications :

1. Y a-t-il un retard effectif (date_paiement > date_echeance_prevue) ?
2. Le retard est-il d'au moins 1 jour ?
3. Le scénario avec pénalités a-t-il été sélectionné ?

Le reçu ne se génère pas

Vérifications :

1. Le module reportlab est-il installé ? (pip install reportlab)
2. Les données du client existent-elles dans Clients_KYC ?
3. Y a-t-il des erreurs dans les logs ?

---

MAINTENANCE

Réinitialisation d'une Échéance

Si une échéance a été ajustée par erreur :

1. Aller dans Ajustements_Echeances
2. Supprimer la ligne correspondante
3. L'échéance reviendra à sa valeur initiale au prochain rafraîchissement

Modification d'un Paiement

Les paiements enregistrés ne peuvent pas être modifiés directement via l'interface. Pour corriger :

1. Aller dans Google Sheets
2. Modifier directement dans la table Remboursements
3. Si nécessaire, ajuster les soldes manuellement

---

AMÉLIORATIONS FUTURES

À Court Terme

• Envoi automatique du reçu par email/SMS
• Dashboard des retards
• Relances automatiques

À Moyen Terme

• Gestion des remises exceptionnelles
• Historique des ajustements
• Export comptable

À Long Terme

• API pour intégration externe
• Système de scoring automatique
• Prédiction des défauts de paiement

---

SUPPORT

Pour toute question ou problème :

1. Vérifier cette documentation
2. Consulter les logs d'erreur
3. Vérifier la structure des données dans Google Sheets

---

Version : 1.0.0 Date : Janvier 2026 Auteur : Système de Gestion de Microfinance