ok

docs/specs/billeterie.md

@@ -121,3 +121,500 @@ def process_entry(zoo):
 ### Vue Isométrique
 - **File d'attente** : Afficher physiquement les sprites des visiteurs qui attendent devant le guichet.
 - **Portiques** : Animation d'ouverture/fermeture des barrières.
+
+## Personnage contextuel (événements & interaction)
+Voir `guichetiere.md`.
+
+### Affichage
+La guichetière s’affiche lorsque :
+- la billetterie est **actionnée** (clic panneau, upgrade, consultation stats) ;
+- un **événement** d’entrée survient (saturation, file longue, arrivée VIP).
+
+### Déclencheurs (exemples)
+| Event | Condition | Effet UI personnage |
+|---|---|---|
+| `CLICK_BILLETERIE` | clic bâtiment | portrait + synthèse (prix, capacité, file) |
+| `ZOO_FULL` | capacité atteinte | bulle “Zoo complet” + CTA “Améliorer billetterie” |
+| `QUEUE_LONG` | file > seuil | bulle “File longue” + CTA “Voir billetterie” |
+| `VIP_BUS` | arrivée VIP | bulle “Bus VIP” + CTA “Voir entrée” |
+
+### Skins & thèmes
+Uniforme et guichet suivent `theme.md` ; variantes éventuelles via `inventaire_skins.md`.
+
+## Définition
+
+| Champ | Valeur |
+|---|---|
+| Concept | Bâtiment “billeterie” : point unique d’entrée/sortie des visiteurs et point de monétisation “tickets”. |
+| Rôle | Transformer l’attractivité (ville → zoo) en entrées contrôlées (capacité/queue) et en revenus (prix ticket), avec signaux visibles (file, portiques, saturation). |
+| Portée | Une instance fixe sur la carte zoo, connectée au réseau de chemins, agissant comme spawn/despawn visiteurs. |
+| Contrainte | Aucun tracking externe/analytics ; flux et revenus calculés à la volée (lazy update), sans cache/mémorisation ; saturation doit produire message + event (pas silencieux). |
+
+## Fonctions (tableau détaillé)
+
+| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
+|---|---|---|---|---|---|
+| Ouvrir panneau billeterie | clic bâtiment | `ticket_booth_id` | UI stats | montre prix/capacité/queue/revenus jour | Event `CLICK_BILLETERIE` |
+| Calculer demandes d’entrée | tick logique | attractivité, villes, saison | `potential_visitors` | dépend distance ville + attractivité zoo | Event `VISITOR_DEMAND_COMPUTED` |
+| Alimenter file | tick logique | `potential_visitors` | `current_queue_length` | clamp ≥ 0 | Event `QUEUE_UPDATED` |
+| Convertir file en entrées | tick logique | level, queue | `actual_entries` | limité par vitesse guichet et capacité zoo | Event `VISITOR_ENTERED` |
+| Encaisser ticket | entrée | ticket_price | coins + | atomicité par visiteur entré | Event `TICKET_SOLD` |
+| Bloquer si zoo complet | capacité atteinte | `current_visitors` | entrée 0 | déclenche alerte + évaporation file (visiteurs partent) | Event `ZOO_FULL` |
+| Gérer bus VIP | event | multiplicateur | pic entrées | bus si condition (réputation/ville riche) | Event `VIP_BUS` |
+| Mesurer impatience | queue longue | temps attente | départs | si attente > seuil, départs + malus réputation léger | Event `QUEUE_LONG` |
+
+## Icone de base
+
+| Élément | Spécification |
+|---|---|
+| Représentation | Guichet + ticket + portique |
+| Couleur dominante | Bleu/rouge (signalétique), or (coins) |
+| Variantes | `billeterie_lvl_{1..7}_dir_{N,E,S,W}.png`, `icon_ticket_booth.png` |
+| États | `open`, `busy` (queue), `full` (zoo complet), `vip_bus` (arrivée) |
+
+## Interactions (tableau détaillé)
+
+| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
+|---|---|---|---|---|---|
+| Consulter stats | Consultation | - | clic billeterie | panneau stats | - |
+| Upgrader | Action | coins ok | panneau → “Améliorer” | level +1 | `NOT_ENOUGH_COINS` |
+| Voir file | Consultation | file > 0 | survol bâtiment | tooltip “X en attente” | - |
+| Aller à la saturation | Navigation | `ZOO_FULL` | clic notif | focus billeterie | - |
+| Forcer fermeture | Action (option future) | mode maintenance | toggle | entrées stoppées | `MAINTENANCE_REQUIRED` |
+
+## Annexes Techniques
+
+### 1. Données et États (tableau détaillé)
+
+| Donnée / État | Type | Exemple | Source | Contraintes |
+|---|---|---|---|---|
+| `id` | uuid_v4 | `uuid_v4` | DB | - |
+| `type` | string | `ticket_booth` | DB | constant |
+| `level` | int | 3 | DB | 1..7 |
+| `position.x` | int | 1 | DB | grid |
+| `position.y` | int | 1 | DB | grid |
+| `stats.total_entries` | int | 1280 | DB | cumul |
+| `stats.daily_revenue` | int | 420 | DB | reset journalier in-game |
+| `stats.current_queue_length` | int | 18 | DB/calcul | clamp ≥ 0 |
+| `entry_log[].timestamp` | timestamp | - | DB | UTC |
+| `entry_log[].visitor_count` | int | 5 | DB | batch |
+| `entry_log[].revenue` | int | 50 | DB | batch |
+| `iso_x` | int | 120 | DB/calcul | rendu |
+| `iso_y` | int | 88 | DB/calcul | rendu |
+| `z_index` | int | 12088 | calcul | profondeur |
+
+#### Caractéristiques Initiales (tableau détaillé)
+
+| Caractéristique | Valeur initiale | Unité | Notes |
+|---|---:|---|---|
+| Prix ticket (lvl1) | 10 | coins | base |
+| Capacité max (lvl1) | 20 | visiteurs | base |
+| Vitesse guichet (lvl1) | 2 | visiteurs/tick | file |
+| Seuil queue longue | 25 | visiteurs | message + départs |
+
+#### Scores Initiaux (tableau détaillé)
+
+| Score | Valeur initiale | Plage | Impact |
+|---|---:|---|---|
+| Satisfaction d’entrée | 50 | 0..100 | queue longue la baisse |
+| Taux départ file | 0% | 0..100% | impatience |
+
+### 2. Cycles de Vie et Apparition (tableau détaillé)
+
+| Phase | Déclencheur | Entrées | Sorties | Invariants |
+|---|---|---|---|---|
+| Apparition | création zoo | - | bâtiment présent | fixe |
+| Fonctionnement | zoo ouvert | attractivité | entrées | capacité respectée |
+| Saturation | zoo plein | - | entrées stoppées | alerte obligatoire |
+| Upgrade | action joueur | coins | level ↑ | monotone |
+
+#### Conditions d'Apparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Zoo créé | true | est | billeterie placée |
+
+#### Conditions de Disparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| - | - | - | bâtiment persistant |
+
+#### Hérédité (tableau détaillé)
+
+| Élément | Hérité | Règle |
+|---|---|---|
+| Niveau | Oui | persiste |
+| Statistiques | Oui | logs conservés, pas d’analytics |
+
+### 3. Impacts Environnementaux
+
+#### Impact Température (tableau détaillé)
+
+| Condition | Effet billeterie | Notes |
+|---|---|---|
+| Canicule | flux -10% | visiteurs évitent attente au soleil |
+| Froid extrême | flux -15% | sortie plus rapide |
+
+#### Impact Milieu (Biome) (tableau détaillé)
+
+| Biome | Effet | Notes |
+|---|---|---|
+| Proche océan (frais) | impatience - | queue tolérée |
+| Boue autour entrée | impatience + | pénalise |
+
+#### Impact Saisons (tableau détaillé)
+
+| Saison | Effet | Notes |
+|---|---|---|
+| Été | demande +20% | vacances |
+| Hiver | demande -30% | froid |
+
+#### Impact Heure / Jour-Nuit (tableau détaillé)
+
+| Période | Effet | Notes |
+|---|---|---|
+| Matin | pics d’entrée | 9h-12h |
+| Soir | pics de sortie | 17h-19h |
+
+### 4. Impacts Biologiques et Sociaux
+
+#### Impact Reproduction (tableau détaillé)
+
+| Facteur | Effet sur taux | Condition |
+|---|---|---|
+| Bébés visibles | satisfaction entrée +5 | marketing “naissances” |
+
+#### Impact Mort (tableau détaillé)
+
+| Cas | Effet | Condition |
+|---|---|---|
+| Incident visible à l’entrée | flux -40% | pendant 1 jour in-game |
+
+#### Impact Nourriture (tableau détaillé)
+
+| Ressource | Effet | Condition |
+|---|---|---|
+| Stand boisson proche | impatience - | file longue |
+
+#### Impact Attractivité(Visiteurs (tableau détaillé)
+
+| Action/État | Gain | Rayon | Notes |
+|---|---:|---:|---|
+| Entrée fluide | +5 | 8 cases | file courte |
+| File longue | -10 | 8 cases | visiteurs partent |
+
+#### Impact Attractivité Animaux) (tableau détaillé)
+
+| Action/État | Effet animaux | Condition |
+|---|---|---|
+| Foule bruyante | stress + | enclos proche entrée |
+
+#### Impact Valeur (tableau détaillé)
+
+| Facteur | Variation | Condition |
+|---|---:|---|
+| Upgrade billeterie | + | valeur zoo | capacité |
+
+### 5. Impacts Logistiques et Économiques
+
+#### Vitesse (Camion) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Bus VIP | entrées batch | event `VIP_BUS` |
+
+#### Vitesse (Nurserie) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Naissances annoncées | demande + | saison |
+
+#### Vitesse (Accueil) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Nouveaux animaux placés près entrée | intérêt + | visiteurs |
+
+#### Vitesse (Recherche) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Marketing recherche | demande + | upgrade futur |
+
+#### Vitesse (Labo) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Offre rare | pics | annonce |
+
+#### Vitesse (Visite) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Portiques auto | entrées/tick + | level élevé |
+
+#### Dépenses (Billeterie) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Impression tickets | 100 | $/semaine | lore |
+| Maintenance portiques | 20 | coins/semaine | level ≥ 3 |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Signalétique | 10 | coins/semaine | esthétique |
+
+#### Dépenses (Visiteurs) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Perte opportunité | ticket non vendu | coins | queue trop longue |
+
+#### Dépenses (Employés) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Agent accueil | 1500 | $/mois | lore |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Section dupliquée | 1 | coins | conservée |
+
+#### Dépenses (Nurseries) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Vitrine bébés | 50 | coins/semaine | option |
+
+#### Dépenses (Nourriture) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Eau file d’attente | 5 | coins/jour | été |
+
+#### Dépenses (Acceuil des animaux) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Signal “nouvel animal” | 5 | coins | panneau |
+
+#### Dépenses (Camion) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Bus touristes | 25 | coins/event | `VIP_BUS` |
+
+#### Trajet Visiteurs
+
+##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Ville | Billeterie | demande calculée | spawn file |
+
+##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Billeterie | Enclos | plan visite | route via chemins |
+
+##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Enclos | Boutique | faim/soif | détour |
+
+##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Zoo | Billeterie | fin visite | sortie |
+
+### 6. Événements
+
+#### Événements du Jeu  (tableau détaillé)
+
+| Event | Déclencheur | Payload | Effet |
+|---|---|---|---|
+| `TICKET_SOLD` | entrée | price | coins + |
+| `ZOO_FULL` | capacité | current/max | stop entrées |
+| `QUEUE_LONG` | queue > seuil | length | départs + |
+| `VIP_BUS` | event | count | entrées batch |
+
+#### Événements du Carte (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `FOCUS_TICKET_BOOTH` | clic notif | caméra |
+
+#### Événements du Zoo (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_SPAWNED_AT_ENTRY` | entrée | spawn point |
+
+#### Événements du Ville / Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `CITY_FLOW_DISPATCHED` | calcul | demande |
+
+#### Événements du Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_LEAVES_QUEUE` | impatience | départ |
+
+#### Événements du Joueur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `PLAYER_UPGRADES_TICKET_BOOTH` | UI | stats maj |
+
+### 7. Progression
+
+#### Tableau des Upgrades (tableau détaillé)
+
+| Niveau | Coût | Effet | Débloque |
+|---|---:|---|---|
+| 3 | 400 | portiques visibles + vitesse guichet | anim porte |
+| 5 | 1600 | file plus courte (vitesse) | satisfaction + |
+| 7 | 6400 | capacité 300 + prix 35 | “grand hall” |
+
+### 8. Logique et Interfaces 
+
+#### Pseudo-code Impacts (tableau détaillé)
+
+| Fonction | Entrées | Sorties | Notes |
+|---|---|---|---|
+| `getEntrySpeed` | level | int | visiteurs/tick |
+| `computePotentialVisitors` | zoo, villes, saison | int | à la volée |
+| `processEntry` | zoo, booth | int | encaisse + spawn |
+
+#### Messages d'Infos / Alerte (tableau détaillé)
+
+| ID | Niveau | Message | Condition |
+|---|---|---|---|
+| `ZOO_FULL` | Alerte | "Le zoo est complet." | capacité atteinte |
+| `QUEUE_LONG` | Warning | "La file d'attente est trop longue." | queue > seuil |
+| `VIP_BUS` | Info | "Un bus de touristes arrive." | event |
+
+## Annexes UX/UI 
+
+### 1. Expérience Utilisateur (UX)
+
+#### Description UX (tableau détaillé)
+
+| Parcours | But | Friction | Réduction clics |
+|---|---|---|---|
+| Voir revenus | décider upgrade | stats dispersées | panneau unique billeterie |
+| Réagir à saturation | éviter pertes | notif | clic notif → focus |
+
+#### Description UI (tableau détaillé)
+
+| Composant | Contenu | États |
+|---|---|---|
+| Panneau billeterie | prix/capacité/revenus | normal/full |
+| File visuelle | sprites visiteurs | courte/longue |
+| Badge bus VIP | icône bus | visible |
+
+#### Emplacement (tableau détaillé)
+
+| Zone UI | Position | Notes |
+|---|---|---|
+| Carte zoo | entrée | file visible |
+| HUD | compteur coins | feedback pièces |
+
+#### Intégration (tableau détaillé)
+
+| Intégration | Contrat | Notes |
+|---|---|---|
+| `visiteur.md` | spawn/despawn | flux |
+| `ville.md` | demande | distance |
+
+#### Navigation (tableau détaillé)
+
+| Action | Chemin | Résultat |
+|---|---|---|
+| Ouvrir stats | clic bâtiment | panneau |
+| Upgrader | panneau → bouton | level ↑ |
+| Focus | clic notif | caméra |
+
+#### Événements (tableau détaillé)
+
+| Event UI | Déclencheur | Effet |
+|---|---|---|
+| `CLICK_BILLETERIE` | clic | ouvre |
+| `CLICK_UPGRADE_TICKET_BOOTH` | bouton | upgrade |
+
+#### Assets Skinables
+
+##### Musiques (tableau détaillé)
+
+| Asset | Usage | Durée | Notes |
+|---|---|---:|---|
+| `ticket_booth_crowd_loop.mp3` | proximité entrée | loop | discret |
+
+##### Sons (tableau détaillé)
+
+| Asset | Usage | Volume |
+|---|---|---|
+| `gate_open.mp3` | portiques | bas |
+| `coin_jingle.mp3` | ticket vendu | bas |
+| `ui_denied.mp3` | zoo plein | moyen |
+
+##### Graphiques (tableau détaillé)
+
+| Asset | Usage | Contraintes |
+|---|---|---|
+| `ticket_booth_ui_panel.png` | panneau | scalable |
+| `queue_indicator.png` | badge | lisible |
+| `vip_bus_icon.png` | bus | contraste |
+
+##### Images (tableau détaillé)
+
+| Asset | Usage |
+|---|---|
+| `billeterie_lvl1.png` | bâtiment |
+| `billeterie_lvl7.png` | bâtiment |
+
+##### Vidéos (tableau détaillé)
+
+| Asset | Usage | Durée |
+|---|---|---:|
+| `ticket_gate_cycle.webm` | portiques | 1.0s |
+
+##### Animations (tableau détaillé)
+
+| Animation | Déclencheur | Notes |
+|---|---|---|
+| pièces qui volent | ticket vendu | 0.6s |
+| bounce badge | queue longue | 0.4s |
+
+##### Couleurs (tableau détaillé)
+
+| Token | Valeur | Usage |
+|---|---|---|
+| `ticket_blue` | #1976D2 | signalétique |
+| `ticket_gold` | #D4AF37 | revenus |
+| `ticket_alert_red` | #D32F2F | saturation |
+
+##### Textes (tableau détaillé)
+
+| Clé | FR | EN |
+|---|---|---|
+| `ticket_booth.title` | Billeterie | Ticket booth |
+| `ticket_booth.capacity` | Capacité | Capacity |
+| `ticket_booth.queue_long` | File trop longue. | Queue too long. |
+
+##### Formes (tableau détaillé)
+
+| Élément | Forme | Notes |
+|---|---|---|
+| Panneau | rectangle arrondi | lisible |
+| Badge | rond | constant |