Concept et architecture¶

Le chaos pédagogique est le module d'apprentissage de PerfShop : un escape-room technique greffé sur la boutique e-commerce, dans lequel un étudiant — incarnant un « agent » — résout une série d'énigmes imbriquées dans le tunnel d'achat pour progresser dans un parcours gradué de BAC+1 à BAC+5. Cette page documente la philosophie, les composants et le cycle de vie d'un parcours. Les pages suivantes détaillent chaque mécanique (niveaux, énigmes, code agent, étoiles, indices, succès, thèmes finaux).

Pourquoi un escape-room sur un site e-commerce ?¶

Un site e-commerce est un terrain de jeu narratif universel : tout le monde a déjà ajouté un produit à un panier, rempli une adresse et validé un paiement. En greffant des énigmes sur ces actions familières, l'étudiant apprend à observer un système réel plutôt qu'à suivre un tutoriel. L'énigme le force à lire le catalogue, à comparer des prix, à décoder un payload JWT ou à croiser des en-têtes de réponse avec un dashboard Grafana — c'est-à-dire à naviguer dans une application en production comme un ingénieur qui découvre un environnement inconnu.

La mécanique est volontairement simple côté joueur : chaque énigme attend une réponse textuelle courte. Côté serveur, la réponse est hashée en SHA-256 puis comparée à un hash pré-calculé — la bonne réponse n'est jamais transmise en clair. Cette contrainte oblige à concevoir des énoncés dont la réponse tient en un mot, un nombre ou une adresse IP : les ambiguïtés sont interdites, la pédagogie est explicite.

Ce que le chaos pédagogique n'est pas

Ce n'est pas un MOOC. Il n'y a ni cours magistral, ni vidéo, ni correction automatique des erreurs. L'étudiant apprend en faisant fonctionner la boutique pendant qu'un formateur orchestre la session depuis le panneau chaos-admin. La documentation technique de cette section décrit le mécanisme du moteur ; elle ne contient aucune réponse d'énigme.

Les cinq niveaux — vue à 10 000 pieds¶

Le système propose cinq parcours indépendants ; un étudiant peut rejoindre n'importe lequel dès que le formateur l'a activé.

Niveau	Nom interne	Étapes	Durée	Thématique dominante	⭐ max
BAC+1	`bac1`	10	30 min	Mathématiques pures, arithmétique commerciale	1
BAC+2	`bac2`	15	45 min	Logique, suites, chiffrement de César, combinatoire	2
BAC+3	`bac3`	20	60 min	HTTP, Docker, observabilité, bases de protocoles	3
BAC+4	`bac4`	25	75 min	Hexadécimal, XOR, JWT, IPv6, algorithmique	4
BAC+5	`bac5`	30	90 min	RSA simplifié, Dijkstra, Hamming, complexité, crypto	5

Total : 100 énigmes, toutes stockées dans le backend Java (PedagogiqueEnigmeBac1 … PedagogiqueEnigmeBac5). Chaque niveau se termine par une étape dynamique dont la réponse dépend d'un code agent unique par étudiant — voir agent-code.md. Le détail niveau par niveau est dans levels.md.

Rôles et composants¶

