# Documentation : Système de Pénalités Automatiques

## Vue d'ensemble

Le système applique automatiquement une pénalité de **10%** sur les quittances non payées après le **10 de chaque mois**.

## Fonctionnement

### 1. Vérification automatique

- **Condition** : La quittance n'est pas payée (`is_payer = false`)
- **Date limite** : 10 du mois de la date de fin de la quittance (`end_at`)
- **Pénalité** : 10% du montant du loyer

### 2. Application automatique

La pénalité est appliquée automatiquement dans les cas suivants :

#### A. Lors de la création d'une nouvelle quittance
Si vous créez une quittance avec une date dépassée et non payée, la pénalité sera automatiquement calculée.

#### B. Lors de la modification d'une quittance
Chaque fois qu'une quittance est modifiée, le système vérifie si une pénalité doit être appliquée.

#### C. Via la commande manuelle
Vous pouvez exécuter manuellement la commande pour appliquer les pénalités sur toutes les quittances existantes.

## Utilisation de la commande

### Vérifier quelles quittances seront affectées (mode test)

```bash
php bin/console app:apply-penalties --dry-run
```

### Appliquer les pénalités sur toutes les quittances

```bash
php bin/console app:apply-penalties
```

### Appliquer les pénalités pour une compagnie spécifique

```bash
php bin/console app:apply-penalties --company-id=1
```

### Tester pour une compagnie spécifique

```bash
php bin/console app:apply-penalties --dry-run --company-id=1
```

## Méthodes disponibles dans l'entité Quittances

### `shouldApplyPenalty(): bool`
Vérifie si une pénalité doit être appliquée sur cette quittance.

```php
if ($quittance->shouldApplyPenalty()) {
    // La pénalité doit être appliquée
}
```

### `applyPenaltyIfNeeded(): void`
Applique automatiquement la pénalité si les conditions sont remplies.

```php
$quittance->applyPenaltyIfNeeded();
```

### `getTotalWithPenalty(): float`
Retourne le montant total incluant la pénalité.

```php
$montantAvecPenalite = $quittance->getTotalWithPenalty();
```

### `getPenaltyAmount(): float`
Retourne le montant de la pénalité uniquement.

```php
$montantPenalite = $quittance->getPenaltyAmount();
```

## Automatisation avec Cron

Pour exécuter automatiquement la vérification des pénalités chaque jour à 00h05, ajoutez cette ligne à votre crontab :

```cron
5 0 * * * cd /chemin/vers/projet/loyer && php bin/console app:apply-penalties >> /var/log/penalties.log 2>&1
```

Ou pour Windows (Planificateur de tâches) :
1. Ouvrir le Planificateur de tâches Windows
2. Créer une nouvelle tâche
3. Déclencheur : Quotidien à 00h05
4. Action : Démarrer un programme
   - Programme : `C:\php\php.exe` (chemin vers votre PHP)
   - Arguments : `bin/console app:apply-penalties`
   - Répertoire : `C:\Softsys\immo_customers\loyer_interne\loyer`

## Mise à jour des quittances existantes

Pour appliquer les pénalités sur toutes les quittances existantes non payées :

```bash
# 1. Vérifier d'abord ce qui sera modifié
php bin/console app:apply-penalties --dry-run

# 2. Si tout est correct, appliquer les modifications
php bin/console app:apply-penalties
```

## Exemple de calcul

**Quittance :**
- Montant du loyer : 150 000 FCFA
- Date de fin : 31 janvier 2026
- Statut : Non payée
- Date actuelle : 12 février 2026

**Calcul de la pénalité :**
- Date limite de paiement : 10 janvier 2026
- Jours de retard : 33 jours
- Pénalité : 150 000 × 10% = 15 000 FCFA
- **Montant total à payer : 165 000 FCFA**

## Notes importantes

1. **Les pénalités ne sont pas dupliquées** : Si une quittance a déjà une pénalité appliquée, elle ne sera pas recalculée.

2. **Paiement effectué** : Dès qu'une quittance est marquée comme payée (`is_payer = true`), aucune pénalité ne sera appliquée même après le 10.

3. **Modification manuelle** : Vous pouvez toujours modifier manuellement le pourcentage de pénalité ou le montant si nécessaire.

4. **Logs** : La commande affiche un résumé détaillé de toutes les opérations effectuées.

## Dépannage

### La pénalité ne s'applique pas automatiquement

Vérifiez que :
- La quittance n'est pas marquée comme payée
- La date `end_at` est bien définie
- La date actuelle est bien après le 10 du mois de la quittance
- Le cache Symfony est à jour : `php bin/console cache:clear`

### Vérifier manuellement une quittance spécifique

```php
// Dans un contrôleur ou service
$quittance = $quittancesRepository->find($id);

dump([
    'should_apply' => $quittance->shouldApplyPenalty(),
    'is_payer' => $quittance->isIsPayer(),
    'end_at' => $quittance->getEndAt(),
    'penalty_amount' => $quittance->getPenaltyAmount(),
]);
```

## Support

Pour toute question ou problème, contactez l'équipe de développement.
