# Génération de Sitemaps Whise - Version File-Based

Ce système génère des sitemaps pour les propriétés immobilières Whise en utilisant une approche basée sur des fichiers JSON, sans nécessiter de base de données.

## 🏗️ Architecture

### 1. Synchronisation des données (SyncWhiseJob)

-   Récupère les propriétés depuis l'API Whise
-   Stocke les données dans `storage/app/whise_properties.json`
-   Gère la pagination et le rate limiting
-   Support multilingue (FR/EN/NL)
-   Nettoyage automatique des propriétés supprimées

### 2. Génération des sitemaps (GenerateWhiseSitemapJob)

-   Lit les données depuis le fichier JSON local
-   Génère des sitemaps XML avec support multilingue
-   Crée un index sitemap principal
-   Gestion des chunks (40k URLs par fichier)

### 3. Workflow orchestré (WhiseSitemapWorkflowJob)

-   Combine sync + génération en un seul job
-   Support pour l'exécution en queue
-   Retry automatique en cas d'erreur

## 📋 Commandes disponibles

### Commande principale (synchrone)

```bash
# Sync + génération complète
php artisan sitemap:whise-file-based

# Sync uniquement
php artisan sitemap:whise-file-based --sync-only

# Génération uniquement
php artisan sitemap:whise-file-based --generate-only

# Reset et recommencer
php artisan sitemap:whise-file-based --reset
```

### Commande LENTE (respectueuse du rate limit) ⭐ RECOMMANDÉE

```bash
# Sync + génération complète LENTE (8-10 minutes)
php artisan sitemap:whise-slow

# Sync uniquement LENT
php artisan sitemap:whise-slow --sync-only

# Génération uniquement
php artisan sitemap:whise-slow --generate-only

# Reset et recommencer
php artisan sitemap:whise-slow --reset
```

### Commande queue (asynchrone)

```bash
# Queue le workflow complet
php artisan sitemap:queue-whise

# Queue sync uniquement
php artisan sitemap:queue-whise --sync-only

# Queue génération uniquement
php artisan sitemap:queue-whise --generate-only
```

## ⚡ Différences entre les versions

### Version normale (`sitemap:whise-file-based`)

-   **Vitesse**: 2-3 minutes pour 600 propriétés
-   **PageSize**: 25 propriétés par appel
-   **Délai**: 1 seconde entre les appels
-   **Usage**: Tests rapides, développement

### Version lente (`sitemap:whise-slow`) ⭐ RECOMMANDÉE

-   **Vitesse**: 8-10 minutes pour 600 propriétés
-   **PageSize**: 10 propriétés par appel
-   **Délai**: 3 secondes entre les appels
-   **Gestion d'erreurs**: 60 secondes d'attente en cas de rate limit
-   **Usage**: Production, respect strict du rate limit

## 📅 Planification (Scheduler)

### Production (RECOMMANDÉE)

-   **Sync API LENTE**: Toutes les 2 heures (`sitemap:whise-file-based --sync-only`)
-   **Génération**: Toutes les heures (`sitemap:whise-file-based --generate-only`)
-   **Reset complet**: Hebdomadaire le dimanche à 2h (`sitemap:whise-file-based --reset`)

### Alternative pour rate limit strict

-   **Sync API TRÈS LENTE**: Quotidienne à 3h (`sitemap:whise-slow --sync-only`)
-   **Génération**: Toutes les 2 heures (`sitemap:whise-file-based --generate-only`)

### Development

-   **Workflow complet**: Toutes les 10 minutes (`sitemap:whise-file-based`)

## 📁 Fichiers générés

### Données locales

-   `storage/app/whise_properties.json` - Données des propriétés
-   `storage/app/whise_last_sync.json` - Timestamp de dernière sync

### Sitemaps

-   `public/sitemaps/sitemap-whise-1.xml` - Premier fichier sitemap
-   `public/sitemaps/sitemap-whise-2.xml` - Deuxième fichier sitemap (si >40k URLs)
-   `public/sitemaps/sitemap.xml` - Index principal
-   `public/sitemap.xml` - Symlink vers l'index

