# Plan d'action – Alignement du code avec le cahier des charges

Document de référence : `docs/cahier des charges.md`.  
Objectif : identifier les écarts entre le cahier des charges (version actuelle) et le code, puis ordonner les mises à jour.

---

## 1. Démarrage et grille au lancement (§1, §10, §11)

### Écarts

- **Démarrage autonome (§1)** : ~~Le joueur doit commencer avec 3 couples reproducteurs… Non implémenté~~ **Implémenté** : `default-grid-layout.js` + `addStarterAnimals(state)` placent 6 animaux (3 couples Meadow/Ocean/Mountain) en ligne 2.
- **Grille zoo au lancement (§10)** : ~~pas de recherche, billeterie, accueil, nourriture, ni 24 cases~~ **Implémenté** : `buildDefaultRow1Cells()` (research, billeterie, nursery, reception, food, school) ligne 1 ; 24 cases vides lignes 3–6.
- **Grille monde au lancement (§11)** : 1 Agrandissement carte, compteurs (bébés, animaux, labos, zoos, villes) présents dans l’UI ; Accueil/Nourriture/Camion couverts par la zone camion et les panneaux ventes. Documenté dans `docs/features/grille-lancement.md`.

### Actions

1. ~~Définir le layout…~~ Fait : `default-grid-layout.js`, `buildDefaultRow1Cells()`, `addStarterAnimals()`.
2. ~~Adapter buildDefaultCells()~~ Fait : appelle `buildDefaultRow1Cells()`.
3. ~~Placer 3 couples reproducteurs~~ Fait : `addStarterAnimals(state)` dans `defaultState()` et `doPrestige()`.
4. Documenter layout carte du monde : fait dans `docs/features/grille-lancement.md` (§11).

**Fichiers concernés :** `web/js/state.js`, `web/js/config.js`, `web/js/placement.js` (ou `grid-utils.js`), éventuellement `web/js/main-bootstrap.js`, `docs/features/` (fiche grille au lancement).

---

## 2. Mode automatique et 50 profils (§5)

### Écart

- Le cahier exige **50 archétypes de profils** (Conservateurs 1–10, Éleveurs 11–20, Commerçants 21–30, Expansionnistes 31–40, Scientifiques 41–50), avec **sélection hiérarchique** : Famille → Spécialisation (pas une simple liste déroulante). Chaque profil affiche priorités et risques.
- Le code n’a que **3 profils** (`fast` / `slow` / `balanced`) et **aucune UI** de choix de profil (uniquement `autoModeProfile` dans le state).

### Actions

1. Introduire un **modèle de données des 50 profils** : identifiant, famille, spécialisation, libellé, paramètres (seuil dépense, fréquence, types d’animaux préférés, etc.), priorité et risques (texte ou clés i18n).
2. Étendre `GameState` (ou équivalent) pour stocker le **profil choisi** (ex. id du profil ou famille + spécialisation) au lieu de seulement `autoModeProfile: "fast"|"slow"|"balanced"`.
3. Adapter la **logique bot / mode auto** (`bot-zoo.js`, `game-loop.js`) pour utiliser les paramètres du profil sélectionné (seuils, fréquences, priorités).
4. Ajouter une **interface de sélection hiérarchique** : étape 1 = choix de la Famille (Conservateur, Éleveur, Commerçant, Expansionniste, Scientifique), étape 2 = choix de la Spécialisation dans la famille, avec affichage des priorités et risques. Remplacer/augmenter le simple toggle mode auto actuel.
5. Centraliser les libellés et textes dans `texts-fr.js` (noms des familles, spécialisations, priorités, risques).

**Fichiers concernés :** `web/js/types.js`, `web/js/bot-zoo.js`, `web/js/game-loop.js`, `web/js/ui.js`, `web/js/texts-fr.js`, nouveau module optionnel `web/js/auto-mode-profiles.js` (définition des 50 profils).

---

## 3. Ventes – Validation différée et sablier (§13)

### Écart

