cookiecode/docs/atelier-cartes.md

# Atelier CookieCode avec cartes

Ce document explique comment utiliser CookieCode comme un atelier ludique avec des cartes physiques ou numeriques.

L'objectif n'est pas seulement d'ecrire du code : le participant doit ressentir qu'il construit quelque chose, qu'il progresse, et qu'il recoit un feedback positif a chaque etape.

## Principe de l'atelier

Le parcours conseille est :

```txt
Cartes -> Recette orale -> Code CookieCode -> Feedback -> Badge ou defi bonus
```

Chaque carte correspond a une idee de cuisine et a une notion de programmation.

| Carte | Exemple | Notion apprise |
| --- | --- | --- |
| Structure | `RECETTE`, `SERVIR` | programme, resultat |
| Ingredient | `farine`, `sucre`, `chocolat` | variable |
| Quantite | `200`, `g`, `minutes` | valeur |
| Materiel | `saladier`, `four`, `couteau` | constante / ressource |
| Action | `PRENDRE`, `AJOUTER`, `MELANGER`, `CUIRE` | fonction / instruction |
| Logique | `SI`, `SINON`, `REPETER` | condition / boucle |
| Objectif | `Utilise une boucle`, `Fais un cookie` | critere de reussite |

## Deroule d'une activite

### 1. Tirer une carte objectif

Exemple :

```txt
Defi : Cookie avec boucle
- utilise au moins 3 ingredients ;
- utilise melanger ;
- utilise cuire ;
- utilise repeter ;
- termine par servir.
```

L'animateur presente le defi comme une mission courte, pas comme un examen.

Phrase conseillee :

```txt
Ta mission : creer une recette-programme que Chef Cookie peut comprendre.
```

### 2. Construire la recette avec les cartes

Le participant pose les cartes dans l'ordre :

```txt
[RECETTE] [Cookie]
[PRENDRE] [farine] [200] [g]
[PRENDRE] [sucre] [100] [g]
[PRENDRE] [chocolat] [150] [g]
[AJOUTER] [farine]
[AJOUTER] [sucre]
[AJOUTER] [chocolat]
[MELANGER]
[REPETER] [2 fois] [MELANGER]
[CUIRE] [12] [minutes]
[SERVIR]
```

Le but est de manipuler l'algorithme avant de parler de syntaxe JavaScript.

### 3. Lire la recette a voix haute

Avant de coder, le participant lit son algorithme :

```txt
Je prends la farine, je prends le sucre, j'ajoute les ingredients, je melange, je repete, je cuis, je sers.
```

Ce moment est important : il transforme le code en histoire comprehensible.

### 4. Traduire en CookieCode

```js
const recette = CookieCode.recette("Cookie")
  .prendre("farine", 200, "g")
  .prendre("sucre", 100, "g")
  .prendre("chocolat", 150, "g")
  .ajouter("farine")
  .ajouter("sucre")
  .ajouter("chocolat")
  .melanger()
  .repeter(2, function (recette) {
    recette.melanger();
  })
  .cuire(12, "minutes")
  .servir();
```

### 5. Verifier le defi

```js
const defi = CookieCode.defi("Cookie avec boucle", {
  ingredientsMinimum: 3,
  actionsObligatoires: ["melanger", "cuire", "servir"],
  boucleObligatoire: true,
  terminerParServir: true,
  interdireErreurs: true
});

const verification = CookieCode.verifier(recette, defi);
console.log(verification.toText());
```

Sortie attendue :

```txt
Defi : Cookie avec boucle
Resultat : reussi
✅ Tu as utilise 3 ingredient(s).
✅ Action trouvee : melanger.
✅ Action trouvee : cuire.
✅ Action trouvee : servir.
✅ Tu as utilise une boucle avec repeter.
✅ Ta recette se termine par servir.
✅ Aucune erreur logique detectee.
```

## Feedback de satisfaction

Le feedback doit donner envie de continuer. Il doit valoriser ce qui est reussi avant de proposer une amelioration.

### Regle simple

Toujours utiliser ce format :

```txt
1. Bravo pour ce qui fonctionne.
2. Explique ce qui manque simplement.
3. Propose une action concrete.
```

