builazoo/docs/specs/vip.md

# VIP

## 1. Définition
Statut premium pour les joueurs, généralement obtenu par abonnement ou achat in-app. Le statut VIP confère des avantages de confort et de cosmétique, sans déséquilibrer le gameplay compétitif (Pay-to-Fast ou Pay-to-Cool, pas Pay-to-Win).

## 2. Fonctions
*   **Conservation des Thèmes :** Avantage majeur permettant de garder définitivement les thèmes et skins des passes saisonniers, même après la fin de la saison.
*   **Bonus Passifs :** Peut inclure des bonus légers d'XP ou de pièces.
*   **Prestige :** Badge ou couleur de pseudo distinctif.

## 3. Icone
*   **Représentation :** Couronne ou Diamant.
*   **Couleur dominante :** Or scintillant ou Violet royal.

## 4. Interactions
*   **Achat/Abonnement :** Via la boutique ou le menu profil.
*   **Affichage :** Badge visible à côté de l'avatar et du pseudo.

## 5. Annexes Techniques

### Données (JSON)
```json
{
  "status_id": "vip_subscription",
  "is_active": true,
  "expiry_date": "2026-12-31T23:59:59",
  "benefits": {
    "keep_seasonal_themes": true,
    "xp_multiplier": 1.1,
    "daily_coin_bonus": 50
  }
}
```

### Règles Métier
*   Si le statut VIP expire, le joueur perd l'accès aux thèmes saisonniers passés qu'il avait "sauvegardés", sauf s'il se réabonne (règle à définir : perte définitive ou suspension ? -> Suspension par défaut pour encourager le réabonnement).
*   Le statut VIP s'applique à tout le compte joueur.

## 6. Annexes UX/UI
*   **Badge VIP :** Petite icône couronne à côté du pseudo partout dans l'interface.
*   **Interface Boutique :** Section dédiée "Devenir VIP" avec mise en avant des avantages (surtout la conservation des thèmes).
*   **Feedback :** Effet visuel doré lors de la récupération de récompenses.


# Annexes UX/UI

## 0. Direction Artistique & Vue
*   **Vue** : Isométrique (2.5D).
*   **Style** : Coloré, vivant, détails foisonnants (Réf: IMG_20260303_170253.jpg).
*   **Sprites** : 4 directions.
*   **Interactions** :
    *   **Sélection** : Cliquer sur la base de l'élément (ou son sprite principal) pour le sélectionner.
    *   **Feedback** : Surbrillance (outline blanc/jaune) au survol de la souris.


## Définition

| Champ | Valeur |
|---|---|
| Concept | Statut premium (VIP) lié au compte joueur. |
| Rôle | Déverrouiller des avantages de confort + cosmétiques, notamment la conservation des thèmes/passes tant que VIP actif. |
| Portée | Compte (tous zoos / toutes sessions). |
| Contrainte | Pas de mécanisme de cache/mémorisation côté app : l’état VIP est lu comme un état courant (source de vérité). |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Activer VIP | achat/abonnement | moyen de paiement, plan | `is_active=true`, `expiry_date` | Activation atomique, idempotente sur transaction | Event `VIP_ACTIVATED` |
| Expirer VIP | temps | `expiry_date` | `is_active=false` | Expiration automatique au tick serveur / lazy update au login | Event `VIP_EXPIRED` |
| Conserver thèmes passés | check d’accès contenu | `keep_seasonal_themes` | autorisation | Règle retenue : **suspension** des accès si VIP inactif (pas de perte définitive). | Event `VIP_CONTENT_ACCESS_CHECKED` |
| Bonus passifs | tick journalier | plan | coins/xp | Bonus plafonnés (anti P2W), visibles dans UI | Event `VIP_DAILY_BONUS_GRANTED` |
| Badge prestige | render UI | `is_active` | badge | Affiché partout pseudo/avatar | Event `VIP_BADGE_RENDER` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | Couronne / diamant |
| Couleur dominante | Or / violet |
| Variantes | `icon_vip_crown.png`, `icon_vip_diamond.png` |
| États | Badge “actif” (or), “expiré” (gris), “renouvellement” (horloge) |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Voir offre VIP | Consultation | - | Boutique/Profil → VIP | page détail | - |
| Acheter VIP | Action | paiement ok | Clic “Devenir VIP” → confirmer | VIP actif | `PAYMENT_FAILED`, `NETWORK_ERROR` |
| Renouveler | Action | VIP actif ou expiré | “Renouveler” | `expiry_date` prolongée | `PAYMENT_FAILED` |
| Voir contenu conservé | Consultation | VIP actif | Profil → “Mes thèmes” | liste | `VIP_REQUIRED` |
| Réactiver après expiration | Action | VIP expiré | “Réactiver” | accès restauré (suspension levée) | `PAYMENT_FAILED` |

