Contextes Accounting — cycle, héritage et données entre périodes

Rôle des contextes Accounting

Un contexte représente une période/situation comptable simulée avant le current_module. Il permet de construire l'état initial du module courant à partir d'une ou plusieurs périodes précédentes : bills, comptes, inventaire, immobilisations, contrats, pages calculées et dynamic dropdowns.

Les contextes ne sont donc pas une simple configuration visuelle. Ils font partie du pipeline serveur de génération du TeamModuleTypeData.

flowchart LR
MS[modules_settings.context_list] --> CTX[modules_contexts.json]
CTX --> MERGE[getContextData]
MERGE --> DATA[Copy current ModuleTypeData]
DATA --> BILLS[Create bills for context]
BILLS --> AK[Answer Key du contexte]
AK --> NEXT[getModuleTypeDataFromAnswerKeyModule]
NEXT --> STATE[Accounts / inventory / immobilizations / contracts]
AK --> SAVE[Saved pages + dropdowns]
BILLS --> PREV[previousContextsBills]
STATE --> CURRENT[Generate current_module]
PREV --> CURRENT
SAVE --> TEAM[TeamModuleTypeData]
CURRENT --> TEAM

Les deux fichiers de configuration à ne pas confondre

context_list dans modules_settings.json

Chaque module peut avoir une context_list. Un élément ressemble conceptuellement à :

{
  "uid": "last_year",
  "context_uid": "module_context_aux_journals_with_regularizations_last_year",
  "start_date": {
    "day": 1,
    "month": 1,
    "year_offset": -1
  },
  "end_date": {
    "day": 31,
    "month": 12,
    "year_offset": -1
  },
  "preferences": {
    "uses_regularizations": false
  },
  "saved_pages": [
    "trial_balance_before_regularizations_and_closure"
  ]
}

modules_contexts.json : templates réutilisables

modules_contexts.json contient des définitions comme module_context_aux_journals_with_regularizations. Elles peuvent notamment fournir :

• bills_type_data — types et quantités de bills à générer;
• pages_order — pages comptables utilisées par l'Answer Key du contexte;
• des propriétés réutilisées par le moteur de création.

Héritage avec base_context_uid

getContextData(moduleContext) charge le template correspondant à moduleContext.context_uid. Si ce template possède base_context_uid, le moteur :

1. copie le contexte de base;
2. merge ensuite le contexte enfant par-dessus;
3. applique ensuite les règles/preferences propres à l'instance du module.

Utiliser ce mécanisme lorsqu'un nouveau contexte est une variante d'un contexte existant plutôt que de dupliquer un énorme bloc bills_type_data.

Pipeline réel de création des contextes

Le cœur se trouve dans byModule_utils_create_module_type_data.js.

1. Initialiser l'état de départ

Le moteur possède un currentModuleTypeDataBase qui contient l'état comptable courant : comptes, inventaire, immobilisations, contrats, taxes, services/expenses, etc.

2. Parcourir context_list dans l'ordre

Pour chaque moduleContext :

1. getContextData(moduleContext) résout le template et ses overrides;
2. les dates absolues sont calculées depuis actSettings.year;
3. le moteur fait un deepCopy de l'état comptable courant;
4. les bills du contexte sont générés;
5. BillContext.getBills() devient le jeu de bills du contexte;
6. un Answer Key complet du contexte est calculé;
7. les pages demandées par saved_pages sont snapshotées;
8. le contexte est transformé en nouvel état comptable de base pour le contexte suivant.

3. Conserver les bills des contextes précédents

Après chaque contexte :

currentModuleTypeDataBase.previousContextsBills[moduleContext.uid] =
    previousModuleTypeData.bills;

Les bills ne disparaissent donc pas après leur période. Ils restent disponibles pour les moteurs qui doivent consulter l'historique.

4. Générer le current_module

Une fois tous les contextes calculés, le moteur utilise l'état final comme point de départ du current_module. Les bills du module étudiant sont alors générés avec les comptes/inventaire/immobilisations/contracts issus des contextes.

BillCreationContext vs BillContext vs “module context”

Ces trois termes sont proches mais ne désignent pas la même chose.

Ne pas documenter ou coder ces trois concepts comme s'ils étaient interchangeables.

previousContextsBills

TeamModuleTypeData.previousContextsBills est indexé par contextUid. Chaque contexte contient typiquement :

• billsData;
• billsOrder;
• partners;
• taxes lorsque présentes.

BillContext expose ensuite :

• getPreviousContextsBills() — tous les bills historiques;
• getPreviousContextsBillsByType(...) — filtre par type;
• getPreviousContextsBillsByContextUid(contextUid);
• getBillByUid() — cherche d'abord dans le contexte courant, puis dans les contextes précédents.

Cas particulier module_context_client/provider

BillContext.getSerializedBillsBase() exclut actuellement les bills dont le type contient module_context_client lors de certaines sérialisations. Le code contient d'ailleurs un TODO explicite sur ce cas. Avant de modifier ces types, inspecter leur lifecycle complet au lieu de supposer qu'ils se comportent comme un bill standard.

savedPagesDataByContextUids

Si un contexte déclare saved_pages, le moteur récupère les pages correspondantes depuis l'Answer Key de ce contexte :

