Lang v2.0 System Atlas

sequenceDiagram
  participant U as Ученик
  participant B as Telegram Bot
  participant GW as Gateway :8100
  participant PS as Progress :8103
  participant ES as Exercise :8102
  participant AI as AI :8105

  U->>B: /go
  Note over B: ai_lesson_engine()

  B->>GW: GET /profile/{user_id}
  GW->>B: язык, уровень, настройки

  B->>GW: GET /progress/next-concept/{user_id}
  GW->>PS: ConceptSelector
  Note over PS: ghost → due → weak → new
  PS->>GW: concept_id, review_type, mastery
  GW->>B: Концепт выбран

  B->>GW: GET /exercises/concept/{id}/session
  GW->>ES: block_exercises WHERE concept_id
  ES->>GW: exercises[] + theory_blocks
  GW->>B: Пул 5-15 упражнений

  Note over B: MasterySession создана
  B->>U: Интро: теория + кнопки

  U->>B: "Начать упражнения"
  Note over B: FSM → waiting_for_answer

  loop Каждое упражнение
    B->>U: Задание + варианты/ввод
    U->>B: Ответ
    Note over B: AnswerChecker
8 уровней проверки

    alt Нужна AI проверка
      B->>GW: POST /ai/check-answer
      GW->>AI: GPT-4o-mini
      AI->>GW: is_correct + reason
      GW->>B: Результат
    end

    B->>GW: POST /progress/attempts
    GW->>PS: FSRS update + mastery recalc
    PS->>GW: new_mastery_level

    B->>U: Фидбек (верно/неверно + объяснение)
  end

  Note over B: session.is_ended()?
  B->>U: Результат: X/Y правильно, +XP
    