- Le cahier impose une **validation différée de 10 minutes** en base : l’achat n’est effectif (transfert de propriété et de fonds) qu’à la fin de ce délai ; un **sablier** doit s’afficher sur la transaction pendant ce temps.
- Le code actuel valide la vente **immédiatement** à l’acceptation (accept → sold, transfert de pièces et livraison côté acheteur sans délai).

### Actions

1. Étendre le **schéma BDD** des ventes : ajouter un champ type `validated_at` (ou `pending_until`) pour marquer la fin du délai de 10 minutes après acceptation ; conserver `sold_at` comme date d’acceptation par le vendeur.
2. Adapter la **logique métier serveur** : à l’accept, créer la vente en statut « vendu en attente » et enregistrer l’heure de validation future ; un cron ou un traitement à la lecture vérifie `now >= validated_at` pour effectuer le transfert de pièces et marquer la vente comme définitivement validée. L’acheteur ne peut « récupérer » qu’après cette validation.
3. **API** : exposer pour chaque vente (côté vendeur et acheteur) l’état « en attente de validation » et le temps restant (ou `validated_at`). Le client affiche le sablier à partir de ces infos.
4. **Client** : sur la carte du monde / panneau ventes, afficher un **sablier** (ou compte à rebours) pour les ventes vendues mais pas encore validées ; désactiver le bouton « Récupérer » jusqu’à validation définitive.

**Fichiers concernés :** `server/schema.sql` ou migrations, `server/db.js`, `server/routes/sales.js`, `web/js/api-client.js`, `web/js/ui.js`, `web/js/types.js`, `docs/features/ventes-encheres-phase10.md`.

---

## 4. Visiteurs, incidents et invités de luxe (§2, §10)

### Écarts

- **Disparition des animaux (§2)** : ~~Un animal non visité pendant une durée configurable (ex. 5 min) doit être retiré. À vérifier / implémenter.~~ **Implémenté** : `Visitor.MaxSecondsWithoutVisit` (300 s), `tickAnimalVisits` (mise à jour `lastVisitedAt`), `checkDeathCauses` (retrait si dépassement). Documenté dans `docs/features/attractivite-visiteurs-phase8.md`.
- **Incidents et exigences (§2)** : Les visiteurs peuvent rencontrer des problèmes (soif, poubelle pleine, banc requis, animal trop loin, envie de photo) ; apparition contextuelle en phase d’attente ; bulle d’icône ; résolution par clic ou action ; impact attractivité et pièces. **Implémenté** : voir `docs/features/incidents-visiteurs-phase4.md`.
- **Invités de luxe (§2)** : Une part des visiteurs (ex. 8 %) paie plus l’entrée et dépense plus en boutique. **Implémenté** : `getVisitorParams` (income.js) applique `LuxuryGuestChance`, `LuxuryEntryMultiplier` sur l’entrée et `LuxuryShopMultiplier` sur le bonus boutique ; les revenus visiteurs en tiennent compte.

### Actions

1. **Visitor.MaxSecondsWithoutVisit** : Ajouter la config, et dans la boucle de jeu (ou module visiteurs) retirer les animaux non visités depuis plus de X secondes ; mettre à jour `deathCountRecent` ou équivalent si le cahier le lie aux morts.
2. **Incidents** : Modéliser les types d’incidents (soif, poubelle, banc, animal loin, photo), les associer aux visiteurs, gérer l’affichage des bulles et le clic/action de résolution ; appliquer bonus/malus attractivité et pièces. Config pour fréquence en phase d’attente.
3. **Invités de luxe** : Introduire un flag ou type « luxe » sur une part des visiteurs (ex. 8 %) et modifier le calcul des revenus (entrée + boutique) pour ces visiteurs.

**Fichiers concernés :** `web/js/config.js`, `web/js/income.js` (ou module visiteurs), `web/js/game-loop.js`, `web/js/ui.js` (bulles, clics), `web/js/types.js`, `web/js/texts-fr.js`.

---

## 5. Carte du monde – Villes, stagnation, camions NPC (§3)

### Écarts

