docs: enrich docs/specs and remove placeholders

**Motivations:**
- Make docs/specs implementation-ready without empty sections or placeholders.

**Root causes:**
- Multiple specs still contained non-actionable placeholders (N/A, “see above”, "..."), and inconsistent “no cache” wording.

**Correctifs:**
- Replace placeholders with explicit tables, structures, and typed examples.
- Align “no cache / no memorization” statements where relevant.

**Evolutions:**
- Add a features doc entry to track the documentation enrichment effort.

**Pages affectées:**
- docs/specs/*
- docs/features/docs-specs-enrichment.md
- docs/leo.md
- docs/plan-enrich-docs-specs.md
This commit is contained in:
2026-03-05 03:08:15 +01:00
parent e92c1355d0
commit 5143a79890
44 changed files with 1361 additions and 319 deletions

View File

@@ -18,8 +18,10 @@
- **Optimisation** : Culling (ne pas rendre ce qui est hors écran).
### Infrastructure
- **Cache** : Redis (pour les sessions, les compteurs temps réel et les files d'attente de jobs).
- **Message Broker** : BullMQ (Redis) ou RabbitMQ pour les tâches asynchrones (morts, naissances, enchères).
- **Cache** : Interdit (aucun cache applicatif, aucune mémorisation). Les lectures doivent refléter létat courant calculé/stocké, sans couche de cache.
- **Queue / Jobs** : File de tâches sans cache.
- Option A : RabbitMQ (messages durables) pour les tâches asynchrones (morts, naissances, enchères).
- Option B : Jobs en base PostgreSQL (table `jobs` + workers) avec verrous transactionnels (SKIP LOCKED) pour éviter les doubles traitements.
---
@@ -44,9 +46,9 @@ CREATE TABLE animals (
zoo_id UUID REFERENCES zoos(id),
type VARCHAR(50),
birth_date TIMESTAMPTZ,
state JSONB, -- { health, hunger, stress, ... }
genetics JSONB, -- { color, rarity, parents... }
position JSONB -- { x, y }
state JSONB, -- { health, hunger, stress, happiness, lastFedAt, lastVisitedAt }
genetics JSONB, -- { color, rarity, parents, mutations, lineageId }
position JSONB -- { x, y, iso_x, iso_y, z_index }
);
```
@@ -73,7 +75,9 @@ Calculer l'état d'un zoo **uniquement quand c'est nécessaire** (lecture par le
### Exceptions (Workers)
Certains événements doivent arriver même si le joueur est hors ligne (ex: Enchères, Morts impactant le marché).
* Utiliser des **Cron Jobs** ou des **Delayed Jobs** (Redis) pour traiter ces événements spécifiques à leur heure d'échéance prévue.
* Utiliser des **Cron Jobs** ou des **Delayed Jobs** sans cache pour traiter ces événements à lheure déchéance prévue.
* Option A : messages planifiés via RabbitMQ (plugin de scheduling si utilisé).
* Option B : table PostgreSQL `jobs` (colonnes `run_at`, `locked_at`, `attempts`, `last_error`) + worker(s) avec `SELECT FOR UPDATE SKIP LOCKED`.
---
@@ -93,7 +97,7 @@ Certains événements doivent arriver même si le joueur est hors ligne (ex: Enc
### Système
- `POST /api/auth/login` : Authentification par clé.
- `GET /api/config` : Récupère les tables statiques (Animaux, Coûts, Saisons) pour le cache client.
- `GET /api/config` : Récupère les tables statiques (Animaux, Coûts, Saisons) pour initialiser le client, sans mécanisme de cache applicatif.
# Annexes UX/UI
@@ -112,19 +116,19 @@ Certains événements doivent arriver même si le joueur est hors ligne (ex: Enc
**Description UI** : Écran de chargement avec barre de progression ou animation (Animal qui marche).
**Emplacement** : Plein écran (Démarrage).
**Intégration** : Bloquant.
**Navigation** : N/A
**Navigation** : Aucune (écran dattente avant accès au jeu).
**Événements** : `APP_LOAD`.
#### Assets
- **Musiques** : Thème Principal.
- **Sons** : N/A
- **Sons** : `ui_loader_tick.mp3` (boucle courte et discrète), `ui_loaded_pop.mp3` (fin de chargement).
- **Graphiques** : Logo Jeu.
- **Images** : N/A
- **Vidéos** : N/A
- **Images** : `loading_mascot.png` (mascotte), `loading_background.png` (fond).
- **Vidéos** : `loading_anim.webm` (animation courte, loop).
- **Animations** : Loader.
- **Couleurs** : Thème Jeu.
- **Textes** : "Calcul de la simulation...", "Rattrapage du temps...".
- **Formes** : N/A
- **Textes** : "Calcul de la simulation", "Rattrapage du temps".
- **Formes** : Cercle (spinner), barre (progress).
### Erreur Connexion (Feedback)
**Description UX** : Perte de connexion ou erreur API.
@@ -135,12 +139,12 @@ Certains événements doivent arriver même si le joueur est hors ligne (ex: Enc
**Événements** : `NETWORK_ERROR`.
#### Assets
- **Musiques** : N/A
- **Musiques** : Ducking du thème principal (-6 dB) pendant laffichage de lerreur.
- **Sons** : `error.mp3`.
- **Graphiques** : Icône Wifi barré.
- **Images** : N/A
- **Vidéos** : N/A
- **Images** : `icon_wifi_off.png`, `modal_error_bg.png`.
- **Vidéos** : `network_error_glitch.webm` (optionnel, 0.8s loop).
- **Animations** : Secousse.
- **Couleurs** : Rouge.
- **Textes** : "Connexion perdue".
- **Formes** : N/A
- **Formes** : Rectangle arrondi (modal), toast (pill).