# Système de Pénalités Automatiques - Guide de Mise en Œuvre

## Résumé des Modifications

Ce document décrit les modifications apportées pour implémenter le système de pénalités automatiques de 10% sur les loyers non payés après le 10 de chaque mois.

## Fichiers Modifiés

### 1. Entité : `src/Entity/Quittances/Quittances.php`
**Ajouts :**
- `shouldApplyPenalty()` : Vérifie si une pénalité doit être appliquée
- `applyPenaltyIfNeeded()` : Applique automatiquement la pénalité si nécessaire
- `getTotalWithPenalty()` : Calcule le montant total avec pénalité
- `getPenaltyAmount()` : Retourne le montant de la pénalité seule

### 2. Contrôleur : `src/Controller/Admin/Quittances/AdminQuittancesController.php`
**Modifications :**
- Ligne ~253 : Appel de `applyPenaltyIfNeeded()` lors de la création d'une quittance
- Ligne ~443 : Appel de `applyPenaltyIfNeeded()` lors de la modification d'une quittance

### 3. Commande : `src/Command/ApplyPenaltiesCommand.php` *(NOUVEAU)*
Commande pour appliquer les pénalités sur les quittances existantes.

### 4. Templates Twig
**`templates/admin/quittances/_partials/_table.html.twig`**
- Affichage d'un badge pour indiquer si une pénalité est appliquée
- Badge d'avertissement si une pénalité est due

**`templates/admin/quittances/_partials/_invoice.html.twig`**
- Affichage détaillé de la pénalité dans la facture
- Séparation sous-total / pénalité / total

### 5. Documentation
- `PENALITES_DOCUMENTATION.md` : Documentation complète du système
- `PENALITES_README.md` : Ce fichier (guide de mise en œuvre)

## Comment Tester

### 1. Test avec les quittances existantes

```bash
# Vérifier quelles quittances seront affectées (sans appliquer)
php bin/console app:apply-penalties --dry-run
```

**Résultat attendu :**
- Liste des quittances non payées après le 10 du mois
- Montants originaux et montants avec pénalité
- Aucune modification en base de données

### 2. Appliquer les pénalités sur les quittances existantes

```bash
# Appliquer les pénalités
php bin/console app:apply-penalties
```

**Résultat attendu :**
- Les quittances éligibles sont mises à jour
- Le flag `is_penalite` est mis à `true`
- Le champ `penalite` est mis à `10`
- Le montant total est recalculé avec la pénalité

### 3. Test de création d'une nouvelle quittance

1. Connectez-vous à l'application
2. Créez une nouvelle quittance avec :
   - Date de fin : un mois passé (ex: 31 janvier 2026)
   - Statut : Non payée
   - Montant : 150000 FCFA

**Résultat attendu :**
- Si la date actuelle > 10 février 2026 :
  - La pénalité est automatiquement appliquée
  - Le montant devient 165000 FCFA (150000 + 10%)
  - Un badge "pénalité" s'affiche dans la liste

### 4. Test de modification d'une quittance

1. Ouvrez une quittance existante non payée avec date dépassée
2. Modifiez un champ quelconque
3. Enregistrez

**Résultat attendu :**
- La pénalité est vérifiée et appliquée si nécessaire
- Le montant est recalculé

### 5. Vérification visuelle

#### Dans la liste des quittances
- Les quittances avec pénalité affichent un badge rouge avec l'icône d'avertissement
- Le pourcentage de pénalité est affiché

#### Dans la facture/quittance
- Une ligne "PÉNALITÉ (10% - Paiement après le 10)" est ajoutée
- Le montant de la pénalité est affiché en rouge
- Le total inclut la pénalité

## Scénarios de Test Détaillés

### Scénario 1 : Quittance payée à temps
**Données :**
- Date de fin : 31 janvier 2026
- Date de paiement : 8 janvier 2026
- Statut : Payée

**Résultat :** ✅ Aucune pénalité appliquée

### Scénario 2 : Quittance payée en retard mais avant application
**Données :**
- Date de fin : 31 janvier 2026
- Date de paiement : 15 janvier 2026 (après le 10)
- Statut : Payée

**Résultat :** ✅ Aucune pénalité appliquée (déjà payée)

### Scénario 3 : Quittance non payée après le 10
**Données :**
- Date de fin : 31 janvier 2026
- Date actuelle : 12 février 2026
- Statut : Non payée

**Résultat :** ✅ Pénalité de 10% appliquée