Exemple :

```txt
Bravo, ta recette a deja une bonne sequence d'actions.
Il manque une boucle pour reussir le defi.
Essaie d'ajouter .repeter(2, function (recette) { recette.melanger(); }).
```

### Messages positifs conseilles

```txt
🍪 Bravo, ton programme-recette est lisible.
🥣 Tu as cree tes premieres variables avec les ingredients.
🔧 Tu as utilise du materiel comme une constante.
🔁 Super, tu as simplifie une repetition avec une boucle.
🧠 Bien joue, tu as utilise une condition pour prendre une decision.
🎉 Defi reussi : Chef Cookie peut suivre ta recette.
```

### Messages d'aide conseilles

```txt
Il manque juste un ingredient pour completer le defi.
Ta recette est presque prete : ajoute une etape servir a la fin.
Tu repetes plusieurs fois la meme action : une carte REPETER peut t'aider.
Tu as servi trop tot : garde SERVIR comme derniere carte.
Ton algorithme est comprehensible, on va maintenant l'ameliorer.
```

Le ton doit rester encourageant : on ne dit pas que le participant a echoue, on dit que la recette est "a ameliorer".

## Badges de progression

Les badges donnent une satisfaction immediate, meme quand le defi principal n'est pas encore complet.

| Badge | Condition |
| --- | --- |
| 🍪 Premier cookie | Premiere recette creee |
| 🥣 Chef des variables | Au moins 3 ingredients |
| 🔧 Chef du materiel | Au moins 1 materiel utilise |
| 🔁 Chef des boucles | Utilisation de `repeter` |
| 🧠 Chef des conditions | Utilisation de `si` |
| 🎯 Defi reussi | Tous les criteres du defi sont valides |
| 🛠 Debug cuisinier | Une recette incomplete a ete corrigee |

Ces badges peuvent etre donnes oralement, imprimes sur papier, ou affiches dans l'interface plus tard.

## Rythme conseille pour un atelier de 45 minutes

| Temps | Activite |
| --- | --- |
| 5 min | Presentation : recette = programme |
| 10 min | Manipulation libre des cartes |
| 10 min | Premier defi simple sans boucle |
| 10 min | Defi avec carte `REPETER` |
| 5 min | Feedback collectif et badges |
| 5 min | Defi bonus ou correction d'une recette cassee |

## Exemple de defis progressifs

### Defi 1 : Recette simple

```txt
Objectif : creer une recette qui se termine par servir.
Contraintes :
- au moins 2 ingredients ;
- au moins 3 actions ;
- finir par SERVIR.
```

### Defi 2 : Trouve la boucle

```txt
Objectif : ameliorer une recette repetee.
Contraintes :
- utiliser REPETER ;
- utiliser MELANGER dans la boucle ;
- finir par SERVIR.
```

### Defi 3 : Recette avec decision

```txt
Objectif : utiliser une condition.
Situation : la pate est trop seche.
Contrainte : utiliser SI pour ajouter du lait.
```

## Interaction cartes -> feedback CookieCode

Une carte objectif devient un objet `CookieCode.defi`.

```txt
Carte objectif :
- 3 ingredients minimum
- utiliser melanger
- utiliser cuire
- utiliser repeter
- finir par servir
```

Devient :

```js
CookieCode.defi("Cookie avec boucle", {
  ingredientsMinimum: 3,
  actionsObligatoires: ["melanger", "cuire", "servir"],
  boucleObligatoire: true,
  terminerParServir: true,
  interdireErreurs: true
});
```

Une suite de cartes recette devient un enchainement CookieCode.

```txt
[PRENDRE] [farine] [200] [g]
```

Devient :

```js
.prendre("farine", 200, "g")
```

```txt
[REPETER] [2 fois] [MELANGER]
```

Devient :

```js
.repeter(2, function (recette) {
  recette.melanger();
})
```

## A retenir pour l'animateur

- Le participant doit manipuler avant de coder.
- Le feedback doit etre rapide, visible et positif.
- Une erreur est une occasion de debug, pas un echec.
- Les cartes doivent aider a comprendre l'ordre des instructions.
- Le badge recompense une notion apprise, pas seulement un resultat parfait.