Flux métier

Cette section suit les sept parcours principaux de BlockLucky à travers le code, du clic dans l'application jusqu'à la base de données et à la blockchain. Chaque page contient un diagramme de séquence, puis une explication pas à pas qui cite les fichiers et les fonctions réellement appelés, les erreurs possibles avec leur code HTTP et la manière dont le flux résiste aux doublons.

Toutes les pages décrivent le mode BLOCKCHAIN_MODE=onchain, celui de la production et de Docker Compose. Les différences du mode simulated sont signalées à la fin de chaque page concernée.

#Carte des flux

#Vue d'ensemble de la loterie

Les quatre flux de la loterie s'enchaînent autour du cycle de vie d'un tour dans le contrat :

stateDiagram-v2
  [*] --> Open: _openRound
  Open --> Open: buyTickets, buyTicketsFor
  Open --> Drawing: requestDraw
  Drawing --> Completed: fulfillRandomWords
  Drawing --> Drawing: retryDraw après drawTimeout
  Open --> Cancelled: closeExpiredRound ou cancelRound
  Drawing --> Cancelled: cancelRound
  Completed --> [*]
  Cancelled --> [*]

Chaque passage à Completed ou Cancelled ouvre immédiatement le tour suivant (_openRound) dans la même transaction. La base suit ces états avec l'énumération Status : OPEN, LOCKED (pour Drawing), COMPLETED, CANCELLED. Le détail du contrat est dans Cycle de vie d'un tour.

#Principes communs

#Chaîne d'une requête

Toutes les requêtes HTTP traversent la même chaîne, montée dans backend/src/app.ts : contexte de requête, métriques, Helmet, CORS, parsing JSON, mode maintenance, rate limit global (300 requêtes par 15 minutes et par IP), puis le routeur du module. Dans le routeur, l'ordre est toujours :

authenticate -> requireRoles ou requireAgeVerification -> idempotency -> validate -> controller -> service -> repo ou passerelle

Le controller appelle un service, puis répond avec sendSuccess. Toute exception remonte par next(error) jusqu'à errorHandler (backend/src/middlewares/error.middleware.ts). Voir Réponses et erreurs.

#Erreurs communes à tous les flux

#Erreurs du contrat

La passerelle backend/src/blockchain/lottery.gateway.ts décode l'erreur personnalisée renvoyée par le contrat (decodeContractError) et la traduit par toAppError :

Les détails (contractError, canRetry, circuitBreaker) sont renvoyés dans le champ errors de la réponse. Les clients web et mobile s'en servent pour proposer de réessayer ou afficher le disjoncteur.

#Idempotence

Trois mécanismes complémentaires protègent contre les doublons :

#Temps réel

Deux événements produits par ces flux sont relayés du worker vers l'API par Redis pub/sub : points:awarded (achat) et draw:winner (tirage). Ils sont diffusés à tous les clients connectés, invités compris. Voir Relais temps réel.

#Tests qui couvrent ces flux