builazoo/docs/specs/tech_architecture.md

# Spécifications Techniques : Architecture et Performance

## 1. Stack Technologique Recommandée

### Backend
- **Langage** : Node.js (TypeScript) ou Go (pour la performance brute des workers).
- **Framework** : NestJS (Node) ou Gin (Go).
- **Base de Données** : PostgreSQL.
  - Utilisation intensive du type `JSONB` pour les données flexibles (états animaux, génétique).
  - Indexation GIN sur les champs JSONB souvent requêtés.

### Frontend
- **Framework** : React ou Vue.js.
- **État** : Zustand ou Pinia (léger et performant).
- **Rendu Grille** : Canvas API (via PixiJS ou Konva) pour la **Vue Isométrique**.
  - Gestion de la profondeur (z-index) pour les bâtiments et animaux.
  - Système de tuiles (Tilemap) isométriques.
- **Optimisation** : Culling (ne pas rendre ce qui est hors écran).

### Infrastructure
- **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.

---

## 2. Modélisation des Données (Hybride Relationnel / Document)

L'approche hybride permet de garder l'intégrité référentielle sur les entités (Zoo, User) tout en gardant la souplesse sur les attributs de gameplay.

### Schéma SQL Simplifié

```sql
CREATE TABLE zoos (
  id UUID PRIMARY KEY,
  owner_id UUID NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  resources JSONB DEFAULT '{"coins": 200, "research": 0}',
  stats JSONB DEFAULT '{"reputation": 0, "survival": 100}',
  last_update TIMESTAMPTZ DEFAULT NOW() -- Clé pour le Lazy Update
);

CREATE TABLE animals (
  id UUID PRIMARY KEY,
  zoo_id UUID REFERENCES zoos(id),
  type VARCHAR(50),
  birth_date TIMESTAMPTZ,
  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 }
);
```

---

## 3. Stratégie de Performance : "Lazy Updates"

Le calcul temps réel pour 1000 joueurs * 50 animaux est impossible à scaler naïvement.

### Principe
Ne jamais mettre à jour la BDD à chaque seconde ("tick").
Calculer l'état d'un zoo **uniquement quand c'est nécessaire** (lecture par le joueur ou interaction).

### Algorithme de Mise à Jour Différée (Lazy Update)

1.  **État Stocké** : Le zoo est sauvegardé à `T0` avec `Faim = 10`.
2.  **Requête** : Le joueur se connecte à `T1` (2 heures plus tard).
3.  **Calcul à la Volée** :
    *   `Delta_Temps = T1 - T0`.
    *   `Faim_Actuelle = Faim_Initiale + (Vitesse_Faim * Delta_Temps)`.
    *   Appliquer les seuils (si Faim > 100, déclencher Mort).
4.  **Persistance** : Sauvegarder le nouvel état à `T1`.
5.  **Réponse** : Envoyer l'état à jour au client.

### 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** sans cache pour traiter ces événements à l’heure 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`.

---

## 4. API : Définition des Endpoints (REST)

### Core Loop (Jeu)
- `GET /api/zoo/me` : Récupère l'état complet du zoo (déclenche le Lazy Update).
- `POST /api/zoo/move` : Déplace un élément (Animal/Bâtiment).
  - Body: `{ "entity_id": "uuid", "x": 10, "y": 5 }`
- `POST /api/zoo/feed` : Nourrit les animaux (Global ou Ciblé).

### Économie & Marché
- `GET /api/market/auctions` : Liste les enchères actives (Filtres: Type, Rareté).
- `POST /api/market/bid` : Placer une offre.
  - Body: `{ "auction_id": "uuid", "amount": 500 }`
- `POST /api/market/sell` : Créer une enchère.

### Système
- `POST /api/auth/login` : Authentification par clé.
- `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

## 0. Direction Artistique & Vue
*   **Vue** : Isométrique (2.5D).
*   **Style** : Coloré, vivant, détails foisonnants (Réf: IMG_20260303_170253.jpg).
*   **Sprites** : 4 directions.
*   **Interactions** :
    *   **Sélection** : Cliquer sur la base de l'élément (ou son sprite principal) pour le sélectionner.
    *   **Feedback** : Surbrillance (outline blanc/jaune) au survol de la souris.


## 1. Expérience Utilisateur (UX)
### Chargement (Feedback)
**Description UX** : Le joueur attend le calcul du Lazy Update à la connexion.
**Description UI** : Écran de chargement avec barre de progression ou animation (Animal qui marche).
**Emplacement** : Plein écran (Démarrage).
**Intégration** : Bloquant.
**Navigation** : Aucune (écran d’attente avant accès au jeu).
**Événements** : `APP_LOAD`.

#### Assets
- **Musiques** : Thème Principal.
- **Sons** : `ui_loader_tick.mp3` (boucle courte et discrète), `ui_loaded_pop.mp3` (fin de chargement).
- **Graphiques** : Logo Jeu.
- **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** : Cercle (spinner), barre (progress).

### Erreur Connexion (Feedback)
**Description UX** : Perte de connexion ou erreur API.
**Description UI** : Toast ou Modal "Erreur Réseau". Bouton "Réessayer".
**Emplacement** : Overlay.
**Intégration** : Bloquant ou Non-bloquant.
**Navigation** : Clic Réessayer.
**Événements** : `NETWORK_ERROR`.

#### Assets
- **Musiques** : Ducking du thème principal (-6 dB) pendant l’affichage de l’erreur.
- **Sons** : `error.mp3`.
- **Graphiques** : Icône Wifi barré.
- **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** : Rectangle arrondi (modal), toast (pill).