# Configuration Accounting — guide des JSON

## Objectif

Cette page sert de carte des fichiers de configuration du système Accounting / ByModule. Le point important est de distinguer trois familles : les **données statiques** utilisées par la simulation, les **settings** qui activent/configurent les modules, et les **definitions** qui décrivent surtout les champs disponibles dans les écrans d'édition/wizards.

## 1. Vue générale du chargement

```mermaid
flowchart LR
    JSON[Resources/data_byModule/*.json] --> STATIC[StaticDataByModule.Initialize]
    STATIC --> CATALOG[Catalogues statiques]
    STATIC --> SETTINGS[ModulesSettings / PagesSettings]
    STATIC --> DEFINITIONS[Definitions pour éditeur / wizard]

    CATALOG --> GAME[Runtime Accounting]
    SETTINGS --> GAME
    DEFINITIONS --> EDITOR[Configuration des activités/modules]
    EDITOR --> MODULECFG[Configuration sauvegardée du module]
    MODULECFG --> GAME

```

Le point d'entrée Unity est `Assets/Src/Game/Data/ByModule/StaticDataByModule.cs`. Il charge les fichiers du dossier `Assets/GameSpecific/byModule/Resources/data_byModule` via `Resources.Load`.

## 2. Les JSON principaux

<table id="bkmrk-fichier-r%C3%B4le-quand-l"><thead><tr><th>Fichier</th><th>Rôle</th><th>Quand le modifier</th></tr></thead><tbody><tr><td>`modules.json`</td><td>Catalogue des modules disponibles : uid, nom, description, type de module, editor, icône/image, limites et métadonnées d'affichage.</td><td>Quand on ajoute un nouveau module ou qu'on change son identité dans le catalogue.</td></tr><tr><td>`modules_settings.json`</td><td>Valeurs/settings par défaut des modules : pages, préférences, bills, outils accounting, durée, options de validation, etc.</td><td>Quand on change le comportement par défaut d'un module existant ou sa configuration Accounting.</td></tr><tr><td>`modules_settings_definitions.json`</td><td>Décrit quels champs/préférences/bill definitions sont exposés pour chaque type de module dans les écrans de configuration.</td><td>Quand un nouveau paramètre doit devenir configurable dans le wizard/editor.</td></tr><tr><td>`module_pages.json`</td><td>Structure statique des pages et tableaux : pages, tables, rows, inputs, types d'inputs et outils comme journal général, grand livre, balance, états financiers, cash flow, etc.</td><td>Quand la structure visuelle ou fonctionnelle d'une page Accounting change.</td></tr><tr><td>`pages_settings.json`</td><td>Comportement d'une page : rangées/sections dynamiques, row editor, formules, navigation et autres options runtime.</td><td>Quand une page existante doit accepter un comportement dynamique différent.</td></tr><tr><td>`pages_settings_definitions.json`</td><td>Définitions des champs éditables de `pages_settings`.</td><td>Quand on ajoute un nouveau setting de page configurable.</td></tr><tr><td>`preferences_settings_definitions.json`</td><td>Définitions des préférences de module utilisables dans l'éditeur.</td><td>Quand une nouvelle préférence doit être sélectionnable/configurable.</td></tr><tr><td>`bills_settings_definitions.json`</td><td>Schéma des données configurables **par type de bill** : type, nombre de bills, dates, comptes, taxes, partner subtype, produit/service, règles spécifiques, etc.</td><td>Quand un nouveau type de bill ou un nouveau paramètre de génération doit être exposé à la configuration.</td></tr><tr><td>`bills_category_settings_definitions.json`</td><td>Schéma des options **par catégorie de bills**. Dans la version actuelle, ces definitions décrivent les options que l'éditeur peut présenter.</td><td>Quand une catégorie de bills reçoit une nouvelle option commune.</td></tr><tr><td>`accounts.json`</td><td>Plan comptable statique : comptes par défaut/by-sector/custom, numéro, nom, type, unique\_identifier, ordre, balance par défaut et metadata cash-flow.</td><td>Quand on ajoute/modifie un compte ou son comportement comptable.</td></tr><tr><td>`account_types.json`</td><td>Définitions des types/catégories de comptes.</td><td>Quand la taxonomie des comptes change.</td></tr><tr><td>`taxes.json`</td><td>Taxes de vente et données associées chargées dans `SalesTaxes`.</td><td>Quand une taxe de vente ou sa configuration statique change.</td></tr><tr><td>`income_taxes.json`</td><td>Définitions générales des impôts sur le revenu.</td><td>Quand les types/règles générales d'impôt changent.</td></tr><tr><td>`employer_income_taxes.json`</td><td>Données de charges/taxes employeur.</td><td>Quand les règles employeur changent.</td></tr><tr><td>`income_tax_*_YEAR.json`</td><td>Tables fiscales annuelles fédérales/provinciales, chargées à la demande selon région et année.</td><td>Lors d'une mise à jour fiscale annuelle.</td></tr><tr><td>`income_taxes_codes.json`</td><td>Codes liés aux calculs/configurations d'impôt.</td><td>Quand la correspondance des codes fiscaux change.</td></tr><tr><td>`interests.json`</td><td>Définitions de taux/catégories d'intérêts.</td><td>Quand le calcul d'intérêts doit utiliser de nouvelles données statiques.</td></tr><tr><td>`immobilizations.json`</td><td>Catalogue/configuration des immobilisations.</td><td>Quand un type d'immobilisation ou ses données changent.</td></tr><tr><td>`contract_regularizations.json`</td><td>Données de régularisation des contrats.</td><td>Quand les règles de régularisation de contrats changent.</td></tr><tr><td>`regions.json`</td><td>Catalogue des régions supportées.</td><td>Quand une région est ajoutée/modifiée.</td></tr><tr><td>`regions_settings.json`</td><td>Comportements propres à une région : options fiscales/employeur/employé, congés et autres paramètres régionaux.</td><td>Quand une région doit avoir un comportement Accounting différent.</td></tr><tr><td>`act_settings.json`</td><td>Settings globaux d'activité utilisés par les modules.</td><td>Pour une configuration transversale à l'activité plutôt qu'à une page/module précis.</td></tr><tr><td>`constants.json`</td><td>Constantes globales ByModule utilisées par les systèmes runtime.</td><td>Quand un comportement dépend d'une constante partagée plutôt que d'un module particulier.</td></tr><tr><td>`dropdown_data.json`</td><td>Données de dropdown statiques utilisées dans les configurateurs.</td><td>Quand une liste de choix statique change.</td></tr><tr><td>`dynamic_dropdown_data_structure.json`</td><td>Structure des dropdowns dynamiques.</td><td>Quand une donnée sélectionnable dépend d'autres données/configurations.</td></tr></tbody></table>