### Scénario 4 : Quittance du mois en cours avant le 10
**Données :**
- Date de fin : 28 février 2026
- Date actuelle : 8 février 2026
- Statut : Non payée

**Résultat :** ✅ Aucune pénalité (pas encore le 10)

## Vérification en Base de Données

```sql
-- Vérifier les quittances avec pénalité
SELECT 
    id,
    code,
    total,
    is_payer,
    is_penalite,
    penalite,
    end_at,
    DATE_FORMAT(end_at, '%Y-%m-10') as date_limite
FROM quittances
WHERE is_penalite = 1;

-- Vérifier les quittances éligibles à la pénalité mais pas encore appliquée
SELECT 
    id,
    code,
    total,
    is_payer,
    is_penalite,
    end_at,
    DATE_FORMAT(end_at, '%Y-%m-10') as date_limite
FROM quittances
WHERE is_payer = 0 
  AND is_penalite = 0
  AND CURDATE() > DATE_FORMAT(end_at, '%Y-%m-10');
```

## Points de Vérification

### ✅ Checklist Avant Mise en Production

- [ ] Les tests unitaires passent
- [ ] La commande `app:apply-penalties --dry-run` fonctionne
- [ ] La commande `app:apply-penalties` applique correctement les pénalités
- [ ] Les badges de pénalité s'affichent dans la liste
- [ ] Les pénalités sont visibles sur les factures
- [ ] Les quittances payées ne reçoivent pas de pénalité
- [ ] Les quittances avant le 10 du mois ne reçoivent pas de pénalité
- [ ] La documentation est à jour

### 🔧 Configuration Requise

1. **PHP >= 8.0** (pour les unions types et attributs)
2. **Symfony >= 5.4**
3. **Droits d'écriture** sur la base de données
4. **Cron ou Planificateur de tâches** (optionnel, pour automatisation)

## Automatisation (Optionnel)

### Linux/Mac - Crontab

```bash
# Éditer le crontab
crontab -e

# Ajouter cette ligne pour exécution quotidienne à 00h05
5 0 * * * cd /chemin/vers/projet/loyer && php bin/console app:apply-penalties >> /var/log/penalties.log 2>&1
```

### Windows - Planificateur de tâches

1. Ouvrir "Planificateur de tâches"
2. "Créer une tâche de base"
3. Nom : "Application Pénalités Loyers"
4. Déclencheur : Quotidien à 00h05
5. Action : "Démarrer un programme"
   - Programme : `C:\php\php.exe`
   - Arguments : `bin/console app:apply-penalties`
   - Dossier : `C:\Softsys\immo_customers\loyer_interne\loyer`

## Dépannage

### Problème : La pénalité ne s'applique pas

**Solutions :**
1. Vérifier que la quittance est bien non payée (`is_payer = false`)
2. Vérifier que la date actuelle > 10 du mois de `end_at`
3. Vider le cache : `php bin/console cache:clear`
4. Vérifier les logs d'erreur Symfony

### Problème : La pénalité est appliquée deux fois

**Solution :**
La méthode `shouldApplyPenalty()` vérifie déjà si une pénalité est appliquée. Si le problème persiste :
1. Vérifier la logique dans le contrôleur (ligne 447)
2. S'assurer que la pénalité n'est pas recalculée à chaque modification

### Problème : Le badge ne s'affiche pas dans Twig

**Solution :**
Si la méthode `shouldApplyPenalty()` n'est pas accessible dans Twig, créer un service Twig :

```php
// src/Twig/QuittanceExtension.php
namespace App\Twig;

use App\Entity\Quittances\Quittances;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class QuittanceExtension extends AbstractExtension
{
    public function getFunctions()
    {
        return [
            new TwigFunction('should_apply_penalty', [$this, 'shouldApplyPenalty']),
        ];
    }

    public function shouldApplyPenalty(Quittances $quittance): bool
    {
        return $quittance->shouldApplyPenalty();
    }
}
```

## Support et Contact

Pour toute question ou problème :
- Consulter la documentation complète : `PENALITES_DOCUMENTATION.md`
- Contacter l'équipe de développement
- Créer un ticket de support

## Changelog

### Version 1.0.0 - 2026-02-12
- ✅ Implémentation initiale du système de pénalités automatiques
- ✅ Ajout de la commande `app:apply-penalties`
- ✅ Mise à jour des templates pour affichage des pénalités
- ✅ Documentation complète