## Annexes Techniques

### 1. Données et États (tableau détaillé)

| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `status_id` | string | `vip_subscription` | DB | constant |
| `is_active` | boolean | true | DB | dérivé de `expiry_date` |
| `expiry_date` | timestamp | `2026-12-31T23:59:59Z` | DB | UTC |
| `plan_id` | string | `vip_monthly` | DB | enum plans |
| `benefits.keep_seasonal_themes` | boolean | true | config | gating contenu |
| `benefits.xp_multiplier` | float | 1.1 | config | cap 1.2 |
| `benefits.daily_coin_bonus` | int | 50 | config | cap 200 |
| `timestamps.created_at` | timestamp | - | DB | audit |
| `timestamps.updated_at` | timestamp | - | DB | audit |

#### Caractéristiques Initiales (tableau détaillé)

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| VIP actif | false | bool | par défaut |
| Multiplicateur XP | 1.0 | coef | sans VIP |
| Bonus coins/jour | 0 | coins | sans VIP |
| Conservation thèmes | false | bool | gating |

#### Scores Initiaux (tableau détaillé)

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Jours VIP cumulés | 0 | 0..∞ | UI historique (pas d’analytics) |
| Bonus total distribués | 0 | 0..∞ | transparence UI |

### 2. Cycles de Vie et Apparition (tableau détaillé)

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Apparition | création compte | - | VIP inactif | - |
| Activation | achat | plan | VIP actif | atomicité |
| Renouvellement | achat | plan | expiry prolongée | monotone |
| Expiration | temps | date | VIP inactif | suspension contenu |

#### Conditions d'Apparition (tableau détaillé)

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Compte créé | true | est | entrée VIP créée (inactive) |

#### Conditions de Disparition (tableau détaillé)

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Compte supprimé | true | est | VIP supprimé |

#### Hérédité (tableau détaillé)

| Élément | Hérité | Règle |
|---|---|---|
| Historique VIP | Oui | persiste |
| Contenu “conservé” | Oui | reste possédé mais **gated** si VIP off |

### 3. Impacts Environnementaux

#### Impact Température (tableau détaillé)

| Condition | Effet VIP | Notes |
|---|---|---|
| - | aucun | statut méta |

#### Impact Milieu (Biome) (tableau détaillé)

| Biome | Effet VIP | Notes |
|---|---|---|
| - | aucun | - |

#### Impact Saisons (tableau détaillé)

| Saison | Effet VIP | Notes |
|---|---|---|
| Saison active | contenu pass dispo | lié au passe |

#### Impact Heure / Jour-Nuit (tableau détaillé)

| Période | Effet VIP | Notes |
|---|---|---|
| Jour | bonus journalier | horaire fixe serveur |

### 4. Impacts Biologiques et Sociaux

#### Impact Reproduction (tableau détaillé)

| Facteur | Effet sur taux | Condition |
|---|---|---|
| - | aucun | VIP n’affecte pas reproduction |

#### Impact Mort (tableau détaillé)

| Cas | Effet | Condition |
|---|---|---|
| - | aucun | - |

#### Impact Nourriture (tableau détaillé)

| Ressource | Effet | Condition |
|---|---|---|
| - | aucun | - |

#### Impact Attractivité(Visiteurs (tableau détaillé)

| Action/État | Gain | Rayon | Notes |
|---|---:|---:|---|
| Thèmes conservés | + (cosmétique) | zoo | impact via esthétique |

#### Impact Attractivité Animaux) (tableau détaillé)

| Action/État | Effet animaux | Condition |
|---|---|---|
| - | aucun direct | - |

#### Impact Valeur (tableau détaillé)

| Facteur | Variation | Condition |
|---|---:|---|
| Prestige VIP | + | classement/présentation |

### 5. Impacts Logistiques et Économiques

#### Vitesse (Camion) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| - | aucun | - |

#### Vitesse (Nurserie) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| - | aucun | - |

#### Vitesse (Accueil) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| - | aucun | - |

#### Vitesse (Recherche) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| XP multiplier | xp × 1.1 | VIP actif |

#### Vitesse (Labo) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| - | aucun | - |

#### Vitesse (Visite) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| Temps visite | + léger | confort (option) |

#### Dépenses (Billeterie) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

#### Dépenses (Boutiques) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Abonnement VIP | variable | coins/€ | boutique |

#### Dépenses (Visiteurs) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

#### Dépenses (Employés) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

#### Dépenses (Boutiques) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Section dupliquée | 0 | - | conservée |

