# 📘 Logique de Paiement et Application des Pénalités

## Comment le système sait-il si une quittance est payée avant le 10 ou pas ?

### 🔍 Champs Utilisés

Le système utilise **3 champs** principaux dans la table `quittances` :

| Champ | Type | Description |
|-------|------|-------------|
| `is_payer` | boolean | Indique si la quittance est payée ou non |
| `payer_at` | date | **Date exacte du paiement** |
| `end_at` | date | Date de fin de la période de location |

### 📅 Date Limite : Le 10 du Mois

La date limite de paiement est calculée ainsi :
- **Mois** : Le mois de la date `end_at`
- **Jour** : Le 10
- **Année** : L'année de la date `end_at`

**Exemple :**
- Si `end_at` = 31 janvier 2026
- Alors date limite = **10 janvier 2026**

---

## 🎯 Logique Complète d'Application des Pénalités

### Cas 1 : Quittance Payée AVANT ou LE 10 ✅

```
Quittance créée : 15 décembre 2025
Date de fin : 31 décembre 2025
Date limite : 10 décembre 2025

Paiement effectué : 8 décembre 2025
→ payer_at = 2025-12-08
→ is_payer = true

RÉSULTAT : ✅ PAS de pénalité (payé avant le 10)
```

### Cas 2 : Quittance NON Payée après le 10 ⚠️

```
Quittance créée : 15 décembre 2025
Date de fin : 31 décembre 2025
Date limite : 10 décembre 2025

Date actuelle : 15 décembre 2025
→ payer_at = null
→ is_payer = false

RÉSULTAT : ⚠️ PÉNALITÉ de 10% appliquée
```

### Cas 3 : Quittance Payée APRÈS le 10 (mais pénalité déjà appliquée) 💰

```
Quittance créée : 15 décembre 2025
Date de fin : 31 décembre 2025
Date limite : 10 décembre 2025

12 décembre : Pénalité appliquée automatiquement
→ is_penalite = true
→ penalite = 10
→ Montant passe de 100 000 à 110 000 FCFA

18 décembre : Locataire paie
→ payer_at = 2025-12-18
→ is_payer = true

RÉSULTAT : 💰 La pénalité RESTE dans le montant total
Le locataire doit payer 110 000 FCFA
```

### Cas 4 : Quittance Payée (sans date précise) ✅

```
Quittance marquée comme "Payée" via l'interface
→ is_payer = true
→ payer_at = null (pas de date définie)

RÉSULTAT : ✅ PAS de pénalité (considérée comme payée)
```

---

## ⚙️ Fonctionnement Technique

### 1. Enregistrement Automatique de la Date de Paiement

Quand une quittance est **marquée comme payée** :

```php
// Dans ApisQuittancesController.php
if ($quittance->isIsPayer() === true) {
    // Définir la date de paiement à aujourd'hui
    if (!$quittance->getPayerAt()) {
        $quittance->setPayerAt(new \DateTime());
    }
}
```

### 2. Vérification si Pénalité Applicable

```php
// Dans Quittances.php
public function shouldApplyPenalty(): bool
{
    // Étape 1 : Vérifier si date de fin existe
    if (!$this->end_at) {
        return false;
    }

    // Étape 2 : Calculer la date limite (10 du mois)
    $endMonth = (int) $this->end_at->format('m');
    $endYear = (int) $this->end_at->format('Y');
    $deadline = new \DateTime("{$endYear}-{$endMonth}-10");

    // Étape 3 : Si payé et date de paiement existe
    if ($this->is_payer && $this->payer_at) {
        // Payé AVANT le 10 → PAS de pénalité
        if ($this->payer_at <= $deadline) {
            return false;
        }
        // Payé APRÈS le 10 → Ne pas appliquer de nouvelle pénalité
        return false;
    }

    // Étape 4 : Si payé mais sans date → considéré comme payé
    if ($this->is_payer && !$this->payer_at) {
        return false;
    }

    // Étape 5 : NON payé et après le 10 → Pénalité
    $now = new \DateTime();
    return $now > $deadline;
}
```

### 3. Nouvelles Méthodes Utiles

```php
// Vérifier si payé avant le 10
$isPaidBeforeDeadline = $quittance->isPaidBeforeDeadline();

// Obtenir le nombre de jours de retard
$daysLate = $quittance->getDaysLate();
```

---

## 📊 Scénarios Détaillés

### Scénario A : Paiement Normal (avant le 10)

```
┌─────────────────────────────────────────────────────────┐
│ Chronologie                                             │
├─────────────────────────────────────────────────────────┤
│ 01/12 : Quittance créée (end_at = 31/12)              │
│ 05/12 : Locataire paie                                │
│         → payer_at = 05/12/2025                        │
│         → is_payer = true                              │
│ 10/12 : Date limite (AUCUNE ACTION)                   │
│                                                         │
│ ✅ Montant payé : 100 000 FCFA (sans pénalité)        │
└─────────────────────────────────────────────────────────┘
```

### Scénario B : Paiement en Retard (après le 10)

```
┌─────────────────────────────────────────────────────────┐
│ Chronologie                                             │
├─────────────────────────────────────────────────────────┤
│ 01/12 : Quittance créée (end_at = 31/12)              │
│ 10/12 : Date limite passée                            │
│ 11/12 : Système applique pénalité automatiquement     │
│         → is_penalite = true                           │
│         → penalite = 10                                │
│         → total = 110 000 FCFA (était 100 000)        │
│ 15/12 : Locataire paie                                │
│         → payer_at = 15/12/2025                        │
│         → is_payer = true                              │
│                                                         │
│ 💰 Montant payé : 110 000 FCFA (avec pénalité)        │
└─────────────────────────────────────────────────────────┘
```

