chineseclass/ClassGenSystem/README.md

# ClassGenSystem - Système de Génération de Cours Gamifiés

## L'Idée

**ClassGenSystem** est un système basé sur JSON pour créer des cours d'apprentissage de langues structurés et gamifiés.

### Concept Original
Développé initialement pour **donner des cours d'anglais à des enfants chinois**, ce système transforme n'importe quel contenu éducatif en expérience d'apprentissage interactive et progressive.

### Application Actuelle
Le système est maintenant utilisé pour **réviser et apprendre le chinois** en transformant le contenu des cours (Hanyu Jiaocheng) en format gamifié, permettant un apprentissage autonome plus engageant.

---

## Architecture du Système

### Structure Hiérarchique

```
Book (Livre)
  ├── Métadonnées générales (niveau, durée, objectifs)
  └── Chapters (Chapitres)
        ├── Vocabulary (Vocabulaire)
        ├── Grammar (Grammaire)
        ├── Texts (Textes de lecture)
        └── Exercises (Exercices)
```

### Fichiers Principaux

- **`ledu-book.json`** : Métadonnées du livre complet et index des chapitres
- **`ledu-chapterX.json`** : Contenu détaillé de chaque chapitre
- **`Ref/`** : Fichiers de test et de référence pour valider le système

---

## Contenu d'un Chapitre

Chaque chapitre contient :

### 1. Vocabulaire
- **Mot** avec prononciation (pinyin/IPA)
- **Type** (nom, verbe, adjectif, morphème...)
- **Traduction** dans la langue de l'utilisateur
- **Exemples d'usage** (3-5 phrases contextuelles)
- **Notes** culturelles ou spéciales

**Exemple :**
```json
"重视": {
  "pronunciation": "zhòngshì",
  "type": "verb",
  "user_language": "attacher de l'importance à",
  "examples": [
    "中国人重视家庭。",
    "我们应该重视健康。"
  ]
}
```

### 2. Grammaire
- **Patterns** grammaticaux avec explications
- **Exemples** traduits avec pinyin
- **Usage** et nuances

**Exemple :**
```json
"yinci": {
  "title": "因此 (yīncǐ)",
  "pattern": "Situation, 因此 + Conséquence",
  "explanation": "Façon formelle d'exprimer cause-effet"
}
```

### 3. Textes
- **Textes principaux** (300-500 mots)
- **Textes étendus** pour lecture approfondie
- **Questions de compréhension** (ouvertes, vrai/faux, QCM)
- **Contexte culturel** authentique

### 4. Exercices
- Inférence de caractères (radicaux)
- Questions de compréhension
- Pratique vocabulaire
- Application grammaticale
- Pensée critique

---

## Gamification & Progression

### Métadonnées de Progression

Chaque chapitre inclut :
- **Durée estimée** (heures)
- **Niveau de difficulté**
- **Prérequis** (chapitres/compétences)
- **Objectifs d'apprentissage**
- **Tags de contenu** (thèmes)

### Critères de Complétion

```json
{
  "vocabulary_mastery_percentage": 80,
  "comprehension_score": 75,
  "exercises_completed": 15
}
```

### Suivi du Progrès

- Pourcentage global de progression
- Statut chapitre par chapitre
- Maîtrise du vocabulaire
- Scores de compréhension

---

## Exemples de Chapitres

### Chapitre 1 : "民以食为天" (Culture Alimentaire)
- **Focus** : Culture culinaire chinoise, étiquette
- **Vocabulaire** : 45+ termes (nourriture, culture, étiquette)
- **Contenu** : Philosophie culinaire + 9 règles d'étiquette
- **Durée** : 10 heures

### Chapitre 3 : "生命在于运动" (Sport & Fitness)
- **Focus** : Habitudes sportives, culture du sport
- **Vocabulaire** : 35+ termes sport et santé
- **Contenu** : Histoire du ping-pong, culture sportive chinoise
- **Durée** : 10 heures

### Stress Test (Ref/)
- **But** : Validation des performances système
- **Contenu** : 156 termes académiques avancés
- **Domaine** : Méthodologie de recherche, vocabulaire scientifique

---

## Utilisation

### 1. Créer un Nouveau Chapitre

```json
{
  "id": "chapter-X",
  "book_id": "ledu",
  "name": "Titre du chapitre",
  "chapter_number": X,
  "difficulty": "intermediate",
  "estimated_hours": 10,
  "vocabulary": { ... },
  "grammar": { ... },
  "texts": [ ... ],
  "exercises": [ ... ]
}
```

### 2. Workflow d'Apprentissage

1. **Lire le vocabulaire** et les patterns grammaticaux
2. **Étudier les textes** principaux et étendus
3. **Répondre aux questions** de compréhension
4. **Compléter les exercices** interactifs
5. **Vérifier la progression** selon les critères

### 3. Ajouter du Contenu de Cours

Pour transformer un cours (ex: Hanyu Jiaocheng) en JSON :
1. Identifier le vocabulaire clé du chapitre
2. Extraire les patterns grammaticaux
3. Sélectionner/créer des textes de lecture
4. Concevoir des exercices adaptés
5. Définir les critères de complétion

---

## Principes de Design

1. **Architecture Modulaire** : Séparation claire Livre → Chapitre → Contenus
2. **Apprentissage Multi-modal** : Vocabulaire + Grammaire + Lecture + Exercices
3. **Difficulté Progressive** : Prérequis et niveaux de difficulté
4. **Contexte Culturel** : Textes authentiques chinois
5. **Évaluation Complète** : Critères multiples (vocabulaire, compréhension, exercices)
6. **Multi-langue** : Support de plusieurs langues (chinois, anglais, français)
7. **Scalable** : Nombre illimité de chapitres avec schéma cohérent

---

## Localisation des Fichiers

**Contenu Principal :**
- `ledu-book.json` - Métadonnées du livre complet
- `ledu-chapter1.json` à `ledu-chapter4.json` - Chapitres individuels

**Référence/Tests :**
- `Ref/test-heavy.json` - Test de charge standard
- `Ref/test-heavy-stress.json` - Test de stress système

---

## Statut Actuel

- ✅ **Système prêt** depuis 5 jours
- ✅ **4 chapitres** créés et structurés
- ✅ **Tests de stress** validés
- 🔄 **En cours** : Intégration du contenu Hanyu Jiaocheng pour révisions
- 🎯 **Objectif** : Transformer tous les cours en format gamifié pour apprentissage autonome

---

## Vision

Créer une plateforme d'apprentissage complète où :
- Le contenu pédagogique devient **engageant** et **interactif**
- La progression est **mesurable** et **motivante**
- L'apprentissage est **structuré** mais **flexible**
- Le système s'adapte à **n'importe quel contenu** linguistique

**From teaching tool to learning companion.**