- **Villes (§3, §11)** : Plus le zoo est proche d’une ville, plus il attire de visiteurs (formule d’attraction). Cases villes : 1 case nom, 1 case nombre max visiteurs vers les zoos. **Implémenté** : `maxVisitorsTowardZoos` par ville dans config ; `getCityAttraction` plafonne la contribution par ville ; carte du monde affiche nom + « max N » par ville (voir `docs/features/villes-phase11.md`).
- **Stagnation (§3)** : Zoos qui n’évoluent pas subissent une baisse progressive du multiplicateur de visiteurs (jusqu’à un plancher, ex. 10 %). **Implémenté** : getStagnationMultiplier, lastEvolutionAt (voir attractivite-visiteurs-phase8).
- **Camions NPC (§3)** : Des camions (ventes d’œufs entre zoos) sont visibles sur la carte, en mouvement entre deux zoos, ajoutés périodiquement par la boucle de jeu. **Implémenté** : `world-map.js` (`addNpcTruckSale`, `shouldAddNpcTruck`, `pruneTruckSales`) ; game-loop appelle `shouldAddNpcTruck` / `addNpcTruckSale` ; ui.js affiche `worldTruckSales` dans `worldMapNpcTrucksEl` avec position interpolée selon `truckMs`.

### Actions

1. **Villes** : Vérifier / implémenter la formule d’attraction (proximité zoo–ville + valeur des animaux) et le plafond « max visiteurs vers zoos » par ville ; afficher sur la carte les cases ville avec nom et compteur max visiteurs (voir `docs/features/villes-phase11.md`).
2. **Stagnation** : Suivre la « dernière action d’évolution » par zoo (ou par joueur) ; appliquer un multiplicateur de visiteurs dégressif jusqu’à un plancher (ex. 10 %) si aucune action depuis un délai configurable.
3. **Camions NPC** : S’assurer que la boucle de jeu et l’UI créent et affichent bien des camions entre zoos (animations interpolées) selon la config existante.

**Fichiers concernés :** `web/js/config.js`, `web/js/income.js` ou module attractivité, `web/js/ui.js` (carte du monde, villes), `web/js/game-loop.js`, `docs/features/villes-phase11.md`.

---

## 6. Interface et barre du haut (§4)

### Écarts

- **Rafraîchissement (§4)** : La barre du haut ne doit pas être reconstruite à chaque mise à jour ; seules les parties dynamiques (indicateurs, grille, carte) sont rafraîchies. **Vérifié** : `setState()` appelle la closure `fullRender()` retournée par `render()` ; celle-ci ne recrée pas le DOM de la barre, elle appelle seulement `updateStatus()` puis `renderWorldMap()` et `renderGrid()`. La barre est créée une seule fois au premier `render(root, opts)`.
- **Pas d’onglets avec titres** : Pas d’onglets « Carte du zoo » / « Carte du monde » avec titres ; un seul sélecteur (icônes zoo / monde). À vérifier dans l’UI.
- **Message d’erreur** : Masqué et ne prenant pas de place lorsqu’il n’y a pas d’erreur. **Fait** : `setError("")` met `errEl.hidden = true` ; la règle CSS `.error-msg[hidden] { display: none; margin: 0; padding: 0; min-height: 0; }` garantit l’absence d’emprise au layout.

### Actions

1. **Barre** : Isoler la barre dans des composants ou n’actualiser que les nœuds dynamiques (indicateurs, icônes) au lieu de recréer toute la barre à chaque rendu.
2. **Onglets** : Supprimer ou ne pas afficher de titres d’onglets « Carte du zoo » / « Carte du monde » si présents ; garder uniquement le sélecteur icônes.
3. **Erreur** : S’assurer que le message d’erreur est caché (et n’occupe pas d’espace) quand `errorMsg` est vide.

**Fichiers concernés :** `web/js/ui.js`.

---

## 7. Animaux – Feedbacks visuels, morts, saisons (§12)

### Écarts