flowchart LR
  subgraph "Таксономия"
    CAT["Категории
grammar, vocabulary,
pronunciation, culture"]
    CON["Концепты
469 всего
235 ES / 735 EN"]
    CB["Content Blocks
Теория + микро-концепты"]
    EX["Упражнения
8 905 активных
9 типов"]
  end

  CAT --> CON
  CON --> CB
  CB --> EX

  CON -.->|"каждый имеет"| F1
  CON -.->|"граф зависимостей"| P1
  CON -.->|"для русскоговорящих"| D5

  subgraph "Поля концепта"
    F1["concept_key
(articulo_definido)"]
    F2["russian_l1_difficulty
1=лёгкий → 5=тяжёлый"]
    F3["fsrs_init_difficulty
начальная сложность"]
    F4["requires_explicit_cf
нужна Corrective Feedback"]
    F5["early_intervention_critical
произношение"]
  end

  subgraph "Prerequisites (пример)"
    P1["articles"] --> P2["noun_gender"]
    P2 --> P3["adjective_agreement"]
    P3 --> P4["noun_adj_position"]
  end

  subgraph "L1 Difficulty (русские)"
    D5["5 — Артикли
mult 0.7 (больше повторений)"]
    D4["4 — Предлоги, Perfect
mult 0.75"]
    D3["3 — Средние
mult 0.85"]
    D2["2 — Знакомые
mult 1.0"]
    D1["1 — Когнаты
mult 1.1 (быстрее)"]
  end

  style D5 fill:#b62324,stroke:#f85149,color:#fff
  style D4 fill:#9e6a03,stroke:#d29922,color:#fff
  style D3 fill:#6e40c9,stroke:#bc8cff,color:#fff
  style D2 fill:#238636,stroke:#3fb950,color:#fff
  style D1 fill:#1f6feb,stroke:#58a6ff,color:#fff
    

flowchart TB
  subgraph "SSOT: exercise_types.py"
    T1["fill_gaps 25%
Input Processing"]
    T2["transformation 20%
Focus on Form"]
    T3["error_correction 10%
Metalinguistic"]
    T4["translation 10%
Pushed Output L1→L2"]
    T5["minimal_pairs 10%
Meaning Contrast"]
    T6["open_answer 10%
Free Production"]
    T7["multiple_choice 5%
Quick Recognition"]
    T8["matching 5%
Pair Linking"]
    T9["reorder 5%
Syntax Awareness"]
  end

  NORM["NORMALIZATION_MAP
54 legacy → 9 canonical"]
  NORM --> T1
  NORM --> T2
  NORM --> T3
  NORM --> T4
  NORM --> T5
  NORM --> T6
  NORM --> T7
  NORM --> T8
  NORM --> T9

  subgraph "3-Agent Pipeline (Прокачай)"
    CP["CurriculumPlanner
Алгоритм
skeleton + gaps"]
    MP["Methodologist
Claude Sonnet
~$0.03/вызов"]
    OR["OpusReviewer
Claude Opus
~$0.05/вызов
4 критерия"]
  end

  CP --> MP --> OR

  subgraph "Автоматическая генерация"
    GEN["generator.py
1130 LOC"]
    OPT["option_designer.py
782 LOC"]
    CSD["closed_set_detector.py
36 правил: 26 ES + 10 EN"]
  end

  GEN --> OPT
  GEN --> CSD

  subgraph "Выход"
    DB[("block_exercises
8 905 записей")]
    QS["quality_score
0-100"]
  end

  OR --> DB
  GEN --> DB
  DB --> QS

  style T1 fill:#238636,stroke:#3fb950,color:#fff
  style T2 fill:#1f6feb,stroke:#58a6ff,color:#fff
  style OR fill:#b62324,stroke:#f85149,color:#fff
  style QS fill:#9e6a03,stroke:#d29922,color:#fff
    

flowchart TB
  START["Ответ ученика"] --> L0

  L0{"Level 0
personal_info?
true_sentences?"}
  L0 -->|Да| ACCEPT["Принять любой ответ"]
  L0 -->|Нет| AICHECK

  AICHECK{"requires_ai_check?
translation / open_answer /
transformation"}
  AICHECK -->|Да| L3["Level 2+: AI сразу
GPT-4o-mini"]
  AICHECK -->|Нет| L1

  L1{"Level 1.0
Exact match?"}
  L1 -->|Да| CORRECT["Правильно"]
  L1 -->|Нет| L11

  L11{"Level 1.1
Normalized?
lowercase + без акцентов"}
  L11 -->|Да| CORRECT
  L11 -->|Нет| L21

  L21{"Level 2.1
Опечатка?
Levenshtein ≤ 2"}
  L21 -->|Да| TYPO["Принято с пометкой
Орфография: correct"]
  L21 -->|Нет| L22

  L22{"Level 2.2
error_correction?
слово из предложения"}
  L22 -->|Да| CORRECT
  L22 -->|Нет| L23

  L23{"Level 2.3
Core extraction?
ядро ответа совпадает"}
  L23 -->|Да| CORRECT
  L23 -->|Нет| L25

  L25{"Level 2.5
Disputed?
Sonnet vs Opus"}
  L25 -->|Оба согласны| WRONG["Неправильно"]
  L25 -->|Расхождение| DISPUTED["Принято как
альтернативный вариант"]

  L3 --> L3R{"AI результат"}
  L3R -->|correct| CORRECT
  L3R -->|incorrect| WRONG
  L3R -->|disputed| DISPUTED

  style CORRECT fill:#238636,stroke:#3fb950,color:#fff
  style WRONG fill:#b62324,stroke:#f85149,color:#fff
  style TYPO fill:#9e6a03,stroke:#d29922,color:#fff
  style DISPUTED fill:#6e40c9,stroke:#bc8cff,color:#fff
  style ACCEPT fill:#1f6feb,stroke:#58a6ff,color:#fff
    

stateDiagram-v2
  [*] --> New: Новый концепт

  New --> Learning: Первый ответ
  Learning --> Review: Правильные ответы
  Review --> Review: Правильный (Good/Easy)
  Review --> Relearning: Неправильный (Again)
  Relearning --> Review: Снова правильный

  state "Ghost Review" as Ghost {
    [*] --> Step0: 2+ ошибки подряд
    Step0: Шаг 0 — через 4 часа
    Step0 --> Step1: Если опять ошибка
    Step1: Шаг 1 — через 12 часов
    Step1 --> Step2: Если опять ошибка
    Step2: Шаг 2 — через 24 часа
    Step2 --> Step3: Если опять ошибка
    Step3: Шаг 3 — через 48 часов
  }

  Review --> Ghost: 2 подряд неправильных
  Ghost --> Review: Правильный ответ
    

flowchart TB
  START["/go запрос"] --> CHECK["Получить все
progress_records
для user_id"]

  CHECK --> P1{"P1: Ghost Review?
ghost_review_active = true
ghost_review_next ≤ now"}
  P1 -->|Есть| G1["Пул Ghost-концептов"]
  P1 -->|Нет| P2

  P2{"P2: Due Review?
fsrs_data.due_date ≤ now
mastery ≥ learning"}
  P2 -->|Есть| G2["Пул Due-концептов"]
  P2 -->|Нет| P3

  P3{"P3: Weak Spots?
confidence_score ≤ 70%
attempts ≥ 3"}
  P3 -->|Есть| G3["Пул Weak-концептов"]
  P3 -->|Нет| P4

  P4{"P4: New Concept?
prerequisites met?
не изучался сегодня?"}
  P4 -->|Есть| G4["Пул New-концептов"]
  P4 -->|Нет| EMPTY["Нет доступных
концептов"]

  G1 & G2 & G3 & G4 --> RND["Случайный из пула 5"]

  RND --> RESULT["concept_id +
review_type +
mastery_level"]

  style P1 fill:#b62324,stroke:#f85149,color:#fff
  style P2 fill:#9e6a03,stroke:#d29922,color:#fff
  style P3 fill:#6e40c9,stroke:#bc8cff,color:#fff
  style P4 fill:#238636,stroke:#3fb950,color:#fff
  style G1 fill:#b62324,stroke:#f85149,color:#fff
  style G2 fill:#9e6a03,stroke:#d29922,color:#fff
  style G3 fill:#6e40c9,stroke:#bc8cff,color:#fff
  style G4 fill:#238636,stroke:#3fb950,color:#fff
    

erDiagram
  concepts {
    int id PK
    string concept_key UK
    string category
    string name
    string name_ru
    int russian_l1_difficulty
    float fsrs_init_difficulty
    bool requires_explicit_cf
    bool early_intervention_critical
  }

  content_blocks {
    int id PK
    int concept_id FK
    text theory_text
    jsonb theory_blocks
    jsonb source_textbooks
    jsonb source_units
    bool is_active
  }

  block_exercises {
    int id PK
    int concept_id FK
    int block_id FK
    string exercise_type
    string difficulty_tier
    text task
    text correct_answer
    text explanation_ru
    text hint
    text format_hint
    jsonb options
    int quality_score
    bool is_active
    string review_status
  }

  progress_records {
    int id PK
    int user_id
    int concept_id FK
    string context_type
    jsonb attempts
    string srs_algorithm
    jsonb sm2_data
    jsonb fsrs_data
    int confidence_score
    string mastery_level
    bool ghost_review_active
    int ghost_review_step
    timestamp first_practiced
    timestamp last_practiced
  }

  student_profiles {
    int user_id PK
    jsonb preferences
    string target_language
    string current_textbook
  }

  user_answers {
    int id PK
    int user_id
    int exercise_id FK
    text user_answer
    bool is_correct
    int response_time_ms
    string session_id
  }

  concepts ||--o{ content_blocks : "теория"
  content_blocks ||--o{ block_exercises : "упражнения"
  concepts ||--o{ progress_records : "прогресс"
  concepts ||--o{ block_exercises : "напрямую"
  block_exercises ||--o{ user_answers : "ответы"
    

flowchart LR
  subgraph "Публикаторы"
    direction TB
    BOT["Telegram Bot"]
    ES["Exercise :8102"]
    PS["Progress :8103"]
    PF["Profile :8104"]
  end

  subgraph "Redis DB0 Pub/Sub"
    direction TB
    E1["exercise.answered"]
    E3["content.pool_low"]
    E2["progress.updated"]
    E4["profile.updated"]
    E5["lesson.completed"]
  end

  subgraph "Подписчики"
    direction TB
    PS2["Progress :8103"]
    AA["Answer Analytics"]
    PF2["Profile :8104"]
    EN["Engagement :8106"]
    AI2["AI :8105"]
  end

  BOT -->|"ответ"| E1
  ES -->|"валидация"| E1
  ES -->|"пул ≤ 8"| E3
  PS -->|"FSRS"| E2
  PF -->|"изменён"| E4
  BOT -->|"пройден"| E5

  E1 --> PS2
  E1 --> AA
  E1 --> PF2
  E3 --> AI2
  E2 --> EN
  E4 --> PS2
  E5 --> EN

  style E1 fill:#b62324,stroke:#f85149,color:#fff
  style E2 fill:#9e6a03,stroke:#d29922,color:#fff
  style E3 fill:#6e40c9,stroke:#bc8cff,color:#fff
    

flowchart TB
  REQ["Запрос"] --> ROUTER{"AI Router
Определяет сложность"}

  ROUTER -->|"Простое: проверка,
batch, fallback"| MINI["GPT-4o-mini
$0.15 / 1M tokens"]
  ROUTER -->|"Стандартное: генерация,
теория, анализ ошибок"| GPT4["GPT-4o
$2.50 / 1M tokens"]
  ROUTER -->|"Методическое: prompt
для упражнений"| SONNET["Claude Sonnet
$3.00 / 1M tokens"]
  ROUTER -->|"Ревью: проверка
качества, disputed"| OPUS["Claude Opus
$15.00 / 1M tokens"]

  subgraph "Embeddings"
    EMB["text-embedding-3-small
1536 dims
$0.02 / 1M tokens"]
  end

  subgraph "Кэш (Redis DB1)"
    CACHE["TTL 30 дней
Ключ: hash(prompt)
Экономия ~70%"]
  end

  GPT4 --> CACHE
  SONNET --> CACHE
  MINI --> CACHE
  EMB --> QD[("Qdrant :6333")]

  ROUTER -.->|"стоимость"| C1

  subgraph "Стоимость за сессию"
    C1["Проверка ответа: ~$0.001"]
    C2["Генерация упражнения: ~$0.01"]
    C3["Методист (Прокачай): ~$0.03"]
    C4["Ревью Opus: ~$0.05"]
    C5["Разжуй теорию: ~$0.02"]
  end

  style MINI fill:#238636,stroke:#3fb950,color:#fff
  style GPT4 fill:#1f6feb,stroke:#58a6ff,color:#fff
  style SONNET fill:#6e40c9,stroke:#bc8cff,color:#fff
  style OPUS fill:#b62324,stroke:#f85149,color:#fff
    

flowchart TB
  START(["start / menu"]) --> idle["idle
Главное меню"]

  idle -->|"/go"| concept_intro["concept_intro
Теория + кнопки"]
  concept_intro -->|"Начать"| waiting["waiting_for_answer
Ввод ответа"]
  waiting -->|"Ответ"| feedback["feedback
Результат"]
  feedback -->|"Следующее"| waiting
  feedback -->|"Сессия окончена"| complete["concept_complete
Результаты"]
  complete -->|"Следующий"| concept_intro
  complete -->|"В меню"| idle

  concept_intro -->|"Разжуй теорию"| theory_ov["theory_overview
Обзор секций"]
  theory_ov -->|"Секция"| theory_sec["theory_section
Формула / Ловушки / ..."]
  theory_sec -->|"Обзор"| theory_ov
  theory_sec -->|"Другая"| theory_sec
  theory_ov -->|"Практика"| waiting

  idle -->|"/reading"| phrase["waiting_for_phrase
Ввод фразы"]
  phrase -->|"Текст"| analysis["phrase_analysis
Разбор"]
  analysis -->|"Ещё"| phrase
  idle -->|"/import_kindle"| vocab["waiting_for_vocab
Ожидание vocab.db"]
  vocab -->|"Файл"| imported["import_complete"]

  idle -->|"/lang"| lang["lang_select"]
  lang -->|"Выбрано"| idle
  idle -->|"/stats"| stats_view["stats
Статистика"]
  stats_view -->|"В меню"| idle

  style idle fill:#238636,stroke:#3fb950,color:#fff
  style waiting fill:#1f6feb,stroke:#58a6ff,color:#fff
  style concept_intro fill:#6e40c9,stroke:#bc8cff,color:#fff
  style phrase fill:#9e6a03,stroke:#d29922,color:#fff
  style theory_ov fill:#6e40c9,stroke:#bc8cff,color:#fff
    

flowchart TB
  subgraph "CRITICAL — Сломано"
    C1["Distribution Skew
86% fill_gaps vs 25% цель
Генератор игнорирует
TARGET_TYPE_WEIGHTS"]
    C2["Качество упражнений
99% quality_score ≤ 80
Нужен массовый re-review"]
  end

  subgraph "MEDIUM — Работает плохо"
    M1["Opus Reviewer
Недостаточно строгий
для translation"]
    M2["Event Bus
Redis Pub/Sub без persistence
Потеря событий при рестарте"]
    M3["10 микросервисов
Distributed monolith
для 1 пользователя"]
  end

  subgraph "GAP — Отсутствует"
    G1["Learning Outcomes
Нет метрик D1/D7/D30
Строим вслепую"]
    G2["Session Analytics
Нет данных о длине сессий
и вовлечённости"]
    G3["Concept Taxonomy
235 концептов слишком гранулярно
Надо 60-80"]
  end

  subgraph "Архитектурный долг"
    D1["Bot: 25k LOC
Слишком много логики
в presentation layer"]
    D2["Progress: 19k LOC
Самый большой сервис
нужен рефакторинг"]
    D3["Shared generator: 1130 LOC
Файл > лимита 300"]
  end

  C1 -.->|"вызывает"| M1
  C2 -.->|"вызывает"| M1
  M2 -.->|"усугубляет"| G1
  M2 -.->|"усугубляет"| G2
  D1 -.->|"замедляет фикс"| C1
  D2 -.->|"замедляет фикс"| C2

  style C1 fill:#b62324,stroke:#f85149,color:#fff
  style C2 fill:#b62324,stroke:#f85149,color:#fff
  style M1 fill:#9e6a03,stroke:#d29922,color:#fff
  style M2 fill:#9e6a03,stroke:#d29922,color:#fff
  style M3 fill:#9e6a03,stroke:#d29922,color:#fff
  style G1 fill:#6e40c9,stroke:#bc8cff,color:#fff
  style G2 fill:#6e40c9,stroke:#bc8cff,color:#fff
  style G3 fill:#6e40c9,stroke:#bc8cff,color:#fff