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` :

```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