# Documentation des tâches CRON - API Geosector

Ce dossier contient les scripts automatisés de maintenance et de traitement pour l'API Geosector.

## Scripts disponibles

### 1. `process_email_queue.php`

**Fonction** : Traite la queue d'emails en attente (reçus fiscaux, notifications)

**Caractéristiques** :

- Traite 50 emails maximum par exécution
- 3 tentatives maximum par email
- Lock file pour éviter l'exécution simultanée
- Nettoyage automatique des emails envoyés de plus de 30 jours

**Fréquence recommandée** : Toutes les 5 minutes

**Ligne crontab** :

```bash
*/5 * * * * /usr/bin/php /var/www/geosector/api/scripts/cron/process_email_queue.php >> /var/www/geosector/api/logs/email_queue.log 2>&1
```

---

### 2. `cleanup_security_data.php`

**Fonction** : Purge les données de sécurité obsolètes selon la politique de rétention

**Données nettoyées** :

- Métriques de performance : 30 jours
- Tentatives de login échouées : 7 jours
- Alertes résolues : 90 jours
- IPs expirées : Déblocage immédiat

**Fréquence recommandée** : Quotidien à 2h du matin

**Ligne crontab** :

```bash
0 2 * * * /usr/bin/php /var/www/geosector/api/scripts/cron/cleanup_security_data.php >> /var/www/geosector/api/logs/cleanup_security.log 2>&1
```

---

### 3. `cleanup_logs.php`

**Fonction** : Supprime les fichiers de logs de plus de 10 jours

**Caractéristiques** :

- Cible tous les fichiers `*.log` dans `/api/logs/`
- Exclut le dossier `/logs/events/` (rétention 15 mois)
- Rétention : 10 jours
- Logs détaillés des fichiers supprimés et taille libérée
- Lock file pour éviter l'exécution simultanée

**Fréquence recommandée** : Quotidien à 3h du matin

**Ligne crontab** :

```bash
0 3 * * * /usr/bin/php /var/www/geosector/api/scripts/cron/cleanup_logs.php >> /var/www/geosector/api/logs/cleanup_logs.log 2>&1
```

---

### 4. `rotate_event_logs.php`

**Fonction** : Rotation des logs d'événements JSONL (système EventLogService)

**Politique de rétention (15 mois)** :

- 0-15 mois : fichiers `.jsonl` conservés (non compressés pour accès API)
- > 15 mois : suppression automatique

**Caractéristiques** :

- Suppression des fichiers > 15 mois
- Pas de compression (fichiers accessibles par l'API)
- Logs détaillés des suppressions
- Lock file pour éviter l'exécution simultanée

**Fréquence recommandée** : Mensuel le 1er à 3h du matin

**Ligne crontab** :

```bash
0 3 1 * * /usr/bin/php /var/www/geosector/api/scripts/cron/rotate_event_logs.php >> /var/www/geosector/api/logs/rotation_events.log 2>&1
```

---

### 5. `sync_databases.php`

**Fonction** : Synchronise les bases de données entre environnements

**Note** : Ce script est spécifique à un cas d'usage particulier. Vérifier son utilité avant activation.

**Fréquence recommandée** : À définir selon les besoins

**Ligne crontab** :

```bash
# À configurer selon les besoins
# 0 4 * * * /usr/bin/php /var/www/geosector/api/scripts/cron/sync_databases.php >> /var/www/geosector/api/logs/sync_databases.log 2>&1
```

---

## Installation sur les containers Incus

### 1. Déployer les scripts sur les environnements

```bash
# DEV (dva-geo sur IN3)
./deploy-api.sh

# RECETTE (rca-geo sur IN3)
./deploy-api.sh rca

# PRODUCTION (pra-geo sur IN4)
./deploy-api.sh pra
```

### 2. Configurer le crontab sur chaque container

```bash
# Se connecter au container
incus exec dva-geo -- sh    # ou rca-geo, pra-geo

# Éditer le crontab
crontab -e

# Ajouter les lignes ci-dessous (adapter les chemins si nécessaire)
```

### 3. Configuration complète recommandée

```bash
# Traitement de la queue d'emails (toutes les 5 minutes)
*/5 * * * * /usr/bin/php /var/www/geosector/api/scripts/cron/process_email_queue.php >> /var/www/geosector/api/logs/email_queue.log 2>&1

# Nettoyage des données de sécurité (quotidien à 2h)
0 2 * * * /usr/bin/php /var/www/geosector/api/scripts/cron/cleanup_security_data.php >> /var/www/geosector/api/logs/cleanup_security.log 2>&1

# Nettoyage des anciens logs (quotidien à 3h)
0 3 * * * /usr/bin/php /var/www/geosector/api/scripts/cron/cleanup_logs.php >> /var/www/geosector/api/logs/cleanup_logs.log 2>&1

# Rotation des logs événements (mensuel le 1er à 3h)
0 3 1 * * /usr/bin/php /var/www/geosector/api/scripts/cron/rotate_event_logs.php >> /var/www/geosector/api/logs/rotation_events.log 2>&1
```

### 4. Vérifier que les CRONs sont actifs

```bash
# Lister les CRONs configurés
crontab -l

# Vérifier les logs pour s'assurer qu'ils s'exécutent
tail -f /var/www/geosector/api/logs/email_queue.log
tail -f /var/www/geosector/api/logs/cleanup_logs.log
```

---

## Surveillance et monitoring

### Emplacement des logs

Tous les logs CRON sont stockés dans `/var/www/geosector/api/logs/` :

- `email_queue.log` : Traitement de la queue d'emails
- `cleanup_security.log` : Nettoyage des données de sécurité
- `cleanup_logs.log` : Nettoyage des anciens fichiers logs
- `rotation_events.log` : Rotation des logs événements JSONL

### Vérification de l'exécution

```bash
# Voir les dernières exécutions du processeur d'emails
tail -n 50 /var/www/geosector/api/logs/email_queue.log

# Voir les derniers nettoyages de logs
tail -n 50 /var/www/geosector/api/logs/cleanup_logs.log

# Voir les dernières rotations des logs événements
tail -n 50 /var/www/geosector/api/logs/rotation_events.log
```

---

## Notes importantes

1. **Détection d'environnement** : Tous les scripts détectent automatiquement l'environnement via `gethostname()` :

   - `pra-geo` → Production (app3.geosector.fr)
   - `rca-geo` → Recette (rapp.geosector.fr)
   - `dva-geo` → Développement (dapp.geosector.fr)

2. **Lock files** : Les scripts critiques utilisent des fichiers de lock dans `/tmp/` pour éviter l'exécution simultanée

3. **Permissions** : Les scripts doivent être exécutables (`chmod +x script.php`)

4. **Logs** : Tous les scripts loggent via `LogService` pour traçabilité complète

---

## Dépannage

### Le CRON ne s'exécute pas

```bash
# Vérifier que le service cron est actif
rc-service crond status    # Alpine Linux

# Relancer le service si nécessaire
rc-service crond restart
```

### Erreur de permissions

```bash
# Vérifier les permissions du script
ls -l /var/www/geosector/api/scripts/cron/

# Rendre exécutable si nécessaire
chmod +x /var/www/geosector/api/scripts/cron/*.php

# Vérifier les permissions du dossier logs
ls -ld /var/www/geosector/api/logs/
```

### Lock file bloqué

```bash
# Si un script semble bloqué, supprimer le lock file
rm /tmp/process_email_queue.lock
rm /tmp/cleanup_logs.lock
```
