From 430e8d3fd564c0c90c395e217263f96a01401006 Mon Sep 17 00:00:00 2001
From: Nicolas Cantu <nicolas.cantu@pm.me>
Date: Thu, 5 Mar 2026 04:03:17 +0100
Subject: [PATCH] ok

---
 docs/specs/chercheur.md                      |   3 +
 docs/specs/inventaire_problemes_visiteurs.md |  12 +
 docs/specs/ville.md                          | 440 +++++++++++++++++++
 3 files changed, 455 insertions(+)

diff --git a/docs/specs/chercheur.md b/docs/specs/chercheur.md
index f19153d..6f1298f 100644
--- a/docs/specs/chercheur.md
+++ b/docs/specs/chercheur.md
@@ -50,6 +50,9 @@ Employé travaillant dans le Centre de Recherche pour générer des points de sc
 *   **Interface Bâtiment :** Slots d'employés (0/3) dans le menu du Centre de Recherche.
 *   **Feedback :** Bulles de science (fioles, atomes) s'élevant du bâtiment quand ils travaillent.
 
+## Affichage contextuel (modules)
+Le chercheur est le personnage contextuel du `centre_recherche.md` lors de l’ouverture du panneau, de l’assignation et des événements de production/déverrouillage.
+
 
 # Annexes UX/UI
 
diff --git a/docs/specs/inventaire_problemes_visiteurs.md b/docs/specs/inventaire_problemes_visiteurs.md
index ba8e455..7a1e81f 100644
--- a/docs/specs/inventaire_problemes_visiteurs.md
+++ b/docs/specs/inventaire_problemes_visiteurs.md
@@ -95,6 +95,18 @@ function checkVisitorNeeds(visitor):
 | :--- | :--- | :--- |
 | `INCIDENT_ALERT` | Warning | "Un visiteur se plaint !" |
 
+## Personnages contextuels (événements & interaction)
+- **Visiteur** : voir `visiteur.md` (source de l’incident, bulle, besoins).
+- **Agent de sécurité** : voir `agent_securite.md` (incidents d’ordre/vandalisme si présents dans la liste d’incidents).
+- **Soigneur** : voir `soigneur.md` (si incident “blessure/urgence” est introduit).
+- **Nourisseur** : voir `nourisseur.md` (incidents faim/soif indirects via stocks et boutiques).
+
+### Déclencheurs (exemples)
+| Event | Condition | Personnage | Effet UI |
+|---|---|---|---|
+| `INCIDENT_ALERT` | incident créé | visiteur | bulle + CTA résolution |
+| incident non résolu | TTL dépassé | sécurité/soigneur | bulle “Intervention requise” + deep-link |
+
 # Annexes UX/UI
 
 ## 0. Direction Artistique & Vue
diff --git a/docs/specs/ville.md b/docs/specs/ville.md
index 5e04008..0a0095e 100644
--- a/docs/specs/ville.md
+++ b/docs/specs/ville.md
@@ -169,3 +169,443 @@ function calculateVisitorFlow(city, zoo):
 - **Couleurs** : Gris/Bleu.
 - **Textes** : Nom Ville.
 - **Formes** : Cercle d'influence (zone de chalandise).
