Ocelot - Museum Back End

Backend Fastify pour le musée avec authentification Discord OAuth2.

🚀 Installation

yarn install

📝 Scripts disponibles

• yarn dev - Démarre le serveur en mode développement avec rechargement automatique
• yarn start - Démarre le serveur en mode production (utilise Node.js 24 avec support TypeScript natif)
• yarn test - Lance les tests unitaires
• yarn test:watch - Lance les tests en mode watch (re-exécution automatique)
• yarn docs - Génère la documentation OpenAPI/Swagger (JSON, YAML et HTML) à partir des fichiers .feature et des schémas Fastify
• yarn migrate - Applique toutes les migrations en attente
• yarn migrate:up - Applique les migrations en attente
• yarn migrate:down - Annule la dernière migration
• yarn migrate:create <nom> - Crée une nouvelle migration

🌐 Endpoints

Authentification

• GET /auth/signin - Redirige vers Discord OAuth2 pour l'authentification
• GET /auth/login - Alias de /auth/signin
• GET /auth/callback - Callback OAuth2 de Discord (échange le code contre un token)
• GET /auth/session - Vérifie l'état de la session (authentifié, refresh token disponible)
• GET /auth/me - Récupère les informations de l'utilisateur authentifié (gère automatiquement le refresh du token)

Paiement (SumUp)

• POST /pay/checkout - Crée un nouveau checkout SumUp
  • Body: { amount: number, currency?: string, description?: string, checkout_reference?: string }
  • Retourne: { checkout_id, checkout_reference, amount, currency, status }
• GET /pay/checkout/:checkoutId - Vérifie le statut d'un checkout SumUp
  • Retourne: { id, checkout_reference, amount, currency, status, payment_type?, transaction_code? }

⚙️ Configuration

Le serveur utilise les variables d'environnement suivantes (définies dans .env.local) :

Serveur

• PORT - Port d'écoute (défaut: 3000)
• HOST - Host d'écoute (défaut: 0.0.0.0)
• NODE_ENV - Environnement (development ou production)

CORS

