Restructure: Move 43 files into 8 domain packages (backend-lehrer)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

backend-lehrer/units/analytics_models.py

@@ -0,0 +1,127 @@
+"""
+Unit Analytics API - Pydantic Models.
+
+Data models for learning gains, stop performance, misconceptions,
+student progress, class comparison, and export.
+"""
+
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class TimeRange(str, Enum):
+    """Time range for analytics queries"""
+    WEEK = "week"
+    MONTH = "month"
+    QUARTER = "quarter"
+    ALL = "all"
+
+
+class LearningGainData(BaseModel):
+    """Pre/Post learning gain data point"""
+    student_id: str
+    student_name: str
+    unit_id: str
+    precheck_score: float
+    postcheck_score: float
+    learning_gain: float
+    percentile: Optional[float] = None
+
+
+class LearningGainSummary(BaseModel):
+    """Aggregated learning gain statistics"""
+    unit_id: str
+    unit_title: str
+    total_students: int
+    avg_precheck: float
+    avg_postcheck: float
+    avg_gain: float
+    median_gain: float
+    std_deviation: float
+    positive_gain_count: int
+    negative_gain_count: int
+    no_change_count: int
+    gain_distribution: Dict[str, int]
+    individual_gains: List[LearningGainData]
+
+
+class StopPerformance(BaseModel):
+    """Performance data for a single stop"""
+    stop_id: str
+    stop_label: str
+    attempts_total: int
+    success_rate: float
+    avg_time_seconds: float
+    avg_attempts_before_success: float
+    common_errors: List[str]
+    difficulty_rating: float  # 1-5 based on performance
+
+
+class UnitPerformanceDetail(BaseModel):
+    """Detailed unit performance breakdown"""
+    unit_id: str
+    unit_title: str
+    template: str
+    total_sessions: int
+    completed_sessions: int
+    completion_rate: float
+    avg_duration_minutes: float
+    stops: List[StopPerformance]
+    bottleneck_stops: List[str]  # Stops where students struggle most
+
+
+class MisconceptionEntry(BaseModel):
+    """Individual misconception tracking"""
+    concept_id: str
+    concept_label: str
+    misconception_text: str
+    frequency: int
+    affected_student_ids: List[str]
+    unit_id: str
+    stop_id: str
+    detected_via: str  # "precheck", "postcheck", "interaction"
+    first_detected: datetime
+    last_detected: datetime
+
+
+class MisconceptionReport(BaseModel):
+    """Comprehensive misconception report"""
+    class_id: Optional[str]
+    time_range: str
+    total_misconceptions: int
+    unique_concepts: int
+    most_common: List[MisconceptionEntry]
+    by_unit: Dict[str, List[MisconceptionEntry]]
+    trending_up: List[MisconceptionEntry]  # Getting more frequent
+    resolved: List[MisconceptionEntry]  # No longer appearing
+
+
+class StudentProgressTimeline(BaseModel):
+    """Timeline of student progress"""
+    student_id: str
+    student_name: str
+    units_completed: int
+    total_time_minutes: int
+    avg_score: float
+    trend: str  # "improving", "stable", "declining"
+    timeline: List[Dict[str, Any]]  # List of session events
+
+
+class ClassComparisonData(BaseModel):
+    """Data for comparing class performance"""
+    class_id: str
+    class_name: str
+    student_count: int
+    units_assigned: int
+    avg_completion_rate: float
+    avg_learning_gain: float
+    avg_time_per_unit: float
+
+
+class ExportFormat(str, Enum):
+    """Export format options"""
+    JSON = "json"
+    CSV = "csv"