## 3. Relation entre modules\_settings et les definitions

```mermaid
flowchart TD
    DEF[modules_settings_definitions.json] -->|liste des preferences| PREF[preferences_settings_definitions.json]
    DEF -->|liste des bills| BILLDEF[bills_settings_definitions.json]
    BILLDEF --> WIZ[BillsDataWizardPageControl]
    PREF --> WIZARD[Module settings wizard]

    DEFAULT[modules_settings.json] --> MS[ModuleSettingsBase]
    WIZ --> SAVED[Configuration du module/activité]
    WIZARD --> SAVED
    SAVED --> MS

    MS --> PREFS[preferences]
    MS --> BTD[bills_type_data]
    MS --> BCS[bills_category_settings]
    MS --> HIDDEN[bills_types_hidden_total]

```

**À retenir :** un fichier `*_definitions.json` ne représente pas forcément la valeur runtime. Il définit souvent *comment configurer* cette valeur. Les valeurs effectives d'un module finissent dans `ModuleSettingsBase`.

## 4. Configuration des bills dans un module

`ModuleSettingsBase` expose deux structures principales :

- `bills_type_data` → dictionnaire de `BillTypeData` / données détaillées de génération par bill;
- `bills_category_settings` → options communes par catégorie, par exemple le nombre de bills aléatoires à sélectionner dans une catégorie.

