ok

docs/specs/accueil_animaux.md

@@ -266,3 +266,510 @@ def add_animal_to_reception(reception_center, animal):
 - **Occlusion** : Le bâtiment doit être semi-transparent si le joueur passe la souris derrière (pour voir les objets cachés).
 - **Indicateur d'état** : Une icône flottante (bulle) au-dessus du bâtiment indique si un animal est prêt (point d'exclamation vert) ou en cours (sablier).
 - **Z-Index** : Doit être trié correctement par rapport aux visiteurs passant devant.
+
+## Définition
+
+| Champ | Valeur |
+|---|---|
+| Concept | Bâtiment “Accueil des animaux” : point d’entrée unique des animaux livrés/achetés, avec slots, acclimatation/quarantaine, et passage vers placement sur la grille. |
+| Rôle | Éviter le placement immédiat, révéler/afficher des informations avant placement, appliquer des règles d’acclimatation et incidents sanitaires observables. |
+| Portée | Une instance de bâtiment sur la carte zoo (iso), gérant une liste de slots `EMPTY/OCCUPIED/READY`. |
+| Contrainte | Timers et statuts recalculés à la volée (lazy update), sans cache/mémorisation ; aucun fallback silencieux en cas d’incohérence (log + erreur + message). |
+
+## Fonctions (tableau détaillé)
+
+| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
+|---|---|---|---|---|---|
+| Ouvrir accueil | clic bâtiment | `reception_id` | bottom sheet slots | liste slots + progression | Event `OPEN_RECEPTION` |
+| Réceptionner un animal | livraison camion/achat | `animal_id`, `arrival_time` | slot OCCUPIED | 1 slot libre requis, sinon `RECEPTION_FULL` | Event `ANIMAL_ARRIVAL` |
+| Calculer fin acclimatation | arrivée/upgrade | level, baseDuration | `acclimatization_end_time` | formule par niveau ; clamp ≥ now | Event `ACCLIMATIZATION_SCHEDULED` |
+| Passer READY | tick lazy | now, end_time | status READY | idempotent ; pas de skip | Event `ANIMAL_READY` |
+| Inspection pré-placement | ouverture slot | `animal_id` | UI stats | révèle traits selon “Traçabilité” | Event `RECEPTION_INSPECTED` |
+| Placement vers zoo | action joueur | `animal_id`, coord/enclos | animal placé | valide biome/enclos/case, sinon `PLACEMENT_ERROR` | Event `ANIMAL_PLACED` |
+| Appliquer bonus temporaire | sortie accueil | level | modifs temporaires | fertilité + calm/confident selon niveau | Event `RECEPTION_BONUS_APPLIED` |
+| Déclencher incident quarantaine | tick (par animal) | `risk_contamination` | quarantaine prolongée/coût | probabilité explicite ; jamais silencieux | Event `QUARANTINE_ALERT` |
+| Gestion saturation | slot plein | - | signal UI | badge + réduction attractivité façade | Event `RECEPTION_SATURATED` |
+
+## Icone de base
+
+| Élément | Spécification |
+|---|---|
+| Représentation | Porte/étable + caisse, badge quarantaine |
+| Couleur dominante | Ambre/bois (caisse), vert (prêt) |
+| Variantes | `reception_building_dir_{N,E,S,W}.png`, `reception_icon.png` |
+| États | `idle`, `occupied`, `ready`, `quarantine_alert`, `full` |
+
+## Interactions (tableau détaillé)
+
+| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
+|---|---|---|---|---|---|
+| Ouvrir slots | Consultation | - | clic accueil | bottom sheet | - |
+| Inspecter animal | Consultation | slot OCCUPIED/READY | clic slot | panneau détail | `ANIMAL_NOT_FOUND` |
+| Placer animal | Action | slot READY | bouton “Placer” → mode placement | placement | `PLACEMENT_ERROR` |
+| Détails incident | Consultation | `QUARANTINE_ALERT` actif | clic badge | panneau cause/coût | - |
+| Quitter | Navigation | sheet ouvert | fermer | retour carte | - |
+
+## Personnage contextuel (événements & interaction)
+Voir `personnel_accueil.md`.
+
+### Affichage
+Le personnel d’accueil s’affiche lorsque :
+- le module est **actionné** (ouverture de l’accueil, inspection d’un slot, lancement du placement) ;
+- un **événement** lié à l’accueil survient (arrivée, prêt, saturation, quarantaine).
+
+### Déclencheurs (événements)
+| Event | Condition | Effet UI personnage |
+|---|---|---|
+| `OPEN_RECEPTION` | clic bâtiment | portrait + état slots, CTA vers slot/placement |
+| `ANIMAL_ARRIVAL` | slot affecté | bulle “Arrivée enregistrée” + deep-link inspection |
+| `ANIMAL_READY` | slot passe READY | bulle “Prêt à placer” + CTA “Placer” |
+| `RECEPTION_FULL` | pas de slot libre | bulle “Accueil saturé” + CTA “Voir slots” |
+| `QUARANTINE_ALERT` | incident actif | bulle “Alerte quarantaine” + CTA “Voir détails” |
+
+### Skins & thèmes
+Le rendu du personnage suit `theme.md` et les skins éventuels via `inventaire_skins.md` (uniforme, badge, clipboard).
+
+## 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 | `building_reception` | DB | constant |
+| `level` | int | 1 | DB | 1..7 |
+| `position.x` | int | 10 | DB | grid |
+| `position.y` | int | 12 | DB | grid |
+| `iso_x` | int | 120 | DB/calcul | rendu iso |
+| `iso_y` | int | 88 | DB/calcul | rendu iso |
+| `z_index` | int | 12088 | calcul | profondeur |
+| `slots[].slot_id` | int | 0 | DB | 0..capacity-1 |
+| `slots[].animal_id` | uuid_v4 \| null | `uuid_v4` | DB | null si vide |
+| `slots[].status` | enum | `OCCUPIED` | DB | `EMPTY/OCCUPIED/READY` |
+| `slots[].arrival_time` | timestamp \| null | - | DB | UTC |
+| `slots[].acclimatization_end_time` | timestamp \| null | - | DB | UTC |
+| `slots[].bonus_applied` | boolean | false | DB | idempotent |
+| `scores.comfort_quarantine` | int | 60 | calcul/config | 0..100 |
+| `scores.risk_contamination` | float | 0.02 | config | 0..0.25 |
+| `scores.traceability` | int | 80 | config | 0..100 |
+
+#### Caractéristiques Initiales (tableau détaillé)
+
+| Caractéristique | Valeur initiale | Unité | Notes |
+|---|---:|---|---|
+| Capacité | 1 | slots | level 1 |
+| Temps acclimatation | 600 | s | base |
+| Zone température | neutre | - | stase |
+| Nourrissage | auto | bool | coût inclus |
+
+#### Scores Initiaux (tableau détaillé)
+
+| Score | Valeur initiale | Plage | Impact |
+|---|---:|---|---|
+| Confort quarantaine | 60 | 0..100 | stress initial \(\downarrow\) |
+| Risque contamination | 2% | 0..25% | incident sanitaire |
+| Traçabilité | 80 | 0..100 | traits révélés |
+
+### 2. Cycles de Vie et Apparition (tableau détaillé)
+
+| Phase | Déclencheur | Entrées | Sorties | Invariants |
+|---|---|---|---|---|
+| Apparition | début jeu | - | bâtiment présent | indestructible |
+| Entrée animal | livraison | animal_id | slot OCCUPIED | capacité |
+| READY | fin timer | now | status READY | idempotent |
+| Sortie | placement | coord | animal placé | slot libéré |
+| Incident | tirage risque | risk | prolongation/coût | observable |
+
+#### Conditions d'Apparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Nouvelle partie | true | est | accueil présent |
+
+#### Conditions de Disparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| - | - | - | indestructible |
+
+#### Hérédité (tableau détaillé)
+
+| Élément | Hérité | Règle |
+|---|---|---|
+| Bonus temporaires | Non | expirent |
+| Niveau accueil | Oui | persiste |
+
+### 3. Impacts Environnementaux
+
+#### Impact Température (tableau détaillé)
+
+| Condition | Effet accueil | Notes |
+|---|---|---|
+| - | neutre | pas de dégâts température |
+
+#### Impact Milieu (Biome) (tableau détaillé)
+
+| Biome | Effet accueil | Notes |
+|---|---|---|
+| - | neutre | compatible tous |
+
+#### Impact Saisons (tableau détaillé)
+
+| Saison | Effet accueil | Notes |
+|---|---|---|
+| - | protégé | pas d’intempéries |
+
+#### Impact Heure / Jour-Nuit (tableau détaillé)
+
+| Période | Effet accueil | Notes |
+|---|---|---|
+| Nuit | aucun | 24/7 |
+
+### 4. Impacts Biologiques et Sociaux
+
+#### Impact Reproduction (tableau détaillé)
+
+| Facteur | Effet sur taux | Condition |
+|---|---|---|
+| Level 4..6 | +10% temporaire | 2 jours in-game |
+| Level 7 | +25% temporaire | 5 jours in-game |
+
+#### Impact Mort (tableau détaillé)
+
+| Cas | Effet | Condition |
+|---|---|---|
+| Stase | pas de mort | jauges gelées |
+
+#### Impact Nourriture (tableau détaillé)
+
+| Ressource | Effet | Condition |
+|---|---|---|
+| Stock global | nourri auto | coût inclus |
+
+#### Impact Attractivité(Visiteurs (tableau détaillé)
+
+| Action/État | Gain | Rayon | Notes |
+|---|---:|---:|---|
+| Façade propre > 80 | +5 | 6 cases | ambiance |
+| File visible (saturation) | -10 | 8 cases | frustration |
+| Livraison animal rare | +20 | 10 cases | spectacle |
+
+#### Impact Attractivité Animaux) (tableau détaillé)
+
+| Action/État | Effet animaux | Condition |
+|---|---|---|
+| Quarantaine visible | stress voisin + | proximité |
+
+#### Impact Valeur (tableau détaillé)
+
+| Facteur | Variation | Condition |
+|---|---:|---|
+| Niveau accueil | +5% / niveau | valeur zoo |
+| Sans incident 7 jours | +10% | aucun `QUARANTINE_ALERT` |
+
+### 5. Impacts Logistiques et Économiques
+
+#### Vitesse (Camion) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Livraison | pousse slot OCCUPIED | camion arrive |
+
+#### Vitesse (Nurserie) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | - | - |
+
+#### Vitesse (Accueil) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Temps acclimatation | table par level | 1..7 |
+
+#### Vitesse (Recherche) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Traçabilité | + | score |
+
+#### Vitesse (Labo) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | - | - |
+
+#### Vitesse (Visite) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Saturation | détour visiteurs | `QUARANTINE_ALERT` |
+
+#### Dépenses (Billeterie) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Consommables quarantaine | 50 | coins / semaine | utilisation |
+| Nettoyage/désinfection | 30 | coins / semaine | maintenance |
+| Contrôle vétérinaire | 80 | coins / semaine | périodique |
+
+#### Dépenses (Visiteurs) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Dépenses (Employés) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Intervention quarantaine | 10 | coins | incident |
+
+#### 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 |
+|---|---:|---|---|
+| Nourrissage auto | 0 | - | inclus |
+
+#### Dépenses (Acceuil des animaux) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Maintenance accueil | 10 | coins / semaine | base |
+
+#### Dépenses (Camion) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Trajet Visiteurs
+
+##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Ville | Zoo | réputation | fréquentation \(\downarrow\) si incidents |
+
+##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Allées | Accueil | curiosité façade | détour faible |
+
+##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Accueil | Boutique | stress/peur | détour fuite |
+
+##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Accueil | Sortie | quarantaine visible | sortie anticipée |
+
+### 6. Événements
+
+#### Événements du Jeu  (tableau détaillé)
+
+| Event | Déclencheur | Payload | Effet |
+|---|---|---|---|
+| `ANIMAL_ARRIVAL` | camion | animal_id | slot OCCUPIED |
+| `ANIMAL_READY` | timer | animal_id | status READY |
+| `ANIMAL_PLACED` | placement | animal_id, coord | sortie slot |
+| `RECEPTION_FULL` | livraison | - | message |
+| `QUARANTINE_ALERT` | tirage | animal_id | avoidance visiteurs |
+
+#### Événements du Carte (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| - | - | - |
+
+#### Événements du Zoo (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `OPEN_RECEPTION` | clic | bottom sheet |
+
+#### Événements du Ville / Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_AVOIDS_QUARANTINE` | `QUARANTINE_ALERT` | reroute |
+
+#### Événements du Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_SEES_QUEUE` | saturation | satisfaction - |
+
+#### Événements du Joueur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `PLAYER_PLACES_ANIMAL_FROM_RECEPTION` | CTA | placement |
+
+### 7. Progression
+
+#### Tableau des Upgrades (tableau détaillé)
+
+| Niveau | Coût | Effet | Débloque |
+|---|---:|---|---|
+| 1 | 100 | 1 slot, 10 min | base |
+| 4 | 800 | fertilité +10% (2j) | bonus calme |
+| 7 | 6400 | instant, fertilité +25% (5j) | bonus confiant |
+
+### 8. Logique et Interfaces 
+
+#### Pseudo-code Impacts (tableau détaillé)
+
+| Fonction | Entrées | Sorties | Notes |
+|---|---|---|---|
+| `getAcclimatizationDuration` | level | seconds | table |
+| `updateReceptionSlots` | reception, now | reception | READY idempotent |
+| `tryStartQuarantineIncident` | slot, risk | incident? | observable |
+| `applyReceptionBonus` | animal, level | animal | temporaire |
+
+#### Messages d'Infos / Alerte (tableau détaillé)
+
+| ID | Niveau | Message | Condition |
+|---|---|---|---|
+| `ANIMAL_READY` | Info | "Un animal est prêt à rejoindre le zoo." | slot READY |
+| `RECEPTION_FULL` | Warning | "Accueil saturé." | pas de slot libre |
+| `PLACEMENT_ERROR` | Error | "Impossible de placer ici." | placement invalide |
+| `QUARANTINE_ALERT` | Warning | "Alerte quarantaine." | incident |
+
+## Annexes UX/UI 
+
+### 1. Expérience Utilisateur (UX)
+
+#### Description UX (tableau détaillé)
+
+| Parcours | But | Friction | Réduction clics |
+|---|---|---|---|
+| Voir arrivées | savoir quoi faire | dispersion | notif → deep-link accueil |
+| Inspecter | vérifier stats | menus | clic slot direct |
+| Placer | intégrer au zoo | erreurs | overlay OK/KO + CTA |
+
+#### Description UI (tableau détaillé)
+
+| Composant | Contenu | États |
+|---|---|---|
+| Bottom sheet accueil | liste slots | open/closed |
+| Slot | portrait + barre | empty/occupied/ready |
+| Badge état | sablier/! | visible au-dessus bâtiment |
+
+#### Emplacement (tableau détaillé)
+
+| Zone UI | Position | Notes |
+|---|---|---|
+| Carte zoo | bâtiment | sélection base sprite |
+| HUD | notifications | deep-link |
+
+#### Intégration (tableau détaillé)
+
+| Intégration | Contrat | Notes |
+|---|---|---|
+| `camion.md` | livraison | pousse vers accueil |
+| `enclos.md` | placement | validation |
+
+#### Navigation (tableau détaillé)
+
+| Action | Chemin | Résultat |
+|---|---|---|
+| Ouvrir accueil | clic bâtiment | slots |
+| Aller depuis notif | clic notif | focus slot |
+| Placer | CTA | mode placement |
+
+#### Événements (tableau détaillé)
+
+| Event UI | Déclencheur | Effet |
+|---|---|---|
+| `OPEN_RECEPTION` | clic | sheet |
+| `CLICK_PLACE_FROM_RECEPTION` | CTA | placement |
+
+#### Assets Skinables
+
+##### Musiques (tableau détaillé)
+
+| Asset | Usage | Durée | Notes |
+|---|---|---:|---|
+| `ambience_stable_soft.mp3` | accueil | loop | discret |
+
+##### Sons (tableau détaillé)
+
+| Asset | Usage | Volume |
+|---|---|---|
+| `crate_drop.mp3` | arrivée | moyen |
+| `ui_open.mp3` | ouvrir | bas |
+| `ui_confirm_place.mp3` | placer | bas |
+
+##### Graphiques (tableau détaillé)
+
+| Asset | Usage | Contraintes |
+|---|---|---|
+| `badge_quarantine.png` | état | contraste |
+| `reception_icon_ready.png` | prêt | lisible |
+
+##### Images (tableau détaillé)
+
+| Asset | Usage |
+|---|---|
+| `reception_building.png` | bâtiment |
+| `placement_ghost_ok.png` | overlay |
+
+##### Vidéos (tableau détaillé)
+
+| Asset | Usage | Durée |
+|---|---|---:|
+| `delivery_short.webm` | notif | 2.0s |
+
+##### Animations (tableau détaillé)
+
+| Animation | Déclencheur | Notes |
+|---|---|---|
+| badge sablier | OCCUPIED | loop |
+| badge ! vert | READY | loop |
+
+##### Couleurs (tableau détaillé)
+
+| Token | Valeur | Usage |
+|---|---|---|
+| `reception_amber` | #F39C12 | en cours |
+| `reception_green` | #2ECC71 | prêt |
+| `reception_red` | #E74C3C | erreur |
+
+##### Textes (tableau détaillé)
+
+| Clé | FR | EN |
+|---|---|---|
+| `reception.delivery_done` | Livraison effectuée | Delivery complete |
+| `reception.ready` | Prêt | Ready |
+| `reception.full` | Accueil saturé | Reception full |
+
+##### Formes (tableau détaillé)
+
+| Élément | Forme | Notes |
+|---|---|---|
+| Slot | rectangle arrondi | lisible |
+| Badge état | rond | visible |