Collectif API · documentation interne

Niveau suivant

La page depuis laquelle tout se retrouve. Les liens, l'architecture, la façon d'écrire une épreuve, les décisions déjà prises et les raisons qui les ont motivées. Écrite pour moi maintenant, pour moi dans six mois, et pour ceux qui reprendront le dispositif quand il sera public.

Point de départ

Les liens

Tout ce qui existe ou existera autour du projet. L'état de chaque pièce est indiqué : ne pas envoyer un lien marqué à construire.

La proposition à l'E2C écritLe document adressé à l'école, celui qu'on donne à Cécile. Adresse à retenir : /doc/presentation.html La note de conception écritLe détail du jeu : mécaniques, épreuves, part physique, écarts de niveau, pauses créatives, questions ouvertes. Le jeu en placeLe plateau isométrique, un segment par époque de l'informatique, de 1983 à aujourd'hui. Se joue seul.La version précédente conservéeLe premier jeu, celui qui sait jouer à plusieurs avec un code et que pilote la console du maître du jeu. Gardé entier dans /v1/.L'écran du mur en placeLa scène affichée sur les 55 pouces : le plateau en grand, et le plein cadre sur les moments forts.Mode maître du jeu ?mjAjouter ?mj à l'adresse du jeu ouvre un raccourci vers n'importe quel segment, sans refaire les épreuves, plus un bouton pour ouvrir l'étage où l'on se trouve. ⛔ Ne se montre jamais aux joueurs. Ce n'est pas une serrure : les réponses sont de toute façon dans contenu.js. La console du maître du jeu en placeMot de passe. Les parties en direct, les codes à dicter, les solutions, et l'effacement des parties. ⛔ ne se montre jamais aux joueurs. L'écran du maître du jeu en placeDiffusé sur l'écran mural du QG. Palier en cours, score du groupe, codes de validation. La récréation en placeLa page de création générative ouverte à chaque palier franchi. Trois onglets depuis le 13/09 : Image · Synthé (synthe.html, formes d'onde, filtre, enveloppe, LFO, écho) · Beat (beat.html, 16 pas, boom bap, lo-fi, trap, drill). Aucun son téléchargé : tout est fabriqué par le code, comme la vraie 808. Chaque atelier a un carnet de mots qui se remplit en touchant les boutons, jamais noté.
L'éditeur d'épreuves à écrireÉcrire une épreuve sans coder. Sert le troisième jour, quand les jeunes fabriquent celles de la promotion suivante.
Le langage visuel en placeUne seule feuille pour les quatre pages : couleurs, boutons, champs, récompenses. Chaque étage y pose sa couleur dans --accent. Le contenu écritLa source unique des épreuves. Un seul fichier, lu par toutes les pages. Le site en ligne sous-domaine à créerniveau-suivant.collectif-api.com — dépôt dédié, base MySQL partagée.
En bref

Le projet en dix lignes

Quatre promotions de l'École de la deuxième chance de Coutras viennent chacune trois jours au QG Créatif relever des épreuves numériques. Le site est le jeu : on le fouille, comme un escape game, et le parcours quitte régulièrement l'écran.

Le Collectif API écrit quatre épreuves sur cinq. La cinquième est écrite par les jeunes, qui la testent d'abord sur l'autre moitié de leur propre groupe avant qu'elle ne parte, en bonus, à la promotion suivante.

Les points mesurent la progression et non le niveau. Chaque palier franchi ouvre une récréation créative de dix minutes, jamais notée, et c'est elle qui produit les œuvres que chacun rapporte.

Le dossier vise l'axe 3 de l'appel « Ateliers Numériques » de la Fondation Afnic, dépôt le 9 octobre 2026.

Technique

Architecture

Où ça vit

  • Sous-domaine dédié niveau-suivant.collectif-api.com, son propre dépôt, déploiement par webhook.php comme les autres sites. Jamais le module Git du panneau d'hébergement, il se déconnecte sans prévenir.
  • Base MySQL partagée avec les autres outils, tables préfixées ns_. Les identifiants vivent dans db.php, à la racine, jamais versionné.
  • Migration automatique dans le code. Une fonction gardée par un numéro de version de schéma crée et fait évoluer les tables au premier chargement. ⛔ Jamais de SQL tapé à la main dans phpMyAdmin.

Le temps réel qui n'en est pas

L'hébergement mutualisé ne permet pas de connexion permanente. Chaque poste interroge le serveur toutes les une à deux secondes. Pour huit joueurs c'est invisible et c'est increvable. Ne pas chercher mieux tant que ça suffit.

Les tables

TableCe qu'elle garde
ns_partiesUne partie : son code à six caractères, la promotion, le palier atteint, le score du groupe, la date. Une ligne par séance.
ns_joueursUn pseudo par personne, rattaché à une partie, avec son score, son sous-groupe et sa dernière activité. Aucun nom réel, aucune adresse.
ns_validationsChaque épreuve réussie : par qui, quand, en combien de temps, avec ou sans indice. C'est de là que sort la mesure de progression.
ns_partageL'état des épreuves à plusieurs pendant qu'elles se jouent. Vidé en fin de partie.
ns_oeuvresLes réglages de chaque création de récréation, pour pouvoir la rejouer et la réimprimer plus tard.

Vie privée

Le jeu accueille un public en insertion, chez un partenaire. Il ne manipule que des pseudonymes, les parties sont effacées après chaque promotion, et les fichiers déposés dans les épreuves sont vérifiés dans le navigateur : ils ne quittent jamais la machine du joueur.

Pas de mesure d'audience sur ce sous-domaine. Suivre des sessions de public en insertion contredirait ce qu'on annonce. C'est une exception assumée à la règle qui l'impose partout ailleurs.

Le geste le plus fréquent

Écrire ou corriger une épreuve

Tout se passe dans contenu.js. C'est la source unique : le plateau, l'écran du maître du jeu et l'éditeur le lisent tous. ⛔ Ne jamais recopier une épreuve ailleurs, les deux versions finiraient par diverger.

Les champs

ChampÀ quoi il sert
idIdentifiant court et stable. Ne jamais le changer une fois qu'une partie a été jouée avec, sinon les scores enregistrés ne se rattachent plus à rien.
mecanique1 comparer · 2 chercher dans un fichier · 3 produire et déposer · 4 coopérer en asymétrie · 0 validé par le maître du jeu.
difficulte1 facile, 2 moyen, 3 difficile. Sert à doser un parcours, pas à classer les joueurs.
typeflag réponse tapée · fichier dépôt vérifié localement · duo épreuve partagée · code délivré par le maître du jeu.
reponseComparée sans tenir compte de la casse, des accents, des espaces ni de la ponctuation. Le jeu accepte en plus les variantes courantes d'écriture : « control f », « ctrl+f » et « ctrl f » sont la même réponse, comme « 2 janvier 2025 » et « 02/01/2025 ». Plusieurs formulations acceptées : un tableau.
formatObligatoire dès qu'on tape une réponse. Une ligne courte affichée sous le champ : « jj/mm/aaaa », « un nombre », « le nom du fichier, extension comprise ». Sans elle, quelqu'un qui a trouvé 39 et qui écrit trente-neuf croit s'être trompé.
aidesLes deux niveaux gratuits du panneau latéral : d'abord de quoi on parle (le vocabulaire), puis où regarder (la piste). Exactement deux, ni plus ni moins.
indiceLe troisième niveau, payant : la méthode exacte, le geste précis. Il coûte un point, et c'est le seul.
plusLe « aller plus loin ». Obligatoire depuis le 10 septembre 2026 : une épreuve n'est finie que quand ses deux réponses sont trouvées, et la porte de l'étage ne s'ouvre pas avant.
teaserSur le palier, pas sur l'épreuve. Une seule phrase, affichée à l'entrée de l'étage. Elle annonce de quoi il va être question sans rien déflorer.

Le panneau d'indices, et pourquoi deux niveaux sont gratuits

Chaque épreuve porte trois niveaux d'aide, ouverts l'un après l'autre depuis le panneau latéral de la fenêtre. Les deux premiers ne coûtent rien, le troisième coûte un point.

  • ① De quoi on parle. Le vocabulaire. Ce qu'est un fichier CSV, ce qu'est une extension, ce que sont des métadonnées. Gratuit.
  • ② Où regarder. La piste, sans le geste. Gratuit.
  • ③ La méthode. Le geste exact, celui qui résout. Coûte un point, et c'est le seul qui coûte quelque chose.

Quelqu'un qui ignore ce qu'est un fichier CSV n'est pas en train de tricher : il est exactement au point où le jeu est censé lui apprendre quelque chose. Lui faire payer ça reviendrait à faire payer le cours. Le panneau ne s'ouvre jamais de force : au bout d'une minute sans bonne réponse, le bouton respire et annonce combien d'aides attendent. Le joueur décide, mais il sait.

⛔ Une réponse ne doit jamais pouvoir se deviner

Les questions à deux ou trois choix ont toutes été retirées le 10 septembre 2026. Le défaut était net : rien n'empêchait d'écrire A, de voir que c'était faux, puis d'écrire B. On réussissait sans jamais ouvrir la pièce jointe, donc sans rien apprendre.

À la place, une réponse est une preuve qu'on est allé voir : une adresse à recopier, un nom de fichier, un compte à faire, une date à calculer. Un verrou de quelques secondes après une erreur casse en plus la saisie en rafale, mais c'est un garde-fou, pas la solution. La solution est dans la question.

⛔ Et on ne punit jamais l'erreur : aucun point retiré, aucun compteur de fautes affiché. Un public en insertion n'a pas besoin d'un rappel de plus qu'il s'est trompé. Ce qu'on garde, c'est l'inverse : les épreuves trouvées du premier coup, saluées à la fin.

Les quatre mécaniques

Le jeu n'a que quatre familles d'épreuves, plus une soupape. C'est ce qui le rend extensible : on ajoute du contenu, jamais du code. Et c'est ce qui permet à des jeunes d'écrire une épreuve sans savoir programmer.

  • 1 · Comparer et choisir. Deux choses se ressemblent, une seule est la bonne.
  • 2 · Chercher dans un vrai fichier. On ouvre un vrai document avec un vrai logiciel et on en rapporte un code.
  • 3 · Produire et déposer. On fabrique un fichier, le jeu vérifie son format, son poids, ses dimensions.
  • 4 · Coopérer en asymétrie. Personne ne voit la même chose, il faut se parler.
  • 0 · La soupape. Le maître du jeu constate et délivre un code. C'est ce qui permet d'inventer des épreuves qu'aucun programme ne saurait vérifier, et c'est indispensable pour laisser les jeunes écrire librement.
Version courte

Le parcours de démonstration

Une vingtaine de minutes, dix épreuves, cinq étages, et une récréation entre chacun. Elle sert à trois publics : l'E2C, qui jouera à plusieurs dans ses locaux ; le comité de sélection de la Fondation Afnic, qui ouvrira le lien seul et sans prévenir ; et nos propres essais.

La courbe est voulue : on entre par deux épreuves que personne ne peut rater, pour que tout le monde marque avant de réfléchir, et on sort par deux épreuves qui demandent vraiment de fouiller. Chaque étage porte sa propre couleur, reposée sur toute la page dès qu'on y entre.

ÉtageÉpreuveCe qu'on y apprendDiff.
1 · Mise en boucheLe presse-papierCopier et coller au lieu de retaper1
Combien ça pèseLire le poids d'un fichier dans ses propriétés1
2 · Ouvrir l'œilPresque le mêmeLire une adresse d'expéditeur caractère par caractère1
La photo se souvientLes données cachées d'une image2
3 · Mettre les mains dedansQuatre cents lignesTrier et filtrer plutôt que lire3
Au formatRecadrer, redimensionner, exporter2
4 · Se parlerÀ trois voixDécrire un écran qu'on est seul à voir3
Le mot du maître du jeuNommer et ranger ses fichiers1
5 · Le fond du sacLe dossier en désordreDécompresser une archive et y chercher3
L'extension mentLe nom d'un fichier ne dit pas ce qu'il contient3

Deux portes d'entrée, et pourquoi

La partie à plusieurs pour l'E2C : un code, des pseudos, et des épreuves qui n'ont de sens qu'à plusieurs. Elle suppose que les joueurs soient dans la même pièce ou au téléphone, et la page d'accueil doit le dire.

Le parcours solo pour le comité de sélection. Un membre du jury ouvrira le lien seul, un soir. S'il tombe sur une épreuve qui exige trois joueurs, il ferme l'onglet. En solo, l'épreuve asymétrique montre les trois panneaux côte à côte, avec la mention qu'en partie réelle chacun n'en voit qu'un.

Ce qui manque volontairement à la démonstration

Le chrono de progression, la phase d'écriture du troisième jour, les épreuves qui passent par le monde physique (le nom du réseau, le scanner, le cadenas, la carte mémoire, la clé USB piégée) et le kaléidoscope piloté à la main. Aucune n'est jouable à distance, c'est la seule raison de leur absence. Le dire sur la page d'accueil, plutôt que de laisser croire que le jeu se résume à ça.

La salle

L'écran du maître du jeu

Le QG Créatif est un open space. Six à huit postes sur une table centrale, le maître du jeu sur un côté, et un écran de 55 pouces au mur relié à sa machine.

  • Le grand écran est une scène, pas une surface de contrôle. On fabrique aux postes, on montre au mur.
  • Pendant le jeu il affiche le palier en cours, le score du groupe, le seuil à atteindre et qui vient de valider quoi. Lisible à quatre mètres.
  • Pendant la récréation il devient la salle d'exposition : une œuvre à la fois, plein cadre, avec le pseudo de son auteur. ⛔ Jamais une grille de vignettes, ce serait un concours.
  • À part, une page réservée au maître du jeu génère les codes de validation. Elle ne se montre jamais aux joueurs.

Techniquement, la même page sert les deux usages : un paramètre dans l'adresse bascule entre la vue écran, sans contrôles et en grand, et la vue poste avec les réglages.

Mise en ligne

Brancher le sous-domaine

À faire une seule fois. Le dépôt doit contenir le code à sa racine : l'hébergeur déploie tout le contenu dans le dossier public, un sous-dossier ne fonctionnerait pas.

  1. Créer le sous-domaineniveau-suivant.collectif-api.com dans le panneau d'hébergement.
  2. Créer le dépôtUn dépôt dédié sur le compte de l'association, et y pousser le contenu de ce dossier.
  3. Déposer db.phpÀ la racine du dossier public, avec les identifiants de la base partagée. Jamais versionné.
  4. Cloner sur le serveurEn SSH et en adresse SSH : l'adresse en https échoue, l'authentification par mot de passe n'existe plus.
  5. Brancher le webhookUne adresse de charge utile vers webhook.php, un secret propre au sous-domaine, et l'évènement de poussée uniquement.
  6. Vérifier la première livraisonLire le corps de la réponse, pas seulement le code. Un 200 accompagné d'un message d'erreur signifie que le déploiement a échoué quand même.

Les pièges déjà payés

  • Le webhook doit forcer la mise à jour plutôt que fusionner, sinon un fichier déposé à la main sur le serveur bloque tout.
  • Certaines fonctions d'exécution sont désactivées sur ce compte. Une réponse vide en 500 veut dire que le script est mort avant les commandes.
  • ⛔ Ne jamais téléverser à la main un fichier qui est aussi suivi par le dépôt. C'est la cause la plus fréquente de site figé.
  • Si le téléversement échoue en 400, changer de navigateur avant de chercher plus loin.
Mémoire du projet

Décisions prises, et pourquoi

Cette liste existe pour éviter de refaire deux fois le même débat. Chaque ligne a été tranchée, la raison compte autant que la décision.

  • Quatre mécaniques, pas quarante. Des énigmes codées une par une auraient rendu impossible l'écriture par les jeunes, et donc effondré la boucle qui tient tout le projet.
  • Les points mesurent la progression, pas le niveau. Le plus à l'aise se retrouve avec un plafond bas, celui qui partait loin a un boulevard. Le handicap est automatique et invisible.
  • ⛔ Pas de parcours séparés par niveau. Séparer visiblement les forts et les autres dans un groupe de six à huit est socialement désastreux, et cela doublerait le contenu à écrire. À la place : une seule épreuve, plusieurs profondeurs.
  • ⛔ L'auto-évaluation déclarative ne classe personne. Les publics en insertion se sous-estiment, les plus assurés se surestiment. On la garde pour l'écart entre croire et savoir. Le vrai point de départ se mesure par un échauffement pratique, dont le résultat reste invisible.
  • ⛔ La récréation n'est jamais notée. Dès qu'il y a des points, ce n'est plus une pause, et le groupe le sent.
  • Les œuvres sont individuelles. Une par personne et par palier. Les rassembler plus tard en fresque collective reste une option ouverte, pas un engagement.
  • Les 20 % écrits par les jeunes s'ajoutent en bonus. Ils ne remplacent rien, donc aucune promotion n'hérite d'un parcours plus long que la précédente.
  • ⛔ Le CV reste au programme de l'école. On ne traite que les gestes numériques qui le servent, via la recopie d'un modèle d'affiche.
  • ⛔ Les démarches administratives sont simulées chez nous, jamais sur les vrais services.
  • « Les mains sur la table ». Sur une épreuve dont il a déjà la réponse, le plus à l'aise n'a plus le droit de toucher au clavier, il peut seulement parler. Règle tenue en direct par le maître du jeu, volontairement pas codée.
  • ⛔ Écartés au fil des discussions : le podcast et le court-métrage, le guide écrit par les participants sous forme scolaire, les badges fabriqués, le magazine, et tout habillage qui ferait ressembler l'outil à un formulaire en ligne.
Chantier

Ce qui reste à faire

  1. La partie à plusieurs dans la version actuelleLe plateau attend déjà les autres joueurs, il manque la conversation avec le serveur. Tant que ce n'est pas fait, une séance passe par la version précédente, ce qui veut dire deux jeux à maintenir.
  2. L'écran du mur sur le réseauIl passe aujourd'hui par un canal interne au navigateur : deux fenêtres d'un même ordinateur. Assez pour une démonstration, pas pour la salle.
  3. Les trophées à collectionnerÀ la fin de chaque étage, choisir son trophée parmi plusieurs images animées, avec un titre attaché — « roi du copier-coller », « acharné des raccourcis ». Des communs, des rares, des légendaires, pour que deux personnes n'aient jamais la même collection. La fiche de score reprend les choix.
  4. Un endroit où souffler ensembleUn espace numérique qui se mérite plutôt qu'un salon de discussion ouvert en permanence : de quoi poser une blague, envoyer une icône, teinter quelque chose de commun. ⚠️ Un serveur de discussion grand public avait fait perdre un groupe entier pendant trente minutes il y a trois ans. Ce qu'on cherche, c'est le plaisir de l'échange, pas la porte ouverte.
  5. La revue des méthodes sur le grand écranÀ la fin d'un étage, un jeune vient refaire l'épreuve en direct sur la machine du maître du jeu et montre comment lui a fait. Plusieurs chemins mènent à la même réponse, et c'est justement ce qu'on veut rendre visible. C'est aussi la documentation par les jeunes, sans qu'ils aient rien à rédiger.
  6. Les autres épreuvesVingt-quatre existent, deux épisodes de douze. L'objectif annoncé est de quatre-vingts, y compris celles qui passent par le monde physique.
  7. L'éditeur d'épreuvesPour que les jeunes en écrivent sans coder, le troisième jour. ⛔ Reporté explicitement.

Questions encore ouvertes

  • Quand la récréation doit-elle être accessible ? Elle s'ouvre aujourd'hui à chaque étage franchi, et depuis l'écran de fin. Faut-il la fermer le reste du temps, et qu'est-ce qui l'ouvre : la vitesse, le groupe, un trophée ?
  • Le bloc numérique de l'école s'appuie-t-il déjà sur le référentiel national des compétences numériques ? Si oui, le jeu s'y branche au lieu d'inventer son échelle.
  • La taille réelle des groupes disponibles trois jours d'affilée.
  • Les téléphones : posés sur la table, ou utilisés puisque c'est justement l'appareil à comprendre ? La piste retenue est les deux, posés par défaut et repris explicitement quand ils sont l'outil de l'épreuve.
  • Le budget matériel de la part physique : cadenas, boîtes, carte mémoire, lecteur.
  • L'image de victoire est encore appelée chez un service tiers. À remplacer par une image à nous avant les séances avec les jeunes, et avant de bâtir les trophées dessus.