Documentation Côté Serveur

Le serveur de jeu est construit selon une architecture orientée services, utilisant Node.js avec TypeScript. Il s'appuie principalement sur Socket.IO pour les communications en temps réel, Firebase (Authentication + Storage + Messaging) pour l'authentification, le stockage et les notifications, et MongoDB pour la persistance des données. L'architecture est conçue pour gérer plusieurs parties simultanées, avec une logique complexe pour les mécanismes de jeu, le combat, les interactions entre joueurs, un système social complet, et une économie virtuelle.

Stack Technique

Technologies principales

Node.js : Runtime JavaScript
TypeScript : Langage de programmation
Express : Framework web
Socket.IO : Communication temps réel
MongoDB : Base de données NoSQL
TypeDI : Injection de dépendances

Services Firebase

Firebase Admin SDK : Vérification des tokens d'authentification
Firebase Storage : Stockage des avatars utilisateur
Firebase Cloud Messaging (FCM) : Notifications push (mobile)

Autres dépendances

Multer : Upload de fichiers
GridFS : Stockage de fichiers dans MongoDB (obsolète, remplacé par Firebase Storage)
UUID : Génération d'identifiants uniques
http-status-codes : Codes de statut HTTP

Point d'Entrée

Fichier : server.ts

Initialise le serveur HTTP, configure Socket.IO, et démarre tous les services via TypeDI.

Architecture et Organisation

Injection de Dépendances

Le serveur utilise TypeDI pour l'injection de dépendances, permettant:

Couplage faible entre services
Testabilité accrue
Gestion centralisée des instances

Pattern :

@Service()
export class MyService {
    constructor(private readonly otherService: OtherService) {}
}

Structure des Dossiers

server/app/
├── classes/          # Classes métier (OnGoingGame, Player, User, etc.)
├── controllers/      # Contrôleurs REST (endpoints HTTP)
├── middleware/       # Middlewares Express (auth)
├── services/         # Services métier et logique
├── app.ts           # Configuration Express
├── server.ts        # Point d'entrée Socket.IO
├── env.ts          # Variables d'environnement
└── index.ts        # Démarrage de l'application

Organisation Fonctionnelle des Services

Le côté serveur est divisé en plusieurs catégories fonctionnelles. Les sections suivantes présentent un résumé technique de chaque catégorie.

Sous-sections détaillées disponibles

Pour une documentation détaillée de chaque composant, consultez les sous-sections :

1. Infrastructure et Configuration

Responsabilité : Initialisation et configuration du serveur

Fichiers clés :

server.ts : Point d'entrée, configuration Socket.IO
app.ts : Configuration Express, middlewares, CORS
database.service.ts : Connexion MongoDB avec retry
database-indexes.service.ts : Création automatique des index MongoDB
env.ts : Variables d'environnement (Firebase, MongoDB, Tenor API)

Technologies :

Express avec CORS
Socket.IO avec namespaces
MongoDB native driver
Firebase Admin SDK

Configuration :

// Variables d'environnement
FIREBASE_PROJECT_ID
FIREBASE_PRIVATE_KEY
FIREBASE_CLIENT_EMAIL
MONGODB_URI
TENOR_API_KEY
FCM_SERVER_KEY

2. Authentification et Gestion des Sessions

Services :

AuthController (REST) : Endpoints d'authentification
FirebaseAuthService : Vérification des tokens Firebase ID
SessionService : Gestion des sessions utilisateur (UUID)
AuthMiddleware : Middleware de vérification des tokens
AuthSocketService : Authentification des sockets

Flux d'authentification :

Client s'authentifie avec Firebase (client-side)
Client envoie token ID Firebase au serveur
Serveur vérifie token avec FirebaseAuthService.verifyIdToken()
Serveur crée/récupère utilisateur dans MongoDB
Serveur vérifie session unique (un appareil à la fois)
Serveur crée session avec UUID via SessionService
Serveur retourne session ID
Client authentifie socket avec session ID
Serveur valide et associe socket à session

Endpoints :

POST /api/auth/signup : Inscription
POST /api/auth/signin : Connexion
POST /api/auth/signout : Déconnexion
POST /api/auth/check-username : Vérifier disponibilité username

Sécurité :

Tokens Firebase vérifiés pour chaque requête protégée
Sessions uniques (un seul appareil connecté)
Nettoyage automatique des sessions déconnectées
Middleware authMiddleware sur toutes les routes protégées

3. Gestion des Utilisateurs

Services :

