# 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`.

```mermaid
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

<table id="bkmrk-fichier-responsabili"><thead><tr><th>Fichier</th><th>Responsabilité</th></tr></thead><tbody><tr><td>`modules_settings.json`</td><td>Choisit **quels contextes** un module utilise, dans quel ordre, avec quelles dates et quels overrides.</td></tr><tr><td>`modules_contexts.json`</td><td>Définit les **templates réutilisables** de contexte : bills à générer, pages disponibles et configuration partagée.</td></tr></tbody></table>

## context\_list dans modules\_settings.json

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

```json
{
  "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"
  ]
}
```

<table id="bkmrk-champ-r%C3%B4le-uid-ident"><thead><tr><th>Champ</th><th>Rôle</th></tr></thead><tbody><tr><td>`uid`</td><td>Identité de **l'instance de contexte** dans ce module. Sert notamment de clé dans `previousContextsBills` et les snapshots.</td></tr><tr><td>`context_uid`</td><td>Template chargé depuis `modules_contexts.json`.</td></tr><tr><td>`start_date` / `end_date`</td><td>Bornes utilisées pour générer les bills et calculs de cette période. `year_offset` permet de viser l'année précédente.</td></tr><tr><td>`preferences`</td><td>Overrides propres à ce contexte. Ils sont résolus via les helpers de préférence avec override.</td></tr><tr><td>`saved_pages`</td><td>Pages de l'Answer Key de ce contexte à conserver dans le `TeamModuleTypeData` final.</td></tr></tbody></table>

## 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 :

```javascript
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.

<table id="bkmrk-concept-responsabili"><thead><tr><th>Concept</th><th>Responsabilité</th></tr></thead><tbody><tr><td>**Module context**</td><td>Période logique définie dans `context_list` / `modules_contexts.json`.</td></tr><tr><td>`BillCreationContext`</td><td>État temporaire global utilisé pendant la **création** des bills : RNG, dates, partners, inventory, comptes, ordre de calcul, etc.</td></tr><tr><td>`BillContext`</td><td>Vue runtime des bills/comptes/inventory utilisée par les bills, Answer Key et calculs comptables après/pendant génération.</td></tr></tbody></table>

**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** :

```text
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.

<table id="bkmrk-donn%C3%A9e-comportement-"><thead><tr><th>Donnée</th><th>Comportement entre contextes</th></tr></thead><tbody><tr><td>Comptes</td><td>Recalculés depuis l'Answer Key / account state puis propagés.</td></tr><tr><td>Inventaire</td><td>Copié/transformé à partir de l'état final de `BillContext`.</td></tr><tr><td>Immobilisations</td><td>Copiées avec mise à jour de l'usage/dépréciation lorsque les règles du contexte l'exigent.</td></tr><tr><td>Contrats</td><td>Copiés vers le contexte suivant.</td></tr><tr><td>Taxes immobilisations</td><td>Copiées vers le contexte suivant.</td></tr><tr><td>Services / expenses</td><td>Conservés lorsqu'ils existent.</td></tr><tr><td>Bills</td><td>Archivé dans `previousContextsBills`; le contexte suivant obtient ses propres bills.</td></tr></tbody></table>

## 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é

<table id="bkmrk-cas-v%C3%A9rification-con"><thead><tr><th>Cas</th><th>Vérification</th></tr></thead><tbody><tr><td>Contexte année précédente</td><td>Dates avec `year_offset = -1`, balances correctement reportées.</td></tr><tr><td>Deux contextes successifs</td><td>Le second part de l'état final du premier.</td></tr><tr><td>`saved_pages`</td><td>Page + dynamic dropdowns relisibles côté Unity.</td></tr><tr><td>Inventory</td><td>Stock final du contexte précédent devient l'état de départ suivant.</td></tr><tr><td>Immobilisations</td><td>Usage/dépréciation cumulative correcte.</td></tr><tr><td>Contrats</td><td>Contrat encore disponible et régularisation correcte.</td></tr><tr><td>Bills historiques</td><td>`BillContext.getBillByUid()` retrouve un bill précédent.</td></tr><tr><td>Current module</td><td>Answer Key final et grading à 100 % avec les données propagées.</td></tr></tbody></table>

## 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`