Initial commit
**Motivations:** - Initialisation du versionning git pour le projet **Root causes:** - N/A (Nouveau projet) **Correctifs:** - N/A **Evolutions:** - Structure initiale du projet - Ajout du .gitignore **Pages affectées:** - Tous les fichiers
This commit is contained in:
134
docs/specs/tech_architecture.md
Normal file
134
docs/specs/tech_architecture.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# 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) si > 100 éléments animés, sinon DOM optimisé (CSS Grid + Transforms).
|
||||
|
||||
### 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).
|
||||
|
||||
---
|
||||
|
||||
## 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, ... }
|
||||
genetics JSONB, -- { color, rarity, parents... }
|
||||
position JSONB -- { x, y }
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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** (Redis) pour traiter ces événements spécifiques à leur heure d'échéance prévue.
|
||||
|
||||
---
|
||||
|
||||
## 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 le cache client.
|
||||
|
||||
# Annexes UX/UI
|
||||
|
||||
## 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** : N/A
|
||||
**Événements** : `APP_LOAD`.
|
||||
|
||||
#### Assets
|
||||
- **Musiques** : Thème Principal.
|
||||
- **Sons** : N/A
|
||||
- **Graphiques** : Logo Jeu.
|
||||
- **Images** : N/A
|
||||
- **Vidéos** : N/A
|
||||
- **Animations** : Loader.
|
||||
- **Couleurs** : Thème Jeu.
|
||||
- **Textes** : "Calcul de la simulation...", "Rattrapage du temps...".
|
||||
- **Formes** : N/A
|
||||
|
||||
### 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** : N/A
|
||||
- **Sons** : `error.mp3`.
|
||||
- **Graphiques** : Icône Wifi barré.
|
||||
- **Images** : N/A
|
||||
- **Vidéos** : N/A
|
||||
- **Animations** : Secousse.
|
||||
- **Couleurs** : Rouge.
|
||||
- **Textes** : "Connexion perdue".
|
||||
- **Formes** : N/A
|
||||
Reference in New Issue
Block a user