savedPagesDataByContextUids
└── <moduleContext.uid>
    ├── trial_balance_before_regularizations_and_closure
    ├── statement_income
    └── ...

Côté Unity, TeamByModuleController.GetContextSavedPageData(actModuleUid, moduleContextUid, modulePageUid) permet de relire ces snapshots.

Quand utiliser saved_pages

Utiliser saved_pages lorsqu'une page historique doit être consultable/référencée plus tard. Ne pas l'utiliser pour recopier toutes les pages “au cas où” : chaque snapshot augmente les données persistées dans teamsModules.

savedDynamicDropdownsDataByContextUids

Lorsqu'une saved page dépend d'un dynamic dropdown, le moteur conserve aussi les entrées correspondantes dans :

savedDynamicDropdownsDataByContextUids[contextUid]

Sinon la page historique pourrait contenir des tables indexées par des UIDs que le client ne saurait plus nommer/afficher.

Propagation entre contextes

getModuleTypeDataFromAnswerKeyModule() transforme la sortie du contexte en état de départ pour le suivant.

Overrides de préférences par contexte

Un contexte peut modifier temporairement des préférences du module. Le code utilise getPreferenceWithOverride(moduleSettings, moduleContext, preference) pour plusieurs règles.

Exemples visibles dans modules_settings.json :

• answer_key_until;
• uses_accounting_closing;
• uses_regularizations;
• uses_stock_regularizations;
• uses_taxes_payment_form;
• has_new_immobilizations;
• has_new_contracts.

Une préférence mise dans le contexte doit affecter uniquement cette période de génération. Si le comportement doit aussi changer dans le current module, configurer la preference au bon niveau du module.

initial_pages_data et préfixe previous_

Après les contextes, current_module.initial_pages_data peut construire l'état initial de certaines pages depuis l'état actuel ou précédent.

Le moteur traite notamment :

• ledger / previous_ledger;
• bank_statement / previous_bank_statement;
• clients_subledger;
• providers_subledger;
• stocks_subledger;
• fallback vers une page de l'Answer Key précédent.

Le préfixe previous_ indique au générateur de prendre la donnée du contexte/module précédent puis le préfixe est retiré avant de sauvegarder dans initialPagesData.

Ajouter un nouveau contexte de A à Z

1. Décider s'il faut vraiment un nouveau template. Si seule une préférence/date change, réutiliser un context_uid existant avec overrides.
2. Si nécessaire, créer le template dans modules_contexts.json.
3. Préférer base_context_uid si le nouveau contexte est une variante d'un gros contexte existant.
4. Ajouter l'instance dans modules_settings.context_list au bon ordre.
5. Donner un uid stable à l'instance.
6. Définir start_date/end_date et year_offset.
7. Ajouter les overrides preferences nécessaires.
8. Ajouter seulement les saved_pages qui doivent réellement survivre.
9. Importer la static data Google Sheets/JSON si la source officielle passe par le pipeline d'export.
10. Générer le Module Type Data avec un seed fixe.
11. Inspecter l'état avant/après ce contexte.
12. Vérifier que le contexte suivant et le current module partent du bon état.

Ajouter une nouvelle donnée qui doit traverser les contextes

C'est une modification plus profonde. Il faut auditer au minimum :

1. createInitialModuleTypeData() — création initiale;
2. createBills() / BillCreationContext — utilisation pendant la période;
3. BillContext — état calculé;
4. getModuleTypeDataFromAnswerKeyModule() — propagation vers le contexte suivant;
5. TeamModuleTypeData.cs — désérialisation Unity;
6. migration teamsModules si vieux documents;
7. Answer Key et Grading si la donnée influence une page comptable.

Debug d'un contexte

Pour un bug “la bonne valeur existe dans l'année précédente mais disparaît dans le module courant”, inspecter dans cet ordre :

1. Configuration — le contexte est-il réellement dans context_list ?
2. Template — context_uid existe-t-il dans modules_contexts.json ?
3. Merge — base_context_uid + overrides produisent-ils le contexte attendu ?
4. Dates — vérifier year_offset et les timestamps calculés.
5. Bills du contexte — inspecter moduleTypeDataForContext.bills.
6. Answer Key du contexte — la valeur attendue existe-t-elle déjà ici ?
7. Transformation — inspecter getModuleTypeDataFromAnswerKeyModule().
8. previousContextsBills — le contexte est-il présent sous le bon uid ?
9. saved_pages — le snapshot est-il présent ?
10. current_module — la donnée est-elle encore correcte juste avant sa génération ?

Test de régression recommandé

Fichiers clés

• Assets/GameSpecific/byModule/Resources/data_byModule/modules_settings.json
• Assets/GameSpecific/byModule/Resources/data_byModule/modules_contexts.json
• node.js/backend/braincloud/server_scripts/_utils/by_module/byModule_utils_create_module_type_data.js
• .../_utils/by_module/contexts/BillCreationContext.js
• .../_utils/by_module/contexts/BillContext.js
• Assets/Src/Game/Data/ByModule/TeamModuleTypeData.cs
• Assets/Src/UI/SimByModule/Controllers/TeamByModuleController.cs