ok

docs/specs/carte_zoo.md

@@ -203,3 +203,498 @@ function initZooMap():
 - **Couleurs** : Vert/Rouge (Alpha 0.5).
 - **Textes** : "Placer ici".
 - **Formes** : Carrés.
+
+## Définition
+
+| Champ | Valeur |
+|---|---|
+| Concept | “Carte du zoo” : grille isométrique principale de gestion (construction, placement animaux/bâtiments, chemins, déplacements visiteurs). |
+| Rôle | Centraliser l’édition (build/paint), le rendu isométrique (tri z-index, occlusion), et la simulation locale (pathfinding, signaux terrain). |
+| Portée | Une map par zoo (`owner_id`), composée de `cases[]` et d’entités rendues (bâtiments, animaux, visiteurs, décorations). |
+| Contrainte | Pas de cache/mémorisation : états dérivés (z_index, variants auto-tiling, heatmap) calculés à la volée ; aucune interaction silencieuse (placement invalide => erreur + message). |
+
+## Fonctions (tableau détaillé)
+
+| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
+|---|---|---|---|---|---|
+| Rendre grille iso | frame render | cases visibles | draw list | tri par `z_index` + occlusion | Event `ZOO_MAP_RENDERED` |
+| Sélectionner une case | clic/tap | coord | panneau contexte | contenu dépend occupancy | Event `CLICK_CASE` |
+| Entrer mode build | bouton UI | type item | overlay | indique cases valides | Event `ENTER_BUILD_MODE` |
+| Placer entité | drop/tap place | entity, coord | occupancy update | invariants case/biome/enclos | Event `PLACE_ENTITY` |
+| Paint multi-case | drag | brush, path | batch placements | pas de “continue” silencieux : stop sur case invalide + message | Event `PAINT_APPLIED` |
+| Auto-tiling terrain/chemins | placement | voisins | variant keys | recalcul local voisinage | Event `AUTOTILE_UPDATED` |
+| Calculer pathfinding visiteurs | besoin/objectif | graph | route | A* à la volée, coûts par tuile | Event `VISITOR_ROUTE_COMPUTED` |
+| Mettre à jour signaux terrain | tick lazy | env | flags | givre/jaunissement selon compatibilité | Event `TERRAIN_SIGNAL_UPDATED` |
+| Gérer zoom | input | zoom level | camera scale | clamp + snap | Event `ZOO_MAP_ZOOM` |
+
+## Icone de base
+
+| Élément | Spécification |
+|---|---|
+| Représentation | Icône carte pliée / grille losange |
+| Couleur dominante | Vert (prairie), bleu (océan), gris (montagne) |
+| Variantes | `icon_zoo_map.png`, `icon_grid_iso.png` |
+| États | normal, build_mode, placement_invalid |
+
+## Interactions (tableau détaillé)
+
+| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
+|---|---|---|---|---|---|
+| Clic case | Consultation | - | clic | panneau | - |
+| Construire bâtiment | Action | item choisi | build → place | entité posée | `CELL_OCCUPIED`, `PLACEMENT_INVALID` |
+| Placer animal | Action | animal prêt | drag → drop | animal enclos | `BIOME_INCOMPATIBLE` |
+| Déplacer (réaménager) | Action | feature active | drag entité | relocalisation | `MOVE_BLOCKED` |
+| Zoom | Navigation | - | pinch/wheel | vue ajustée | - |
+
+## Personnages contextuels (événements & interaction)
+La carte du zoo est un module transversal : plusieurs personnages peuvent servir de contexte selon l’événement.
+
+### Personnage principal
+- **Joueur actif (avatar)** : voir `avatar_joueur.md`. Visible en HUD et utilisé comme personnage contextuel des actions de construction/gestion.
+
+### Personnages secondaires (selon événement)
+- **Visiteurs homme/femme** : voir `visiteur.md` (flux, pathfinding, congestion).
+- **Staff** : `nourisseur.md`, `soigneur.md`, `agent_securite.md`, `personnel_accueil.md`, `nurse.md` (déplacements et actions visibles sur la carte).
+
+### Déclencheurs (exemples)
+| Event / Action | Condition | Personnage | Effet UI |
+|---|---|---|---|
+| `CLICK_CASE` | clic case | avatar | panneau contexte + action principale |
+| `ENTER_BUILD_MODE` | build activé | avatar | rappel des invariants (cases valides) |
+| `PLACEMENT_INVALID` / `CELL_OCCUPIED` | placement refusé | avatar | message explicite + surbrillance cause |
+| `VISITOR_ROUTE_COMPUTED` | recalcul route | visiteur | bulle info si congestion/obstacle |
+| `DELIVERY_COMPLETE` | arrivée camion | accueil/nurse | bulle livraison + deep-link module |
+
+### Skins & thèmes
+Rendu des personnages : `theme.md` + équipements `inventaire_skins.md` (avatar + uniformes + variantes visiteurs si activées).
+
+## Annexes Techniques
+
+### 1. Données et États (tableau détaillé)
+
+| Donnée / État | Type | Exemple | Source | Contraintes |
+|---|---|---|---|---|
+| `id` | uuid_v4 | `uuid_v4` | DB | - |
+| `owner_id` | uuid_v4 | `uuid_v4` | DB | - |
+| `width` | int | 5 | DB | init |
+| `height` | int | 6 | DB | init |
+| `cases[].id` | uuid_v4 | `uuid_v4` | DB | unique |
+| `cases[].grid.x` | int | 2 | DB | 0..width-1 |
+| `cases[].grid.y` | int | 4 | DB | 0..height-1 |
+| `cases[].iso.iso_x` | int | 120 | calcul | rendu |
+| `cases[].iso.iso_y` | int | 88 | calcul | rendu |
+| `cases[].z_index` | int | 12088 | calcul | tri |
+| `cases[].biome` | enum | `prairie` | DB | tiers |
+| `cases[].terrain.ground_type` | enum | `herbe` | DB | - |
+| `cases[].terrain.path_type` | enum | `gravier` | DB | auto-tiling |
+| `cases[].occupancy.type` | enum | `building` | DB | un principal |
+| `cases[].occupancy.entity_id` | uuid_v4 \| null | `uuid_v4` | DB | null si vide |
+| `cases[].render.tile_variant` | string | `path_gravel_T` | calcul | key |
+| `cases[].render.occluder` | boolean | true | config | - |
+| `cases[].render.click_hitbox` | enum | `base_sprite` | config | accessibilité clic |
+| `timestamps.updated_at` | timestamp | - | DB | UTC |
+
+#### Caractéristiques Initiales (tableau détaillé)
+
+| Caractéristique | Valeur initiale | Unité | Notes |
+|---|---:|---|---|
+| Taille | 30 | cases | ~5x6 |
+| Biomes | 3 | count | tiers |
+| Zoom min/max | 0.7 / 1.6 | scale | clamp |
+| Coût marche herbe | 1.2 | coef | pathfinding |
+
+#### Scores Initiaux (tableau détaillé)
+
+| Score | Valeur initiale | Plage | Impact |
+|---|---:|---|---|
+| Score aménagement | 0 | 0..100 | utilisation espace |
+| Propreté globale | 100 | 0..100 | satisfaction |
+
+### 2. Cycles de Vie et Apparition (tableau détaillé)
+
+| Phase | Déclencheur | Entrées | Sorties | Invariants |
+|---|---|---|---|---|
+| Création | compte | seed | cases init | contenu initial |
+| Expansion | achat case | coord | width/height | adjacency |
+| Réaménagement | action | entité | nouvelle position | pas de collision |
+| Catastrophes | event | saison | flags case | observable |
+
+#### Conditions d'Apparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Compte joueur | true | est | map créée |
+
+#### Conditions de Disparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Suppression compte | true | est | map supprimée |
+
+#### Hérédité (tableau détaillé)
+
+| Élément | Hérité | Règle |
+|---|---|---|
+| Extensions achetées | Oui | conservées en prestige (soft reset) |
+| Variants render | Non | recalcul à la volée |
+
+### 3. Impacts Environnementaux
+
+#### Impact Température (tableau détaillé)
+
+| Condition | Effet | Notes |
+|---|---|---|
+| Proche océan | -2°C | micro-climat |
+| Montagne | -5°C | micro-climat |
+
+#### Impact Milieu (Biome) (tableau détaillé)
+
+| Biome | Effet | Notes |
+|---|---|---|
+| Prairie | herbe repousse | nourriture passive |
+| Océan | humidité + | froid adjacent |
+| Montagne | givre + | froid |
+
+#### Impact Saisons (tableau détaillé)
+
+| Saison | Effet | Notes |
+|---|---|---|
+| Hiver | neige/givre | décor + path cost |
+| Automne | teintes orange | visuel |
+
+#### Impact Heure / Jour-Nuit (tableau détaillé)
+
+| Période | Effet | Notes |
+|---|---|---|
+| Nuit | lumières | lampadaires/bâtiments |
+
+### 4. Impacts Biologiques et Sociaux
+
+#### Impact Reproduction (tableau détaillé)
+
+| Facteur | Effet sur taux | Condition |
+|---|---|---|
+| Buissons “intimité” | +5% | autour enclos |
+
+#### Impact Mort (tableau détaillé)
+
+| Cas | Effet | Condition |
+|---|---|---|
+| Animal mort sur case | fertilité sol + | case verdit après TTL |
+
+#### Impact Nourriture (tableau détaillé)
+
+| Ressource | Effet | Condition |
+|---|---|---|
+| Herbe prairie vide | repousse | tick lent |
+
+#### Impact Attractivité(Visiteurs (tableau détaillé)
+
+| Action/État | Gain | Rayon | Notes |
+|---|---:|---:|---|
+| Décoration | +1 | 3 cases | beauté |
+
+#### Impact Attractivité Animaux) (tableau détaillé)
+
+| Action/État | Effet animaux | Condition |
+|---|---|---|
+| Foule proche | stress + | densité élevée |
+
+#### Impact Valeur (tableau détaillé)
+
+| Facteur | Variation | Condition |
+|---|---:|---|
+| Case achetée | + | foncier | valeur zoo |
+
+### 5. Impacts Logistiques et Économiques
+
+#### Vitesse (Camion) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Accès camion | chemin connecté | case camion |
+
+#### Vitesse (Nurserie) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Overlay placement | valid/invalid | mode sortie |
+
+#### Vitesse (Accueil) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Mode placement | overlay | READY |
+
+#### Vitesse (Recherche) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | - | - |
+
+#### Vitesse (Labo) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | - | - |
+
+#### Vitesse (Visite) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Chemins | +50% vitesse | path tiles |
+
+#### Dépenses (Billeterie) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Entretien espaces verts | 1 | coins/case/semaine | propreté |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Maintenance routes | 1 | coins/tuile/semaine | option |
+
+#### Dépenses (Visiteurs) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Saleté | temps staff | min | déchets |
+
+#### Dépenses (Employés) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Soigneur déplacement | temps | min | chemins |
+
+#### 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 |
+|---|---:|---|---|
+| - | 1 | coins | visuel couplé |
+
+#### Dépenses (Nourriture) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Stock global | variable | coins | achats |
+
+#### Dépenses (Acceuil des animaux) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Quarantaine | variable | coins | incidents |
+
+#### Dépenses (Camion) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Carburant | variable | coins | distance |
+
+#### Trajet Visiteurs
+
+##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Billeterie | Ville | sortie | despawn |
+
+##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Billeterie | Enclos | plan visite | route |
+
+##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Enclos | Boutique | besoin | détour |
+
+##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Enclos | Billeterie | fin visite | sortie |
+
+### 6. Événements
+
+#### Événements du Jeu  (tableau détaillé)
+
+| Event | Déclencheur | Payload | Effet |
+|---|---|---|---|
+| `MAP_EXPAND` | achat | coord | size + |
+| `AUTOTILE_UPDATED` | terrain | coord | variants |
+
+#### Événements du Carte (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `ZOO_MAP_ZOOM` | input | camera |
+
+#### Événements du Zoo (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `PLACE_ENTITY` | placement | occupancy |
+
+#### Événements du Ville / Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_ROUTE_COMPUTED` | besoin | route |
+
+#### Événements du Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_REROUTE` | obstacle | route |
+
+#### Événements du Joueur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `ENTER_BUILD_MODE` | UI | overlay |
+
+### 7. Progression
+
+#### Tableau des Upgrades (tableau détaillé)
+
+| Niveau | Coût | Effet | Débloque |
+|---|---:|---|---|
+| 1 | 100 | +1 case | extension |
+
+### 8. Logique et Interfaces 
+
+#### Pseudo-code Impacts (tableau détaillé)
+
+| Fonction | Entrées | Sorties | Notes |
+|---|---|---|---|
+| `getBiomeByColumn` | x, width | biome | tiers |
+| `computeZIndex` | x,y | int | tri iso |
+| `isPlacementValid` | entity, coord | bool | invariants |
+
+#### Messages d'Infos / Alerte (tableau détaillé)
+
+| ID | Niveau | Message | Condition |
+|---|---|---|---|
+| `MAP_EXPAND` | Info | "Le zoo s'agrandit." | achat |
+| `PLACEMENT_INVALID` | Warning | "Placement invalide." | validation |
+| `CELL_OCCUPIED` | Warning | "Case occupée." | collision |
+
+## Annexes UX/UI 
+
+### 1. Expérience Utilisateur (UX)
+
+#### Description UX (tableau détaillé)
+
+| Parcours | But | Friction | Réduction clics |
+|---|---|---|---|
+| Construire | façonner zoo | erreurs placement | overlay OK/KO |
+| Inspecter case | comprendre contenu | navigation | panneau contextuel |
+
+#### Description UI (tableau détaillé)
+
+| Composant | Contenu | États |
+|---|---|---|
+| Highlight case | outline | hover/selected |
+| Bottom sheet | infos/actions | open/closed |
+| Overlay build | vert/rouge | valid/invalid |
+
+#### Emplacement (tableau détaillé)
+
+| Zone UI | Position | Notes |
+|---|---|---|
+| Canvas monde | plein écran | caméra |
+| HUD build | barre | outils |
+
+#### Intégration (tableau détaillé)
+
+| Intégration | Contrat | Notes |
+|---|---|---|
+| `case_zoo.md` | unité case | occupancy |
+| `chemin.md` | auto-tiling | path |
+
+#### Navigation (tableau détaillé)
+
+| Action | Chemin | Résultat |
+|---|---|---|
+| Sélection | clic case | panneau |
+| Build | bouton build | overlay |
+
+#### Événements (tableau détaillé)
+
+| Event UI | Déclencheur | Effet |
+|---|---|---|
+| `CLICK_CASE` | clic | panneau |
+| `ENTER_BUILD_MODE` | clic | overlay |
+
+#### Assets Skinables
+
+##### Musiques (tableau détaillé)
+
+| Asset | Usage | Durée | Notes |
+|---|---|---:|---|
+| `zoo_map_ambience_loop.mp3` | carte zoo | loop | discret |
+
+##### Sons (tableau détaillé)
+
+| Asset | Usage | Volume |
+|---|---|---|
+| `click_tile.mp3` | sélection | bas |
+| `grid_snap.mp3` | placement | bas |
+
+##### Graphiques (tableau détaillé)
+
+| Asset | Usage | Contraintes |
+|---|---|---|
+| `tile_highlight.png` | hover | overlay |
+| `build_overlay.png` | build | alpha |
+
+##### Images (tableau détaillé)
+
+| Asset | Usage |
+|---|---|
+| `biome_prairie_tiles.png` | sol |
+| `biome_mountain_tiles.png` | sol |
+
+##### Vidéos (tableau détaillé)
+
+| Asset | Usage | Durée |
+|---|---|---:|
+| `grid_holo.webm` | build | 1.0s |
+
+##### Animations (tableau détaillé)
+
+| Animation | Déclencheur | Notes |
+|---|---|---|
+| pulsation highlight | hover | 0.4s |
+| snap | placement | 0.2s |
+
+##### Couleurs (tableau détaillé)
+
+| Token | Valeur | Usage |
+|---|---|---|
+| `build_ok_green` | #00FF00 | valid |
+| `build_ko_red` | #FF0000 | invalid |
+
+##### Textes (tableau détaillé)
+
+| Clé | FR | EN |
+|---|---|---|
+| `zoo_map.place_here` | Placer ici | Place here |
+| `zoo_map.invalid` | Placement invalide | Invalid placement |
+
+##### Formes (tableau détaillé)
+
+| Élément | Forme | Notes |
+|---|---|---|
+| Case | losange | iso |
+| Panneau | rectangle arrondi | lisible |