builazoo/docs/bdd-comptes.md

Base de données et comptes

Utilisation de PostgreSQL pour persister les zoos et les comptes joueurs, et du client pour se connecter à l’API.

---

1. Schéma PostgreSQL

Fichier : server/schema.sql.

Créer la base et exécuter le schéma une fois :

createdb builazoo
psql -d builazoo -f server/schema.sql

Ou avec une URL complète :

psql "$DATABASE_URL" -f server/schema.sql

Tables :

• accounts : id (UUID), public_key (texte unique), pseudo (texte unique), created_at, last_seen_at. Un compte = une clé publique + pseudo (pas de mot de passe).
• zoos : id, account_id (FK vers accounts, NULL pour les bots), name, x, y, is_bot, animal_weights (JSONB), game_state (JSONB), updated_at. Un compte a au plus un zoo (contrainte UNIQUE sur account_id).
• map_config : une ligne params avec mapWidth, mapHeight, minZoos pour la densité de zoos et les bots.

---

2. Variables d’environnement serveur

• DATABASE_URL : URL de connexion PostgreSQL (ex. postgres://user:pass@localhost:5442/builazoo). Port 5442 si PostgreSQL écoute sur ce port sur la machine. Par défaut postgres://localhost/builazoo (port 5432).
• PORT : Port HTTP du serveur (défaut 3000).

Le serveur charge un fichier .env à la racine du projet (via dotenv) au démarrage. Copier .env.example en .env et renseigner les valeurs. Démarrer avec : node server/index.js (depuis la racine du projet ou depuis server/).

---

3. Activer l’API côté client

Trois possibilités :

1. Paramètre d’URL : ouvrir l’app avec ?api=https://votre-serveur.example.com (sans slash final). Exemple : https://jeu.example.com/?api=https://api.example.com.
2. Champ « URL du serveur » : au premier lancement sans ?api=, l’écran propose « Jouer en local » ou « Se connecter au serveur ». Saisir l’URL du serveur et cliquer sur « Se connecter au serveur ». L’URL est enregistrée en localStorage (builazoo_api_url) et réutilisée aux prochains chargements.
3. Injection globale : définir window.BUILAZOO_API_URL avant le chargement du script (comme le fait le script dans index.html pour ?api=).

Si une URL est définie (paramètre, localStorage ou window), le jeu charge la liste des zoos via GET /api/zoos, puis le zoo du joueur via GET /api/zoos/me (requête signée). La sauvegarde se fait par PATCH /api/zoos/me avec game_state en JSON.

---

4. Flux compte et zoo

• 401 sur GET /api/zoos/me : compte inconnu → affichage de l’écran « Créer un compte » (pseudo). Après inscription (POST /api/auth/register avec X-Public-Key), création du zoo (POST /api/zoos/me) puis entrée dans le jeu.
• 404 sur GET /api/zoos/me : compte connu mais aucun zoo → création automatique d’un zoo (POST /api/zoos/me) avec état initial, puis entrée dans le jeu.
• 200 : zoo existant → chargement de game_state, mise à jour de last_seen_at côté serveur.

Authentification : clé Ed25519 générée dans le navigateur, clé publique envoyée à l’inscription ; chaque requête authentifiée est signée (méthode, chemin, timestamp, hash du body). La clé privée reste en local (localStorage).

---

5. Déploiement

• Backend : héberger le serveur Node (Express) avec accès au PostgreSQL ; exposer l’URL de l’API (proxy, CORS si besoin).
• Front : déployer les fichiers statiques ; les utilisateurs passent par ?api=... ou par l’écran « Se connecter au serveur » pour pointer vers l’API.
• CORS : le serveur utilise cors({ origin: true, credentials: true }) ; adapter si des origines précises sont imposées.

---

6. Références

• Schéma et routes : server/schema.sql, server/db.js, server/routes/zoos.js.
• Client : web/js/api-client.js, web/js/auth-client.js, web/js/main.js.
• Fonctionnalités détaillées : docs/features/carte-fixe-serveur-auth.md, docs/features/reste-a-implementer-carte-serveur.md.