builazoo/docs/plan-enrich-docs-specs.md

Plan Cursor (Cas A) — Exécution “build-ready” : enrichir docs/specs/ sans suppression

Référence direction artistique : docs/specs/IMG_20260303_170253.jpg.

Objectif exécutable

Enrichir tous les fichiers docs/specs/*.md pour qu’ils soient “prêts à coder” (règles, données, cas limites, UX/UI), en garantissant :

• Aucune suppression de rubriques existantes (même vides).
• Aucune renommage / réordonnancement de la structure.

Règles immuables (garde-fous)

• Ne supprimer aucun titre / sous-titre / tableau / section, même si vide.
• Ne pas renommer les rubriques.
• Si une section existe déjà mais est faible : enrichir dans la même section.
• Si une section existe en doublon : conserver les deux, enrichir, ajouter une ligne de clarification (“complément / fait foi”).
• Intégrer partout où pertinent la contrainte isométrique 2.5D (grille losange, sprites 4 directions, occlusion, z_index, hitbox base sprite).
• Ne pas déclencher de build/checks sans validation explicite “OK build”.
• Ne pas committer sans validation explicite du message de commit.

Definition of Done (DoD) — par fichier

Un fichier est “Done” si :

• Structure intacte (rubriques identiques à avant).
• Tous les placeholders évidents (N/A, ..., “voir ci-dessus” non actionnable) ont été remplacés par des détails implémentables.
• Les tableaux ont unités, plages, règles de cumul, caps/planchers si la rubrique existe.
• Si un modèle de données existe : il contient id, created_at, updated_at, types/enums, et les champs isométriques si entité visuelle (grid, iso_x, iso_y, z_index, hitbox).
• Si UX/UI existe : interactions (clic base sprite), feedback hover/selection, assets, événements, messages i18n (clés FR/EN).

Protocole exécutable (à dérouler mécaniquement)

Étape 0 — Pré-scan global

• Rechercher N/A dans docs/specs/ et obtenir la liste des fichiers impactés.
• Rechercher ... / placeholders de structure (“[ ... ]”, “voir ci-dessus”) dans docs/specs/.
• Classer les fichiers en 5 lots (A→E) ci-dessous.

Critère de sortie Étape 0 : liste des fichiers à corriger par placeholder, et ordre de traitement.

Étape 1 — Traitement par lots (ordre strict)

Lot A — Fondations carte / iso / rendu

Objectif : tout ce qui touche à grille, cases, enclos, chemins, ponts, profondeur.

• Traiter chaque fichier du lot A en suivant “Procédure par fichier”.

Critère de sortie Lot A : champs transverses iso (grid, iso_x, iso_y, z_index, hitbox) cohérents entre ces fichiers.

Lot B — Entités vivantes

Objectif : visiteurs, animaux, bébés, reproduction, mort, besoins.

• Traiter chaque fichier du lot B en suivant “Procédure par fichier”.

Critère de sortie Lot B : cycles de vie, seuils, impacts et événements cohérents entre fichiers (ex. reproduction ↔ saisons ↔ température).

Lot C — Bâtiments & services

Objectif : boutique, billeterie, nurserie, accueil, camion, centre recherche, labo.

• Traiter chaque fichier du lot C en suivant “Procédure par fichier”.

Critère de sortie Lot C : capacités, files d’attente, dépenses/recettes, préconditions, erreurs, interactions UI codables.

Lot D — Économie & méta

Objectif : scores, attractivité, enchères, ventes, upgrades, skins/themes/passes/VIP, inventaires, menu achats.

• Traiter chaque fichier du lot D en suivant “Procédure par fichier”.

Critère de sortie Lot D : toutes les mécaniques ont unités, formules, règles de cumul, caps/planchers et messages UX.

Lot E — Inventaires & tables de référence

Objectif : saisons, météo, températures, milieux, quêtes, problèmes visiteurs, heures.

• Traiter chaque fichier du lot E en suivant “Procédure par fichier”.

Critère de sortie Lot E : tables de ref complètes (enums/ranges/priorités) et réutilisées par les autres specs.

Procédure par fichier (checklist atomique)

Pour chaque fichier .md ciblé :

• Lire le fichier en entier.
• Vérifier la liste des rubriques existantes (ne rien supprimer).
• Remplacer chaque occurrence de N/A par un contenu implémentable (valeurs, conditions, règles, assets).
• Remplacer chaque placeholder de structure (..., [ ... ]) par un exemple complet cohérent.
• Compléter les tableaux : unités, plages, cumul, caps/planchers, préconditions, postconditions.
• Compléter les interactions : erreurs (fonds insuffisants, inventaire plein, placement invalide), cas limites (pathfinding bloqué, occlusion, click ambiguity).
• Si la rubrique JSON existe : ajouter/normaliser id, timestamps, enums, et champs iso si entité visuelle.
• Si UX/UI existe : préciser hitbox base sprite, feedback hover/selection, Z-order, assets, events, messages i18n FR/EN.
• Vérifier qu’aucun titre/sous-titre n’a disparu.

Critère de sortie du fichier : DoD “par fichier” satisfait.

Étape 2 — Contrôle final global

• Vérifier cohérence des champs transverses (id, created_at, updated_at, owner_id, grid, iso_x, iso_y, z_index, status_flags).
• Vérifier cohérence des événements/messages (noms, niveaux, conditions).
• Vérifier conformité aux règles projet (ex. interdiction de cache dans les specs).

Commit et checks (gated)

• Préparer le message de commit au format imposé (**Motivations:**, **Root causes:**, **Correctifs:**, **Evolutions:**, **Pages affectées:**) et demander validation.
• Ne pas committer sans validation explicite.
• Ne pas exécuter de build/checks sans “OK build”.

Mapping des lots (ordre recommandé)

• Lot A : carte_zoo.md, case_generique.md, case_zoo.md, enclos.md, chemin.md, pont.md, affiche_enclos.md, objet_enclos.md, tech_architecture.md
• Lot B : animal_generique.md, bebe_animal.md, visiteur.md, reproduction.md, mort_bebe.md, temperature.md, milieu.md, etat.md
• Lot C : boutique.md, billeterie.md, nurserie.md, accueil_animaux.md, camion.md, centre_recherche.md, laboratoire.md
• Lot D : score_reputation.md, score_survie.md, attractivite_interne_zoo.md, attractivite_zoo_sur_ville.md, enchere_generique.md, vente_animal.md, vente_enchere_animal.md, vente_enchere_bebe.md, achat_upgrade_*.md, inventaire_animaux.md, inventaire_bebe_animaux.md, menu_achats.md, skin.md, theme.md, passe_saisonnier.md, vip.md, inventaire_skins.md, joueur.md, personnage_generique.md, bot.md, zoo.md
• Lot E : inventaire_saisons.md, inventaire_meteos.md, inventaire_temperatures.md, inventaire_milieux.md, inventaire_quetes.md, inventaire_problemes_visiteurs.md, inventaire_heures.md, carte_monde.md, carte_generique.md, case_monde.md, site_generique.md, agrandissement_carte.md

Checklist exhaustive — fichiers docs/specs/ à enrichir (sans suppression)

• docs/specs/accueil_animaux.md
• docs/specs/achat_upgrade_boutique.md
• docs/specs/achat_upgrade_camion.md
• docs/specs/achat_upgrade_case.md
• docs/specs/achat_upgrade_case_zoo.md
• docs/specs/achat_upgrade_centre_recherche.md
• docs/specs/achat_upgrade_generique.md
• docs/specs/achat_upgrade_nurserie.md
• docs/specs/affiche_enclos.md
• docs/specs/agent_securite.md
• docs/specs/agrandissement_carte.md
• docs/specs/animal_generique.md
• docs/specs/artiste.md
• docs/specs/attractivite_interne_zoo.md
• docs/specs/attractivite_zoo_sur_ville.md
• docs/specs/avatar_joueur.md
• docs/specs/banderole_accueil.md
• docs/specs/bebe_animal.md
• docs/specs/billeterie.md
• docs/specs/bot.md
• docs/specs/boutique.md
• docs/specs/camion.md
• docs/specs/carte_generique.md
• docs/specs/carte_monde.md
• docs/specs/carte_zoo.md
• docs/specs/case_generique.md
• docs/specs/case_monde.md
• docs/specs/case_zoo.md
• docs/specs/centre_recherche.md
• docs/specs/chemin.md
• docs/specs/chercheur.md
• docs/specs/enchere_generique.md
• docs/specs/enclos.md
• docs/specs/etat.md
• docs/specs/impacts_generique.md
• docs/specs/inventaire_animaux.md
• docs/specs/inventaire_bebe_animaux.md
• docs/specs/inventaire_heures.md
• docs/specs/inventaire_meteos.md
• docs/specs/inventaire_milieux.md
• docs/specs/inventaire_problemes_visiteurs.md
• docs/specs/inventaire_quetes.md
• docs/specs/inventaire_saisons.md
• docs/specs/inventaire_skins.md
• docs/specs/inventaire_temperatures.md
• docs/specs/joueur.md
• docs/specs/laboratoire.md
• docs/specs/menu_achats.md
• docs/specs/milieu.md
• docs/specs/mort_bebe.md
• docs/specs/nourisseur.md
• docs/specs/nourriture_speciale.md
• docs/specs/nurserie.md
• docs/specs/objet_enclos.md
• docs/specs/passe_saisonnier.md
• docs/specs/personnage_generique.md
• docs/specs/pont.md
• docs/specs/reproduction.md
• docs/specs/score_reputation.md
• docs/specs/score_survie.md
• docs/specs/site_generique.md
• docs/specs/skin.md
• docs/specs/soigneur.md
• docs/specs/tech_architecture.md
• docs/specs/temperature.md
• docs/specs/theme.md
• docs/specs/vente_animal.md
• docs/specs/vente_enchere_animal.md
• docs/specs/vente_enchere_bebe.md
• docs/specs/ville.md
• docs/specs/vip.md
• docs/specs/visiteur.md
• docs/specs/zoo.md