DeutschLernen/docs/features/lesson-management.md

# Feature: Lesson & Content Management

> **Status**: ⏳ Planned  
> **Priority**: High  
> **Complexity**: High  
> **Estimate**: 10-16 hours  
> **Assignee**: -  
> **Created**: May 31, 2025  
> **Target Completion**: -  
> **PR**: -  
> **Related Features**: Infrastructure Setup, User Authentication, Vocabulary System, Quiz System, Story Integration

---

## 📌 Overview

### Purpose
Implement the core lesson management system that allows users to browse, access, and progress through structured German lessons organized by CEFR levels (A1-C1).

### User Story
As a learner, I want to access structured lessons organized by difficulty level so that I can systematically learn German from A1 to C1.

### Acceptance Criteria
- [ ] Lessons are organized by CEFR levels (A1, A2, B1, B2, C1)
- [ ] Lessons within each level must be completed in order
- [ ] Each lesson contains vocabulary, grammar, story segment, and exercises
- [ ] Users can view lesson details and content
- [ ] Progress is tracked per user per lesson
- [ ] Lessons unlock sequentially based on quiz completion (80% passing score)

---

## 📋 Requirements

### Functional Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-001 | Create/Read/Update/Delete lessons (Admin) | High |
| FR-002 | List lessons by level | High |
| FR-003 | Get lesson details with all content | High |
| FR-004 | Track user progress through lessons | High |
| FR-005 | Enforce sequential lesson unlocking | High |
| FR-006 | Lesson contains: vocabulary, grammar, story, reading, listening, speaking, writing, quiz | High |
| FR-007 | Calculate level completion percentage | Medium |
| FR-008 | Admin can reorder lessons | Low |

### Non-Functional Requirements
- Performance: Lesson listing < 200ms
- Performance: Lesson details < 500ms
- Security: Only authorized admins can create/edit lessons
- Data Integrity: Lesson order must be maintained

---

## 🏗️ Technical Design

### Components Involved
- **Backend**: LessonsController, LessonService, LevelService
- **Database**: Levels, Lessons, UserProgress tables
- **Models**: Level, Lesson, LessonDto, LevelDto
- **Frontend**: LessonPage, LessonList, LessonCard components

### Data Flow
```
1. User requests lessons for A1 level
2. Backend queries Lessons table filtered by LevelId = A1
3. Backend checks UserProgress to determine which lessons are unlocked
4. Backend returns list of lessons with locked/unlocked status
5. User selects a lesson
6. Backend returns full lesson content (vocabulary, grammar, story, etc.)
7. User completes lesson activities
8. User takes quiz
9. If quiz passed (80%), mark lesson as completed and unlock next lesson
```

### API Endpoints
| Endpoint | Method | Description | Auth Required |
|----------|--------|-------------|----------------|
| `/api/levels` | GET | List all CEFR levels | Yes |
| `/api/levels/{levelId}/lessons` | GET | List lessons for a specific level | Yes |
| `/api/lessons/{id}` | GET | Get full lesson details with all content | Yes |
| `/api/lessons` | POST | Create new lesson (Admin) | Yes |
| `/api/lessons/{id}` | PUT | Update lesson (Admin) | Yes |
| `/api/lessons/{id}` | DELETE | Delete lesson (Admin) | Yes |
| `/api/lessons/{id}/reorder` | POST | Reorder lessons (Admin) | Yes |

### Database Schema (from application-plan.md)
```sql
-- Levels table
CREATE TABLE Levels (
    Id SERIAL PRIMARY KEY,
    Name VARCHAR(10) UNIQUE NOT NULL,  -- e.g., "A1", "A2"
    Description TEXT,
    Order INT UNIQUE NOT NULL
);

-- Lessons table
CREATE TABLE Lessons (
    Id SERIAL PRIMARY KEY,
    LevelId INT REFERENCES Levels(Id) ON DELETE CASCADE,
    Title VARCHAR(100) NOT NULL,
    Order INT NOT NULL,
    Topic VARCHAR(100) NOT NULL,
    UNIQUE(LevelId, Order)
);

-- User Progress table
CREATE TABLE UserProgress (
    Id SERIAL PRIMARY KEY,
    UserId INT REFERENCES Users(Id) ON DELETE CASCADE,
    LessonId INT,
    IsCompleted BOOLEAN DEFAULT FALSE,
    QuizScore INT,
    LastAttemptDate TIMESTAMP DEFAULT NOW(),
    UNIQUE(UserId, LessonId)
);
```

