builazoo/docs/plan-action-cahier-des-charges.md

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.