+
+## Définition
+
+| Champ | Valeur |
+|---|---|
+| Concept | Site “Ville” : nœud de la carte monde générant un potentiel de visiteurs et un budget moyen (wealth_factor). |
+| Rôle | Alimenter le flux ville→zoo (choix par attractivité/distance) et porter des événements (festivals, grèves) modifiant la demande. |
+| Portée | Une entité fixe sur carte monde, référencée par les calculs d’attractivité. |
+| Contrainte | Flux calculé à la volée (pas de cache/mémorisation) ; aucun mécanisme d’analytics ; événements doivent être explicités via events/messages. |
+
+## Fonctions (tableau détaillé)
+
+| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
+|---|---|---|---|---|---|
+| Calculer flux vers un zoo | tick / ouverture carte | `population`, `wealth_factor`, distance, attractivité zoo | `baseFlow` | formule \(Pop \cdot A / d^2\) + mods heure/event | Event `CITY_FLOW_DISPATCHED` |
+| Déclencher événement ville | calendrier/saison | type event | mod flux/budget | durée bornée | Event `CITY_EVENT` |
+| Vendre nourriture (marché) | interaction (feature) | stock, price | items | pricing selon wealth | Event `CITY_MARKET_OPENED` |
+| Marquer jumelage | relation max | city_id | bonus permanent | +5% flux vers zoo jumelé | Event `CITY_TWINNED` |
+
+## Icone de base
+
+| Élément | Spécification |
+|---|---|
+| Représentation | Skyline (petite/moyenne/grande) |
+| Couleur dominante | Gris/bleu + lumières jaunes |
+| Variantes | `city_small.png`, `city_medium.png`, `city_large.png` |
+| États | jour (clair), nuit (lumières), event (feux d’artifice) |
+
+## Interactions (tableau détaillé)
+
+| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
+|---|---|---|---|---|---|
+| Ouvrir ville | Consultation | ville visible | clic marker | panneau | `ZONE_NOT_EXPLORED` |
+| Voir flux | Consultation | zoo sélectionné | onglet flux | valeurs | - |
+| Lancer campagne (feature) | Action | coins ok | bouton campagne | flux + | `NOT_ENOUGH_COINS` |
+
+## 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 | `city` | DB | constant |
+| `name` | string | `Rivemont` | DB | - |
+| `population` | int | 250000 | DB | >0 |
+| `wealth_factor` | float | 1.2 | DB | 0.5..2.0 |
+| `events.active_event` | enum \| null | `NATIONAL_HOLIDAY` | DB | null si none |
+| `events.ends_at` | timestamp \| null | - | DB | UTC |
+| `iso_x` | int | 120 | calcul | rendu |
+| `iso_y` | int | 88 | calcul | rendu |
+| `z_index` | int | 12088 | calcul | profondeur |
+
+#### Caractéristiques Initiales (tableau détaillé)
+
+| Caractéristique | Valeur initiale | Unité | Notes |
+|---|---:|---|---|
+| Bonheur ville | 50 | % | influe fréquence |
+| Îlot chaleur | +2 | °C | vs campagne |
+
+#### Scores Initiaux (tableau détaillé)
+
+| Score | Valeur initiale | Plage | Impact |
+|---|---:|---|---|
+| Relation | 0 | 0..100 | jumelage |
+| Flux envoyé | 0 | 0..∞ | suivi in-game |
+
+### 2. Cycles de Vie et Apparition (tableau détaillé)
+
+| Phase | Déclencheur | Entrées | Sorties | Invariants |
+|---|---|---|---|---|
+| Génération | seed monde | biome | ville | fixe |
+| Événement | calendrier | type | mods | durée |
+
+#### Conditions d'Apparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Génération carte | true | est | ville créée |
+
+#### Conditions de Disparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Désastre rare | true | est | ville détruite (event) |
+
+#### Hérédité (tableau détaillé)
+
+| Élément | Hérité | Règle |
+|---|---|---|
+| Jumelage | Oui | bonus permanent |
+| Événements | Non | expirent |
+
+### 3. Impacts Environnementaux
+
+#### Impact Température (tableau détaillé)
+
+| Condition | Effet | Notes |
+|---|---|---|
+| îlot chaleur | +2°C | constant |
+
+#### Impact Milieu (Biome) (tableau détaillé)
+
+| Biome | Effet | Notes |
+|---|---|---|
+| toundra | architecture igloos | visuel |
+
+#### Impact Saisons (tableau détaillé)
+
+| Saison | Effet | Notes |
+|---|---|---|
+| hiver | marché Noël | flux + |
+
+#### Impact Heure / Jour-Nuit (tableau détaillé)
+
+| Période | Effet | Notes |
+|---|---|---|
+| nuit | lumières | pollution lumineuse |
+
+### 4. Impacts Biologiques et Sociaux
+
+#### Impact Reproduction (tableau détaillé)
+
+| Facteur | Effet sur taux | Condition |
+|---|---|---|
+| baby boom | pop + | 1 semaine in-game |
+
+#### Impact Mort (tableau détaillé)
+
+| Cas | Effet | Condition |
+|---|---|---|
+| épidémie | pop - | temporaire |
+
+#### Impact Nourriture (tableau détaillé)
+
+| Ressource | Effet | Condition |
+|---|---|---|
+| marché | stock joueur + | achats |
+
+#### Impact Attractivité(Visiteurs (tableau détaillé)
+
+| Action/État | Gain | Rayon | Notes |
+|---|---:|---:|---|
+| richesse | budget ↑ | monde | VIP |
+
+#### Impact Attractivité Animaux) (tableau détaillé)
+
+| Action/État | Effet animaux | Condition |
+|---|---|---|
+| - | neutre | - |
+
+#### Impact Valeur (tableau détaillé)
+
+| Facteur | Variation | Condition |
+|---|---:|---|
+| PIB | dépense moyenne ± | wealth_factor |
+
+### 5. Impacts Logistiques et Économiques
+
+#### Vitesse (Camion) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| trafic pointe | vitesse - | 8-9h, 17-18h |
+
+#### Vitesse (Nurserie) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | neutre | - |
+
+#### Vitesse (Accueil) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | neutre | - |
+
+#### Vitesse (Recherche) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| campagne marketing | flux + | achat |
+
+#### Vitesse (Labo) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| conférence science | affluence + | event |
+
+#### Vitesse (Visite) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| distance | flux \(\downarrow\) | d^2 |
+
+#### Dépenses (Billeterie) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| campagne 1 | 500 | coins | panneaux |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 1 | coins | lore |
+
+#### Dépenses (Visiteurs) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| budget visiteurs | wealth_factor × | $ | ville |
+
+#### Dépenses (Employés) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 1 | coins | 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 |
+|---|---:|---|---|
+| - | 1 | coins | lore |
+
+#### Dépenses (Nourriture) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| marchés | variable | coins | achats |
+
+#### Dépenses (Acceuil des animaux) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 1 | coins | lore |
+
+#### Dépenses (Camion) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| parking (lore) | 5 | $ | voiture |
+
+#### Trajet Visiteurs
+
+##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Ville | Zoo | flux | entrée billeterie |
+
+##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Zoo | Enclos | visite | satisfaction |
+
+##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Zoo | Boutiques | besoins | dépenses |
+
+##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Zoo | Ville | sortie | despawn |
+
+### 6. Événements
+
+#### Événements du Jeu  (tableau détaillé)
+
+| Event | Déclencheur | Payload | Effet |
+|---|---|---|---|
+| `CITY_EVENT` | calendrier | type | flux mod |
+| `CITY_TWINNED` | relation 100 | city_id | bonus + |
+
+#### Événements du Carte (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `MAP_ZOOM` | zoom | taille icône |
+
+#### Événements du Zoo (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `CITY_FLOW_DISPATCHED` | calcul | spawn potentiels |
+
+#### Événements du Ville / Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `NATIONAL_HOLIDAY` | event | flux x2 |
+
+#### Événements du Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_SPAWNS_FROM_CITY` | flux | origine |
+
+#### Événements du Joueur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `PLAYER_STARTS_CITY_CAMPAIGN` | action | flux + |
+
+### 7. Progression
+
+#### Tableau des Upgrades (tableau détaillé)
+
+| Niveau | Coût | Effet | Débloque |
+|---|---:|---|---|
+| 2 | 1500 | flux +10% | radio |
+| 3 | 5000 | flux +20% | TV |
+
+### 8. Logique et Interfaces 
+
+#### Pseudo-code Impacts (tableau détaillé)
+
+| Fonction | Entrées | Sorties | Notes |
+|---|---|---|---|
+| `calculateVisitorFlow` | city, zoo | float | distance |
+| `isPeakHour` | now | bool | trafic |
+
+#### Messages d'Infos / Alerte (tableau détaillé)
+
+| ID | Niveau | Message | Condition |
+|---|---|---|---|
+| `CITY_EVENT` | Info | "C'est la fête à {city}." | event |
+| `CITY_STRIKE` | Warning | "Grève : flux réduit." | event |
+
+## Annexes UX/UI 
+
+### 1. Expérience Utilisateur (UX)
+
+#### Description UX (tableau détaillé)
+
+| Parcours | But | Friction | Réduction clics |
+|---|---|---|---|
+| Identifier ville | choisir cible | densité | taille icône + tooltip |
+| Comprendre flux | arbitrer | maths | panneau simple “flux” |
+
+#### Description UI (tableau détaillé)
+
+| Composant | Contenu | États |
+|---|---|---|
+| Marker ville | sprite skyline | petit/moyen/grand |
+| Cercle influence | rayon | visible |
+| Tooltip | nom + pop | hover |
+
+#### Emplacement (tableau détaillé)
+
+| Zone UI | Position | Notes |
+|---|---|---|
+| Carte monde | sites | iso |
+
+#### Intégration (tableau détaillé)
+
+| Intégration | Contrat | Notes |
+|---|---|---|
+| `carte_monde.md` | usage | map |
+| `billeterie.md` | entrées | spawn |
+
+#### Navigation (tableau détaillé)
+
+| Action | Chemin | Résultat |
+|---|---|---|
+| Ouvrir ville | clic marker | panneau |
+
+#### Événements (tableau détaillé)
+
+| Event UI | Déclencheur | Effet |
+|---|---|---|
+| `MAP_ZOOM` | zoom | scale |
+
+#### Assets Skinables
+
+##### Musiques (tableau détaillé)
+
+| Asset | Usage | Durée | Notes |
+|---|---|---:|---|
+| `city_ambience_loop.mp3` | proximité ville | loop | discret |
+
+##### Sons (tableau détaillé)
+
+| Asset | Usage | Volume |
+|---|---|---|
+| `traffic_far.mp3` | ville | bas |
+
+##### Graphiques (tableau détaillé)
+
+| Asset | Usage | Contraintes |
+|---|---|---|
+| `city_skyline_set.png` | sprites | 4 dirs |
+
+##### Images (tableau détaillé)
+
+| Asset | Usage |
+|---|---|
+| `city_influence_ring.png` | cercle |
+
+##### Vidéos (tableau détaillé)
+
+| Asset | Usage | Durée |
+|---|---|---:|
+| `city_lights_night.webm` | nuit | 2.0s |
+
+##### Animations (tableau détaillé)
+
+| Animation | Déclencheur | Notes |
+|---|---|---|
+| fumée | idle | loop |
+
+##### Couleurs (tableau détaillé)
+
+| Token | Valeur | Usage |
+|---|---|---|
+| `city_gray` | #546E7A | bâtiments |
+| `city_light_yellow` | #FFEE58 | fenêtres |
+
+##### Textes (tableau détaillé)
+
+| Clé | FR | EN |
+|---|---|---|
+| `city.population` | Population | Population |
+| `city.wealth` | Richesse | Wealth |
+
+##### Formes (tableau détaillé)
+
+| Élément | Forme | Notes |
+|---|---|---|
+| Cercle influence | cercle | zone |