Le backend lit notamment `_moduleSettings.bills_category_settings` lors de la génération et utilise `bills_type_data` comme source réelle pour `BillFactory`.

### bills\_settings\_definitions.json

Ce fichier est la grosse table de définition des champs disponibles pour les bills. On y retrouve notamment :

- `type`, `num_bills`, `min_num_entries`, `max_num_entries`;
- dates, fréquences, occurrences, délais et termes;
- comptes impactés : sales, expenses, payable, receivable, cash, loan, amortization, etc.;
- taxes : taxes de vente, déductions, taxes récupérables;
- relations : product/service, contract, immobilization, employee, supplier, investment;
- règles de création/édition et données spécifiques au type de bill.

## 5. Configuration des pages Accounting

```mermaid
flowchart LR
    M[modules.json] --> UID[module uid]
    UID --> MS[modules_settings.json]
    MS --> ORDER[pages_order]
    ORDER --> MP[module_pages.json]
    MP --> STRUCT[Structure UI: page/table/input]
    STRUCT --> PS[pages_settings.json]
    PS --> BEHAVIOR[Rows/sections dynamiques, formules, navigation]

```

`module_pages.json` répond principalement à la question **« qu'est-ce qui existe dans la page ? »**, tandis que `pages_settings.json` répond à **« comment cette page se comporte ? »**.

## 6. Plan comptable et calculs

```mermaid
flowchart LR
    ACC[accounts.json] --> STATIC[StaticDataByModule.Accounts]
    TYPES[account_types.json] --> STATIC
    TAX[taxes / income_taxes / employer_income_taxes] --> STATIC
    REG[regions + regions_settings] --> STATIC
    STATIC --> BILL[Bills]
    STATIC --> JOURNAL[General Journal]
    STATIC --> LEDGER[General Ledger]
    STATIC --> TB[Trial Balance]
    STATIC --> FS[Financial Statements]

```

## 7. `regions_settings.json` : filtre régional critique

**À ne pas oublier :** ajouter une donnée dans son JSON principal ne suffit pas toujours à la rendre disponible dans le jeu. Pour plusieurs données Accounting, `regions_settings.json` agit comme un **filtre/routeur par région**.

### Comptes

Pour les comptes, c'est particulièrement important. `UtilsByModule.GetRegionAccounts()` lit la région de l'activité, choisit un type via `global.accounts.type_by_regions`, puis prend uniquement les UIDs présents dans `global.accounts.data_by_type[type]`. Ensuite seulement, ces UIDs sont résolus dans `accounts.json`.

Donc un compte peut exister parfaitement dans `accounts.json` et **ne jamais apparaître** dans le jeu s'il n'est pas ajouté dans la liste appropriée de `regions_settings.json`. Après ce filtre régional, `GetUsedAccounts()` applique encore les `visibilityConditions` du compte et `preferences.hiddenAccounts`.

```mermaid
flowchart LR
    A[accounts.json] --> ALL[Catalogue complet des comptes]
    R[act_settings.region] --> RS[regions_settings.json]
    RS --> LIST[Liste de comptes autorisés pour la région]
    ALL --> FILTER[GetRegionAccounts]
    LIST --> FILTER
    FILTER --> VIS[visibilityConditions + hiddenAccounts]
    VIS --> USED[Comptes réellement disponibles]

```

### Ce que `regions_settings.json` pilote aussi

