Class_generator/docs/progress-system.md

# Progress System

## 🎯 Core Philosophy

**FUNDAMENTAL RULE**: Every piece of content is a trackable progress item with strict validation and type safety.

## 🏗️ Pedagogical Flow

```
1. DISCOVERY → 2. MASTERY → 3. APPLICATION
   (passive)      (active)       (context)
```

### Flow Rules (NON-NEGOTIABLE)

- ❌ **NO Flashcards on undiscovered words** - Must discover first
- ❌ **NO Text exercises on unmastered vocabulary** - Must master first
- ✅ **Always check prerequisites before ANY exercise**
- ✅ **Form vocabulary lists on-the-fly** from next exercise content

## 📦 Progress Item Types & Weights

| Type | Weight | Prerequisites |
|------|--------|---------------|
| vocabulary-discovery | 1 | None |
| vocabulary-mastery | 1 | Must be discovered |
| phrase | 6 | Vocabulary mastered |
| dialog | 12 | Vocabulary mastered |
| text | 15 | Vocabulary mastered |
| audio | 12 | Vocabulary mastered |
| image | 6 | Vocabulary discovered |
| grammar | 6 | Vocabulary discovered |

**Total for 1 vocabulary word** = 2 points (1 discovery + 1 mastery)

## 📈 Progress Calculation

### Chapter Analysis

When loading a chapter:

1. **Scans ALL content** (vocabulary, phrases, dialogs, texts, etc.)
2. **Creates progress items** for each piece
3. **Calculates total weight** (sum of all item weights)
4. **Stores item registry** for tracking

**Example Chapter:**
- 171 vocabulary words → 342 points (171×2: discovery + mastery)
- 75 phrases → 450 points (75×6)
- 6 dialogs → 72 points (6×12)
- 3 lessons → 45 points (3×15)
- **TOTAL: 909 points**

### Progress Formula

```javascript
percentage = (completedWeight / totalWeight) × 100

// Example:
// - Discovered 50 words = 50 points
// - Mastered 20 words = 20 points
// - Completed 3 phrases = 18 points (3×6)
// - Completed 1 dialog = 12 points
// Total completed = 100 points
// Progress = (100 / 909) × 100 = 11%
```

### Breakdown Display

```javascript
{
  percentage: 11,
  completedWeight: 100,
  totalWeight: 909,
  breakdown: {
    'vocabulary-discovery': { count: 50, weight: 50 },
    'vocabulary-mastery': { count: 20, weight: 20 },
    'phrase': { count: 3, weight: 18 },
    'dialog': { count: 1, weight: 12 }
  }
}
```

## 🎯 Smart Vocabulary Prerequisites

### OLD Approach (Wrong)
Force all 171 words upfront based on arbitrary percentages.

### NEW Approach (Correct)
Analyze next content → extract words → check user status → force only needed words.

### Example Flow

```javascript
// Next exercise: Dialog "Academic Conference"
// Words in dialog: methodology, hypothesis, analysis, paradigm, framework

// User status check:
// - methodology: never seen → Discovery needed
// - hypothesis: discovered, not mastered → Mastery needed
// - analysis: mastered → Skip
// - paradigm: never seen → Discovery needed
// - framework: discovered, not mastered → Mastery needed

// Smart system creates:
// 1. Discovery module: [methodology, paradigm] (2 words)
// 2. Mastery module: [hypothesis, framework] (2 words)
// 3. Then allow dialog exercise
```

### Benefits

- **Targeted Learning** - Only learn words actually needed
- **Context-Driven** - Vocabulary tied to real content usage
- **Efficient Progress** - No time wasted on irrelevant words
- **Better Retention** - Words learned in context of upcoming usage
- **Smart Adaptation** - UI accurately reflects what's happening

## 🔧 Key Components

### 1. ProgressItemInterface
Abstract base with strict validation for all progress items.

**Location**: `src/DRS/interfaces/ProgressItemInterface.js`

**Methods**:
- `validate()` - Validate item data
- `serialize()` - Convert to JSON
- `getWeight()` - Return item weight
- `canComplete(state)` - Check prerequisites