UserService : CRUD utilisateurs, monnaie virtuelle, statistiques
UserController (REST) : Endpoints de profil
UserStatsService : Mise à jour des statistiques de jeu
AvatarService : OBSOLÈTE (remplacé par Firebase Storage)
AvatarController : OBSOLÈTE (remplacé par Firebase Storage)
FirebaseStorageService : Upload et gestion des avatars sur Firebase Storage

Modèle User (MongoDB) :

{
    _id: ObjectId,
    firebaseUid: string (unique),
    username: string (unique),
    email: string,
    virtualCurrencyBalance: number,
    purchaseHistory: string[],           // IDs des items achetés
    channels: string[],                   // IDs des canaux
    friends: string[],                    // Firebase UIDs des amis
    pendingFriendsRequest: string[],      // Firebase UIDs des demandes en attente
    activeSessionId: string,              // UUID de session
    lastLoginAt: Date,
    avatarUrl: string,                    // URL Firebase Storage
    predefinedAvatarId: string,           // ID d'avatar prédéfini (ex: 'avatar_01')
    lastReadAt: { [channelId: string]: Date },  // Dernière lecture par canal
    fcmTokens: string[],                  // Tokens FCM pour notifications push
    isDeleted: boolean,                   // Soft delete
    deletedAt: Date,
    preferences: {
        musicName: string,
        themeName: string,
        languageName: string
    },
    stats: {
        totalGamesPlayed: number,
        totalGamesWon: number,
        gamesPlayedClassic: number,
        gamesWonClassic: number,
        gamesPlayedCTF: number,
        gamesWonCTF: number,
        totalDurationClassic: number,
        totalDurationCTF: number,
        totalDurationTotal: number
    },
    createdAt: Date
}

Endpoints :

GET /api/user/profile : Profil utilisateur
POST /api/user/avatar : Upload avatar (Firebase Storage)
GET /api/user/:firebaseUid/avatar : Récupérer avatar
PUT /api/user/preferences : Mettre à jour préférences
POST /api/user/fcm-token : Enregistrer token FCM

Fonctionnalités :

Monnaie virtuelle par défaut (1000 coins)
Statistiques par mode de jeu (Classic, CTF)
Avatars stockés sur Firebase Storage
Support avatars prédéfinis
Notifications push (mobile)
Soft delete des comptes

4. Système d'Amis

Services :

FriendsService : Logique de gestion des amis
FriendsController (REST) : Endpoints de gestion des amis
FriendsSocketService : Événements socket liés aux amis
FriendsNotificationService : Notifications en temps réel

Endpoints :

GET /api/friends/search?username=X : Rechercher utilisateurs (min 2 caractères)
POST /api/friends/request : Envoyer demande d'ami
POST /api/friends/accept : Accepter demande
POST /api/friends/reject : Refuser demande
GET /api/friends/list : Liste d'amis
GET /api/friends/pending : Demandes reçues
GET /api/friends/sent : Demandes envoyées
DELETE /api/friends/:friendFirebaseUid : Supprimer ami

Events Socket.IO émis :

FriendRequestReceived : Notification de demande reçue
FriendRequestAccepted : Notification d'acceptation
FriendRequestRejected : Notification de refus
FriendRemoved : Notification de suppression

Fonctionnalités :

Recherche temps réel par username
Notifications push (FCM) pour demandes d'amis
États : pending, accepted
Suppression bilatérale

5. Système de Canaux et Chat

Services :

ChannelService : Gestion des canaux de chat
ChannelController (REST) : Endpoints de gestion des canaux
ChatSocketService : Événements socket pour le chat
MessageCensorshipService : Censure de mots inappropriés

Modèle Channel (MongoDB) :

{
    _id: ObjectId,
    name: string (unique),
    owner: string (Firebase UID),
    users: string[] (Firebase UIDs),
    messages: [{
        _id: ObjectId,
        author: string (Firebase UID),
        content: string,              // Peut contenir URL Tenor
        creationDate: Date
    }],
    isGeneral: boolean,               // Canal général (non supprimable)
    isPartyChannel: boolean,          // Canal de partie (auto-créé)
    createdAt: Date,
    updatedAt: Date
}

Endpoints :

POST /api/channels : Créer canal
GET /api/channels : Liste des canaux de l'utilisateur
GET /api/channels/search?name=X : Rechercher canaux
POST /api/channels/:channelId/join : Rejoindre canal
POST /api/channels/:channelId/leave : Quitter canal
GET /api/channels/:channelId/messages : Historique de messages
DELETE /api/channels/:channelId : Supprimer canal (owner only)

Events Socket.IO :

