ok

docs/specs/camion.md

@@ -231,3 +231,495 @@ function updateTruck(truck, deltaTime):
 - **Couleurs** : Rouge (Feux stop).
 - **Textes** : "Livraison effectuée".
 - **Formes** : Carré de stationnement.
+
+## Définition
+
+| Champ | Valeur |
+|---|---|
+| Concept | Unité de transport “Camion” : véhicule qui exécute des missions (achat/vente/transfert) entre sites (carte monde) et le zoo. |
+| Rôle | Relier les transactions (enchères/achats/ventes) à une logistique observable (trajet, délais, incidents), et injecter le cargo dans `accueil_animaux` / `nurserie` selon le cas. |
+| Portée | Entité persistante (par joueur/zoo) avec `level`, `status`, `cargo`, `target_site_id`. |
+| Contrainte | ETA et trajectoire calculés à la volée, sans cache/mémorisation ; aucun fallback silencieux (cargo manquant => erreur + log). |
+
+## Fonctions (tableau détaillé)
+
+| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
+|---|---|---|---|---|---|
+| Démarrer mission | achat/vente | `target_site_id`, cargo | status moving | refuse si déjà en mission | Event `TRUCK_DEPART` |
+| Calculer durée | départ | distance, level | ETA | vitesse table par level + météo | Event `TRUCK_ETA_COMPUTED` |
+| Déplacer sur carte | tick lazy | now, route | position | interpolation | Event `TRUCK_POSITION_UPDATED` |
+| Appliquer stress cargo | tick | cargo, confort | fertilité/stress | perte fertilité/h selon level | Event `CARGO_STRESS_APPLIED` |
+| Gérer incidents | tick | météo, entretien | delay | crevaison/panne explicités | Event `TRUCK_DELAYED` |
+| Arriver au site | ETA atteint | - | status arrived | charge/décharge | Event `TRUCK_ARRIVED_SITE` |
+| Retourner au zoo | fin opération | - | status moving_home | trajet retour | Event `TRUCK_RETURNING` |
+| Décharger au zoo | arrivée | cargo | slot réception | adultes → `accueil_animaux`, œufs/bébés → `nurserie` (selon type) | Event `DELIVERY_COMPLETE` |
+| Mini-jeu attente | clic camion | - | bonus léger | bonus borné, non obligatoire | Event `CLEAN_WINDSHIELD` |
+
+## Icone de base
+
+| Élément | Spécification |
+|---|---|
+| Représentation | Camion isométrique + flèche direction |
+| Couleur dominante | Jaune/noir ou blanc |
+| Variantes | `truck_lvl_{1..7}_dir_{N,E,S,W}.png` |
+| États | `idle`, `moving`, `delayed`, `arrived`, `cargo_loaded` |
+
+## Interactions (tableau détaillé)
+
+| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
+|---|---|---|---|---|---|
+| Envoyer en mission | Action | camion idle | achat → auto départ | mission lancée | `TRUCK_BUSY` |
+| Suivre trajet | Consultation | mission active | clic icône | panel ETA | - |
+| Ouvrir mini-jeu | Action | mission active | clic camion | modal mini-jeu | - |
+| Voir arrivée | Consultation | mission finie | notif | focus cargo | - |
+
+## Personnages contextuels (événements & interaction)
+Selon le contexte de la mission, le camion peut afficher un personnage contextuel :
+- **Personnel d’accueil (déchargement au zoo)** : voir `personnel_accueil.md` (cargo adulte).
+- **Nurse (déchargement vers nurserie)** : voir `nurse.md` (cargo œuf/bébé).
+- **Laborantin (achat depuis le laboratoire)** : voir `laborantin.md` (refus/gating/validation).
+- **Agent de sécurité (incident de trajet)** : voir `agent_securite.md` (retard/menace si la cause est “sécurité”).
+
+### Déclencheurs (exemples)
+| Event | Condition | Personnage | Effet UI |
+|---|---|---|---|
+| `TRUCK_DEPART` | mission démarrée | (option UI) | état “en route” + destination |
+| `TRUCK_DELAYED` | incident détecté | sécurité | bulle “Retard” + cause + CTA “Voir trajet” |
+| `TRUCK_ARRIVE` / `DELIVERY_COMPLETE` | arrivée zoo | accueil ou nurse | bulle “Livraison effectuée” + deep-link vers `accueil_animaux`/`nurserie` selon cargo |
+| `TRUCK_ARRIVED_SITE` | arrivée site | laborantin (si site labo) | bulle “Offre disponible” + CTA “Ouvrir labo” |
+
+### Skins & thèmes
+Le rendu des personnages suit `theme.md` et `inventaire_skins.md` (uniformes + accessoires). Le camion lui-même reste skinable via `inventaire_skins.md`.
+
+## 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 | - |
+| `level` | int | 1 | DB | 1..7 |
+| `status` | enum | `idle` | DB | `idle/moving_to_target/moving_home/delayed` |
+| `cargo.type` | string \| null | `animal` | DB | null si vide |
+| `cargo.id` | uuid_v4 \| null | `uuid_v4` | DB | - |
+| `position.x` | float | 10.2 | calcul/DB | carte monde |
+| `position.y` | float | 12.7 | calcul/DB | carte monde |
+| `target_site_id` | uuid_v4 \| null | `uuid_v4` | DB | - |
+| `iso_x` | int | 120 | DB/calcul | si rendu zoo |
+| `iso_y` | int | 88 | DB/calcul | si rendu zoo |
+| `z_index` | int | 12088 | calcul | profondeur |
+| `maintenance.km_since_service` | float | 0 | DB | - |
+| `timers.departed_at` | timestamp \| null | - | DB | UTC |
+| `timers.eta_at` | timestamp \| null | - | calcul/DB | UTC |
+
+#### Caractéristiques Initiales (tableau détaillé)
+
+| Caractéristique | Valeur initiale | Unité | Notes |
+|---|---:|---|---|
+| Vitesse (lvl1) | 50 | km/h | simulé |
+| Capacité | 1 | cargo | par camion |
+| Confort | 0.0 | score | réduit stress |
+
+#### Scores Initiaux (tableau détaillé)
+
+| Score | Valeur initiale | Plage | Impact |
+|---|---:|---|---|
+| Kilométrage | 0 | 0..∞ | entretien |
+| Retards cumulés | 0 | 0..∞ | info joueur |
+
+### 2. Cycles de Vie et Apparition (tableau détaillé)
+
+| Phase | Déclencheur | Entrées | Sorties | Invariants |
+|---|---|---|---|---|
+| Apparition | début jeu | - | camion idle | 1 camion min |
+| Mission | achat/vente | cargo+site | moving | exclusif |
+| Arrivée | ETA | - | arrived | décharge |
+| Retour | fin op | - | moving_home | - |
+| Idle | arrivée zoo | - | idle | cargo null |
+
+#### Conditions d'Apparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Début partie | true | est | camion créé |
+
+#### Conditions de Disparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| - | - | - | camion persiste |
+
+#### Hérédité (tableau détaillé)
+
+| Élément | Hérité | Règle |
+|---|---|---|
+| Upgrades | Oui | persiste |
+| Cargo | Non | mission-only |
+
+### 3. Impacts Environnementaux
+
+#### Impact Température (tableau détaillé)
+
+| Condition | Effet camion | Notes |
+|---|---|---|
+| > 40°C | vitesse -10% | surchauffe |
+| < -10°C | démarrage +5s | gel |
+
+#### Impact Milieu (Biome) (tableau détaillé)
+
+| Biome | Effet camion | Notes |
+|---|---|---|
+| Sable | vitesse - | sans pneus |
+| Terre | vitesse + | pneus adaptés |
+
+#### Impact Saisons (tableau détaillé)
+
+| Saison | Effet camion | Notes |
+|---|---|---|
+| Hiver | vitesse -20% | neige |
+| Automne | vitesse -5% | boue |
+
+#### Impact Heure / Jour-Nuit (tableau détaillé)
+
+| Période | Effet camion | Notes |
+|---|---|---|
+| Nuit sans phares | vitesse -30% | prudence |
+| Nuit avec phares | normal | level ≥ 2 |
+
+### 4. Impacts Biologiques et Sociaux
+
+#### Impact Reproduction (tableau détaillé)
+
+| Facteur | Effet sur taux | Condition |
+|---|---|---|
+| Stress transport | fertilité \(\downarrow\) | cargo animal |
+
+#### Impact Mort (tableau détaillé)
+
+| Cas | Effet | Condition |
+|---|---|---|
+| Trajet > 24h + confort bas | risque mort | cas extrême |
+
+#### Impact Nourriture (tableau détaillé)
+
+| Ressource | Effet | Condition |
+|---|---|---|
+| Carburant | coût/km | mission |
+
+#### Impact Attractivité(Visiteurs (tableau détaillé)
+
+| Action/État | Gain | Rayon | Notes |
+|---|---:|---:|---|
+| Skin camion | +1 | zoo | esthétique |
+
+#### Impact Attractivité Animaux) (tableau détaillé)
+
+| Action/État | Effet animaux | Condition |
+|---|---|---|
+| Klaxon | stress + | au passage |
+
+#### Impact Valeur (tableau détaillé)
+
+| Facteur | Variation | Condition |
+|---|---:|---|
+| Niveau camion | + | richesse (score) |
+
+### 5. Impacts Logistiques et Économiques
+
+#### Vitesse (Camion) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Niveau | table vitesse | 1..7 |
+
+#### Vitesse (Nurserie) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Livraison œuf/bébé | push vers nurserie | cargo type |
+
+#### Vitesse (Accueil) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Livraison adulte | push vers accueil | cargo type |
+
+#### Vitesse (Recherche) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | - | - |
+
+#### Vitesse (Labo) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Route labo | vitesse selon route | autoroute/piste |
+
+#### Vitesse (Visite) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | - | - |
+
+#### Dépenses (Billeterie) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Entretien | 10 | coins / 1000 km | règle |
+
+#### Dépenses (Visiteurs) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Dépenses (Employés) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Chauffeur (abstrait) | 0 | - | inclus |
+
+#### 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 |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Dépenses (Nourriture) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Dépenses (Acceuil des animaux) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### 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 |
+|---|---|---|---|
+| - | - | - | - |
+
+##### 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 |
+|---|---|---|---|
+| `TRUCK_DEPART` | mission | target, cargo | moving |
+| `TRUCK_DELAYED` | incident | reason, delta | ETA \(\uparrow\) |
+| `TRUCK_ARRIVE` | retour zoo | cargo | décharge |
+
+#### Événements du Carte (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `TRACK_TRUCK` | clic | panel |
+
+#### Événements du Zoo (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `DELIVERY_COMPLETE` | arrivée | push accueil/nurserie |
+
+#### É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 |
+|---|---|---|
+| `PLAYER_OPENS_TRUCK_PANEL` | clic | UI |
+
+### 7. Progression
+
+#### Tableau des Upgrades (tableau détaillé)
+
+| Niveau | Coût | Effet | Débloque |
+|---|---:|---|---|
+| 1 | 100 | 50 km/h | base |
+| 2 | 200 | 70 km/h + phares | nuit |
+| 7 | 6400 | 200 km/h | rapide |
+
+### 8. Logique et Interfaces 
+
+#### Pseudo-code Impacts (tableau détaillé)
+
+| Fonction | Entrées | Sorties | Notes |
+|---|---|---|---|
+| `computeTruckSpeed` | level, season, temp | float | table + mods |
+| `computeETA` | distance, speed | timestamp | à la volée |
+| `applyCargoStress` | cargo, comfort, dt | cargo | fertilité/stress |
+
+#### Messages d'Infos / Alerte (tableau détaillé)
+
+| ID | Niveau | Message | Condition |
+|---|---|---|---|
+| `TRUCK_ARRIVED` | Info | "Le camion est revenu au zoo." | arrivée |
+| `TRUCK_DELAY` | Info | "Le camion a du retard." | incident |
+| `TRUCK_BUSY` | Warning | "Camion déjà en mission." | lancement |
+
+## Annexes UX/UI 
+
+### 1. Expérience Utilisateur (UX)
+
+#### Description UX (tableau détaillé)
+
+| Parcours | But | Friction | Réduction clics |
+|---|---|---|---|
+| Acheter sur carte | déclencher livraison | navigation | auto-focus camion |
+| Suivre | connaître ETA | dispersion | panel clic icône |
+| Mini-jeu | occuper attente | option | accessible en 1 clic |
+
+#### Description UI (tableau détaillé)
+
+| Composant | Contenu | États |
+|---|---|---|
+| Icône camion | position + badge | moving/delayed |
+| Panel trajet | ETA + destination | open/closed |
+| Modal mini-jeu | taches | progress |
+
+#### Emplacement (tableau détaillé)
+
+| Zone UI | Position | Notes |
+|---|---|---|
+| Carte monde | overlay | camion |
+| Carte zoo | case camion | départ/arrivée |
+
+#### Intégration (tableau détaillé)
+
+| Intégration | Contrat | Notes |
+|---|---|---|
+| `accueil_animaux.md` | livraison adulte | dépôt |
+| `nurserie.md` | livraison œuf/bébé | dépôt |
+| `vente_animal.md` | logistique | mission |
+
+#### Navigation (tableau détaillé)
+
+| Action | Chemin | Résultat |
+|---|---|---|
+| Suivre | clic camion | panel |
+| Jouer | clic camion → mini-jeu | modal |
+| Voir arrivée | clic notif | focus |
+
+#### Événements (tableau détaillé)
+
+| Event UI | Déclencheur | Effet |
+|---|---|---|
+| `TRACK_TRUCK` | clic | panel |
+| `CLEAN_WINDSHIELD` | clic | mini-jeu |
+
+#### Assets Skinables
+
+##### Musiques (tableau détaillé)
+
+| Asset | Usage | Durée | Notes |
+|---|---|---:|---|
+| `truck_radio_lofi.mp3` | mini-jeu | loop | doux |
+
+##### Sons (tableau détaillé)
+
+| Asset | Usage | Volume |
+|---|---|---|
+| `engine_start.mp3` | départ | moyen |
+| `truck_stop.mp3` | arrivée | moyen |
+| `wipe.mp3` | mini-jeu | bas |
+
+##### Graphiques (tableau détaillé)
+
+| Asset | Usage | Contraintes |
+|---|---|---|
+| `truck_route_dotted.png` | route | overlay |
+| `truck_badge_delayed.png` | retard | lisible |
+
+##### Images (tableau détaillé)
+
+| Asset | Usage |
+|---|---|
+| `truck_map_icon.png` | carte |
+
+##### Vidéos (tableau détaillé)
+
+| Asset | Usage | Durée |
+|---|---|---:|
+| `truck_depart_zoom.webm` | départ | 1.5s |
+
+##### Animations (tableau détaillé)
+
+| Animation | Déclencheur | Notes |
+|---|---|---|
+| fumée échappement | moving | loop |
+| rotation roues | moving | loop |
+
+##### Couleurs (tableau détaillé)
+
+| Token | Valeur | Usage |
+|---|---|---|
+| `truck_yellow` | #FBC02D | carrosserie |
+| `truck_black` | #212121 | accents |
+
+##### Textes (tableau détaillé)
+
+| Clé | FR | EN |
+|---|---|---|
+| `truck.en_route` | En route vers {dest} | En route to {dest} |
+| `truck.arrived` | Camion rentré | Truck arrived |
+
+##### Formes (tableau détaillé)
+
+| Élément | Forme | Notes |
+|---|---|---|
+| Badge | rond | statut |
+| Flèche | triangle | direction |