## 🔧 Format des données

### Structure du fichier properties.json

```json
[
    {
        "id": "12345",
        "slugs": {
            "fr": "bel-appartement-centre-ville-12345",
            "en": "beautiful-apartment-city-center-12345",
            "nl": "mooi-appartement-stadscentrum-12345"
        },
        "updated_at": "2025-08-30T10:22:00Z",
        "status": "active",
        "purpose_id": 2,
        "title": "Bel appartement centre-ville",
        "sync_time": "2025-08-30T15:30:00Z"
    }
]
```

### URLs générées

-   **Vente FR**: `/fr/nos-biens/a-vendre/{slug}`
-   **Vente EN**: `/en/our-estates/for-sale/{slug}`
-   **Vente NL**: `/nl/onze-eigendommen/te-koop/{slug}`
-   **Location FR**: `/fr/nos-biens/a-louer/{slug}`
-   **Location EN**: `/en/our-estates/for-rent/{slug}`
-   **Location NL**: `/nl/onze-eigendommen/te-huur/{slug}`

## 🎯 Avantages de cette approche

### ✅ Pros

-   **Pas de DB requise** - Tout stocké en fichiers JSON
-   **Rate limit friendly** - Sync découplée de la génération
-   **Rapide** - Génération depuis fichiers locaux
-   **Resilient** - Continue même si l'API Whise est down
-   **Multilingue** - Support natif FR/EN/NL
-   **Scalable** - Chunks automatiques pour gros volumes

### 🔍 Monitoring

#### Logs à surveiller

```bash
# Logs de sync
grep "SyncWhise" storage/logs/laravel.log

# Logs de génération
grep "GenerateSitemap" storage/logs/laravel.log

# Logs du workflow
grep "WhiseWorkflow" storage/logs/laravel.log
```

#### Vérification manuelle

```bash
# Vérifier les fichiers générés
ls -la storage/app/whise_*
ls -la public/sitemaps/sitemap-whise-*

# Taille du fichier de données
du -h storage/app/whise_properties.json

# Nombre de propriétés actives
cat storage/app/whise_properties.json | jq '.[] | select(.status=="active") | .id' | wc -l
```

## 🚨 Dépannage

### Problèmes courants

#### 1. Aucune propriété synchronisée

-   Vérifier les credentials Whise dans `.env`
-   Vérifier les logs d'erreurs API
-   Tester manuellement: `php artisan sitemap:whise-file-based --sync-only`

#### 2. Sitemaps vides

-   Vérifier que le fichier `whise_properties.json` contient des données
-   Vérifier le status des propriétés (doivent être "active")
-   Tester: `php artisan sitemap:whise-file-based --generate-only`

#### 3. Symlink échoue

-   Problème de permissions sur `public/`
-   Le système fallback copie le fichier automatiquement

### Reset complet

```bash
# Nettoyer et recommencer
php artisan sitemap:whise-file-based --reset
```

## 📈 Performance

### Métriques par version

#### Version normale

-   **Sync 600 propriétés**: ~2-3 minutes
-   **Appels API**: 25 propriétés/appel, 1s entre appels
-   **Risque**: Possible rate limit sur gros volumes

#### Version lente ⭐ RECOMMANDÉE

-   **Sync 600 propriétés**: ~8-10 minutes
-   **Appels API**: 10 propriétés/appel, 3s entre appels
-   **Sécurité**: Gestion automatique du rate limit (attente 60s)
-   **Robustesse**: Retry intelligent en cas d'erreur

#### Génération (identique)

-   **Génération 600 propriétés**: ~10-20 secondes
-   **Fichier JSON 600 propriétés**: ~240KB
-   **Sitemap 600 propriétés**: ~390KB (1800 URLs multilingues)

### Optimisations

-   Le cache Whise réduit les appels API redondants
-   Les chunks évitent les timeouts sur gros volumes
-   La queue permet l'exécution en arrière-plan