### Lesson Content Structure
Each lesson contains:
1. **Vocabulary**: 5-10 words with translations, articles, audio
2. **Grammar**: Concept explanation with examples and audio
3. **Story Segment**: Part of continuous narrative using lesson vocabulary
4. **Reading**: Short text with comprehension questions
5. **Listening**: Audio exercises with questions
6. **Speaking**: Recording exercises
7. **Writing**: Open-ended prompts
8. **Quiz**: 10-15 questions to test understanding

---

## 🚀 Implementation Plan

### Phase 1: Database & Models (2-3 hours)
- [ ] Create Level entity and repository
- [ ] Create Lesson entity and repository
- [ ] Create UserProgress entity and repository
- [ ] Set up relationships between entities
- [ ] Create migrations for Levels, Lessons, UserProgress
- [ ] Seed initial A1 level and lessons

### Phase 2: Backend Services (3-5 hours)
- [ ] Create LevelService with CRUD operations
- [ ] Create LessonService with CRUD operations
- [ ] Create ProgressService to track user progress
- [ ] Implement sequential unlocking logic
- [ ] Create DTOs for Level, Lesson, UserProgress
- [ ] Create mapping profiles (AutoMapper or manual)

### Phase 3: API Controllers (2-3 hours)
- [ ] Create LevelsController
- [ ] Create LessonsController
- [ ] Add authorization (Admin for write operations)
- [ ] Add validation for lesson data
- [ ] Implement proper error handling

### Phase 4: Business Logic (2-3 hours)
- [ ] Implement lesson unlocking logic
- [ ] Calculate level completion percentage
- [ ] Add next lesson recommendation
- [ ] Implement lesson order validation

### Phase 5: Integration with Other Features (1-2 hours)
- [ ] Integrate with Vocabulary system
- [ ] Integrate with Story system
- [ ] Integrate with Quiz system
- [ ] Update user progress on quiz completion

### Milestones
| Milestone | Date | Status |
|-----------|------|--------|
| Database & Models | - | ⏳ |
| Backend Services | - | ⏳ |
| API Controllers | - | ⏳ |
| Business Logic | - | ⏳ |
| Integration | - | ⏳ |

---

## ✅ Tasks

### Backend
- [ ] Create Domain/Entities/Level.cs
- [ ] Create Domain/Entities/Lesson.cs
- [ ] Create Domain/Entities/UserProgress.cs
- [ ] Create Domain/Interfaces/ILevelRepository.cs
- [ ] Create Domain/Interfaces/ILessonRepository.cs
- [ ] Create Infrastructure/Data/Repositories/LevelRepository.cs
- [ ] Create Infrastructure/Data/Repositories/LessonRepository.cs
- [ ] Create Infrastructure/Data/Repositories/UserProgressRepository.cs
- [ ] Create Application/DTOs/LevelDto.cs
- [ ] Create Application/DTOs/LessonDto.cs
- [ ] Create Application/DTOs/UserProgressDto.cs
- [ ] Create Application/Services/LevelService.cs
- [ ] Create Application/Services/LessonService.cs
- [ ] Create Application/Services/ProgressService.cs
- [ ] Create Presentation/Controllers/LevelsController.cs
- [ ] Create Presentation/Controllers/LessonsController.cs
- [ ] Register services in Program.cs
- [ ] Write unit tests for services
- [ ] Write integration tests for controllers

### Database
- [ ] Create migration for Levels table
- [ ] Create migration for Lessons table
- [ ] Create migration for UserProgress table
- [ ] Seed A1 level with initial lessons
- [ ] Add indexes for performance

### Business Logic
- [ ] Implement LessonUnlockService
- [ ] Implement LevelCompletionCalculator
- [ ] Add validation for lesson order
- [ ] Add authorization checks

### Integration
- [ ] Integrate with Vocabulary feature
- [ ] Integrate with Story feature
- [ ] Integrate with Quiz feature
- [ ] Update progress when quiz is passed

---

## 🔗 Dependencies

### Feature Dependencies
- [Infrastructure Setup](infrastructure-setup.md) - Required (backend project and database)
- [User Authentication](user-authentication.md) - Required (for user-specific progress tracking)
- Vocabulary System - Required (lesson content)
- Story Integration - Required (lesson content)
- Quiz System - Required (lesson completion)

### Technical Dependencies
- Entity Framework Core
- AutoMapper (optional, for DTO mapping)

### Blockers
- [ ] Infrastructure Setup must be complete
- [ ] User Authentication must be complete for progress tracking

---

## ✅ Definition of Done

