builazoo/docs/specs/enchere_generique.md

# Spécifications : Enchère (Générique)

## Définition
Mécanisme de vente entre joueurs/bots sur la Carte du Monde.

## Fonctionnement
1.  **Mise en vente** : Le vendeur place un animal/bébé sur la case Camion/Vente de son zoo. Définit un prix initial.
2.  **Offre** : Visible sur la Carte du Monde (slot sous le zoo).
3.  **Enchères** : Les acheteurs (joueurs/bots) proposent des prix.
4.  **Validation** : Le vendeur accepte une offre ou laisse courir.
5.  **Sécurisation** : Une fois l'offre acceptée/validée, un **délai de 10 minutes** (Sablier) s'enclenche.
6.  **Finalisation** : À la fin du sablier, le transfert de propriété et de fonds est effectué (anti-race condition).

## Types
- Vente de Bébés
- Vente d'Animaux Adultes

# Annexes Techniques

## 1. Données et États
### Modèle de Données (JSON)
```json
{
  "id": "uuid",
  "seller_id": "uuid",
  "animal_ref": "uuid",
  "start_price": "integer",
  "current_bid": "integer",
  "highest_bidder_id": "uuid | null",
  "end_time": "timestamp",
  "status": "enum ('active', 'pending_validation', 'finalizing', 'completed', 'cancelled')",
  "finalization_timer": "timestamp (end)",
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Caractéristiques Initiales
**Durée par défaut** : 24h.

## 8. Logique et Interfaces
### Pseudo-code Impacts
```
function placeBid(auction, bidder, amount):
  if amount <= auction.current_bid: return Error
  if bidder.coins < amount: return Error

  auction.current_bid = amount
  auction.highest_bidder_id = bidder.id

function finalizeAuction(auction):
  if now < auction.finalization_timer: return

  transferCoins(auction.highest_bidder_id, auction.seller_id, auction.current_bid)
  transferAnimal(auction.seller_id, auction.highest_bidder_id, auction.animal_ref)
  auction.status = 'completed'
```

### Messages d'Infos / Alerte
| ID | Niveau | Message |
| :--- | :--- | :--- |
| `BID_PLACED` | Info | "Offre placée avec succès." |
| `OUTBID` | Alerte | "Vous avez été surenchéri !" |
| `AUCTION_WON` | Succès | "Vous avez remporté l'enchère ! Livraison en cours." |

# 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)
### Consultation des Offres (Consultation)
**Description UX** : Le joueur survole les zoos sur la carte du monde pour voir les offres.
**Description UI** : Tooltip ou Slot sous le zoo affichant l'icône de l'animal et le prix actuel.
**Emplacement** : Carte Monde.
**Intégration** : Overlay Zoo.
**Navigation** : Survol -> Info.
**Événements** : `HOVER_OFFER`.

#### Assets
- **Musiques** : `ui_market_hover.mp3` (jingle discret optionnel).
- **Sons** : `hover_soft.mp3`.
- **Graphiques** : Cadre Offre (Doré si rare).
- **Images** : Icône Animal.
- **Vidéos** : `offer_hover_glow.webm` (0.6s loop, optionnel).
- **Animations** : Prix qui clignote si nouvelle enchère.
- **Couleurs** : Vert (Abordable), Rouge (Trop cher).
- **Textes** : "Lapin Rare - 500$".
- **Formes** : Rectangle arrondi.

### Enchérir (Action)
**Description UX** : Le joueur clique sur une offre pour ouvrir le détail et placer une enchère.
**Description UI** : **Bottom Sheet** d'enchère. Infos complètes de l'animal. Champ de saisie "Votre offre" ou boutons rapides (+10, +50, +100).
**Emplacement** : Modal Enchère.
**Intégration** : Modal centrée.
**Navigation** : Clic Offre -> Modal -> Enchérir.
**Événements** : `PLACE_BID`.

#### Assets
- **Musiques** : `ui_market_bid.mp3` (jingle court).
- **Sons** : `bid_placed.mp3` (bruit de marteau).
- **Graphiques** : Icône Marteau.
- **Images** : Portrait Animal HD.
- **Vidéos** : `bid_counter_up.webm` (0.8s loop, optionnel).
- **Animations** : Compteur prix qui monte.
- **Couleurs** : Bouton Vert.
- **Textes** : "Enchérir".
- **Formes** : Boutons rapides (+10/+50/+100), champ numérique.

### Sablier de Validation (Attente)
**Description UX** : L'enchère est remportée, le transfert est en cours (10 min).
**Description UI** : Icône Sablier sur l'offre et dans le HUD de l'acheteur.
**Notification Push** : "Enchère remportée ! Animal livré." à la fin du timer.
**Emplacement** : Carte Monde & HUD.
**Intégration** : Statut "En cours".
**Navigation** : Clic sur sablier dans HUD → ouvre le détail transaction (temps restant, statut, destination).
**Événements** : `TIMER_START`.

#### Assets
- **Musiques** : `ui_timer_soft.mp3` (optionnel, très discret).
- **Sons** : `tick_tock.mp3` (ambiance très discrète si focus).
- **Graphiques** : Sablier animé.
- **Images** : `icon_hourglass.png`, `badge_pending.png`.
- **Vidéos** : `hourglass_flow.webm` (1s loop, optionnel).
- **Animations** : Sable qui coule.
- **Couleurs** : Orange.
- **Textes** : "Validation : MM:SS".
- **Formes** : Badge rond (HUD), icône sur slot.

### Activité "Clic" (Gameplay)
**Description UX** : Pendant les 10 min, le joueur peut cliquer sur le sablier pour "accélérer" (symboliquement) ou gagner un petit bonus (XP/Pièce) pour patienter.
**Description UI** : Le sablier réagit au clic (secousse).
**Emplacement** : Modal Validation.
**Intégration** : Mini-jeu.
**Navigation** : Clic Sablier.
**Événements** : `CLICK_HOURGLASS`.

#### Assets
- **Musiques** : `ui_click_reward.mp3` (jingle court).
- **Sons** : `sand_shake.mp3`. **Design ASMR** : Bruit de sable qui crisse ou petit choc mat.
- **Graphiques** : Particules de sable.
- **Images** : `sand_particle.png`.
- **Vidéos** : `hourglass_shake.webm` (0.5s non loop, optionnel).
- **Animations** : Secousse.
- **Couleurs** : Doré.
- **Textes** : "+1 XP".
- **Formes** : Bouton rond (tap cible), badge sablier (HUD).