# Menu Achats

## 1. Définition
Interface centralisée dédiée aux transactions utilisant la monnaie premium (pièces du zoo) ou standard, regroupant les employés, la nourriture spéciale, les skins et les améliorations. C'est le "hub" économique du joueur.

## 2. Fonctions
*   **Catalogue :** Présente tous les articles achetables de manière organisée.
*   **Transaction :** Gère la validation des achats et le débit des ressources.
*   **Offres :** Peut afficher des promotions ou des packs (bundles).

## 3. Icone
*   **Représentation :** Caisse enregistreuse ou Panier d'achat.
*   **Couleur dominante :** Vert (billet) et Or (pièce).

## 4. Interactions
*   **Accès :** Bouton principal dans la barre d'interface (HUD).
*   **Navigation :** Onglets par catégorie (Animaux, Enclos, Employés, Déco, Spécial).
*   **Achat Rapide :** Possibilité d'acheter en quantité (x1, x10).

## 5. Annexes Techniques

### Données (JSON)
```json
{
  "shop_categories": [
    {
      "id": "employees",
      "label": "Personnel",
      "items": ["healer_01", "feeder_01", "security_01"]
    },
    {
      "id": "consumables",
      "label": "Nourriture Spéciale",
      "items": ["food_boost_lion", "food_boost_monkey"]
    }
  ],
  "currency_balance": {
    "coins": 1500,
    "gems": 50
  },
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Règles Métier
*   **Déblocage :** Certains articles ne sont visibles qu'à partir d'un certain niveau de zoo.
*   **Stock :** Certains items peuvent être en quantité limitée (ex: offres du jour).

## 6. Annexes UX/UI
*   **Design :** Fenêtre modale propre, avec de grandes icônes et des prix clairs.
*   **Feedback Achat :** Animation de pièces qui volent vers le compteur total lors de la dépense.
*   **Confirmation :** Pop-up de confirmation pour les achats coûteux (> 1000 pièces).


# 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 | Menu “Achats” : hub UI des transactions (employés, consommables, cosmétiques, upgrades). |
| Rôle | Réduire les clics d’achat via catégories/onglets, et garantir des transactions atomiques (débit + attribution). |
| Portée | UI globale (HUD) ; impacte inventaires, bâtiments, personnel, monnaies. |
| Contrainte | Aucun tracking/analytics ; pas de cache/mémorisation côté app : catalogue et soldes sont lus comme état courant à l’ouverture. |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Ouvrir menu achats | clic HUD | `player_id` | modal hub | focus dernière catégorie (état UI local) | Event `OPEN_SHOP_HUB` |
| Charger catalogue | ouverture | `shop_version` | catégories + items | filtrer par niveau, conditions | Event `SHOP_CATALOG_LOADED` |
| Filtrer catégorie | clic onglet | `category_id` | liste items | tri stable, recherche | Event `SHOP_CATEGORY_SELECTED` |
| Prévisualiser item | clic item | `item_id` | panneau détail | affiche prix, effets, prérequis | Event `SHOP_ITEM_PREVIEWED` |
| Acheter item | clic “Acheter” | `item_id`, quantité | débit + attribution | transaction atomique ; pas d’achat si fonds insuffisants | Event `SHOP_PURCHASED` |
| Confirmer achat coûteux | seuil | `price` | modal confirm | requis si > 1000 coins | Event `SHOP_CONFIRM_SHOWN` |
| Achat en quantité | clic x1/x10 | quantité | panier/achat | clamp par stock/solde | Event `SHOP_QUANTITY_CHANGED` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | Caisse / panier |
| Couleur dominante | Vert + or |
| Variantes | `icon_shop_cash.png`, `icon_shop_cart.png` |
| États | normal, hover, disabled (fonds) |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Accès hub | Navigation | - | clic HUD | ouvre hub | - |
| Changer onglet | Navigation | - | clic onglet | liste update | - |
| Achat simple | Action | fonds ok | clic acheter | item attribué | `NOT_ENOUGH_COINS` |
| Achat coûteux | Action | fonds ok | acheter → confirm | item attribué | `CANCELLED` |
| Achat x10 | Action | fonds/stock ok | select x10 → acheter | 10 items | `LIMIT_REACHED` |

## Personnage contextuel (événements & interaction)
Deux personnages contextuels peuvent être affichés selon la section :
- **Vendeur “achat en pièces”** : voir `vendeur_pieces.md` (section “Pièces”, conversion/pack).
- **Vendeur (boutique)** : voir `vendeur.md` (prévisualisation/achat d’items boutique/cosmétiques si le hub les expose).

### Déclencheurs (exemples)
| Section | Event / Action | Effet UI personnage |
|---|---|---|
| Hub | `OPEN_SHOP_HUB` | personnage visible dans l’en-tête du hub (thématisé) |
| Hub | `SHOP_ITEM_PREVIEWED` | bulle “Détails item” + CTA “Acheter” |
| Hub | `SHOP_CONFIRM_SHOWN` | confirmation contextualisée (prix, quantité) |
| Pièces | ouverture section | vendeur pièces présente les packs + limites |
| Pièces | achat pack | reçu + solde mis à jour ; erreur explicite si paiement impossible |

### Skins & thèmes
Le rendu suit `theme.md` et les skins de la UI/boutique si disponibles via `inventaire_skins.md`.

## Annexes Techniques

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

| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `shop_categories[].id` | string | `employees` | config/DB | stable |
| `shop_categories[].label_key` | string | `shop.cat.employees` | i18n | FR/EN |
| `shop_categories[].items[]` | string[] | `["healer_01"]` | config/DB | ids |
| `items[item_id].price.coins` | int | 250 | config | >=0 |
| `items[item_id].price.gems` | int | 0 | config | >=0 |
| `items[item_id].requires.zoo_level` | int | 3 | config | gating |
| `items[item_id].stock_daily` | int \| null | 10 | config | null = illimité |
| `currency_balance.coins` | int | 1500 | DB | source de vérité |
| `currency_balance.gems` | int | 50 | DB | source de vérité |
| `ui.last_category_id` | string | `employees` | client | état UI |

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

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| Seuil confirmation | 1000 | coins | règle existante |
| Quantités rapides | 1,10 | unités | boutons |
| Catégorie par défaut | `employees` | id | configurable |

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

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Achats du jour | 0 | 0..∞ | historique local, pas d’analytics |
| Dépenses du jour | 0 | 0..∞ | transparence UI |

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

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Apparition | jeu lancé | config | hub dispo | bouton HUD |
| Navigation | clic onglets | category_id | liste | tri stable |
| Transaction | achat | item+prix | débit+attribution | atomicité |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Compte créé | true | est | hub visible |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Mode tutorial verrou | true | est | hub masqué temporairement |

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

| Élément | Hérité | Règle |
|---|---|---|
| Soldes | Oui | persistants DB |
| Achats | Oui | items attribués |

### 3. Impacts Environnementaux

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

| Condition | Effet shop | Notes |
|---|---|---|
| - | aucun | UI |

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

| Biome | Effet shop | Notes |
|---|---|---|
| - | aucun | UI |

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

| Saison | Effet shop | Notes |
|---|---|---|
| Saison active | items saisonniers visibles | gating explicite |

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

| Période | Effet shop | Notes |
|---|---|---|
| - | aucun | - |

### 4. Impacts Biologiques et Sociaux

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

| Facteur | Effet sur taux | Condition |
|---|---|---|
| - | aucun | shop n’impacte pas directement |

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

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

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

| Ressource | Effet | Condition |
|---|---|---|
| Achat nourriture spéciale | stock + | transaction ok |

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

| Action/État | Gain | Rayon | Notes |
|---|---:|---:|---|
| - | 0 | 0 | UI |

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

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

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

| Facteur | Variation | Condition |
|---|---:|---|
| Skins/thèmes achetés | + | valeur perçue | cosmétique |

### 5. Impacts Logistiques et Économiques

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

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

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

| Paramètre | Effet | Condition |
|---|---|---|
| Achat upgrade nurserie | level ↑ | transaction ok |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Achat accueil | capacité ↑ | transaction ok |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Achat recherche | vitesse ↑ | transaction ok |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Achat labo | capacité ↑ | transaction ok |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Achat décor | attractivité ↑ | transaction ok |

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

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

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

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

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

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

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Recrutement | variable | coins | item employé |

#### 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 |
|---|---:|---|---|
| Upgrade | variable | coins | achat |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Consommables | variable | coins | achat |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Achat capacité | variable | coins | achat |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Achat upgrade | variable | coins | achat |

#### Trajet Visiteurs

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

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

##### 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 |
|---|---|---|---|
| `OPEN_SHOP_HUB` | clic | - | ouvre |
| `SHOP_CATALOG_LOADED` | open | version | liste |
| `SHOP_PURCHASED` | achat | item_id, qty | attribue |

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

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

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

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

#### É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 |
|---|---|---|
| `SHOP_CATEGORY_SELECTED` | onglet | UI |

### 7. Progression

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

| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| Hub 1 | 0 | catégories base | - |

### 8. Logique et Interfaces 

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

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `canPurchase` | balance, price | bool | fonds + gating |
| `purchaseItem` | item_id, qty | receipt | atomique |

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

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `NOT_ENOUGH_COINS` | Warning | "Fonds insuffisants." | achat |
| `SHOP_PURCHASED` | Info | "Achat effectué." | succès |

## Annexes UX/UI 

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

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

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Acheter employé | renforcer zoo | navigation | hub + onglet + CTA |
| Acheter consommable | soigner/booster | quantité | x1/x10 direct |

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

| Composant | Contenu | États |
|---|---|---|
| Onglets | catégories | actif/inactif |
| Carte item | icône, prix, CTA | disabled si fonds |
| Modal confirm | item + prix | ok/cancel |

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

| Zone UI | Position | Notes |
|---|---|---|
| HUD | bouton | accès direct |
| Modal | centre | hub |

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

| Intégration | Contrat | Notes |
|---|---|---|
| `boutique.md` | boutique interne | cohérence |
| `inventaire_skins.md` | cosmétiques | attribution |

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

| Action | Chemin | Résultat |
|---|---|---|
| Ouvrir | HUD → menu | hub |
| Acheter | item → CTA | attribution |

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

| Event UI | Déclencheur | Effet |
|---|---|---|
| `OPEN_SHOP_HUB` | clic | modal |
| `CLICK_BUY_ITEM` | CTA | achat |

#### Assets Skinables

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

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `shop_hub_loop.mp3` | menu achats | loop | neutre |

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

| Asset | Usage | Volume |
|---|---|---|
| `ui_purchase_success.mp3` | succès | moyen |
| `ui_purchase_fail.mp3` | échec | moyen |

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

| Asset | Usage | Contraintes |
|---|---|---|
| `shop_item_card.png` | carte item | scalable |
| `shop_coin_fly_fx.png` | feedback achat | overlay |

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

| Asset | Usage |
|---|---|
| `shop_banner.png` | header |

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

| Asset | Usage | Durée |
|---|---|---:|
| `coin_fly.webm` | feedback | 0.8s |

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

| Animation | Déclencheur | Notes |
|---|---|---|
| pièces qui volent | achat | 0.8s |

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

| Token | Valeur | Usage |
|---|---|---|
| `shop_green` | #2E7D32 | CTA |
| `shop_gold` | #D4AF37 | prix |

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

| Clé | FR | EN |
|---|---|---|
| `shop.title` | Achats | Shop |
| `shop.buy` | Acheter | Buy |

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

| Élément | Forme | Notes |
|---|---|---|
| Cartes | rectangles arrondis | lisible |