- **Feedbacks visuels (§12)** : Froid (bleuâtre, givre), chaud (rougeâtre, vapeur), faim (lent, maigre, icône), maladie/mort proche (couché, ternes, mouches), heureux/reproduction (cœurs, couleurs vives). Pas de jauges. Non implémenté côté rendu.
- **Mort (§12)** : Toutes les causes listées (seuls, pas visités, nourriture, tué autre zoo, recherche trop basse, bébé non vendu à temps, bébé mature non placé à temps, animal accueil non placé à temps, vente échouée, température/milieu en écart). Partiellement implémentées ; recensement dans `docs/features/causes-mort-audit.md`.
- **Saisons (§12)** : Les 4 saisons influencent météo, température, bonus/malus reproduction et survie. Non implémenté.

### Actions

1. **Feedbacks** : Définir les états visuels des animaux (froid, chaud, faim, maladie, heureux) à partir des données déjà calculées (température, nourriture, visite, etc.) et adapter le rendu (CSS, teintes, icônes) sans ajouter de jauges.
2. **Morts** : Auditer les causes de mort dans le code et les comparer à la liste du §12 ; implémenter les manquantes (délais bébé mature / accueil / vente échouée, température/milieu, etc.).
3. **Saisons** : Introduire une notion de saison (Printemps, Été, Automne, Hiver) liée au temps de jeu ou à la date ; faire évoluer météo, température et formules de reproduction/survie selon la saison.

**Fichiers concernés :** `web/js/loot-tables.js`, `web/js/game-loop.js`, `web/js/income.js` (ou modules nourriture/visiteurs), `web/js/ui.js` (rendu animaux), `web/js/config.js`, `web/js/types.js`.

---

## 8. Billeterie – Flux explicite (§7, §10)

### Écart

- Le cahier indique que la **billeterie** (entrée des visiteurs, 20 visiteurs/unité) et le flux arrivée/départ/retour selon l’attraction sont **non implémentés** (§7). Le code a déjà une capacité billeterie et un plafond de visiteurs ; le flux « entrée par la billeterie, départ avant fin de journée, retour selon attraction » reste à préciser et à coder.

### Actions

1. Clarifier le **design** : arrivée des visiteurs depuis les villes → billeterie (cap), durée max 1 journée, départ par la billeterie, retour selon attractivité.
2. Implémenter le flux dans le module visiteurs / income : génération des arrivées, suivi du temps passé, départ, et réinjection selon attractivité (en lien avec phase Villes si besoin).

**Fichiers concernés :** `web/js/income.js`, `web/js/config.js`, `docs/features/` (fiche billeterie).

---

## 9. Références et cohérence

- **Règles économie (§1)** : Compatibilité anciennes sauvegardes (animal inconnu → c0_r0, œuf inconnu → Color_1) : déjà gérée dans `normalizeLoadedCells` / loadState.
- **Sécurité (§1)** : Pas de confiance au client, limitation fréquence, traçabilité : à garder en tête pour toute évolution API/serveur.
- **BDD et comptes** : Rester aligné avec `docs/bdd-comptes.md` pour tout changement de schéma ou de flux 401/404/200.

---

## 10. Ordre recommandé des mises à jour

1. **Grille au lancement + 3 couples reproducteurs** (§1, §10) – prérequis pour un démarrage conforme.
2. **Ventes – validation différée + sablier** (§13) – changement métier important et visible.
3. **Mode automatique – 50 profils et UI hiérarchique** (§5) – grosse évolution UX et données.
4. **Visitor.MaxSecondsWithoutVisit + disparition animaux** (§2) – rapide si la boucle de jeu existe déjà.
5. **Interface – barre non reconstruite, erreur masquée** (§4) – rapide.
6. **Villes – formule attraction + cases** (§3, §11) – voir `docs/features/villes-phase11.md`.
7. **Stagnation** (§3) – après ou avec le module visiteurs.
8. **Incidents visiteurs + invités de luxe** (§2) – après flux visiteurs stable.
9. **Feedbacks visuels animaux + causes de mort manquantes** (§12) – progressif.
10. **Saisons** (§12) – après température/milieu et reproduction.
11. **Billeterie – flux complet** (§7, §10) – après design validé.

Ce plan peut être découpé en fiches `docs/features/` ou en issues par bloc, et réordonné selon les priorités du projet.
