# Référence des utils serveur BrainCloud

## Carte générale

<table id="bkmrk-fichier%2Fdossierrespo"><thead><tr><th>Fichier/dossier</th><th>Responsabilité</th></tr></thead><tbody><tr><td>`utils.js`</td><td>Helpers transversaux, UIDs, calculs simples, copie/merge, équipes/étudiants, rôles, CRC, logging.</td></tr><tr><td>`utils_documents.js`</td><td>Lecture, query, création, sauvegarde, suppression, increments et versioning des Custom Entities.</td></tr><tr><td>`utils_message.js`</td><td>Envoi de messages RTT à user/team/sim/activity et messages spécialisés.</td></tr><tr><td>`utils_eval.js`</td><td>Stubs et scores d'évaluation communs.</td></tr><tr><td>`utils_rankings.js`</td><td>Scores, tops et mise à jour des rankings.</td></tr><tr><td>`utils_RNG.js`</td><td>Random déterministe utilisé par la génération serveur.</td></tr><tr><td>`utils_redis.js`</td><td>Helpers d'accès Redis lorsque la feature l'utilise.</td></tr><tr><td>`utils_game_specific_base.js`</td><td>Base des utils game-specific et accès aux static data/chunks.</td></tr><tr><td>`utils_by_module.js`</td><td>Charge/initialise le socle By Module.</td></tr><tr><td>`utils_by_year.js`</td><td>Cycle annuel, jobs, bots et transitions By Year.</td></tr><tr><td>`by_module/`</td><td>Moteurs Accounting : création data, bills, answer key, grading, results, inventory.</td></tr><tr><td>`command/`</td><td>Implémentations réutilisables appelées par les wrappers command.</td></tr><tr><td>`factory/`</td><td>Sélection game-specific des utils, évaluations et générateurs de résultats.</td></tr><tr><td>`version/`</td><td>Migrations par type de document.</td></tr></tbody></table>

## utils.js — fonctions structurantes

Parmi les helpers importants : `getTeamActUid`, `getActUid`, dates/mois/années, `deleteTeam`, `getDisplayName`, `getActEvalTeamData`, `getTeamDecisionsData`, `getTeamsOfActivity`, `getStudentsOfActivity`, `hasRole`, `getUserUid`, `mergeObjects`, `copyOf/deepCopyOf`, logging Discord et validation CRC avant sauvegarde équipe.

## command/

- `utils_create_activity.js` : logique partagée de création d'activité;
- `utils_create_team.js` : création/initialisation d'équipe;
- `utils_custom_command_by_module.js` : routeur By Module;
- `utils_custom_command_by_year.js` : routeur By Year;
- `utils_join_simulation.js` : logique de join simulation;
- `utils_reopen_module.js` : rollback/réouverture By Module;
- `utils_reopen_year.js` : rollback/réouverture By Year;
- `utils_start_next_activity.js` : transition d'activité.

## factory/

- `utils_factory_game_specific_utils.js` : instancie `utilsByGameUid`;
- `utils_factory_generate_results.js` : moteur de résultats par jeu;
- `utils_factory_eval.js` : moteur d'évaluation par jeu.

## Principe de placement

Un wrapper sous `_command` doit rester mince. Dès qu'une logique est partagée entre plusieurs entrées, elle doit être placée dans `_utils` ou dans la famille métier adéquate. Les règles propres à ENT1/MK1/etc. restent dans leurs dossiers game-specific.