# Foundation Segment Framework

## Version
- Framework: v1.0
- Date: 2025-10-30
- Type: Foundation Segment (Grammar/Vocabulary)

---

## Overview

Le Foundation Segment est un **enabler** - il ne teste pas une skill spécifique comme Speaking ou Writing, mais plutôt la **compréhension grammaticale** et la **maîtrise du vocabulaire** qui servent de base pour toutes les skills.

**Objectif** : Vérifier que l'étudiant comprend et peut appliquer les structures grammaticales et le vocabulaire enseignés durant le mois.

**Important** : Pas de production libre extensive comme dans les Skill Segments. Focus sur compréhension + application contrôlée.

---

## Foundation Exam Structure (100 points)

### **Exercice 1 : Vocabulary Mastery (10 points)**
- **20 mots aléatoires** tirés de tous les chapters du mois
- **10 L1→L2** (ex: Français → 中文)
- **10 L2→L1** (ex: 中文 → Français)
- **Scoring** : 0.5 point par réponse exacte
- **Critère** : Réponse EXACTE uniquement, pas de contexte, pas de MCQ
- **Objectif** : Prouver qu'on connaît le mot sans béquille

---

### **Exercice 2 : Grammar Application (10 points)**
- **10 structures grammaticales** à appliquer
- Une phrase est donnée, l'étudiant doit compléter/utiliser la structure imposée
- **Scoring** : 1 point par structure utilisée correctement
- **Critère** : On évalue UNIQUEMENT la structure, pas le sens/créativité
- **Exemple** : "Utiliser 把字句 : _______" → étudiant produit une phrase avec 把

---