chat:send-message : Envoyer message (avec support GIF Tenor)
chat:message-received : Message reçu
chat:channel-created : Canal créé
chat:user-joined-channel : Utilisateur a rejoint
chat:user-left-channel : Utilisateur a quitté

Fonctionnalités :

Canal "Général" automatique (tous les utilisateurs)
Canaux de partie auto-créés et auto-supprimés
Support GIF Tenor dans les messages
Censure automatique de mots inappropriés
Historique de messages (derniers 50)
Indicateur de lecture par canal (lastReadAt)
Protection canal général (non supprimable/quittable)

6. Boutique (Shop)

Services :

ShopController (REST) : Endpoints de la boutique

Items disponibles : Définis dans @common/shop-item

Avatars (cyberpunk, neon, futuriste)
Profils (bronze, argent, or, diamant)
Prix : 300-1500 coins

Endpoints :

GET /api/shop/check-funds/:itemId : Vérifier si l'utilisateur peut acheter
POST /api/shop/purchase : Acheter un item

Flux d'achat :

Client appelle check-funds/:itemId
Serveur vérifie solde et retourne canAfford
Client appelle purchase avec itemId
Serveur vérifie:
- Item existe
- Pas déjà acheté
- Solde suffisant
Serveur débite et ajoute à purchaseHistory
Retourne nouveau solde

7. GIFs Tenor

Services :

TenorController (REST) : Endpoints Tenor API
TenorService : Communication avec Tenor API

Endpoints :

GET /api/tenor/search?q=query&limit=20 : Rechercher GIFs (max 50)
GET /api/tenor/featured?limit=20 : GIFs en vedette (max 50)

Fonctionnalités :

Intégration Tenor API v2
Recherche de GIFs avec limite configurable
GIFs utilisables dans les messages de chat

8. Gestion des WebSockets

Services :

SocketService : Service central, gestion des connexions
GameSocketHandlerService : Événements de jeu (déplacement, actions)
WaitingSocketService : Événements de salle d'attente
JoinGameService : Logique de rejoindre une partie (drop-in)
CombatSocketService : Événements de combat
TimerSocketService : Événements de timer
StatsRoomSocketService : Événements de statistiques en temps réel
AuthSocketService : Authentification des sockets
ChatSocketService : Chat et canaux
FriendsSocketService : Amis

Namespaces : Tous les événements sur namespace par défaut /

Rooms :

user:{firebaseUid} : Room personnelle utilisateur
game:{gameCode} : Room de partie
channel:{channelId} : Room de canal de chat
waiting:{gameCode} : Room de salle d'attente

Fonctionnalités :

Authentification obligatoire des sockets
Gestion des déconnexions/reconnexions
Support drop-in (rejoindre partie en cours)
Mises à jour en temps réel des parties

9. Gestion des Parties

Services :

OnGoingGameService : État des parties en mémoire
GameStateService : Transitions d'états (waiting, started, ended)
GameTimerService : Gestion des timers de tour
GameAccessService : Contrôle d'accès (visibilité, verrouillage)
JoinGameService : Logique de rejoindre
GameVerifierService : Validation des parties

Classe OnGoingGame (en mémoire) :

{
    code: string,                     // Code à 4 chiffres
    players: Player[],
    game: Game,                       // Configuration du jeu
    status: 'waiting' | 'started' | 'ended',
    prizePool: number,                // Cagnotte accumulée
    entryFee: number,                 // Frais d'entrée (0-100)
    visibility: 'public' | 'friends',
    allowDropInOut: boolean,
    publiclyListed: boolean,
    isLocked: boolean,
    admin: string,                    // Firebase UID de l'hôte
    winner: string,
    gameDuration: number,
    totalTurns: number,
    tilesVisitedPercentage: number,
    doorsToggledPercentage: number,
    timer: Timer
}

Fonctionnalités :

Visibilité publique ou amis uniquement
Frais d'entrée configurables (0-100 coins)
Prize pool accumulant les frais
Drop-in/drop-out support
Verrouillage automatique si plein
Code de partie à 4 chiffres unique
Distribution automatique des gains en fin de partie

Flux de partie :

Admin crée partie avec config (visibilité, frais, drop-in/out)
Vérification monnaie des joueurs rejoignant
Déduction frais → ajout au prize pool
Joueurs rejoignent salle d'attente
Admin lance la partie
Support drop-in si activé
Partie se termine
Distribution prix + mise à jour stats
Suppression partie de la mémoire après stats room

10. Système de Combat

Services :

CombatService : Logique de combat (dés, winner)
CombatSocketService : Événements socket combat
CombatEndingService : Fin de combat, distribution XP/argent
CombatHelperService : Utilitaires combat