• CORS_ORIGINS - Origines autorisées (séparées par des virgules, défaut: http://localhost:3000,http://localhost:4000)

Cookies

• COOKIE_SECRET - Secret pour signer les cookies (défaut: your-secret-key-change-in-production)
• COOKIE_DOMAIN - Domaine des cookies (optionnel, utilisé en production)

Discord OAuth2

• DISCORD_CLIENT_ID - ID du client Discord (requis)
• DISCORD_CLIENT_SECRET - Secret du client Discord (requis)
• DISCORD_REDIRECT_URI - URI de redirection OAuth2 (défaut: http://localhost:{PORT}/auth/callback)
• DISCORD_SCOPES - Scopes Discord demandés (défaut: identify email)
• REFRESH_TOKEN_MAX_AGE_DAYS - Durée de vie du refresh token en jours (défaut: 90)

Base de données PostgreSQL

• DATABASE_URL - URL de connexion PostgreSQL (format: postgresql://user:password@host:port/database)
  • Si configuré, les erreurs seront sauvegardées en base de données
  • Permet la détection de doublons pour éviter le spam sur Discord
• ERROR_DUPLICATE_WINDOW_HOURS - Fenêtre de temps (en heures) pour détecter les erreurs dupliquées (défaut: 1)

Monitoring & Erreurs

• DISCORD_LOG_WEBHOOK_URL - URL du webhook Discord pour recevoir les notifications d'erreurs (optionnel)
  • Si configuré, toutes les erreurs seront envoyées à Discord avec les détails (URL, méthode, IP, stack trace)
  • Les erreurs dupliquées (dans la fenêtre configurée) ne seront pas envoyées pour éviter le spam
  • Les réponses HTTP aux clients restent génériques (sans détails de l'erreur)

SumUp (Paiement)

• SUMUP_API_KEY - Clé API SumUp (requis pour les paiements)
• SUMUP_MERCHANT_CODE - Code marchand SumUp (requis pour les paiements)

Frontend

• FRONTEND_URL - URL du frontend pour les redirections (défaut: http://localhost:3000)

📁 Structure du projet

src/
├── features/
│   ├── auth/
│   │   ├── auth.ctrl.ts      # Contrôleur d'authentification
│   │   ├── auth.ctrl.test.ts # Tests unitaires
│   │   ├── auth.schemas.ts   # Schémas de validation Fastify
│   │   └── auth.types.ts     # Types TypeScript pour Discord
│   ├── docs/
│   │   └── docs.ctrl.ts      # Routes de documentation
│   ├── pay/
│   │   ├── pay.ctrl.ts       # Contrôleur de paiement SumUp
│   │   ├── pay.utils.ts      # Utilitaires pour l'API SumUp
│   │   ├── pay.schemas.ts    # Schémas de validation Fastify
│   │   └── pay.types.ts      # Types TypeScript pour SumUp
│   └── terror/
│       ├── error.handler.ts  # Gestionnaires d'erreurs Fastify
│       ├── error.service.ts  # Services de gestion d'erreurs (DB, Discord)
│       └── error.types.ts    # Types pour les erreurs
├── scripts/
│   └── generate-doc.ts       # Script de génération de documentation
└── server.ts                 # Point d'entrée du serveur
migrations/                   # Migrations de base de données
└── 001_create_errors_table.ts

🧪 Tests

Les tests utilisent l'API de test native de Node.js (node:test) avec les assertions natives (node:assert).

# Lancer tous les tests
yarn test

# Lancer les tests en mode watch
yarn test:watch

🔒 Sécurité

• Validation automatique des entrées avec JSON Schema
• Sérialisation optimisée des réponses
• Cookies HTTP-only et sécurisés en production
• Headers de sécurité (X-Content-Type-Options, X-Frame-Options, etc.)
• CORS configuré avec support des credentials

🛠️ Technologies

• Fastify 5.6.1 - Framework web rapide
• TypeScript 5.3.3 - Typage statique
• Node.js 24 - Support TypeScript natif
• PostgreSQL - Base de données relationnelle
• @fastify/postgres - Plugin PostgreSQL pour Fastify
• @fastify/cookie - Gestion des cookies
• @fastify/cors - Gestion CORS
• node-pg-migrate - Système de migrations pour PostgreSQL
• pino-pretty - Formatage des logs

📚 Documentation

La documentation API est générée automatiquement à partir des scénarios Gherkin/Cucumber (.feature.ts) et des schémas Fastify.

Générer la documentation

yarn docs

Cela génère :

• docs/openapi.json - Spécification OpenAPI en JSON
• docs/openapi.yaml - Spécification OpenAPI en YAML
• docs/index.html - Interface Swagger UI interactive (ouvrir dans un navigateur)

Visualiser la documentation

Ouvrez simplement docs/index.html dans votre navigateur pour accéder à l'interface Swagger UI interactive avec :

• Tous les endpoints documentés
• Les scénarios Gherkin intégrés comme descriptions
• La possibilité de tester les endpoints directement
• Les schémas de validation et exemples

🗄️ Base de données

Migrations

Les migrations sont gérées avec node-pg-migrate. Les fichiers de migration se trouvent dans le dossier migrations/.

Développement (utilise .env.local)

# Appliquer toutes les migrations en attente
yarn migrate

# Créer une nouvelle migration
yarn migrate:create nom_de_la_migration

# Annuler la dernière migration
yarn migrate:down

Production (utilise .env.prod)

# Appliquer toutes les migrations en attente sur la production
yarn migrate:prod

# Annuler la dernière migration en production
yarn migrate:prod:down

⚠️ Attention : Assurez-vous que le fichier .env.prod contient bien la DATABASE_URL de votre base de données de production avant d'exécuter les migrations.

Structure de la table errors

La table errors stocke toutes les erreurs avec :

• Informations sur l'erreur (nom, message, stack trace)
• Contexte (URL, méthode HTTP, IP)
• Hash unique pour détecter les doublons
• Statut d'envoi à Discord
• Timestamps de création et mise à jour

Ressources

• Fastify Documentation
• Discord OAuth2 Documentation
• Fastify Validation & Serialization
• OpenAPI Specification
• node-pg-migrate Documentation