Conventions de code

Cette page décrit les conventions telles qu'elles sont appliquées dans le code et dans les fichiers de configuration du dépôt. Elle ne prescrit rien qui ne soit déjà observable. Les règles de contribution (branches, revues, commits) sont dans Standards de code et Workflow Git. Les conventions de nommage des fichiers et des identifiants sont dans Organisation du dépôt.

#Mise en forme

Le backend et le frontend web n'ont pas de configuration Prettier ni de commande de formatage. Le style y est néanmoins homogène : guillemets simples, points-virgules, virgules finales dans les listes et objets multilignes. Les fichiers Solidity sont indentés de 4 espaces, contrairement à la règle de .editorconfig, et utilisent des guillemets doubles.

#TypeScript

Tous les projets TypeScript sont en mode strict.

Conséquences visibles dans le code :

• exactOptionalPropertyTypes explique les écritures conditionnelles comme ...(data.email ? { email: data.email } : {}) dans backend/src/api/auth/auth.repo.ts, au lieu de passer email: undefined.
• noUncheckedIndexedAccess impose de vérifier les éléments de tableau : const purchase = purchases[0]; if (!purchase) throw ... dans backend/src/blockchain/lottery.gateway.ts.
• Le type any est autorisé par les trois configurations ESLint. Il apparaît surtout pour passer le client ioredis à BullMQ (connection: rawRedis as any) et pour les métadonnées JSON de Prisma.

#ESLint

La règle no-floating-promises impose que toute promesse soit attendue ou explicitement ignorée par void. D'où les appels comme void lotteryIndexer.syncOnce() dans backend/src/blockchain/lottery.keeper.ts ou void redis.set(...) dans backend/src/middlewares/idempotency.middleware.ts. Une promesse lancée volontairement sans attente porte un .catch qui journalise, comme walletService.grantWelcomeEthers(user).catch(...) dans backend/src/api/auth/auth.services.ts.

#Absence de commentaires

Le code livré ne contient pas de commentaires explicatifs : c'est une règle de CONTRIBUTING.md, et elle est respectée. Les noms de fonctions, de variables et de tests portent l'intention. Les seules exceptions observées sont fonctionnelles :

Les contrats n'ont pas de NatSpec (use-natspec désactivée). Leur documentation est dans Référence de BlockLucky.

#Découpage du backend

Chaque domaine de backend/src/api/ suit le même découpage en cinq fichiers. Le module lottery sert d'exemple.

Exemple de chaîne complète tiré de backend/src/api/lottery/lottery.routes.ts :

router.post(
  '/buy',
  authenticate,
  idempotency,
  validate(buyTicketSchema),
  (req, res, next) => lotteryController.buyTicket(req, res, next)
);

Et le controller correspondant, dans backend/src/api/lottery/lottery.controllers.ts :

public async buyTicket(req: Request, res: Response, next: NextFunction): Promise<void> {
  try {
    const userId = req.user?.userId;
    if (!userId) throw new AppError('Authentification requise', 401);
    const result = await lotteryService.buyTickets(userId, req.body);
    sendSuccess(res, result, 'Ticket acheté avec succès', 201);
  } catch (error) {
    next(error);
  }
}

Chaque fichier de couche se termine par l'export d'une instance unique, nommée et par défaut :

export const lotteryController = new LotteryController();
export default lotteryController;

Les modules importent ces instances par leur export par défaut (import lotteryService from './lottery.services'). Le même modèle s'applique aux services transverses de backend/src/services/ et aux composants de backend/src/blockchain/. Les modules system et webhooks sont plus courts : pas de repository, et system n'a pas de controller.

L'ordre des middlewares dans une route est constant : authenticate, requireRoles(...), idempotency, validate(schema). Un routeur entièrement réservé à un rôle applique les deux premiers une fois pour toutes, comme router.use(authenticate, requireRoles('ADMIN')) dans backend/src/api/admin/admin.routes.ts.

#Réponses et erreurs

#Réponse de succès

sendSuccess(res, data, message, statusCode, meta) (backend/src/utils/response.util.ts) produit toujours la même enveloppe, typée par ApiResponse (backend/src/types/api.types.ts) :

{
  "success": true,
  "message": "Ticket acheté avec succès",
  "data": { "tickets": [], "pointsAwarded": 50 },
  "meta": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
}

data et meta sont omis quand ils sont absents. meta est construit par buildPaginationMeta (backend/src/utils/pagination.util.ts) pour les listes paginées. Le message est une phrase en français destinée à l'utilisateur. Le statut par défaut est 200 ; les créations répondent 201.

Les exceptions à l'enveloppe sont les sondes (/health/*), /api/config (qui construit l'enveloppe à la main), /metrics et les métadonnées POAP (/lottery/poap/:file), qui doivent respecter le format ERC-721.

#Réponse d'erreur

Une erreur métier est levée par throw new AppError(message, statusCode, details). Le statut par défaut est 400. details est facultatif et sert à transmettre des informations exploitables par les clients, comme { canRetry: true } ou { contractError: 'RoundSoldOut' }.

errorHandler (backend/src/middlewares/error.middleware.ts) transforme toute erreur en réponse par sendError :

{
  "success": false,
  "message": "Tous les tickets de ce tour ont été vendus.",
  "errors": { "contractError": "RoundSoldOut" }
}

Les middlewares qui refusent une requête (authenticate, requireRoles, validate, idempotency) appellent sendError directement sans lever d'exception. Le détail complet est dans Réponses et erreurs.

#Nommage dans le code

Un seul écart a été relevé : la méthode CancelAndAutoRefundRound de backend/src/api/lottery/lottery.services.ts commence par une majuscule.

Les noms du code sont en anglais ; les messages destinés aux utilisateurs, les journaux et les segments d'URL du frontend web sont en français.

#Autres pratiques observées

• Configuration. Aucun fichier de backend/src/ ne lit process.env en dehors de backend/src/config/env.config.ts. Tout passe par l'objet env validé par Zod. Côté clients, les variables publiques sont lues dans frontend-web/src/lib/config.ts et mobile-app/src/services/api.client.ts.
• Délais. Chaque appel sortant a un délai : RPC 15 s (backend/src/blockchain/chain.client.ts), SMTP 10 s pour la connexion et 20 s pour la socket (backend/src/config/mailer.config.ts), S3 3 s et 10 s, Redis 500 ms, requêtes PostgreSQL DB_STATEMENT_TIMEOUT_MS (15 s), clients HTTP web et mobile 15 s.
• Journaux. Le backend n'utilise jamais console : tout passe par le logger winston de backend/src/utils/logger.util.ts, qui ajoute requestId et userId depuis le contexte de requête et écrit en JSON hors développement.
• catch vides. Ils sont autorisés par ESLint et utilisés pour les replis volontaires, par exemple la bascule vers la mémoire locale dans backend/src/config/redis.config.ts ou la bascule vers l'envoi direct dans backend/src/queues/emails.queue.ts.
• Montants. Les montants en ethers circulent en bigint de wei dans le code blockchain et sont convertis par formatEther seulement pour l'affichage ou la base (prizePool en ETH).
• Adresses. Les adresses Ethereum sont toujours stockées et comparées en minuscules (toLowerCase()).