### Scénario C : Paiement Toggle (via interface)

```
┌─────────────────────────────────────────────────────────┐
│ Chronologie                                             │
├─────────────────────────────────────────────────────────┤
│ 01/12 : Quittance créée                                │
│ 15/12 : Admin clique sur le toggle "Payé"             │
│         → is_payer = true                              │
│         → payer_at = 15/12/2025 (automatique)          │
│         → Système vérifie la date                      │
│                                                         │
│ SI toggle cliqué AVANT le 10 :                        │
│    ✅ PAS de pénalité                                  │
│                                                         │
│ SI toggle cliqué APRÈS le 10 :                        │
│    ⚠️ Pénalité déjà appliquée reste                   │
└─────────────────────────────────────────────────────────┘
```

---

## 🔄 Flux de Traitement

### Création d'une Quittance

```mermaid
graph TD
    A[Quittance créée] --> B{Date actuelle > 10 du mois?}
    B -->|OUI| C[Appliquer pénalité]
    B -->|NON| D[Pas de pénalité]
    C --> E[Montant = Original + 10%]
    D --> F[Montant = Original]
```

### Marquage comme Payée

```mermaid
graph TD
    A[Toggle cliqué] --> B[Définir payer_at = aujourd'hui]
    B --> C[is_payer = true]
    C --> D{payer_at <= 10 du mois?}
    D -->|OUI| E[Supprimer pénalité si existe]
    D -->|NON| F[Garder pénalité si existe]
```

---

## 🛠️ Requêtes SQL Utiles

### Voir les quittances payées avant le 10

```sql
SELECT 
    q.code,
    q.payer_at as date_paiement,
    DATE_FORMAT(q.end_at, '%Y-%m-10') as date_limite,
    CASE 
        WHEN q.payer_at <= DATE_FORMAT(q.end_at, '%Y-%m-10') 
        THEN 'Payé à temps ✅'
        ELSE 'Payé en retard ⚠️'
    END as statut
FROM quittances q
WHERE q.is_payer = 1 
  AND q.payer_at IS NOT NULL
ORDER BY q.payer_at DESC;
```

### Voir les quittances en retard

```sql
SELECT 
    q.code,
    q.total,
    q.end_at,
    DATE_FORMAT(q.end_at, '%Y-%m-10') as date_limite,
    DATEDIFF(CURDATE(), DATE_FORMAT(q.end_at, '%Y-%m-10')) as jours_retard,
    q.is_penalite as penalite_appliquee
FROM quittances q
WHERE q.is_payer = 0
  AND CURDATE() > DATE_FORMAT(q.end_at, '%Y-%m-10')
ORDER BY jours_retard DESC;
```

### Statistiques de paiement

```sql
SELECT 
    COUNT(*) as total_quittances,
    SUM(CASE WHEN is_payer = 1 
             AND payer_at <= DATE_FORMAT(end_at, '%Y-%m-10') 
        THEN 1 ELSE 0 END) as payes_a_temps,
    SUM(CASE WHEN is_payer = 1 
             AND payer_at > DATE_FORMAT(end_at, '%Y-%m-10') 
        THEN 1 ELSE 0 END) as payes_en_retard,
    SUM(CASE WHEN is_payer = 0 
             AND CURDATE() > DATE_FORMAT(end_at, '%Y-%m-10') 
        THEN 1 ELSE 0 END) as impaye_en_retard
FROM quittances
WHERE end_at >= DATE_SUB(CURDATE(), INTERVAL 12 MONTH);
```

---

## ✅ Points Importants à Retenir

1. **Date de Paiement Automatique** : Quand une quittance est marquée comme payée, la date `payer_at` est automatiquement définie à la date actuelle

2. **Pénalité Préservée** : Si une pénalité a été appliquée avant le paiement, elle reste dans le montant total

3. **Pas de Double Pénalité** : Une fois qu'une quittance est payée, aucune nouvelle pénalité ne peut être appliquée

4. **Vérification Intelligente** : Le système vérifie d'abord si une date de paiement existe avant de vérifier le statut

5. **Date Limite Dynamique** : La date limite (10 du mois) est calculée en fonction de la date `end_at` de chaque quittance

---

## 📞 Questions Fréquentes

### Q1 : Que se passe-t-il si je change la date de paiement manuellement ?

**R :** Le système recalcule automatiquement si une pénalité doit être appliquée en fonction de la nouvelle date.

### Q2 : Peut-on retirer une pénalité déjà appliquée ?

**R :** Oui, en modifiant manuellement :
- `is_penalite` → false
- `penalite` → 0
- Recalculer le `total` en retirant 10%

### Q3 : Comment gérer un paiement partiel ?

**R :** Le système actuel ne gère pas les paiements partiels. C'est une évolution future possible.

### Q4 : La pénalité s'applique-t-elle automatiquement tous les jours ?

**R :** Non, elle s'applique une seule fois lorsque :
- La quittance est créée/modifiée après le 10
- La commande `app:apply-penalties` est exécutée

---

**Dernière mise à jour** : 12 février 2026  
**Version** : 1.1.0 (avec gestion de `payer_at`)
