@rookiestar/eng-lang-tutor 1.0.1

package/scripts/core/constants.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+Shared constants for eng-lang-tutor.
+
+This module contains constants used across multiple scripts to avoid duplication.
+"""
+
+# =============================================================================
+# GAME MECHANICS - Activity Levels & Progression
+# =============================================================================
+
+# Level thresholds (XP needed for each level)
+# Note: Level is Activity Level (活跃等级), measuring engagement depth,
+# NOT language ability (which is CEFR level A1-C2)
+LEVEL_THRESHOLDS = [
+    0, 50, 100, 200, 350,       # 1-5 Starter (启程者)
+    550, 800, 1100, 1500, 2000,  # 6-10 Traveler (行路人)
+    2600, 3300, 4100, 5000, 6000,  # 11-15 Explorer (探索者)
+    7200, 8500, 10000, 12000, 15000  # 16-20 Pioneer (开拓者)
+]
+
+# Level range to name mapping
+LEVEL_NAMES = {
+    (1, 5): "Starter",      # 启程者
+    (6, 10): "Traveler",    # 行路人
+    (11, 15): "Explorer",   # 探索者
+    (16, 20): "Pioneer"     # 开拓者
+}
+
+# Streak bonus configuration
+STREAK_BONUS_PER_DAY = 0.05  # 5% bonus per day
+STREAK_BONUS_CAP = 2.0       # Maximum 2x multiplier
+
+# Gem economy
+STREAK_FREEZE_COST = 50  # gems to buy one streak freeze
+HINT_COST = 10           # gems to buy a quiz hint
+
+# =============================================================================
+# QUIZ XP VALUES
+# =============================================================================
+
+QUIZ_XP = {
+    "multiple_choice": 10,
+    "chinglish_fix": 15,
+    "fill_blank": 12,
+    "dialogue_completion": 15
+}
+QUIZ_PASS_THRESHOLD = 2  # 2/3 correct to pass
+QUIZ_QUESTIONS_PER_DAY = 3
+
+# =============================================================================
+# ERROR NOTEBOOK
+# =============================================================================
+
+ERROR_ARCHIVE_WRONG_THRESHOLD = 3   # Archive if wrong_count >= 3
+ERROR_ARCHIVE_DAYS_THRESHOLD = 30   # Archive if over 30 days old
+ERROR_NOTEBOOK_MAX = 100            # Maximum errors in notebook
+
+# =============================================================================
+# AUDIO PROCESSING
+# =============================================================================
+
+AUDIO_TTS_TIMEOUT = 30          # seconds, for single TTS synthesis
+AUDIO_CONCAT_TIMEOUT = 120      # seconds, for concatenating segments
+AUDIO_CONVERSION_TIMEOUT = 60   # seconds, for format conversion
+
+# Audio silence durations
+AUDIO_SILENCE_LEAD_IN = 1.0     # seconds, after lead-in phrase
+AUDIO_SILENCE_SECTION = 2.0     # seconds, between sections
+AUDIO_SILENCE_DIALOGUE = 0.5    # seconds, between dialogue lines
+
+# =============================================================================
+# DEDUPLICATION
+# =============================================================================
+
+DEDUP_DEFAULT_DAYS = 14  # Default days for content deduplication
+
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+def get_level_name(level: int) -> str:
+    """
+    Get the journey stage name for a level.
+
+    Args:
+        level: Activity level (1-20)
+
+    Returns:
+        Stage name (Starter/Traveler/Explorer/Pioneer)
+    """
+    for (min_level, max_level), name in LEVEL_NAMES.items():
+        if min_level <= level <= max_level:
+            return name
+    return "Unknown"
+
+
+def calculate_level(xp: int) -> int:
+    """
+    Calculate level from total XP.
+
+    Args:
+        xp: Total experience points
+
+    Returns:
+        Level (1-20)
+    """
+    for i in range(len(LEVEL_THRESHOLDS) - 1, -1, -1):
+        if xp >= LEVEL_THRESHOLDS[i]:
+            return i + 1
+    return 1
+
+
+def get_streak_multiplier(streak: int) -> float:
+    """
+    Calculate XP multiplier based on streak.
+
+    Args:
+        streak: Number of consecutive days
+
+    Returns:
+        Multiplier (1.0 - 2.0)
+    """
+    return min(1.0 + (streak * STREAK_BONUS_PER_DAY), STREAK_BONUS_CAP)

package/scripts/core/error_notebook.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""
+Error Notebook Manager - 错题本管理
+
+管理用户的错题本功能，包括：
+- 添加错题
+- 分页查询
+- 统计信息
+- 复习标记
+- 自动归档
+
+从 state_manager.py 提取，遵循单一职责原则。
+"""
+
+from typing import Dict, Any, List
+from datetime import datetime, date
+from collections import Counter
+
+from .constants import (
+    ERROR_ARCHIVE_WRONG_THRESHOLD,
+    ERROR_ARCHIVE_DAYS_THRESHOLD,
+    ERROR_NOTEBOOK_MAX
+)
+
+
+class ErrorNotebookManager:
+    """错题本管理器"""
+
+    def __init__(self, state_manager=None):
+        """
+        初始化错题本管理器
+
+        Args:
+            state_manager: StateManager 实例，用于事件日志
+        """
+        self.state_manager = state_manager
+
+    def add_to_error_notebook(self, state: Dict[str, Any],
+                               error: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Add an error to the error notebook.
+
+        Args:
+            state: Current state
+            error: Error entry with date, question, user_answer, correct_answer, explanation
+
+        Returns:
+            Updated state
+        """
+        error['date'] = date.today().isoformat()
+        error['reviewed'] = False
+        error['wrong_count'] = error.get('wrong_count', 1)
+        # keypoint_date and question_type are optional
+
+        errors = state.get('error_notebook', [])
+        errors.append(error)
+
+        # Auto-archive oldest if over size limit
+        if len(errors) > ERROR_NOTEBOOK_MAX:
+            # Sort by date to find oldest
+            errors.sort(key=lambda x: x.get('date', ''))
+            # Archive the oldest
+            oldest = errors.pop(0)
+            archive = state.get('error_archive', [])
+            oldest['archived_at'] = date.today().isoformat()
+            oldest['archived_reason'] = 'notebook_full'
+            archive.append(oldest)
+            state['error_archive'] = archive
+
+        state['error_notebook'] = errors
+        return state
+
+    def get_errors_page(self, state: Dict[str, Any],
+                        page: int = 1,
+                        per_page: int = 5,
+                        month: str = None,
+                        random: int = None) -> Dict[str, Any]:
+        """
+        Get paginated errors from the error notebook.
+
+        Args:
+            state: Current state
+            page: Page number (1-indexed)
+            per_page: Items per page (default 5)
+            month: Filter by month (YYYY-MM format)
+            random: Return N random errors instead of paginated
+
+        Returns:
+            Dictionary with pagination info and error items:
+            {
+                'total': total_count,
+                'page': current_page,
+                'per_page': items_per_page,
+                'total_pages': total_pages,
+                'has_more': bool,
+                'errors': [error_items]
+            }
+        """
+        import random as random_module
+
+        errors = state.get('error_notebook', [])
+
+        # Sort by date descending (newest first)
+        errors = sorted(errors, key=lambda x: x.get('date', ''), reverse=True)
+
+        # Filter by month if specified
+        if month:
+            errors = [e for e in errors if e.get('date', '').startswith(month)]
+
+        total = len(errors)
+
+        # Random mode
+        if random and random > 0:
+            random_count = min(random, total)
+            selected = random_module.sample(errors, random_count) if total > 0 else []
+            return {
+                'total': total,
+                'page': 1,
+                'per_page': random_count,
+                'total_pages': 1,
+                'has_more': total > random_count,
+                'mode': 'random',
+                'errors': selected
+            }
+
+        # Pagination
+        total_pages = (total + per_page - 1) // per_page if per_page > 0 else 1
+        page = max(1, min(page, total_pages)) if total_pages > 0 else 1
+
+        start = (page - 1) * per_page
+        end = start + per_page
+
+        return {
+            'total': total,
+            'page': page,
+            'per_page': per_page,
+            'total_pages': total_pages,
+            'has_more': page < total_pages,
+            'has_prev': page > 1,
+            'mode': 'paginated',
+            'errors': errors[start:end]
+        }
+
+    def get_error_stats(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Get statistics about the error notebook.
+
+        Args:
+            state: Current state
+
+        Returns:
+            Dictionary with error statistics
+        """
+        errors = state.get('error_notebook', [])
+
+        if not errors:
+            return {
+                'total': 0,
+                'reviewed': 0,
+                'unreviewed': 0,
+                'by_month': {}
+            }
+
+        reviewed = sum(1 for e in errors if e.get('reviewed', False))
+        unreviewed = len(errors) - reviewed
+
+        # Group by month
+        by_month = Counter()
+        for e in errors:
+            date_str = e.get('date', '')
+            if date_str:
+                month = date_str[:7]  # YYYY-MM
+                by_month[month] += 1
+
+        # Sort by month descending
+        by_month_sorted = dict(sorted(by_month.items(), reverse=True))
+
+        return {
+            'total': len(errors),
+            'reviewed': reviewed,
+            'unreviewed': unreviewed,
+            'by_month': by_month_sorted
+        }
+
+    def review_error(self, state: Dict[str, Any], error_index: int,
+                     correct: bool) -> Dict[str, Any]:
+        """
+        Mark an error as reviewed (correct answer) or increment wrong count.
+
+        Args:
+            state: Current state
+            error_index: Index of error in error_notebook
+            correct: Whether the user answered correctly
+
+        Returns:
+            Updated state
+        """
+        errors = state.get('error_notebook', [])
+        if 0 <= error_index < len(errors):
+            if correct:
+                # Mark as reviewed - contributes to Error Slayer badge
+                errors[error_index]['reviewed'] = True
+            else:
+                # Increment wrong count
+                errors[error_index]['wrong_count'] = errors[error_index].get('wrong_count', 1) + 1
+            state['error_notebook'] = errors
+        return state
+
+    def increment_wrong_count(self, state: Dict[str, Any],
+                              error_index: int) -> Dict[str, Any]:
+        """
+        Increment wrong count for an error (convenience method).
+
+        Args:
+            state: Current state
+            error_index: Index of error in error_notebook
+
+        Returns:
+            Updated state
+        """
+        return self.review_error(state, error_index, correct=False)
+
+    def get_review_errors(self, state: Dict[str, Any],
+                          count: int = 5) -> List[Dict[str, Any]]:
+        """
+        Get unreviewed errors for a review session.
+
+        Args:
+            state: Current state
+            count: Maximum number of errors to return
+
+        Returns:
+            List of unreviewed errors (most recent first)
+        """
+        errors = state.get('error_notebook', [])
+        # Filter unreviewed errors
+        unreviewed = [e for e in errors if not e.get('reviewed', False)]
+        # Sort by date descending (newest first)
+        unreviewed = sorted(unreviewed, key=lambda x: x.get('date', ''), reverse=True)
+        # Return up to count items
+        return unreviewed[:count]
+
+    def archive_stale_errors(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Archive errors with wrong_count >= threshold and over threshold days old.
+
+        Args:
+            state: Current state
+
+        Returns:
+            Updated state with stale errors moved to error_archive
+        """
+        errors = state.get('error_notebook', [])
+        archive = state.get('error_archive', [])
+        today = date.today()
+
+        remaining = []
+        archived_count = 0
+
+        for error in errors:
+            # Skip already reviewed
+            if error.get('reviewed', False):
+                remaining.append(error)
+                continue
+
+            wrong_count = error.get('wrong_count', 1)
+            error_date_str = error.get('date', '')
+
+            # Calculate days since error was created
+            try:
+                error_date = datetime.strptime(error_date_str, '%Y-%m-%d').date()
+                days_old = (today - error_date).days
+            except (ValueError, TypeError):
+                days_old = 0
+
+            # Archive if wrong_count and days_old meet thresholds
+            if wrong_count >= ERROR_ARCHIVE_WRONG_THRESHOLD and days_old >= ERROR_ARCHIVE_DAYS_THRESHOLD:
+                error['archived_at'] = today.isoformat()
+                archive.append(error)
+                archived_count += 1
+            else:
+                remaining.append(error)
+
+        state['error_notebook'] = remaining
+        state['error_archive'] = archive
+
+        # Log archival event via state_manager
+        if archived_count > 0 and self.state_manager:
+            self.state_manager.append_event("errors_archived", {"count": archived_count})
+
+        return state
+
+    def clear_reviewed_errors(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Remove reviewed errors from the notebook (keep them in archive for stats).
+
+        Args:
+            state: Current state
+
+        Returns:
+            Updated state
+        """
+        errors = state.get('error_notebook', [])
+        # Keep only unreviewed errors
+        state['error_notebook'] = [
+            e for e in errors if not e.get('reviewed', False)
+        ]
+        return state