# Stratégie des Tiers : Gratuit vs Payant

## 🎯 Objectif
Maximiser l'utilisation des **sources gratuites** pour les utilisateurs FREE, tout en offrant des features premium via APIs payantes.

---

## 📊 Tiers Utilisateurs

| Tier | Plan Stripe | Coût mensuel | Sources POI | Modèles AI | Vérification |
|------|-------------|--------------|-------------|------------|--------------|
| **FREE** | `free` | 0€ | **Overpass** (gratuit) | ❌ Aucun | **Overpass** |
| **STANDARD** | `standard` | 5€ | **Overpass + Mapbox** (gratuits) | gpt-4o-mini | **Mapbox + Overpass** |
| **PREMIUM** | `premium` | 15€ | **OpenAI** (payant) | gpt-4o-mini, gpt-4o | **Google + Mapbox + Overpass** |
| **PRO** | `pro` | 30€ | **OpenAI + Overpass** | Tous modèles | **Google + Mapbox + Overpass** |

---

## 🔧 Sources de Données

### POI Suggestions

| Source | Coût | Utilisation | Qualité |
|--------|------|-------------|---------|
| **Overpass (OSM)** | ✅ GRATUIT illimité | FREE, STANDARD, PRO | 70% - Bon pour monuments, parcs, tourisme |
| **Mapbox Places** | ✅ GRATUIT (100k/mois) | STANDARD fallback | 75% - Bon pour commerces, restaurants |
| **OpenAI GPT-4o-mini** | 💰 $0.10/1k requêtes | PREMIUM, PRO | 85% - Excellent contexte |
| **OpenAI GPT-4o** | 💰 $0.30/1k requêtes | PREMIUM, PRO | 90% - Top qualité |

### Vérification POI

| Source | Coût | Utilisation | Fiabilité |
|--------|------|-------------|-----------|
| **Overpass** | ✅ GRATUIT | Tous tiers | 80% - Données OSM |
| **Mapbox Geocoding** | ✅ GRATUIT (100k/mois) | STANDARD+, PRO | 85% - Bon geocoding |
| **Google Places** | 💰 $2.83/1k requêtes | PREMIUM, PRO | 95% - Meilleure source |

---

## 💡 Stratégie d'Implémentation

### Backend (poi.processor.ts)

```typescript
function selectSourcesForTier(userTier: 'free' | 'standard' | 'premium' | 'pro') {
  switch (userTier) {
    case 'free':
      return {
        suggestionSources: ['overpass'],        // 100% gratuit
        verificationSources: ['overpass']       // 100% gratuit
      }
    
    case 'standard':
      return {
        suggestionSources: ['overpass', 'mapbox'],   // Gratuits
        verificationSources: ['mapbox', 'overpass']  // Gratuits
      }
    
    case 'premium':
      return {
        suggestionSources: ['openai'],               // Payant mais qualité
        verificationSources: ['google', 'mapbox', 'overpass']  // Triple check
      }
    
    case 'pro':
      return {
        suggestionSources: ['openai', 'overpass'],   // Hybride
        verificationSources: ['google', 'mapbox', 'overpass']  // Tout
      }
  }
}
```

### Frontend (RouteAISearch.vue)

- **FREE** : Banner informatif "Mode gratuit : OpenStreetMap"
- **STANDARD+** : Sélecteur de modèle selon tier

---

## 📈 Coûts Estimés

### Par Utilisateur FREE (0€/mois)
- POI suggestions : **0€** (Overpass)
- Vérifications : **0€** (Overpass)
- **Total : 0€**

### Par Utilisateur STANDARD (5€/mois)
- POI suggestions : **0€** (Overpass + Mapbox gratuits)
- Vérifications : **0€** (Mapbox + Overpass gratuits)
- **Total : 0€ en coûts API** (marge 100%)

### Par Utilisateur PREMIUM (15€/mois)
- POI suggestions : ~**1€** (OpenAI GPT-4o-mini, 10 requêtes)
- Vérifications : ~**2€** (Google Places, 7 requêtes)
- **Total : ~3€ en coûts API** (marge 80%)

### Par Utilisateur PRO (30€/mois)
- POI suggestions : ~**3€** (OpenAI GPT-4o + Overpass, 10 requêtes)
- Vérifications : ~**5€** (Google Places, 17 requêtes)
- **Total : ~8€ en coûts API** (marge 73%)

---

## ✅ Avantages de cette Stratégie

1. **FREE reste 100% gratuit** (pas de coûts API)
2. **STANDARD génère de la marge pure** (5€ sans coûts API)
3. **PREMIUM/PRO ont une excellente marge** (73-80%)
4. **Qualité croissante** selon le tier
5. **Évolutif** (limites Mapbox : 100k/mois = 3333 users STANDARD)

---

## 🚀 Optimisations Futures

1. **Cache Redis** : TTL 1h pour réduire appels OpenAI
2. **Batch verification** : Vérifier 5 POIs d'un coup
3. **Smart fallback** : Si Mapbox limite atteinte → Overpass
4. **Rate limiting** : FREE = 5 req/jour, STANDARD = 20/jour, PREMIUM = illimité

---

## 📝 Status Actuel

✅ **Implémenté** :
- Tier-based source selection (poi.processor.ts)
- Frontend banner FREE (RouteAISearch.vue)
- Model selector pour STANDARD+ (RouteAISearch.vue)
- Type-check passing (6/6 packages)

⏳ **À tester** :
- Vérifier que FREE utilise bien Overpass uniquement
- Confirmer que STANDARD n'appelle pas OpenAI
- Valider les coûts en production

---

## 🎓 Documentation Complète

- **Architecture** : `docs/ARCHITECTURE.md`
- **API Reference** : `docs/REFERENCE.md`
- **Overpass Integration** : `OVERPASS_INTEGRATION_COMPLETE.md`
- **Tier POI System** : `TIER_BASED_POI_SYSTEM_COMPLETE.md`
