ok

docs/specs/boutique.md

@@ -144,6 +144,25 @@ function processShop(shop, visitors):
 | `SHOP_FULL` | Warning | "Boutique pleine ! Des clients partent." |
 | `SHOP_PROMO` | Info | "Soldes lancées ! Affluence +20%." |
 
+## Personnage contextuel (événements & interaction)
+Voir `vendeur.md`.
+
+### Affichage
+Le vendeur s’affiche lorsque :
+- la boutique est **actionnée** (clic panneau stats, upgrade, skin de boutique) ;
+- un **événement** de boutique survient (vente, surcharge, promo).
+
+### Déclencheurs (exemples)
+| Event | Condition | Effet UI personnage |
+|---|---|---|
+| `OPEN_SHOP` | clic boutique | portrait + stats + CTA |
+| `SALE_MADE` | vente | feedback “caisse” + pièce/FX |
+| `SHOP_FULL` | capacité atteinte | bulle “Surcharge” + CTA “Améliorer / Ajouter boutique” |
+| `SHOP_PROMO` | promo active | bulle “Promo” + détails (si module) |
+
+### Skins & thèmes
+Uniforme et comptoir suivent `theme.md`, avec skins de boutique via `inventaire_skins.md`.
+
 # Annexes UX/UI
 
 ## 0. Direction Artistique & Vue
@@ -213,3 +232,483 @@ function processShop(shop, visitors):
 - **Couleurs** : Bleu (Blueprint).
 - **Textes** : "Construction".
 - **Formes** : Grille de placement.