### 2. ProgressTracker
Manages state, marks completion, saves progress.

**Location**: `src/DRS/services/ProgressTracker.js`

**Key Methods**:
- `markWordDiscovered(word, metadata)`
- `markWordMastered(word, metadata)`
- `markContentCompleted(type, id, metadata)`
- `getProgress(chapterId)`
- `saveProgress(bookId, chapterId)`
- `loadProgress(bookId, chapterId)`

### 3. PrerequisiteEngine
Checks prerequisites and enforces pedagogical flow.

**Location**: `src/DRS/services/PrerequisiteEngine.js`

**Key Methods**:
- `canComplete(itemType, itemId, context)`
- `getUnmetPrerequisites(itemType, itemId)`
- `enforcePrerequisites(exerciseConfig)`

### 4. ContentDependencyAnalyzer
Analyzes content and extracts vocabulary dependencies.

**Location**: `src/DRS/services/ContentDependencyAnalyzer.js`

**Key Methods**:
- `analyzeContentDependencies(nextContent, vocabularyModule)`
- `extractWordsFromContent(content)`
- `findMissingWords(wordsInContent, vocabularyWords)`

## 📊 UI Integration

### Progress Display

```
Chapter Progress: 11% (100/909 points)

✅ Vocabulary Discovery: 50/171 words (50pts)
✅ Vocabulary Mastery: 20/171 words (20pts)
✅ Phrases: 3/75 (18pts)
✅ Dialogs: 1/6 (12pts)
⬜ Texts: 0/3 (0/45pts)
```

### Smart Guide Updates

```
🔍 Analyzing next exercise: Dialog "Academic Conference"
📚 4 words needed (2 discovery, 2 mastery)
🎯 Starting Vocabulary Discovery for: methodology, paradigm
```

## ✅ Validation Checklist

**Before ANY exercise can run:**

- [ ] Prerequisites analyzed for next specific content
- [ ] Missing words identified
- [ ] Discovery forced for never-seen words
- [ ] Mastery forced for seen-but-not-mastered words
- [ ] Progress item created with correct weight
- [ ] Completion properly tracked and saved
- [ ] Total progress recalculated

**If ANY step fails → Clear error message, app stops gracefully**

## 🚨 Error Prevention

### Compile-Time (Startup)
- Interface validation via ImplementationValidator
- Method implementation checks
- Weight configuration validation

### Runtime
- Prerequisite enforcement before exercises
- State consistency checks
- Progress calculation validation

### Visual Feedback
- Red screen for missing implementations
- Clear prerequisite errors
- Progress breakdown always visible

## 🔍 Debug Commands

```javascript
// Get current progress
window.app.getCore().progressTracker.getProgress('chapter-1')

// Check if word discovered
window.app.getCore().progressTracker.isWordDiscovered('methodology')

// Check if word mastered
window.app.getCore().progressTracker.isWordMastered('hypothesis')

// Check prerequisites
window.app.getCore().prerequisiteEngine.canComplete('dialog', 'dialog-3')

// Get unmet prerequisites
window.app.getCore().prerequisiteEngine.getUnmetPrerequisites('text', 'lesson-1')
```

## 📋 Adding New Progress Item Types

1. Create new class extending `ProgressItemInterface`
2. Implement all 4 required methods
3. Add weight to `WEIGHTS` constant
4. Add to `ImplementationValidator`
5. Update `ProgressTracker` tracking methods
6. Update UI components
7. Test with validation

## 🧪 Testing Progress System

```javascript
// Test progress calculation
const tracker = window.app.getCore().progressTracker;

// Mark some progress
await tracker.markWordDiscovered('test', {});
await tracker.markWordMastered('test', {});

// Check progress
const progress = tracker.getProgress('chapter-1');
console.log(progress);

// Should show updated percentage and breakdown
```

## 📖 Further Reading

- `docs/interfaces.md` - Interface system details
- `docs/creating-new-module.md` - Module creation guide
- `README.md` - Project overview