Forge-Engine/docs/plan/PLAN.md

# Plan de développement — Deux éditeurs distincts (Jeu 2D / Support de formation)

## Contexte et évolution du projet

Le système est parti d'un éditeur unique reposant sur des "boîtes" (conteneurs génériques posés sur une scène), avec trois piliers :

- **Scène** : zone d'édition où l'on pose des boîtes
- **Séparation visuel / contenu** : le template définit la mise en page, le contenu est renseigné à part
- **Flow** : système de déclencheurs événement → action

**Décision d'architecture actée : le projet se scinde en deux éditeurs séparés, qui ne se mélangent pas**, avec une différence fondamentale entre les deux qui structure tout ce plan :

| | Éditeur Jeu 2D | Éditeur Support de formation |
|---|---|---|
| Unité de base | Scène de jeu (objets natifs : sprites, formes, zones de collision) | Document unique (arbre d'éléments) |
| Logique | Boucle de jeu (update/render), moteur physique/collision | Pas de boucle de jeu, pas de logique événementielle |
| Mise en page | Positionnement libre x/y | Moteur d'inférence de layout auto (grid/flexbox) |
| **Flow (déclencheurs événement → action)** | **Oui — c'est le seul endroit où le Flow existe** | **Non — aucun Flow côté document** |
| Saisie des données | Propriétés de l'objet + Flow pour le comportement | **Formulaire dans le panneau Propriétés de chaque élément** |
| Contenu produit | Un jeu complet | Un document/parcours de formation |

**Point central de ce plan, à ne pas réintroduire par erreur dans une itération future : le Flow est une notion exclusive à l'éditeur Jeu 2D.** Le Support de formation n'a ni scan automatique d'éléments, ni déclencheurs, ni panneau Flow. Toute donnée ou paramètre d'un élément (texte, image, ou mini-jeu) se saisit directement via un **formulaire dans son panneau de propriétés** — c'est une saisie de contenu, pas une automatisation.

**Le système de "boîtes" disparaît des deux côtés** — c'était un artefact du système unique d'origine.

---

## 0. Restructuration réelle du dépôt — sous-dossiers `game/`/`document`, pas de dossiers racine séparés

**Historique de cette section** (deux corrections successives, pour ne pas répéter les mêmes hésitations) :
1. Version initiale : regrouper tout le code du jeu 2D dans un dossier racine `/game-editor`, le futur chantier dans `/document-editor`. **Jamais fait.**
2. Première correction (19/09/2026) : un simple renommage `screens/` → `game_engine/`, rien d'autre ne bouge. **Dépassée par la suite des événements le même jour** — voir ci-dessous l'état réellement en place.

**État réel du dépôt (actées et committées le 19/09/2026)** :

1. **`screens/` → `game_engine/`** : le paquet Python qui porte la logique du moteur du jeu 2D a été renommé (nom historique peu clair → nom explicite, avant l'arrivée d'un second "moteur" côté document). ~85 imports corrigés, contrat import-linter (`pyproject.toml`) inchangé dans sa forme (`routes -> ai|publish|core -> game_engine -> auth|filters -> db`), seul le nom du paquet a changé.

2. **Sous-dossiers `game/` dans `routes/`, `scripts/`, `static/`, `templates/`, `tests/`** : dans CHACUN de ces cinq dossiers, tout ce qui est propre à l'éditeur Jeu 2D a été déplacé dans un sous-dossier `game/` (`routes/game/`, `scripts/game/`, `static/game/`, `templates/game/`, `tests/game/`), tandis que ce qui est partagé par le site (comptes, onboarding, tableau de bord, upload générique, `db/`) reste directement à la racine de chacun de ces dossiers — **jamais de dossier racine séparé du dépôt**, contrairement à la version initiale de ce plan. Le contenu exact déplacé dans chaque `game/` :
   - `routes/game/` : `animations`, `custom_events`, `flow`, `flow_blocks`, `global_vars`, `ia`, `play`, `public_play`, `publish`, `scenes`, `screens`, `triggers`
   - `scripts/game/` : `build_demo_dialogues.py`, `generate_animal_sprite_manifest.py`, `generate_background_manifest.py`
   - `static/game/` : `js/{play,scenes,screen_edit,triggers,ia}`, `characters/`, `backgrounds/`, `icons/`, `quiz-templates/`
   - `templates/game/` : `scene_edit.html`, `play.html`, `_global_variable_row.html`
   - `tests/game/` : 44 fichiers de test (scène, Flow, dialogues, SCORM, sprites, triggers...)

3. **Un sous-dossier `document/` (vide) créé dans ces cinq mêmes dossiers** (`routes/document/`, `scripts/document/`, `static/document/`, `templates/document/`, `tests/document/`) — chacun avec un court marqueur (`__init__.py` docstring ou `README.md`) rappelant qu'aucune logique Flow n'y sera jamais introduite. Aucun code métier n'y vit encore.

4. **`ai/` et `publish/` (paquets Python racine) n'ont PAS bougé** — ils restent à la racine du dépôt tels quels ; seules leurs références internes vers les fichiers déplacés ci-dessus ont été mises à jour.

5. **`styles/` n'a volontairement PAS été touché** : ses 3 fichiers sources (`bulma-override.css`, `forge-tokens.css`, `forge-custom.css`) sont concaténés par `build_css.py` en un seul `static/style.css`, chargé sur TOUTES les pages du site. `forge-custom.css` mélange très probablement du CSS propre à l'éditeur de scène et du CSS partagé DANS LES MÊMES RÈGLES — scinder ce contenu serait un vrai refactor CSS (classer chaque règle), pas un déplacement mécanique de fichier. Décision explicite : à réévaluer plus tard, pas aujourd'hui.

6. **Deux fichiers orphelins découverts en cours de route** (aucune référence nulle part dans le dépôt), signalés mais non déplacés faute de pouvoir juger de leur destination : `static/object_form.js`, `templates/partials/clause_row.html`.

**Pour le futur chantier Support de formation** : le nouveau moteur de document (arbre unique, layout auto, mini-jeux — voir section 1) vivra dans un paquet Python dédié à sa propre logique métier (nom à choisir le moment venu, ex. `document_engine/`, par symétrie avec `game_engine/`), avec ses routes dans `routes/document/`, son JS/CSS dans `static/document/`, ses templates dans `templates/document/`, ses tests dans `tests/document/` — **jamais un dossier `flow/`** puisque cet éditeur n'a aucun Flow (voir tableau ci-dessus). Les mentions `/document-editor/...` plus bas dans ce document (sections 1 et 3, écrites avant cette restructuration) décrivent des **regroupements logiques** (quel code appartient à quel domaine) et doivent se lire comme `routes/document/`, `static/document/`, `templates/document/` selon le type de fichier — pas comme un dossier racine unique `/document-editor` qui n'existe pas et ne sera pas créé.

---

## 1. Éditeur Support de formation (`/document-editor`)

### 1.1 Principe général

Un seul document par formation/parcours, sans notion de "boîte" et sans Flow. Tout élément posé (forme, texte, image, ou bloc mini-jeu) est un **nœud de l'arbre du document**, mis en page par le même moteur automatique. Le contenu et les paramètres de chaque élément se saisissent via un **formulaire dans le panneau de propriétés**, au moment où l'élément est sélectionné.

### 1.2 Sous-systèmes à implémenter

#### A. Moteur de formes primitives (`/document-editor/elements/shapes`)
4 primitives : rectangle, cercle, triangle, trait. Rendu SVG. Propriétés éditables par panneau : position, taille, couleur de remplissage/bordure, épaisseur de bordure, rotation, z-index, label. **Complexité : faible.**

#### B. Moteur d'inférence de layout (`/document-editor/engine`)
Le plus complexe du projet : grille d'accroche, détection continue row/column/grid, recalcul au déplacement, responsive automatique (row→column, unités relatives, aperçu mobile/tablette/desktop), seuls réglages exposés = espacement et alignement. **Complexité : élevée.**
Point d'attention : performance du recalcul en temps réel, cas limites (chevauchement, éléments isolés).

#### C. Séparation structure / contenu
Chaque élément a un **UUID stable**, jamais recalculé depuis sa position dans l'arbre. Cette séparation n'a plus vocation à alimenter un Flow (qui n'existe pas ici) : elle garantit simplement que le contenu saisi dans un formulaire de propriétés reste attaché au bon élément si le document est réorganisé visuellement.

#### D. Panneau de propriétés — formulaires de contenu par type d'élément
Remplace ce qui était auparavant pensé comme un scan automatique + panneau Flow. Chaque type d'élément a son propre formulaire, affiché dans le panneau de droite dès qu'il est sélectionné :
- **Texte** (titre/paragraphe) : style, contenu, mise en forme, alignement, couleur
- **Image** : texte alternatif, remplacement d'image
- **Mini-jeu** : formulaire dédié à son modèle de données (cf. E) — c'est là que le RH saisit les questions d'un quiz, les paires d'une association, les mots d'un mots-mêlés, etc.

Aucun événement, aucune action, aucune référence croisée entre éléments : chaque formulaire est autonome et local à l'élément sélectionné.

#### E. Bibliothèque de mini-jeux (`/document-editor/elements/minigames`)
6 éléments cœur, regroupés par moteur d'interaction commun. La colonne "Formulaire de contenu" précise ce que le RH saisit dans le panneau de propriétés :

| Élément | Moteur | Templates couverts | Formulaire de contenu (panneau Propriétés) |
|---|---|---|---|
| Quiz | Sélection de réponse(s) + chrono optionnel | QCM, vrai/faux, texte libre, quiz chronométré | Liste de questions, chacune avec ses options, la bonne réponse et un texte de feedback |
| Glisser-déposer | Élément déplacé vers zone cible | Association, remise en ordre, texte à trous, glisser-classer | Liste d'éléments sources + liste de zones cibles + règle d'association attendue |
| Cartes | Retournement/révélation de carte | Memory, flashcards | Liste de paires (recto/verso) ou liste de cartes simples |
| Mots | Grille de lettres / saisie | Mots croisés, mots mêlés | Liste de mots à placer, orientations autorisées |
| Scénario | Choix → branche → conséquence | Scénario à embranchements, étude de cas, dialogue | Graphe de nœuds (situation, choix, nœud suivant) — éditeur dédié, pas un simple formulaire linéaire |
| Zones interactives | Clic sur zone d'une image | Point-and-click / hotspot | Image de fond + liste de zones (position, forme, texte associé) |

Optionnelles (non prioritaires) : Réflexe, Interaction live.

### 1.3 Ordre d'implémentation recommandé
1. Formes primitives + panneau de propriétés
2. Modèle de données du document (arbre unique) + rendu statique
3. Moteur d'inférence de layout
4. Formulaires de contenu pour Texte et Image dans le panneau de propriétés
5. Migration du Quiz existant vers le nouveau modèle d'élément, avec son formulaire de contenu
6. Glisser-déposer, puis Cartes, puis Zones interactives, puis Mots, puis Scénario (avec son éditeur de graphe dédié)
7. Templates de document prédéfinis

---

## 2. Éditeur Jeu 2D (`game_engine/` + `routes/game/`, `static/game/`, `templates/game/`, `tests/game/`, `scripts/game/`)

### 2.1 Principe général
Éditeur séparé pour jeux 2D classiques. **C'est le seul des deux éditeurs à posséder un Flow.** Sans layout auto, sans éléments mini-jeux (ceux-ci n'existent que côté Support de formation).

### 2.2 Retrait du système de boîtes
Les objets de la scène (y compris l'ancienne boîte Quiz avec son affichage plein écran) deviennent des **objets de jeu natifs**. Le comportement plein écran de l'ancienne boîte Quiz est retiré : les mini-jeux n'existent plus que côté Support de formation, où ils n'ont plus besoin de Flow puisqu'ils y fonctionnent par formulaire.

### 2.3 Points d'attention pour la migration
- Auditer les dépendances cachées à l'ancienne boîte Quiz (scoring partagé, timer global, pause pendant plein écran) avant suppression.
- Simplification du rendu vers un registre unique d'objets natifs.
- Pas de rétro-compatibilité automatique prévue avec les anciennes scènes.

### 2.4 Ordre d'implémentation recommandé
1. Audit des fonctionnalités dépendant du système de boîtes
2. Retrait du système de boîtes générique dans `game_engine/`
3. Réimplémentation native des fonctionnalités identifiées à l'audit
4. Nettoyage du Flow (suppression des actions spécifiques aux boîtes) — le Flow lui-même reste et continue de servir uniquement le jeu
5. Tests de non-régression

---

## 3. Fonctionnalités de l'éditeur de support de formation (inventaire complet)

Cette liste consolide toutes les fonctions validées à travers les maquettes interactives produites, à implémenter dans `/document-editor`. **Le panneau "Flow" présent dans les premières maquettes est retiré de la cible** : son contenu (détection d'éléments, déclencheurs) est remplacé par des formulaires de contenu dans le panneau Propriétés, comme détaillé en 3.4.

### 3.1 Document et canvas
- Document unique par module de formation, sans notion de boîte
- Ajout d'un élément par glisser-déposer depuis la bibliothèque (prototypé en clic-pour-ajouter dans la maquette, à remplacer par un vrai drag-and-drop)
- Sélection d'un élément avec poignées visuelles (4 coins)
- Mise en page automatique (grid/flexbox inférés, sans réglage technique exposé)
- Comportement responsive automatique (empilement sous un seuil de largeur)
- Zoom du canvas (boutons +/-, affichage du pourcentage)
- Undo / Redo
- Mode Aperçu
- Action Publier
- Bascule de thème clair/sombre de l'interface d'édition, mémorisée par utilisateur

### 3.2 Bibliothèque d'éléments (panneau gauche)
- Catégorie **Mise en page** : Rectangle, Cercle, Triangle, Trait
- Catégorie **Contenu** : Titre, Paragraphe, Image, Bouton
- Catégorie **Mini-jeux** : Quiz, Association, Memory, Mots mêlés, Scénario, Zones à risque

### 3.3 Panneau Propriétés — élément Texte (titre ou paragraphe)
- Sélecteur de style : Titre 1, Titre 2, Paragraphe, Légende — reclassification en un clic, indépendante de la structure
- Édition du contenu (zone de texte)
- Mise en forme : Gras, Italique, Souligné
- Alignement : gauche, centre, droite
- Couleur du texte (palette limitée aux jetons de la charte graphique)

### 3.4 Panneau Propriétés — élément Image
- Texte alternatif
- Remplacement de l'image

### 3.5 Panneau Propriétés — élément Mini-jeu
- Paramètres spécifiques au moteur (ex. nombre de questions pour un Quiz)
- Options (ex. chronomètre on/off)
- Thème visuel / accent coloré
- **Formulaire de contenu dédié** (cf. tableau en 1.2.E) : c'est ici, et uniquement ici, que le RH saisit les données du mini-jeu (questions/réponses, paires, mots, embranchements, zones). Aucune de ces données ne transite par un système d'événements — c'est un formulaire classique, sauvegardé avec l'élément.

Pour tout autre élément ajouté depuis la bibliothèque sans formulaire encore défini : état par défaut en attendant sa spécification. État vide : message d'invite quand rien n'est sélectionné.

### 3.6 Adaptation mobile de l'éditeur
- Barre de navigation basse à 3 entrées : Éléments / Document / Propriétés
- Panneaux gauche et droit transformés en volets plein écran, ouverts/fermés via la barre de navigation ou un bouton de retour
- Sélection d'un élément sur mobile ouvre automatiquement le panneau Propriétés

### 3.7 Application de la charte graphique Forge
- Jetons de couleur, typographie (Inter, poids 800/700/400/600) et rayons appliqués à toute l'interface
- Logo au tracé verrouillé, toujours affiché sur sa carte de fond dédiée
- Registre **Forgebase (interne)** appliqué à l'éditeur : dégradé réservé au logo uniquement, boutons sobres (contour), pas de badge tape-à-l'œil
- Glow au survol uniquement (jamais statique), sur les cartes de la bibliothèque et les blocs mini-jeux
- Mode clair ajouté en complément du mode sombre par défaut — **écart assumé par rapport à la règle de la charte « thème sombre sur toutes les surfaces »**, à formaliser dans une future révision du document de référence si le mode clair est conservé au-delà du stade de maquette

### 3.8 Document publié — vue apprenant (`/document-editor/viewer`)
- Rendu responsive du document, sans aucun élément d'édition (pas de poignées, pas de panneaux, pas de formulaires)
- Titre héros (H1) avec traitement dégradé signature — cas d'usage validé par la charte pour les « titres clés »
- Barre de progression du parcours de formation
- Élément Quiz pleinement interactif (et par extension chaque mini-jeu), alimenté par les données saisies dans son formulaire côté éditeur — aucune logique Flow n'intervient dans ce rendu
- Retours colorés sémantiques (bonne/mauvaise réponse), jetons dédiés pour rester lisible en clair comme en sombre
- Bascule de thème clair/sombre, mémorisée par apprenant
- Aucune version imprimable prévue — usage web uniquement

---

## 4. Récapitulatif des risques transverses

- **Performance du moteur d'inférence de layout** : recalcul en temps réel à chaque interaction, à profiler tôt
- **Discipline sur l'absence de Flow côté document** : toute tentation future d'ajouter de la logique conditionnelle (ex. "afficher telle section seulement si le quiz est réussi") doit être reconnue comme un changement d'architecture à valider explicitement, pas glissée dans un formulaire de propriétés par facilité
- **Fonctionnalités cachées liées à l'ancienne boîte Quiz côté Jeu 2D** : risque de régression si l'audit est sauté avant suppression
- **Aucun pont entre les deux éditeurs pour le moment** : décision actée, à traiter séparément si un besoin d'intégration émerge
- **Mode clair en écart avec la charte graphique** : à trancher formellement (cf. 3.7) avant implémentation définitive
- **Discipline sur `/shared/`** : éviter d'y placer du code par réflexe de mutualisation

---

## 5. Prochaines étapes suggérées

1. ~~Effectuer la restructuration des dossiers (section 0) avant toute nouvelle ligne de code~~ — **Fait le 19/09/2026** (renommage `game_engine/` + sous-dossiers `game/`/`document/` dans `routes/`, `scripts/`, `static/`, `templates/`, `tests/`, commit `b2e933f3`).
2. **Éditeur Jeu 2D** : lancer l'audit des dépendances à l'ancienne boîte Quiz avant suppression
3. **Éditeur Support de formation** : valider le modèle de données du document (arbre unique), sans dossier Flow
4. Prototyper le moteur d'inférence de layout sur un cas simple avant de généraliser
5. Migrer le Quiz existant vers le nouveau modèle d'élément, avec son formulaire de contenu en panneau Propriétés
6. Implémenter Glisser-déposer en second (meilleur ROI)
7. Trancher la question du mode clair vis-à-vis de la charte Forge
8. Traiter le Scénario à embranchements en dernier (éditeur de graphe dédié à concevoir)