+
+## Définition
+
+| Champ | Valeur |
+|---|---|
+| Concept | Bâtiment “boutique” : point de vente in-zoo (souvenirs/food/boissons) qui convertit les besoins des visiteurs en revenus. |
+| Rôle | Augmenter la rétention et la satisfaction via la résolution des besoins (faim/soif/cadeau), et créer des micro-flux (file, service, rupture). |
+| Portée | Une instance de bâtiment sur carte zoo, avec paramètres (capacité, vitesse service, catalogue, skin). |
+| Contrainte | Pas d’analytics ; revenus calculés à la volée à partir des interactions visiteurs ; pas de fallback silencieux (rupture/plein => message + event). |
+
+## Fonctions (tableau détaillé)
+
+| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
+|---|---|---|---|---|---|
+| Construire boutique | mode build | coord, type boutique | bâtiment créé | case vide requise | Event `BUILD_SHOP` |
+| Ouvrir stats | clic bâtiment | `shop_id` | UI stats | revenus totaux + clients | Event `OPEN_SHOP` |
+| Attirer visiteurs | besoin/curiosité | visitor, rayon | target set | poids pathfinding élevé si besoin > seuil | Event `VISITOR_TARGETS_SHOP` |
+| Servir visiteur | arrivée en file | visitor, stock | revenue + satisfaction | service limité par capacité + vitesse | Event `SALE_MADE` |
+| Gérer file | dépassement capacité | queue length | impatience | si queue > seuil -> départ + malus | Event `SHOP_FULL` |
+| Adapter produits au climat | temp/saison | météo, saison | mod ventes | canicule: eau + ; froid: chocolat + | Event `SHOP_DEMAND_MOD_CHANGED` |
+| Appliquer skin biome | skin, biome | ids | bonus | +10% ventes si match | Event `SHOP_THEME_MATCH_BONUS` |
+| Réapprovisionner | tick économique | CA, ratio | stock + coût | coût = 10% du CA | Event `SHOP_RESTOCKED` |
+| Rupture | stock=0 | - | fermeture temporaire | déclenche panneau “Rupture” | Event `SHOP_OUT_OF_STOCK` |
+
+## Icone de base
+
+| Élément | Spécification |
+|---|---|
+| Représentation | Boutique avec enseigne (cadeau/food) |
+| Couleur dominante | Or (revenu) + couleur du type (rouge food, bleu boisson) |
+| Variantes | `shop_gift_dir_{N,E,S,W}.png`, `shop_food_dir_{N,E,S,W}.png`, `shop_drink_dir_{N,E,S,W}.png` |
+| États | `open`, `busy`, `full`, `out_of_stock`, `promo` |
+
+## Interactions (tableau détaillé)
+
+| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
+|---|---|---|---|---|---|
+| Placer boutique | Action | case libre | sélectionner → placer | construction | `CELL_OCCUPIED` |
+| Voir revenus | Consultation | boutique posée | clic | panneau stats | - |
+| Upgrader | Action | coins ok | panneau → améliorer | level ↑ | `NOT_ENOUGH_COINS` |
+| Voir file | Consultation | visiteurs proches | survol | tooltip file | - |
+| Activer promo | Action (event) | condition event | clic toggle | affluence + | `PROMO_NOT_AVAILABLE` |
+
+## 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 | `shop` | DB | constant |
+| `subtype` | string | `gift` | DB/config | `gift/food/drink` |
+| `level` | int | 2 | DB | 1..7 |
+| `position.x` | int | 10 | DB | grid |
+| `position.y` | int | 12 | DB | grid |
+| `stats.revenue_total` | int | 12500 | DB | cumul |
+| `stats.visitors_served` | int | 840 | DB | cumul |
+| `stock.units` | int | 100 | DB | >=0 |
+| `popularity` | int | 10 | calcul/DB | 0..100 |
+| `capacity` | int | 5 | config | visitors simultanés |
+| `service_seconds_per_visitor` | float | 5.0 | config | 1..10 |
+| `attractiveness` | int | 10 | config | poids target |
+| `skin_id` | string | `shop_wood_forest` | DB | cosmétique |
+| `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 |
+|---|---:|---|---|
+| Revenu / visiteur | 15 | coins | level 1 |
+| Capacité | 5 | visiteurs | level 1 |
+| Vitesse service | 5 | s/visiteur | level 1 |
+| Rayon attraction | 2 | cases | level 1 |
+
+#### Scores Initiaux (tableau détaillé)
+
+| Score | Valeur initiale | Plage | Impact |
+|---|---:|---|---|
+| Stock | 100 | 0..∞ | rupture possible |
+| Popularité | 10 | 0..100 | mod conversion |
+
+### 2. Cycles de Vie et Apparition (tableau détaillé)
+
+| Phase | Déclencheur | Entrées | Sorties | Invariants |
+|---|---|---|---|---|
+| Construction | joueur | coins + coord | bâtiment | case occupée |
+| Service | visiteurs | besoins | revenus | capacité respectée |
+| Réappro | tick | CA | stock + | coût 10% CA |
+| Rupture | stock=0 | - | fermeture | observable |
+| Upgrade | action | coins | level ↑ | monotone |
+
+#### Conditions d'Apparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Construction | true | est | boutique posée |
+
+#### Conditions de Disparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Destruction | true | est | remboursement 50% |
+
+#### Hérédité (tableau détaillé)
+
+| Élément | Hérité | Règle |
+|---|---|---|
+| Franchise | Oui | coût -10% si 5 identiques |
+| Stats | Oui | cumul |
+
+### 3. Impacts Environnementaux
+
+#### Impact Température (tableau détaillé)
+
+| Condition | Effet boutique | Notes |
+|---|---|---|
+| > 30°C | eau +200% | canicule |
+| < 5°C | chocolat +200% | froid |
+
+#### Impact Milieu (Biome) (tableau détaillé)
+
+| Biome | Effet | Notes |
+|---|---|---|
+| forêt + skin bois | ventes +10% | thème match |
+| désert + skin oasis | ventes +10% | thème match |
+
+#### Impact Saisons (tableau détaillé)
+
+| Saison | Effet | Notes |
+|---|---|---|
+| Été | ventes boisson +20% | règle |
+| Hiver | ventes cadeaux +10% | règle |
+
+#### Impact Heure / Jour-Nuit (tableau détaillé)
+
+| Période | Effet | Notes |
+|---|---|---|
+| 12h-14h | demande food ++ | pic |
+| Nuit | fermé | 0 ventes |
+
+### 4. Impacts Biologiques et Sociaux
+
+#### Impact Reproduction (tableau détaillé)
+
+| Facteur | Effet sur taux | Condition |
+|---|---|---|
+| Naissance rare | ventes peluche x2 | “espèce du moment” |
+
+#### Impact Mort (tableau détaillé)
+
+| Cas | Effet | Condition |
+|---|---|---|
+| Mort récente proche | ventes -20% | ambiance |
+
+#### Impact Nourriture (tableau détaillé)
+
+| Ressource | Effet | Condition |
+|---|---|---|
+| Concurrence < 3 cases | ventes food -10% | partage |
+
+#### Impact Attractivité(Visiteurs (tableau détaillé)
+
+| Action/État | Gain | Rayon | Notes |
+|---|---:|---:|---|
+| Boutique level 7 | + | 10 cases | centre commercial |
+| Rupture stock | - | 6 cases | frustration |
+
+#### Impact Attractivité Animaux) (tableau détaillé)
+
+| Action/État | Effet animaux | Condition |
+|---|---|---|
+| Odeurs food | stress + | espèces sensibles |
+
+#### Impact Valeur (tableau détaillé)
+
+| Facteur | Variation | Condition |
+|---|---:|---|
+| Revente | 50% + upgrades | destruction |
+
+### 5. Impacts Logistiques et Économiques
+
+#### Vitesse (Camion) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Livraison stock | stock + | si feature livraison |
+
+#### Vitesse (Nurserie) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Peluches bébé | ventes + | bébés visibles |
+
+#### Vitesse (Accueil) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Nouvel animal rare | promo | event |
+
+#### Vitesse (Recherche) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Tech caisse auto | service 1s | level 7 |
+
+#### Vitesse (Labo) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Produit “science” | panier moyen + | zone labo |
+
+#### Vitesse (Visite) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| File d’attente | temps boutique + | capacité limitée |
+
+#### Dépenses (Billeterie) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 1 | coins | signalétique (conservée) |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Réappro | 10% CA | coins | automatique |
+
+#### Dépenses (Visiteurs) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Temps perdu file | satisfaction - | points | queue |
+
+#### Dépenses (Employés) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Caissier (lore) | 1800 | $/mois | level < 7 |
+
+#### 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 |
+|---|---:|---|---|
+| Peluche naissance | 2 | coins | production |
+
+#### Dépenses (Nourriture) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Matières food | 2 | coins/vente | marge |
+
+#### Dépenses (Acceuil des animaux) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Cadeau “nouvel arrivant” | 1 | coins | souvenir |
+
+#### Dépenses (Camion) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Livraison premium | 5 | coins | option |
+
+#### Trajet Visiteurs
+
+##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Ville | Zoo | entrée | besoins init 0 |
+
+##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Enclos | Boutique | faim/soif > 80 | target |
+
+##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Boutique | Enclos | besoins résolus | continue visite |
+
+##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Boutique | Sortie | budget 0 | départ |
+
+### 6. Événements
+
+#### Événements du Jeu  (tableau détaillé)
+
+| Event | Déclencheur | Payload | Effet |
+|---|---|---|---|
+| `SALE_MADE` | service | revenue | coins + |
+| `SHOP_FULL` | queue | length | départs |
+| `SHOP_OUT_OF_STOCK` | stock | units | fermeture |
+| `SHOP_RESTOCKED` | tick | cost | stock + |
+
+#### Événements du Carte (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `FOCUS_SHOP` | clic | caméra |
+
+#### Événements du Zoo (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_BUYS_ITEM` | transaction | satisfaction + |
+
+#### Événements du Ville / Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `WEATHER_HEATWAVE` | météo | eau ++ |
+
+#### Événements du Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_LEAVES_SHOP_QUEUE` | impatience | satisfaction - |
+
+#### Événements du Joueur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `PLAYER_UPGRADES_SHOP` | UI | params + |
+
+### 7. Progression
+
+#### Tableau des Upgrades (tableau détaillé)
+
+| Niveau | Coût | Effet | Débloque |
+|---|---:|---|---|
+| 4 | 340 | capacité 18 + service plus rapide | file réduite |
+| 7 | 1150 | 50 capacité + caisses auto | 1s/visiteur |
+
+### 8. Logique et Interfaces 
+
+#### Pseudo-code Impacts (tableau détaillé)
+
+| Fonction | Entrées | Sorties | Notes |
+|---|---|---|---|
+| `computeSeasonDemandMod` | season, temp | float | eau/glaces/chocolat |
+| `serveVisitor` | shop, visitor | revenue | résout besoins |
+| `restockIfNeeded` | shop, CA | shop | coût 10% CA |
+
+#### Messages d'Infos / Alerte (tableau détaillé)
+
+| ID | Niveau | Message | Condition |
+|---|---|---|---|
+| `SHOP_FULL` | Warning | "Boutique pleine." | queue > cap |
+| `SHOP_OUT_OF_STOCK` | Warning | "Rupture de stock." | stock=0 |
+| `SALE_MADE` | Info | "Vente effectuée." | service |
+
+## Annexes UX/UI 
+
+### 1. Expérience Utilisateur (UX)
+
+#### Description UX (tableau détaillé)
+
+| Parcours | But | Friction | Réduction clics |
+|---|---|---|---|
+| Construire | générer revenus | placement | mode construction direct |
+| Lire stats | décider upgrade | menus | clic bâtiment |
+
+#### Description UI (tableau détaillé)
+
+| Composant | Contenu | États |
+|---|---|---|
+| Popup coins | +XX | burst | feedback |
+| Panneau stats | total + served | open/closed |
+| Badge rupture | icône | visible |
+
+#### Emplacement (tableau détaillé)
+
+| Zone UI | Position | Notes |
+|---|---|---|
+| Carte zoo | sur case | sélection base sprite |
+| HUD | compteur | pièces volantes |
+
+#### Intégration (tableau détaillé)
+
+| Intégration | Contrat | Notes |
+|---|---|---|
+| `visiteur.md` | besoins | faim/soif |
+| `chemin.md` | pathfinding | poids boutique |
+
+#### Navigation (tableau détaillé)
+
+| Action | Chemin | Résultat |
+|---|---|---|
+| Ouvrir stats | clic | panneau |
+| Upgrader | panneau → CTA | level ↑ |
+
+#### Événements (tableau détaillé)
+
+| Event UI | Déclencheur | Effet |
+|---|---|---|
+| `OPEN_SHOP` | clic | panneau |
+| `BUILD_SHOP` | build | placement |
+
+#### Assets Skinables
+
+##### Musiques (tableau détaillé)
+
+| Asset | Usage | Durée | Notes |
+|---|---|---:|---|
+| `shop_muzak_loop.mp3` | proximité boutique | loop | discret |
+
+##### Sons (tableau détaillé)
+
+| Asset | Usage | Volume |
+|---|---|---|
+| `cash_register.mp3` | vente | bas |
+| `coin_jingle.mp3` | revenue | bas |
+| `ui_open.mp3` | panneau | bas |
+
+##### Graphiques (tableau détaillé)
+
+| Asset | Usage | Contraintes |
+|---|---|---|
+| `shop_coin_popup.png` | popup | lisible |
+| `shop_queue_badge.png` | queue | contraste |
+| `shop_out_of_stock_badge.png` | rupture | rouge |
+
+##### Images (tableau détaillé)
+
+| Asset | Usage |
+|---|---|
+| `shop_blueprint.png` | construction |
+| `shop_product_icons.png` | UI |
+
+##### Vidéos (tableau détaillé)
+
+| Asset | Usage | Durée |
+|---|---|---:|
+| `shop_sales_bars.webm` | stats | 1.0s |
+
+##### Animations (tableau détaillé)
+
+| Animation | Déclencheur | Notes |
+|---|---|---|
+| pièce monte | vente | 0.6s |
+| porte ouvre/ferme | visiteur | 0.4s |
+
+##### Couleurs (tableau détaillé)
+
+| Token | Valeur | Usage |
+|---|---|---|
+| `shop_gold` | #FFD700 | revenus |
+| `shop_profit_green` | #2E7D32 | stats |
+| `shop_alert_red` | #D32F2F | rupture |
+
+##### Textes (tableau détaillé)
+
+| Clé | FR | EN |
+|---|---|---|
+| `shop.title` | Boutique | Shop |
+| `shop.revenue` | Revenus | Revenue |
+| `shop.out_of_stock` | Rupture de stock | Out of stock |
+
+##### Formes (tableau détaillé)
+
+| Élément | Forme | Notes |
+|---|---|---|
+| Popup | rectangle arrondi | lisible |
+| Badge | rond | constant |