- **Taxes de vente** via `global.taxes` : par exemple GST/QST au Québec versus HST selon la province.
- **Retenues / impôts employés** via `global.income_taxes`.
- **Charges employeur** via `global.employer_income_taxes`.
- **Intérêts** via `global.interests`.
- **Colonnes de certaines pages/journaux** via `pages.<page_uid>.column_inputs_order`. L'ordre et même les colonnes affichées peuvent changer selon la région.
- **Prefab de certaines pages/formulaires** via `pages.<page_uid>.prefab_reference`. Exemple : le formulaire de paiement des taxes utilise un contrôle différent selon la province.

### Pattern utilisé

La plupart de ces sections utilisent le même pattern :

```
{
  "type_by_regions": {
    "ca_on": "ca_on"
  },
  "data_by_type": {
    "default": [...],
    "ca_on": [...]
  }
}
```

Si la région courante n'est pas présente dans `type_by_regions`, le code retombe sur `default`.

### Checklist quand on ajoute une donnée régionale

- Créer/modifier la donnée source : `accounts.json`, `taxes.json`, tables fiscales, etc.
- Vérifier `regions_settings.json` et ajouter l'UID dans chaque `data_by_type` où il doit être disponible.
- Si une nouvelle région/variante est nécessaire, ajouter le mapping dans `type_by_regions`.
- Pour une page régionale, vérifier aussi `column_inputs_order` ou `prefab_reference`.
- Tester au minimum la région `default` et une région explicitement mappée.

**Exemple classique de bug :** « j'ai ajouté le compte dans `accounts.json`, il charge sans erreur, mais il n'apparaît nulle part ». Le premier endroit à vérifier est `regions_settings.json → global.accounts`.

## 8. Règle pratique : quel fichier modifier ?

<table id="bkmrk-je-veux...-commencer"><thead><tr><th>Je veux...</th><th>Commencer par...</th></tr></thead><tbody><tr><td>Ajouter un nouveau module</td><td>`modules.json` + `modules_settings.json` + sa définition/settings/pages selon le besoin.</td></tr><tr><td>Changer la structure d'une page</td><td>`module_pages.json`.</td></tr><tr><td>Changer le comportement d'une page</td><td>`pages_settings.json`.</td></tr><tr><td>Ajouter une préférence configurable</td><td>`preferences_settings_definitions.json` puis consommation dans le code/settings.</td></tr><tr><td>Ajouter un paramètre de bill configurable</td><td>`bills_settings_definitions.json` puis le code serveur qui consomme le champ.</td></tr><tr><td>Changer combien/quels bills un module génère</td><td>Configuration effective `bills_type_data`/`bills_category_settings` du module.</td></tr><tr><td>Ajouter/modifier un compte</td><td>`accounts.json`.</td></tr><tr><td>Mettre à jour une table fiscale annuelle</td><td>`income_tax_*_YEAR.json` correspondant.</td></tr><tr><td>Changer une règle propre à une région</td><td>`regions_settings.json`.</td></tr></tbody></table>

## Fichiers de code qui chargent cette configuration

- `Assets/Src/Game/Data/ByModule/StaticDataByModule.cs` — chargement central des JSON de `data_byModule`.
- `Assets/Src/Game/Data/ByModule/ModuleSettingsBase.cs` — désérialisation des settings runtime, incluant bills.
- `Assets/Src/UI/SimByModule/Data/ModuleSettingsDefinition.cs` — relie une définition de module aux définitions de préférences et de bills.
- `Assets/Src/UI/SimByModule/Data/BillsDataWizardPageControl.cs` — éditeur des données de bills.
- `Assets/Src/UI/SimByModule/Data/BillDataSettingDefinitionData.cs` — représentation Unity d'une définition de bill.
- `Assets/Src/UI/SimByModule/Data/BillCategorySettingDefinitionData.cs` — représentation Unity des options de catégorie.

## Point important

Il n'existe pas dans cette branche de fichier statique `bills_settings.json` dans `Resources/data_byModule`. Les fichiers statiques présents sont `bills_settings_definitions.json` et `bills_category_settings_definitions.json`; les valeurs effectives des bills sont intégrées aux settings du module/activité sous `bills_type_data` et `bills_category_settings`.