# Architecture By Year

## Rôle

By Year est le framework historique où une activité progresse année par année. À chaque année, les équipes prennent des décisions game-specific, le serveur génère les résultats, calcule les évaluations et prépare l'année suivante.

```mermaid
flowchart LR
ACT[ActivityByYear] --> Y[Current Year]
Y --> DEC[TeamDecisionsByYear]
DEC --> GAME[Game-specific logic]
GAME --> RES[ResultsByYear]
RES --> EVAL[TeamEvaluation / StudentEvaluation]
RES --> NEXT[Next Year]

```

## Unity

<table id="bkmrk-coucheemplacement-mo"><thead><tr><th>Couche</th><th>Emplacement</th></tr></thead><tbody><tr><td>Modèles</td><td>`Assets/Src/Game/Data/ByYear/`</td></tr><tr><td>Controllers</td><td>`Assets/Src/Game/Controllers/*ByYear*`</td></tr><tr><td>UI commune</td><td>`Assets/Src/UI/SimByYear/`</td></tr><tr><td>Game-specific</td><td>`Assets/GameSpecific/ent1|hr1|mgt1|mk1|mk2/`</td></tr></tbody></table>

## Serveur

- `_utils/utils_by_year.js` : cycle, calendrier, jobs, bots et helpers annuels;
- `_utils/utils_eval.js` : évaluations communes;
- `_utils/utils_rankings.js` : rankings;
- `_utils/factory/utils_factory_generate_results.js` : sélection du moteur de résultats par GameUid;
- `_utils/factory/utils_factory_eval.js` : sélection du moteur d'évaluation par GameUid;
- `<gameUid>/utils/*` : décisions, events, résultats et scoring propres au jeu.

## Game-specific

Contrairement à Accounting, By Year n'a pas une seule logique métier partagée. Le framework fournit le cycle; les jeux fournissent les décisions et les calculs. Il faut donc éviter de mettre les règles MK1, HR1 ou ENT1 dans une page “Common”.

## Ajouter un nouveau jeu By Year de A à Z

Un nouveau jeu annuel n'est pas seulement un nouveau dossier `GameSpecific`. Il doit être branché côté Unity, static data, serveur, génération, évaluation, résultats, messages, UI et factories.

### 1. GameUid et composition Unity

1. Ajouter le GameUid dans `SharedConstants`.
2. Le mapper vers `SimType.ByYear`.
3. Créer `Assets/GameSpecific/<gameUid>/`.
4. Créer les modèles `StaticData`, `Team`, `TeamDecisions`, `Results` et les controllers game-specific nécessaires.
5. Brancher les classes dans `Factory.cs`.

### 2. Static data

Ajouter le jeu dans `node.js/exports/exportAllData.js` avec Spreadsheet/GIDs et fichiers supplémentaires. Créer `Resources/data_<gameUid>`, importer puis vérifier `StaticDataController<Game>`.

### 3. Serveur game-specific

Créer `server_scripts/<gameUid>/` avec :

- `utils/<gameUid>_utils.js` — `GameSpecificUtils*`;
- `utils/<gameUid>_utils_generate_results.js` — `GenerateResults*`;
- `utils/<gameUid>_utils_eval.js` — `Eval*` si l'évaluation est spécifique;
- `utils/..._bots.js` si async/bots;
- wrappers `command/`.

### 4. Brancher les factories serveur

- `utils_factory_game_specific_utils.js`;
- `utils_factory_generate_results.js`;
- `utils_factory_eval.js`;
- `takeBotsDecision()` / factory bots si le jeu supporte les bots.

### 5. Définir le cycle annuel du jeu

Implémenter au minimum `startYearGameSpec(actData)`, `getYearData()`, `generateEvents()`, `gameSpecificInitTeam()`, `startCash()`, `anyDecisionsTaken()` et les helpers métier requis.

### 6. Génération

`GenerateResults<Game>.generateCurrentYearResults(actData)` doit être l'entrée unique du calcul annuel. Il doit lire les équipes/décisions, calculer les résultats, les sauvegarder et préparer l'état de l'année suivante sans dépendre de l'UI.

### 7. Unity UI

Créer les contrôles game-specific dans `GameSpecific/<gameUid>/Src/UI`, plus les prefabs/scenes/Resources. Les composants génériques année/eval/rankings restent sous `Src/UI/SimByYear`.

### 8. Textes, scénario, tutoriels, timelines

Ajouter les textes et assets propres au jeu. Si le jeu possède ses propres tutoriels/timelines, les placer dans ses dossiers GameSpecific et les brancher via les states/UI concernés.

### 9. Validation minimale

1. Créer une simulation.
2. Démarrer année 1.
3. Prendre au moins une décision.
4. Générer résultats.
5. Vérifier résultats + cash + ActPerf.
6. Passer à l'année suivante.
7. Réouvrir une année.
8. Tester async/bot si supporté.
9. Tester rankings/final sequence.