#### Dépenses (Nurseries) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

#### Dépenses (Nourriture) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

#### Dépenses (Acceuil des animaux) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

#### Dépenses (Camion) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

#### Trajet Visiteurs

##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Ville | Zoo | réputation | VIP indirect (via thèmes/esthétique) |

##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| - | - | - | - |

##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| - | - | - | - |

##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| - | - | - | - |

### 6. Événements

#### Événements du Jeu  (tableau détaillé)

| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `VIP_ACTIVATED` | paiement ok | plan_id | active |
| `VIP_EXPIRED` | date | - | suspend |

#### Événements du Carte (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|
| `VIP_BADGE_RENDER` | UI | badge |

#### Événements du Zoo (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|
| `VIP_CONTENT_ACCESS_CHECKED` | apply theme | allow/deny |

#### Événements du Ville / Visiteur (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|
| - | - | - |

#### Événements du Visiteur (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|
| - | - | - |

#### Événements du Joueur (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|
| `VIP_DAILY_BONUS_GRANTED` | reset journalier | coins/xp |

### 7. Progression

#### Tableau des Upgrades (tableau détaillé)

| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| 1 | variable | VIP actif | badge + conservation gating |

### 8. Logique et Interfaces 

#### Pseudo-code Impacts (tableau détaillé)

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `isVipActive` | now, expiry_date | bool | source de vérité |
| `canUseTheme` | vip, theme | allow | suspension si VIP off |

#### Messages d'Infos / Alerte (tableau détaillé)

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `VIP_REQUIRED` | Warning | "VIP requis." | accès contenu gated |
| `VIP_EXPIRED` | Info | "VIP expiré." | expiration |

## Annexes UX/UI 

### 1. Expérience Utilisateur (UX)

#### Description UX (tableau détaillé)

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Devenir VIP | conserver thèmes | paiement | bouton direct profil + boutique |
| Réactiver | restaurer accès | paiement | deep-link depuis contenu locké |

#### Description UI (tableau détaillé)

| Composant | Contenu | États |
|---|---|---|
| Page VIP | bénéfices, prix, CTA | active/expired |
| Badge VIP | couronne | visible partout |

#### Emplacement (tableau détaillé)

| Zone UI | Position | Notes |
|---|---|---|
| Profil | en-tête | badge |
| Boutique | section VIP | CTA |

#### Intégration (tableau détaillé)

| Intégration | Contrat | Notes |
|---|---|---|
| Skins/thèmes | gating | suspension |
| Passe saisonnier | conservation | VIP |

#### Navigation (tableau détaillé)

| Action | Chemin | Résultat |
|---|---|---|
| Ouvrir VIP | profil/boutique | page |
| Acheter | CTA | paiement |

#### Événements (tableau détaillé)

| Event UI | Déclencheur | Effet |
|---|---|---|
| `OPEN_VIP_PAGE` | clic | page |
| `CLICK_BUY_VIP` | CTA | paiement |

#### Assets Skinables

##### Musiques (tableau détaillé)

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `vip_page_loop.mp3` | page VIP | loop | discret |

##### Sons (tableau détaillé)

| Asset | Usage | Volume |
|---|---|---|
| `ui_purchase_success.mp3` | achat ok | moyen |
| `ui_purchase_fail.mp3` | achat fail | moyen |

##### Graphiques (tableau détaillé)

| Asset | Usage | Contraintes |
|---|---|---|
| `vip_badge_crown.png` | badge | scalable |
| `vip_gold_glow.png` | FX | overlay |

##### Images (tableau détaillé)

| Asset | Usage |
|---|---|
| `vip_banner.png` | hero |
| `vip_benefit_cards.png` | cartes |

##### Vidéos (tableau détaillé)

| Asset | Usage | Durée |
|---|---|---:|
| `vip_glow.webm` | succès | 1.0s |

##### Animations (tableau détaillé)

| Animation | Déclencheur | Notes |
|---|---|---|
| glow doré | activation | 0.8s |
| badge pulse | reward | 0.6s |

##### Couleurs (tableau détaillé)

| Token | Valeur | Usage |
|---|---|---|
| `vip_gold` | #D4AF37 | UI |
| `vip_purple` | #6A1B9A | accent |

##### Textes (tableau détaillé)

| Clé | FR | EN |
|---|---|---|
| `vip.become` | Devenir VIP | Become VIP |
| `vip.renew` | Renouveler | Renew |

##### Formes (tableau détaillé)

| Élément | Forme | Notes |
|---|---|---|
| Cartes bénéfices | rectangles arrondis | lisibles |
| Badge | rond | constant |