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`