builazoo/docs/features/ventes-encheres-phase10.md

Phase 10 – Ventes et enchères (bébés et animaux adultes)

Objectif : Mise en vente de bébés et d’animaux depuis le camion ; affichage des ventes sur la carte du monde ; expiration des annonces (bébé invendu meurt) ; enchères (offres joueurs/bots), validation par le vendeur, transfert vers l’acheteur (nurserie/accueil), persistance serveur (API/BDD).

Référence : docs/plan-implementation-rappel-grandes-regles.md phase 10.

Vérification des phases précédentes

Voir docs/plan-verification-phases-0-a-9.md. Les prérequis (4, 6, 7, 9) sont en place.

Impacts

• Glisser un bébé mature (nurserie) ou un animal prêt (accueil) sur la zone camion (vente) → l’entité est retirée de la nurserie/accueil et ajoutée à state.saleListings ; création côté serveur via POST /api/sales ; l’annonce apparaît sur la carte du monde dans la case du zoo joueur.
• Les annonces expirent après un délai configurable (côté client via tickSaleListings et côté serveur via expireSaleListings) ; si l’annonce concernait un bébé et n’a pas été vendue, le bébé est considéré mort (deathCountRecent incrémenté côté client et serveur).
• Enchères : les joueurs et les bots peuvent enchérir sur les ventes actives (POST /api/sales/:id/bid). Le vendeur peut accepter ou refuser la meilleure enchère (POST /api/sales/:id/accept, POST /api/sales/:id/reject). À l’acceptation, la vente passe en statut sold avec un délai de validation différée de 10 minutes : les pièces ne sont pas transférées immédiatement ; validated_at = now() + 10 min. Un traitement à la lecture (processValidatedSales) exécute le transfert (débit acheteur, crédit vendeur) et passe le statut à validated lorsque validated_at <= now(). L’acheteur ne peut « Récupérer » qu’après validation ; un sablier (compte à rebours) s’affiche pour les ventes en attente.

Modifications

• config.js : Sale.ListingDurationSeconds (3600), Sale.DefaultPrice (50).
• trade.js : addMatureBabyToSale, addReceptionAnimalToSale, tickSaleListings.
• game-loop.js : appel à tickSaleListings après tickReproduction.
• ui.js : zone camion (drop) crée la vente localement et appelle createSale si API configurée ; carte du monde : affichage des ventes (sync avec getSales() à l’ouverture) ; panneau « Mes ventes » (Accepter / Refuser), « À récupérer » (Récupérer), « Enchères » (saisie montant + Enchérir).
• types.js : SaleListing étendu avec serverId?, bestBidAmount?, bestBidderZooId?, status? ; GameState.salesFromApi? pour les données renvoyées par GET /api/sales.
• api-client.js : getSales(), createSale(payload), placeBid(listingId, amount), acceptSale(listingId), rejectSale(listingId), deliverSale(listingId).
• Serveur
  • server/migrations/001_sale_listings.sql : tables sale_listings (…), 002_sale_listings_validated_at.sql : colonne validated_at TIMESTAMPTZ, statut validated ajouté au CHECK.
  • server/db.js : mapSaleListingRow(row) centralise le mapping des lignes sale_listings (utilisé par getSaleListingById, getActiveSaleListings, getSalesForZoo). mapZooRowBase(row) pour zoos (getAllZoos, getZooById, getBotZoosForTick). validateListingForSeller(listingId, sellerZooId) pour les vérifications vendeur (acceptSale, rejectSale). … acceptSale (ne transfère plus les pièces ; pose sold_at, validated_at = now() + 10 min), processValidatedSales() (transfert et passage à validated), markSaleDelivered (exige status = 'validated').
  • server/routes/sales.js : GET /api/sales appelle processValidatedSales() avant getSalesForZoo si auth. Réponses incluent validated_at.
  • server/bot-tick.js : après expireSaleListings, récupération des ventes actives et enchère aléatoire d’un bot (si assez de pièces, pas vendeur).
• web : panneau « À récupérer » : sablier et compte à rebours (ex. « Validation dans X min ») pour les ventes status === 'sold' avec validated_at dans le futur ; bouton « Récupérer » désactivé jusqu’à validation. texts-fr.js : salesPendingValidation, salesValidationInMinutes.
• texts-fr.js : errorMessage.BabyNotMature, NoBabyInNursery, AnimalNotReady, NoAnimalInReception.
• web/css/main.css : styles .world-map-sales-panel, .sales-panel-title, .sales-panel-row, boutons Accepter/Refuser/Récupérer/Enchérir.

Modalités de déploiement

• Base de données : exécuter la migration server/migrations/001_sale_listings.sql, puis server/migrations/002_sale_listings_validated_at.sql (validation différée).
• Redémarrage serveur et rechargement client.

Modalités d’analyse

• Glisser un bébé mature / animal prêt sur la zone camion : annonce créée localement et sur le serveur (si API configurée) ; affichage sur la carte du monde.
• Ouvrir la carte du monde avec API + auth : getSales() est appelé ; panneau « Mes ventes », « À récupérer », « Enchères » affiché selon les données.
• Enchérir sur une vente active : saisir un montant > meilleure enchère puis « Enchérir ».
• En tant que vendeur : « Accepter » ou « Refuser » sur la meilleure enchère ; à l’acceptation, vente en statut sold, validated_at = now() + 10 min ; pas de transfert de pièces immédiat.
• En tant qu’acheteur ayant gagné une vente : affichage sablier « Validation dans X min » tant que validated_at > now() ; après 10 min, un prochain GET exécute processValidatedSales, la vente passe en validated, le bouton « Récupérer » s’active ; clic ajoute le bébé/animal à la nurserie/accueil puis appelle deliverSale.
• Expiration : après end_at, la vente passe en expired ; si bébé, deathCountRecent du vendeur incrémenté (GET /api/sales ou bot tick).
• Bots : à chaque tick, un bot peut placer une enchère sur une vente active (autre zoo, assez de pièces).

Phase suivante

Phase 11 – Villes : docs/features/villes-phase11.md.