# 🚀 Optimisations POI - Guide de Validation

## ✅ Statut: TOUTES LES OPTIMISATIONS IMPLÉMENTÉES

**Date:** 24 novembre 2025  
**Type-check:** ✅ Passing (1.8s)  
**Fichiers modifiés:** 5  
**Fichiers créés:** 2

---

## 📋 Checklist de Validation

### 1️⃣ Cache Géographique (Geohash)

**Fichier:** `apps/api/src/modules/ai/ai.controller.ts`  
**Status:** ✅ Implémenté

**Comment vérifier:**
```bash
# Tester cache hit avec coordonnées proches
curl -X POST http://localhost:3000/api/ai/suggest-pois \
  -H "Content-Type: application/json" \
  -d '{
    "location": {"lat": 43.7656, "lng": 4.2464},
    "categories": ["restaurant"],
    "radiusKm": 50
  }'

# Même requête avec coordonnées légèrement différentes (dans les 600m)
curl -X POST http://localhost:3000/api/ai/suggest-pois \
  -H "Content-Type: application/json" \
  -d '{
    "location": {"lat": 43.7660, "lng": 4.2470},
    "categories": ["restaurant"],
    "radiusKm": 50
  }'
```

**Attendu:** 2ème requête devrait retourner `"cached": true` en <100ms

**Logs à surveiller:**
```
[AIController] POI suggestion cache hit { cacheKey: 'ai:poi:geo:spey8u:r50:restaurant' }
```

---

### 2️⃣ Streaming SSE

**Fichier:** `apps/api/src/modules/ai/ai.routes.ts` + `ai.controller.ts`  
**Status:** ✅ Implémenté

**Comment vérifier:**
```bash
# Tester endpoint streaming
curl -N http://localhost:3000/api/ai/suggest-pois/stream \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "location": {"lat": 48.8566, "lng": 2.3522},
    "categories": ["restaurant"],
    "radiusKm": 10
  }'
```

**Attendu:** Stream de messages progressifs
```
data: {"type":"progress","message":"Recherche de suggestions...","percent":10}

data: {"type":"complete","pois":[...],"percent":100}
```

**Intégration frontend nécessaire:**
```typescript
// apps/web/src/modules/ai/services/aiService.ts
const eventSource = new EventSource('/api/ai/suggest-pois/stream')
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data)
  switch (data.type) {
    case 'progress':
      showProgress(data.message, data.percent)
      break
    case 'complete':
      displayPOIs(data.pois)
      eventSource.close()
      break
  }
}
```

---

### 3️⃣ Cache Warmer (Routes Populaires)

**Fichier:** `apps/api/src/modules/ai/cache-warmer.ts`  
**Status:** ✅ Implémenté + Intégré au serveur

**Comment vérifier:**
```bash
# Démarrer le serveur
pnpm dev:api

# Chercher dans les logs
grep "Scheduling cache warming" logs/api.log
# Attendu: "Scheduling cache warming for 3:00 AM daily"

# Tester manuellement une route populaire
curl -X POST http://localhost:3000/api/ai/suggest-pois \
  -H "Content-Type: application/json" \
  -d '{
    "location": {"lat": 47.2012, "lng": 3.0994},
    "categories": ["restaurant", "viewpoint", "castle"],
    "radiusKm": 50
  }'
```

**Routes pré-cachées (10 routes):**
- Paris → Lyon
- Lyon → Marseille
- Marseille → Nice
- Strasbourg → Paris
- Nantes → Bordeaux
- Lunel → Orange
- Bordeaux → Toulouse
- Rennes → Brest
- Angers → Tours
- Grenoble → Valence

**Attendu:** Ces routes devraient répondre en <100ms avec `"cached": true`

**Désactiver si nécessaire:**
```bash
export ENABLE_CACHE_WARMING=false
pnpm dev:api
```

---

### 4️⃣ Vérifications Async (Quick Response)

**Fichier:** `apps/api/src/modules/ai/poi.processor.ts`  
**Status:** ✅ Implémenté

**Comment vérifier:**
```bash
# Mode activé par défaut
export ENABLE_QUICK_RESPONSE=true
pnpm dev:api

# Tester une recherche
curl -X POST http://localhost:3000/api/ai/suggest-pois \
  -H "Content-Type: application/json" \
  -d '{
    "location": {"lat": 45.7640, "lng": 4.8357},
    "categories": ["museum"],
    "radiusKm": 20
  }'
```

**Attendu:**
- Réponse rapide (~5s au lieu de 10s)
- Metadata contient `"quickResponse": true, "verified": false`
- Cache se met à jour en arrière-plan avec POIs vérifiés

**Logs à surveiller:**
```
[POIProcessor] Quick response sent (verification in background)
[POIProcessor] Background verification skipped (already verified)
[POIProcessor] Cache updated with verified POIs
```

**Désactiver si problèmes:**
```bash
export ENABLE_QUICK_RESPONSE=false
```

---

### 5️⃣ Batch Verification (Google Places)

**Fichier:** `apps/api/src/services/google-places.service.ts`  
**Status:** ✅ Implémenté