Mécanique :

Lancer de dés (1-6)
Modificateurs selon items
Winner = plus haut score
XP et argent gagnés

11. Gestion des Items

Services :

GameItemService : Items dans le jeu
GameItemHandlerService : Événements items
ItemHandlerService : Utilitaires items

Types d'items : Attaque, défense, action, vie

12. Gestion des Joueurs

Services :

GamePlayerService : Gestion des joueurs et bots
OnGoingGameItemHandling : Interaction joueur-items
OnGoingGamePathFinding : Déplacement avec A*

Fonctionnalités :

Bots IA (AggressiveBot, DefensiveBot)
Pathfinding A*
Gestion inventaire
Points de vie, actions, victoire

13. Système de Prize Pool et Économie

Services :

PrizePoolService : Distribution des gains

Logique de distribution :

Pendant partie : Frais s'accumulent dans prizePool
Fin de partie :
- 2/3 prize pool → gagnants (divisé équitablement)
- 1/3 prize pool → perdants (prix de consolation)
- Bots exclus
- Mise à jour MongoDB automatique

Fonctionnalités :

Ajout frais au prize pool lors du join
Remboursement si partie annulée
Distribution automatique en fin
Support dernier survivant (1 gagnant)

14. Statistiques en Temps Réel (Stats Room)

Services :

StatsRoomService : Gestion des rooms de statistiques
StatsRoomSocketService : Événements socket stats
UserStatsService : Mise à jour statistiques utilisateur

Fonctionnalités :

Room Socket.IO pour statistiques post-partie
Tracking joueurs dans stats page
Suppression automatique du canal de partie quand dernier joueur quitte
Suppression de l'OnGoingGame de la mémoire
Mise à jour des statistiques par mode de jeu

Events Socket.IO :

stats:join-room : Rejoindre stats room
stats:leave-room : Quitter stats room
stats:player-count-updated : Nombre de joueurs mis à jour

Nettoyage :

Dernier joueur quitte → suppression canal de partie + game de la mémoire

15. Notifications Push (FCM)

Services :

FirebaseMessagingService : Envoi de notifications push

Fonctionnalités :

Notifications pour demandes d'amis
Notifications pour messages de chat
Support multi-device (liste de tokens FCM)
Gestion automatique des tokens expirés

Endpoints :

POST /api/user/fcm-token : Enregistrer token FCM

16. Système de Traduction

Services :

TranslationService : Traductions serveur FR/EN

Fichiers : Partagés avec client (common/i18n/)

Langues : Français, English

17. Classes du Jeu

Classes principales :

OnGoingGame : Partie en cours (en mémoire)
Player : Joueur avec stats de jeu
Bot : IA (AggressiveBot, DefensiveBot)
Game : Configuration de jeu (grille, mode, règles)
Grid : Grille de jeu
Cell : Cellule de grille
Item : Objet de jeu
Timer : Timer de tour
User : Utilisateur (MongoDB)
Channel : Canal de chat (MongoDB)
Avatar : OBSOLÈTE (remplacé par Firebase Storage)

API REST - Résumé des Endpoints

Authentification

POST /api/auth/signup : Inscription
POST /api/auth/signin : Connexion
POST /api/auth/signout : Déconnexion
POST /api/auth/check-username : Vérifier username

Utilisateur

GET /api/user/profile : Profil
POST /api/user/avatar : Upload avatar
GET /api/user/:firebaseUid/avatar : Récupérer avatar
PUT /api/user/preferences : Préférences
POST /api/user/fcm-token : Token FCM

Amis

GET /api/friends/search?username=X : Rechercher
POST /api/friends/request : Demande
POST /api/friends/accept : Accepter
POST /api/friends/reject : Refuser
GET /api/friends/list : Liste
GET /api/friends/pending : Demandes reçues
GET /api/friends/sent : Demandes envoyées
DELETE /api/friends/:friendFirebaseUid : Supprimer

Canaux

POST /api/channels : Créer
GET /api/channels : Liste
GET /api/channels/search?name=X : Rechercher
POST /api/channels/:channelId/join : Rejoindre
POST /api/channels/:channelId/leave : Quitter
GET /api/channels/:channelId/messages : Messages
DELETE /api/channels/:channelId : Supprimer

Boutique

GET /api/shop/check-funds/:itemId : Vérifier fonds
POST /api/shop/purchase : Acheter item

GIFs

GET /api/tenor/search?q=query&limit=20 : Rechercher GIFs
GET /api/tenor/featured?limit=20 : GIFs vedette

Base de Données MongoDB

Collections

