# 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` : ```txt reportlab>=4.0.0 ``` Installer : ```bash 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 ```python # 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