**Comment vérifier:**
```bash
# Observer les logs avec verification batching
pnpm dev:api | grep "Processing batch"

# Lancer plusieurs requêtes POI simultanées
for i in {1..5}; do
  curl -X POST http://localhost:3000/api/ai/suggest-pois \
    -H "Content-Type: application/json" \
    -d "{...}" &
done
```

**Attendu:**
```
[GooglePlacesService] Processing batch of 10 verifications
```

Au lieu de:
```
[GooglePlacesService] Verifying place: Château de Versailles
[GooglePlacesService] Verifying place: Musée du Louvre
... (15 requêtes individuelles)
```

**Configuration:**
- Debounce delay: 100ms
- Batch size: 10 requêtes max par batch

---

## 🧪 Tests d'Intégration

### Test Complet du Flow

```bash
#!/bin/bash
# test-poi-optimizations.sh

echo "🧪 Test 1: Cache géographique"
time curl -X POST http://localhost:3000/api/ai/suggest-pois \
  -H "Content-Type: application/json" \
  -d '{"location":{"lat":48.8566,"lng":2.3522},"categories":["restaurant"],"radiusKm":10}'

echo "\n🧪 Test 2: Même zone (cache hit attendu)"
time curl -X POST http://localhost:3000/api/ai/suggest-pois \
  -H "Content-Type: application/json" \
  -d '{"location":{"lat":48.8570,"lng":2.3525},"categories":["restaurant"],"radiusKm":10}'

echo "\n🧪 Test 3: Streaming SSE"
curl -N http://localhost:3000/api/ai/suggest-pois/stream \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"location":{"lat":43.7656,"lng":4.2464},"categories":["viewpoint"],"radiusKm":25}'

echo "\n✅ Tests terminés"
```

---

## 📊 Métriques Attendues

### Avant Optimisations
| Scénario | Temps | Cache Hit Rate | API Calls |
|----------|-------|----------------|-----------|
| Cache MISS | 15-25s | 15% | 45 (15 POIs × 3 sources) |
| Cache HIT | 50-200ms | 15% | 0 |
| Routes populaires | 15-25s | 0% | 45 |

### Après Optimisations
| Scénario | Temps | Cache Hit Rate | API Calls |
|----------|-------|----------------|-----------|
| Cache MISS | 5-10s | 70% | ~5 (batching) |
| Cache HIT | 50-100ms | 70% | 0 |
| Routes populaires | 50ms | 100% | 0 |

---

## 🐛 Troubleshooting

### Problème: Cache ne fonctionne pas

**Vérifier Redis:**
```bash
redis-cli ping
# Attendu: PONG

redis-cli KEYS "ai:poi:geo:*"
# Devrait lister les clés de cache
```

**Vérifier les clés de cache:**
```typescript
// Dans les logs
grep "Cache key:" logs/api.log
// Exemple: ai:poi:geo:spey8u:r50:restaurant
```

### Problème: Streaming SSE ne fonctionne pas

**Vérifier l'endpoint:**
```bash
curl -v http://localhost:3000/api/ai/suggest-pois/stream

# Chercher:
# Content-Type: text/event-stream
# Connection: keep-alive
```

### Problème: Cache warmer n'est pas actif

**Vérifier les logs au démarrage:**
```bash
grep "Scheduling cache warming" logs/api.log
```

**Forcer execution immédiate (test):**
```typescript
// Dans apps/api/src/server.ts (temporaire)
import { warmCache } from './modules/ai/cache-warmer.js'
await warmCache() // Force immediate execution
```

### Problème: Vérifications toujours lentes

**Vérifier ENABLE_QUICK_RESPONSE:**
```bash
echo $ENABLE_QUICK_RESPONSE
# Devrait être vide (true par défaut) ou "true"
```

**Logs attendus:**
```
[POIProcessor] Quick response sent (verification in background)
```

---

## 🔧 Variables d'Environnement

```bash
# Cache warmer
ENABLE_CACHE_WARMING=true          # Activer cache warmer (défaut: true)

# Quick response mode
ENABLE_QUICK_RESPONSE=true         # Retourner POIs non-vérifiés (défaut: true)

# Redis (requis)
REDIS_HOST=localhost
REDIS_PORT=6379

# Google Places (requis pour vérifications)
GOOGLE_PLACES_API_KEY=AIzaSy...
```

---

## 📈 Monitoring Production

### Requêtes à surveiller

```bash
# Hit rate du cache géographique
redis-cli INFO stats | grep keyspace_hits

# Nombre de clés POI
redis-cli DBSIZE

# Clés POI géographiques
redis-cli KEYS "ai:poi:geo:*" | wc -l
```

### Logs importants

```bash
# Cache hits
grep "Cache HIT" logs/api.log | wc -l

# Cache misses
grep "Cache MISS" logs/api.log | wc -l

# Background verifications
grep "Background verification" logs/api.log

# Batch processing
grep "Processing batch" logs/api.log
```

---

## ✅ Validation Finale

- [x] Type-check passing
- [x] Imports corrigés (geohash depuis @my-roadtrip/utils)
- [x] Cache warmer intégré au server.ts
- [x] Endpoint streaming SSE ajouté aux routes
- [x] Quick response mode configuré
- [x] Batch verification implémenté
- [x] Documentation complète

**Prêt pour tests en dev !** 🚀