### **Exercice 3 : Text Comprehension - Factual (10 points)**
- **1 texte** utilisant vocab et grammar du mois
- **10 questions simples** de type factuel : Où ? Qui ? Quand ? Quoi ? Pourquoi ? Comment ?
- **Scoring** : 1 point par réponse correcte
- **Objectif** : Compréhension basique du texte (factuel, pas d'interprétation)

---

### **Exercice 4 : Text Comprehension - Detailed (10 points)**
- Basé sur le même texte que Exercice 3
- **5 points spécifiques du texte** à expliquer avec ses propres mots
- **Scoring** : 2 points chacun
- **Critère** : Compréhension + début d'expression (reformulation personnelle)
- **Objectif** : Vérifier compréhension plus profonde + capacité à reformuler

---

### **Exercice 5 : Grammar Transformation (10 points)**
- **5 phrases à reformuler** avec contrainte grammaticale imposée
- **Exemples de transformations** :
  - Actif → Passif
  - Affirmatif → Négatif
  - Présent → Passé
  - Phrase simple → Structure complexe (ex: 不但...而且...)
- **Scoring** : 2 points par reformulation correcte
- **Critère** : Structure grammaticale contrôlée uniquement

---

### **Exercice 6 : Error Correction (10 points)**
- **5 phrases générées par IA** avec erreurs grammaticales/vocabulaire intentionnelles
- Basées sur les structures et vocab du mois
- L'étudiant doit identifier et corriger les erreurs
- **Scoring** : 2 points par phrase corrigée sans erreur
- **Objectif** : Capacité à reconnaître et corriger les erreurs courantes

---

### **Exercice 7 : Cloze Test - Vocabulary in Context (10 points)**
- **Texte à trous** avec options proposées pour chaque trou
- **10 mots manquants** à placer correctement (choix multiples pour chaque trou)
- **Scoring** : 1 point par mot correct
- **Objectif** : Comprendre le vocab en contexte, pas juste en isolation

---

### **Exercice 8 : Translation (10 points)**
- **5 phrases à traduire** (L1→L2 ou L2→L1)
- Phrases utilisent vocab et grammar du mois
- **Scoring** : 2 points par phrase correcte
- **Critère** : Traduction correcte (grammar + vocab)

---

### **Exercice 9 : Coherent Production (20 points)**
- **Contraintes imposées** :
  - 5 mots aléatoires du mois (à utiliser obligatoirement)
  - 5 structures grammaticales du mois (à utiliser obligatoirement)
- **Objectif** : Écrire un texte cohérent qui fait du sens ET utilise tous les éléments imposés
- **Scoring** :
  - 1 point par mot utilisé correctement (5 points total)
  - 1 point par structure utilisée correctement (5 points total)
  - 10 points pour la cohérence globale du texte
- **Critère** : Le texte doit faire du sens. On ne peut pas juste lister les mots/structures sans cohérence.

---

## Passing Criteria

- **>80%** : PASS ✓ - Excellent, continue normalement
- **50-80%** : DIFFICULTY ⚠ - Révision nécessaire, identifie les weak points
- **<50%** : CRITICAL ✗ - Arrête la progression, révision intensive obligatoire

---

## Notes Importantes

### Pas de MCQ pur
- Exercice 1 (Vocab Mastery) = réponse libre exacte, pas de choix multiples
- Exercice 7 (Cloze Test) = seul exercice avec options proposées, car c'est du vocab EN CONTEXTE

### Progression de difficulté
- Ex 1-2 : Isolation (vocab/grammar seuls)
- Ex 3-4 : Compréhension (lire et comprendre)
- Ex 5-6 : Application (transformer/corriger)
- Ex 7-8 : Contexte (vocab en contexte + traduction)
- Ex 9 : Production (créer quelque chose de cohérent)

### Universalité
Ce framework fonctionne pour **n'importe quelle langue**. Il suffit d'adapter :
- L1/L2 selon la paire de langues
- Types de structures grammaticales selon la langue cible
- Longueur de texte selon niveau

---

## Technical Implementation

### Format & Storage

**Format** : JSON + HTML interface

**Structure des fichiers** :
```
Exams/Foundation/YYYY-MM/
  ├── exam.json                    # Généré par AI - questions + structure
  ├── exam-answers.json            # Copie de exam.json + réponses étudiant
  └── exam-corrected.json          # Généré par AI - notes + feedback
```

### Workflow A→Z

#### 1. Génération (AI)
- **Input** : Chapters complétés durant le mois (ex: Hanyu Ch 1, 3, 4, 5)
- **Process** : AI génère `exam.json` selon structure définie
- **Output** : `Exams/Foundation/YYYY-MM/exam.json`

#### 2. Passage de l'exam (Étudiant)
- Copier `exam.json` → `exam-answers.json`
- Charger dans interface HTML
- Remplir les champs `"answer": "..."` pour chaque question
- Sauvegarder `exam-answers.json`

#### 3. Correction (AI)
- **Input** : `exam-answers.json` (contient questions + réponses)
- **Process** : AI évalue chaque réponse selon critères
- **Output** : `exam-corrected.json` avec champs `"rate": X` + feedback global

### Structure JSON

Chaque exercice utilise une **structure rigide** pour garantir la validation mécanique.

**Exemple Exercice 1** :
```json
{
  "metadata": {
    "exam_id": "foundation-hanyu-202501",
    "month": "2025-01",
    "segment": "foundation",
    "chapters_covered": ["1", "3", "4", "5"],
    "generated_date": "2025-01-25",
    "total_points": 100
  },
  "exercice1_vocabulary": {
    "total_points": 10,
    "l1_to_l2": {
      "word1": { "l1": "parler", "l2_expected": "说", "points": 0.5, "answer": "", "rate": null },
      "word2": { "l1": "ami", "l2_expected": "朋友", "points": 0.5, "answer": "", "rate": null },
      ...
      "word10": { ... }
    },
    "l2_to_l1": {
      "word11": { "l2": "学习", "l1_expected": "étudier", "points": 0.5, "answer": "", "rate": null },
      ...
      "word20": { ... }
    }
  }
}
```

**Champs** :
- `l1`, `l2`, `l2_expected`, `l1_expected` : Données de l'exam (générées par AI)
- `answer` : Rempli par l'étudiant dans `exam-answers.json`
- `rate` : Rempli par AI dans `exam-corrected.json` (score obtenu)

### Validation

#### Validation Structurelle (mécanique - comme un compilateur)
- Vérifier que JSON est parsable
- Vérifier présence de tous les exercices (1-9)
- Vérifier nombre exact de questions par exercice :
  - Ex1 : word1-word20 (20 mots)
  - Ex2 : structure1-structure10 (10 structures)
  - Ex3 : question1-question10 (10 questions)
  - etc.
- Vérifier que chaque champ requis existe et n'est pas vide

#### Validation de Contenu (basique)
- Vérifier longueur minimum des textes
- Vérifier cohérence des points (total = 100)
- Pas de validation qualité des textes (trust & iterate)

#### Script de validation
À créer : `validate-exam.js` qui vérifie structure + contenu basique avant publication de l'exam.

### Génération de l'exam par AI

**Stratégie** : Trust & Iterate
- Pas de validation qualité AI-to-AI au début
- Si problèmes en pratique → ajuster prompts ou ajouter AI review

**Input requis** :
- Liste des chapters complétés durant le mois
- Vocab lists de ces chapters
- Grammar structures de ces chapters

**Process** :
1. AI scan les chapters du mois pour ce segment
2. AI génère `exam.json` selon structure rigide définie
3. Validation mécanique du JSON
4. Si validation OK → exam publié, sinon → regénération

**Prompt de génération** : À définir (sera créé plus tard)

### Correction par AI

**Input** : `exam-answers.json` (contient toutes les questions + réponses étudiant)

**Process** :
- AI évalue chaque réponse selon critères de l'exercice
- AI génère feedback détaillé par exercice
- AI calcule score total

**Output** : `exam-corrected.json` avec :
- Champs `rate` remplis pour chaque question
- Feedback global
- Score total et statut (PASS/DIFFICULTY/CRITICAL)

**Prompt de correction** : À définir (sera créé plus tard)

---

## Prochaines étapes

- [ ] Définir structure JSON complète exercice par exercice
- [ ] Créer script de validation (validate-exam.js)
- [ ] Définir prompts de génération pour AI
- [ ] Définir prompts de correction pour AI
- [ ] Créer interface HTML pour passage d'exam
- [ ] Tester avec un exam pilote
- [ ] Itérer selon résultats