### General Criteria (All Features)
- [ ] All acceptance criteria met and verified
- [ ] All tasks in this document completed
- [ ] Code follows Clean Architecture principles
- [ ] Code reviewed and approved by at least 1 team member
- [ ] All tests passing (unit, integration)
- [ ] Documentation updated (README, AGENTS.md if applicable)
- [ ] Feature works in development environment
- [ ] Feature deployed to staging environment
- [ ] Performance meets defined targets
- [ ] Security review completed
- [ ] No critical bugs or blockers

### Lesson Management-Specific Criteria
- [ ] All CEFR levels (A1-C1) can be created and managed
- [ ] Lessons can be created, read, updated, and deleted
- [ ] Lessons are properly ordered within levels
- [ ] Sequential lesson unlocking works correctly
- [ ] User progress is tracked per lesson
- [ ] Level completion percentage is calculated correctly
- [ ] Next lesson recommendation works
- [ ] Admin can reorder lessons
- [ ] All lesson content (vocabulary, grammar, story, etc.) can be associated

---

## 🧪 Testing Strategy

### Testing Approach

| Test Type | Coverage | Tools | Responsibility |
|-----------|----------|-------|----------------|
| Unit Tests | 80%+ code coverage | MsTest, Moq | Backend Dev |
| Integration Tests | All service interactions | MsTest, TestContainers | Backend Dev |
| API Tests | All endpoints | MsTest, HttpClient | Backend Dev |
| Frontend Unit Tests | Component logic | Vitest | Frontend Dev |
| Frontend Integration | Service integration | Vitest | Frontend Dev |
| E2E Tests | Critical user journeys | Playwright | QA/Dev |
| Manual Testing | Exploratory, edge cases | BrowserStack | QA |

### Lesson Management-Specific Tests

#### Backend Tests
- [ ] Create level → success
- [ ] Create level with duplicate name → error
- [ ] Get all levels → returns correct list
- [ ] Create lesson → success
- [ ] Create lesson with duplicate (level, order) → error
- [ ] Get lessons by level → returns correct list
- [ ] Get lesson by ID → returns correct lesson
- [ ] Update lesson → success
- [ ] Update lesson order → updates correctly, cascades to other lessons
- [ ] Delete lesson → success, updates other lessons' order
- [ ] Get user progress for lesson → returns correct status
- [ ] Complete lesson → updates progress, unlocks next lesson
- [ ] Calculate level completion → returns correct percentage

#### Business Logic Tests
- [ ] Lesson unlocking with completed previous lesson → success
- [ ] Lesson unlocking without completed previous lesson → fails
- [ ] Level completion with all lessons completed → 100%
- [ ] Level completion with some lessons completed → correct %
- [ ] Lesson reordering updates all subsequent lessons → correct
- [ ] Lesson deletion updates all subsequent lessons → correct

#### Integration Tests
- [ ] Create lesson with vocabulary → both created
- [ ] Create lesson with quiz → both created
- [ ] Complete lesson → triggers quiz availability
- [ ] User progress updates when quiz passed → lesson marked complete

---

## 📝 Notes & Decisions

### Decisions Made
| Date | Decision | Rationale |
|------|----------|-----------|
| May 31, 2025 | Sequential lesson unlocking | Ensures users learn foundation before advanced topics |
| May 31, 2025 | 80% passing score | Balance between rigor and user frustration |
| May 31, 2025 | Lessons organized by CEFR levels | Industry standard for language learning |
| May 31, 2025 | Unlimited quiz retakes | Encourages practice without penalty |

### Technical Notes
- Lesson order is critical - use database UNIQUE constraint on (LevelId, Order)
- UserProgress table tracks both completion status and quiz scores
- Progress calculation: (completed lessons / total lessons in level) * 100
- Lesson unlocking: User can access lesson N only if lesson N-1 is completed

### Gotchas
- ⚠️ Lesson reordering must update all subsequent lessons' Order values
- ⚠️ Deleting a lesson requires updating all lessons with higher Order values
- ⚠️ UserProgress.LessonId can be NULL for lessons not yet started
- ⚠️ Need to handle case where user hasn't started any lessons in a level

---

## 📊 Progress History

| Date | Status Change | Notes |
|------|---------------|-------|
| May 31, 2025 | Created | Initial plan based on application-plan.md |

---

## 📎 Related Files & Links

- Architecture: [Backend Structure](../architecture/backend-structure.md)
- Architecture: [Application Plan](../architecture/application-plan.md)
- Database Schema: [Initial Database Schema](../database/initial-database-schema.sql)
- Feature: [Vocabulary System](vocabulary-system.md)
- Feature: [Story Integration](story-integration.md)
- Feature: [Quiz System](quiz-system.md)

---

*Feature created from application-plan.md*