users : Comptes utilisateurs
- Index : firebaseUid (unique), username (unique)
games : Configurations de jeux (plateaux)
- Index : name (unique)
channels : Canaux de chat
- Index : name (unique), users (array)
fs.files et fs.chunks : OBSOLÈTE (GridFS remplacé par Firebase Storage)

Index automatiques

Créés par DatabaseIndexesService au démarrage :

users.firebaseUid (unique)
users.username (unique)
channels.name (unique)
channels.users (array)
games.name (unique)

Sécurité

Authentification

Tous les endpoints protégés par authMiddleware
Vérification token Firebase pour chaque requête
Sessions uniques (un seul appareil)
Validation session pour events socket critiques

Validation

Validation des entrées utilisateur
Censure de messages (mots inappropriés)
Vérification des permissions (owner de canal, admin de partie)
Protection contre connexions multiples

Soft Delete

Utilisateurs marqués isDeleted au lieu de suppression
Préservation des données pour historique
Anonymisation possible

Variables d'Environnement

# Firebase
FIREBASE_PROJECT_ID=...
FIREBASE_PRIVATE_KEY=...
FIREBASE_CLIENT_EMAIL=...

# MongoDB
MONGODB_URI=mongodb://...

# Tenor API
TENOR_API_KEY=...

# FCM (optionnel)
FCM_SERVER_KEY=...

Flux d'Information

Client se connecte via Socket.IO
Client s'authentifie avec token Firebase
Serveur crée session et associe socket
Events socket routés vers services appropriés
Services mettent à jour état en mémoire (OnGoingGame)
Modifications émises à tous les clients concernés (rooms)
Données persistantes sauvegardées dans MongoDB
Notifications temps réel via Socket.IO et FCM

Résumé des Fonctionnalités

Authentification et Sécurité

Firebase Admin SDK
Sessions UUID
Protection connexions multiples
Middleware auth
Socket auth

Système Utilisateur

Profils complets
Monnaie virtuelle (1000 par défaut)
Avatars Firebase Storage
Statistiques par mode (Classic, CTF)
Notifications push FCM
Soft delete

Amis avec demandes
Notifications temps réel
Recherche utilisateurs
Liste amis avec avatars

Chat et Canaux

Canal général automatique
Canaux de partie auto-gérés
Support GIFs Tenor
Censure de messages
Historique messages
Indicateurs de lecture

Économie de Jeu

Frais d'entrée (0-100 coins)
Prize pool par partie
Distribution automatique (2/3 gagnants, 1/3 perdants)
Boutique avec items cosmétiques
Historique d'achats

Parties

Visibilité (public/amis)
Drop-in/drop-out
Verrouillage automatique
Code à 4 chiffres
Statistiques en temps réel

Statistiques

Stats par mode de jeu
Temps de jeu total
Taux de victoire
Mise à jour automatique

Internationalisation

Support FR/EN
Traductions partagées
Détection langue

Services Obsolètes

Les services suivants sont dépréciés et remplacés :

AvatarService → Remplacé par FirebaseStorageService
AvatarController → Remplacé par FirebaseStorageService
GridFS → Remplacé par Firebase Storage

Les champs suivants dans User sont dépréciés :

avatarId → Remplacé par avatarUrl
avatarVersion → Non utilisé avec Firebase Storage

Documentation Côté Serveur

Stack Technique

Technologies principales

Services Firebase

Autres dépendances

Point d'Entrée

Architecture et Organisation

Injection de Dépendances

Structure des Dossiers

Organisation Fonctionnelle des Services

Sous-sections détaillées disponibles

1. Infrastructure et Configuration

2. Authentification et Gestion des Sessions

3. Gestion des Utilisateurs

4. Système d'Amis

5. Système de Canaux et Chat

6. Boutique (Shop)

7. GIFs Tenor

8. Gestion des WebSockets

9. Gestion des Parties

10. Système de Combat

11. Gestion des Items

12. Gestion des Joueurs

13. Système de Prize Pool et Économie

14. Statistiques en Temps Réel (Stats Room)

15. Notifications Push (FCM)

16. Système de Traduction

17. Classes du Jeu

API REST - Résumé des Endpoints

Authentification

Utilisateur

Amis

Canaux

Boutique

GIFs

Base de Données MongoDB

Collections

Index automatiques

Sécurité

Authentification

Validation

Soft Delete

Variables d'Environnement

Flux d'Information

Résumé des Fonctionnalités

Authentification et Sécurité

Système Utilisateur

Système Social

Chat et Canaux

Économie de Jeu

Parties

Statistiques

Internationalisation

Services Obsolètes