Skip to main content

Commandes, documents et persistance BrainCloud

Architecture serveur commune

Le backend du Game repose principalement sur les Cloud Scripts dans node.js/backend/braincloud/server_scripts. Les dossiers _command, _admin_command, _job et _utils constituent le socle partagé.

Familles de scripts

DossierRôle
_command/Entrées appelées par le client : simulations, activités, équipes, évaluations, logbook, chat, rankings, static data, etc.
_admin_command/Outils administratifs comme création de documents en bulk et récupération de joueurs.
_job/Travaux planifiés : génération et migrations/versioning de documents.
_utils/Logique réutilisable : documents, messages, eval, rankings, RNG, By Year et By Module.
<gameUid>/command/Wrappers game-specific.

utils_documents.js

Ce fichier est la couche d'accès commune aux Custom Entities. Ses fonctions structurantes sont getDocumentData, gatherDocumentsData, gatherDocumentsDataWithQuery, saveDocumentData, saveDocumentDataFields, saveDocumentIncrementData, createDocumentData, deleteDocumentData, initializeDocument et updateDocumentVersion.

sequenceDiagram
participant CMD as Cloud Script
participant UD as utils_documents
participant CE as Custom Entity
participant VER as version/*
CMD->>UD: getDocumentData(type, uid)
UD->>CE: lecture
CE-->>UD: data + version
UD->>VER: initialize / migrate
UD-->>CMD: objet métier
CMD->>CMD: modifications
CMD->>UD: saveDocumentData(type, uid)
UD->>CE: écriture

Versioning et migrations

Les scripts _utils/version/version_*.js portent les migrations par type de document. Chaque type peut enregistrer une fonction d'initialisation et une suite de transformations successives.

version_teams_modules.js est un bon exemple : il contient plusieurs migrations teamModuleDataToV*. Un vieux document peut donc être transformé jusqu'au schéma actuel avant d'être resauvegardé.

Documents principaux

  • simulation : état/configuration de simulation;
  • activity : activité en cours;
  • actDataGameSpec : données propres au jeu pour l'activité;
  • teams : état commun d'équipe;
  • teamsModules : données By Module d'une équipe et d'un module;
  • results, evaluation, evaluationTeam;
  • teamsLogbooks, userDetails, simComments.

Règle lorsqu'un schéma change

  1. Définir le nouveau schéma attendu.
  2. Ajouter la migration dans le bon version_<entity>.js.
  3. Garantir le passage de toutes les versions antérieures supportées.
  4. Tester lecture, migration et resauvegarde.
  5. Ne lancer un job de migration globale qu'après validation sur des documents représentatifs.

Static data serveur

_command/update_static_data.js est l'entrée utilisée par les outils d'export pour publier les JSON dans BrainCloud. La chaîne complète est documentée dans Données statiques et pipeline import/export.

Diagnostic concurrence

Un bug qui n'apparaît qu'avec plusieurs utilisateurs peut venir d'écritures concurrentes et de versions de Custom Entities. Dans ce cas, suivre le document concerné, sa version lue, la fonction de sauvegarde utilisée et les éventuels retries avant d'accuser l'UI.

Back to top