flowchart LR
    subgraph FORMA[Formateur]
      ADM[Page chaos-admin<br/>onglet Pédagogique]
    end
    subgraph ETUDIANT[Étudiant]
      BOUT[Navigateur<br/>boutique PerfShop]
      OVR[Overlay<br/>PedagogiqueOverlay]
      TIM[Timer<br/>PedagogiqueTimer]
      SUC[Page succès<br/>/s/:token]
    end
    subgraph BACK[Backend Spring Boot]
      CTRL[ChaosStudentController]
      SVC[PedagogiqueSessionService]
      ENI[PedagogiqueEnigme<br/>+ catalogues Bac1–5]
    end
    subgraph DB[(MySQL)]
      TAB[pedagogique_sessions]
    end
    ADM -->|POST /activate<br/>/deactivate<br/>/hints| CTRL
    BOUT --> OVR
    BOUT --> TIM
    OVR -->|POST /join<br/>/validate| CTRL
    SUC -->|GET /succes/{token}<br/>POST /logique/*<br/>/finale/validate| CTRL
    CTRL --> SVC
    SVC --> TAB
    CTRL --> ENI

Les deux acteurs humains — formateur et étudiant — ne partagent aucun identifiant : le formateur s'authentifie avec son jeton admin (X-Admin-Token), l'étudiant avec un token de session opaque (X-Student-Token) généré au POST /pedagogique/join et stocké en localStorage sous la clé ped_student_token. Ce cloisonnement est le fondement de l'architecture multi-session décrite dans architecture/multi-session.md.

Côté formateur — `chaos-admin`¶

Le panneau chaos-admin, servi par le conteneur éponyme, expose l'onglet Pédagogique. Depuis ce panneau le formateur peut :

activer un parcours pour un niveau donné (POST /pedagogique/activate)
désactiver le parcours en cours (POST /pedagogique/deactivate)
consulter en direct la liste des étudiants connectés et leur progression (GET /pedagogique/sessions)
basculer les indices (bouton 💡) en temps réel pendant le parcours (POST /pedagogique/hints)
activer ou non le cache mémoire write-through pour la démonstration Chaos Mémoire (case à cocher « Mode mémoire — heap dump pédagogique »)
consulter le dernier récapitulatif après une désactivation (GET /pedagogique/last-summary)

Le panneau formateur ne stocke rien en local : toutes les vues sont construites à partir des endpoints du backend. Il polle sessions toutes les quelques secondes pour rafraîchir le tableau de progression.

Côté étudiant — boutique + overlay¶

Trois composants React orchestrent l'expérience étudiant depuis App.jsx :

Composant	Rôle	Durée de vie
`PedagogiqueOrchestrator`	Point d'entrée monté une seule fois hors des `<Routes>`. Détecte l'activation d'un parcours, pilote le timer et l'overlay, déclenche la navigation vers `/s/:token` quand le parcours est complété.	Toute la session navigateur
`PedagogiqueTimer`	Timer fixe en haut à droite de l'écran. Couleur verte → orange → rouge, puis « Temps écoulé ». Ancrage anti-drift : décompte basé sur `Date.now()`, resynchronisé à chaque polling.	Pendant le parcours actif
`PedagogiqueOverlay`	Fenêtre flottante, draggable, qui affiche l'énoncé de l'étape courante, un champ de réponse, le bouton 💡 indice (si activé), et — après une bonne réponse — la note culturelle et le décompte avant l'étape suivante.	Pendant le parcours actif

Le hook usePedagogiqueState pilote le polling GET /api/chaos/student/status toutes les 15 secondes. Il gère aussi le join automatique : si la réponse contient pedagogique.needsJoin = true, le hook envoie un POST /pedagogique/join avec un alias aléatoire (Agent-XXXX — 4 chars hex), stocke le token reçu et redéclenche un polling immédiat. Côté frontend, le token est la seule preuve d'identité ; le perdre revient à perdre sa progression.

Côté backend — Spring Boot¶

Le backend expose tous les endpoints sous le préfixe /api/chaos/student/pedagogique/* dans ChaosStudentController. La logique métier est déléguée à PedagogiqueSessionService (interface) et son unique implémentation DefaultPedagogiqueSessionService. Le catalogue des énigmes est statique et monté en mémoire au démarrage par la classe PedagogiqueEnigme, qui délègue le chargement à cinq classes compagnes : PedagogiqueEnigmeBac1 à PedagogiqueEnigmeBac5.

Les énoncés, indices et notes culturelles ne sont pas codés en dur en Java : ils sont externalisés dans des fichiers JSON i18n, résolus via la méthode t(level, key) selon la variable d'environnement PERFSHOP_LANG. Le mécanisme est détaillé dans la page i18n/enigmes.md.

Cycle de vie d'un parcours¶

Du clic formateur jusqu'au déblocage du hub de mini-jeux, une session traverse neuf étapes bien identifiées.

sequenceDiagram
    autonumber
    actor F as Formateur
    actor E as Étudiant
    participant ADM as chaos-admin
    participant CTR as ChaosStudentController
    participant SVC as DefaultPedagogiqueSessionService
    participant DB as MySQL<br/>pedagogique_sessions
    participant ENI as PedagogiqueEnigme

    F->>ADM: Clique "Activer bac3"
    ADM->>CTR: POST /pedagogique/activate<br/>{level:"bac3", memoryCache:false}
    CTR->>SVC: clearAll()
    CTR->>ENI: forLevel("bac3")
    Note over CTR: pedagogiqueActive=true<br/>startTime=now()

    E->>CTR: GET /status (polling)
    CTR-->>E: pedagogique.needsJoin=true

    E->>CTR: POST /pedagogique/join {alias}
    CTR->>SVC: createSession(alias, "bac3", 3600)
    SVC->>SVC: compute agentCode (hex)
    SVC->>SVC: compute extractionAnswerHash
    SVC->>SVC: compute logiqueQuestionIndices (LCG)
    SVC->>SVC: compute logiqueExpectedHash
    SVC->>DB: INSERT pedagogique_sessions
    SVC-->>CTR: MutableSession
    CTR-->>E: {token, alias, level, totalSteps, timerRemaining}

    loop Pour chaque étape
      E->>E: Lit l'énoncé, agit dans la boutique
      E->>CTR: POST /pedagogique/validate<br/>{step, answerHash}
      CTR->>CTR: Compare hash (DYNAMIC ou statique)
      alt Réponse correcte
        CTR->>SVC: saveSession(step+=1)
        SVC->>DB: UPDATE current_step
        CTR-->>E: {valid:true, nextEnigme, culturalNote?}
      else Réponse incorrecte
        CTR->>SVC: saveSession(attempts++)
        CTR-->>E: {valid:false, attempts}
      end
    end

    Note over E: Dernière étape DYNAMIC validée
    CTR->>SVC: completedAt = now()
    CTR-->>E: {valid:true, completed:true, stars, maxStars}

    E->>E: Navigation vers /s/{token}
    E->>CTR: GET /pedagogique/succes/{token}
    CTR-->>E: {alias, level, stars, durationSeconds}

    E->>E: Choisit un thème final
    E->>CTR: POST /pedagogique/finale/validate<br/>{theme, answerHash}
    alt Thème logique
      Note over E,CTR: Phase 1 : /logique/check<br/>Phase 2 : /finale/validate
    end
    CTR-->>E: {valid:true, gameUrl}
    E->>E: window.location = gameUrl

Quand la dernière énigme est validée, completedAt est renseigné et le PedagogiqueOrchestrator navigue automatiquement vers /s/:token. Le token est l'authentification : il est non-devinable (UUID v4), porté par l'URL, et la page est entièrement hors de la navbar/footer PerfShop pour un effet « fin de parcours » distinct. Voir success.md pour le détail.

Accès au hub de mini-jeux pédagogiques

Une fois le thème final validé, l'étudiant accède à un hub de mini-jeux pédagogiques déployé à part. La documentation technique du hub elle-même n'est pas exposée dans cette référence.

Architecture multi-session en une phrase¶

La base de données MySQL est toujours la source de vérité ; un cache mémoire ConcurrentHashMap write-through peut être activé à chaud par le formateur pour la démonstration Chaos Mémoire — dans ce mode, les objets MutableSession apparaissent dans les heap dumps et illustrent visuellement une fuite mémoire typique. Voir architecture/multi-session.md pour le détail du pattern write-through, et hints.md pour la propagation en temps réel des indices.

Limite de 500 sessions concurrentes

Le endpoint POST /pedagogique/join refuse tout nouveau join avec un HTTP 429 Too Many Requests dès que le service dépasse 500 sessions actives. Cette limite est une protection contre la saturation mémoire/base et couvre très largement les usages attendus (cohortes classiques de 20 à 60 étudiants). Pour un événement exceptionnel de type hackathon à plusieurs centaines de participants, envisager plusieurs instances backend ou une adaptation de la constante dans ChaosStudentController.

Internationalisation¶

Le moteur est nativement multilingue. Les énoncés, indices et notes culturelles sont chargés une fois au démarrage depuis les fichiers src/main/resources/i18n/enigmes/bacN/enigmes_XX.json selon la variable d'environnement PERFSHOP_LANG (défaut : fr).

Le code Java supporte sept langues (fr, en, de, zh, es, it, pt) ; à date, les cinq niveaux disposent des sept fichiers correspondants pour les énigmes. Le pool de 25 questions du thème Logique & Mathématiques est disponible en fr et en ; les autres langues tomberont automatiquement sur le fallback français en attendant leur traduction. Ajouter une langue ne nécessite aucune modification Java : il suffit de déposer le fichier JSON traduit dans le bon répertoire et de redémarrer le backend.

La documentation MkDocs que vous lisez est quant à elle construite pour cinq langues (fr, en, es, de, it) — voir la configuration plugins.i18n dans mkdocs.yml.

Pages suivantes : Niveaux BAC1 à BAC5 → · Système d'énigmes → · Code agent dynamique →