Conventions de code

Résumé opérationnel des conventions du backend. La source de vérité complète est CONVENTIONS.md dans le dépôt.

TypeScript

• strict: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true.
• Pas de any sans commentaire justifiant (// any justifié : …).
• Pas de as sans justification, sauf as const.
• Préférer type à interface (sauf extension), et les imports nommés aux exports par défaut.

Nommage

Élément	Convention	Exemple
Fichier / dossier	kebab-case	create-session.ts
Classe / type	PascalCase	PaymentSession, SessionRepository
Fonction	camelCase	createSession
Constante globale	UPPER_SNAKE	MAX_LEGS_PER_SESSION
Port	suffixe par rôle, pas de I	SessionRepository
Use case	verbe au début	CreateSession, SubmitSession
Schéma Zod	suffixe Schema	CreateSessionSchema
Test	même nom que le fichier testé	create-session.test.ts

Structure d’un use case

Injection par constructeur, méthode execute(input) :

export class CreateSession {
  constructor(
    private readonly sessions: SessionRepository,
    private readonly clock: Clock,
    private readonly ids: IdGenerator,
  ) {}

  async execute(input: CreateSessionInput): Promise<PaymentSession> { /* … */ }
}

Structure d’un handler HTTP

Trois étapes seulement : parse (Zod) + appel use case + sérialise. Aucune logique métier, aucun try/catch dans le handler (l’error handler global s’en charge).

Montants & dates

• Montants : entiers en centimes, jamais de flottant.
• Dates dans les schémas HTTP : chaîne ISO 8601, jamais un objet Date.

Erreurs

• Jamais throw new Error('texte') dans le domaine → toujours une sous-classe de DomainError avec un code stable.
• Jamais de try/catch dans les handlers.
• « Introuvable » = retour null, pas une exception.
• Toujours un code machine stable dans les réponses d’erreur HTTP.

Tests

• Vitest partout. Unitaires à côté du code (*.test.ts), intégration dans tests/integration/.
• Convention AAA (Arrange / Act / Assert), un test = un comportement.
• Pas de mocks globaux : injection par constructeur, fixtures typées dans tests/fixtures/.

Secrets, logs, format

• process.env lu uniquement dans src/config/index.ts, validé par Zod (voir Configuration).
• Logs pino JSON, avec masquage des champs sensibles. Jamais de PAN/CVV/token en clair.
• Biome gère format + lint (pas ESLint/Prettier).

Commits

Conventional Commits, une langue choisie et tenue dans la durée :

feat(sessions): add create session use case
fix(outbox): retry backoff capped at 5 minutes
docs(readme): clarify phase 1 scope

Source de vérité : CONVENTIONS.md. Voir aussi Architecture hexagonale.