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é

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).