Learn_System/plans/ai-trainer/PLAN.md

# ИИ-Тренажёр — план развития модуля

Модуль `/trainer`: бесконечные задачи, которые рождаются из **данных-генераторов**, а
математика считается и проверяется **детерминированно** через `SimExpr` (без `eval`).
LLM в ядре не участвует — его роль (Уровень 1+) сочинять генераторы и текстовые задачи,
которые тот же слой верифицирует подстановкой. Тема-пилот: **уравнения, 7 класс**.

## Инвариант корректности (не нарушать)

> Любой источник задачи (генератор, шаблон, LLM) обязан пройти `TrainerEngine.verifyRoot`:
> заявленный корень подставляется в уравнение, расходится → задача отбрасывается.
> Та же подстановка проверяет ответ ученика (принимает `5`, `x=5`, `10/2`, `2+3`).
> Выражения — ТОЛЬКО `SimExpr` (whitelist, без `eval`/`new Function`). Цвета/текст от
> пользователя — только в безопасные стоки или с escape.

## Состояние: Phase 0 — DONE (прототип, в этом коммите)

- **Движок** `frontend/js/trainer/_trainer_engine.js`: `instantiate` / `generateBatch` /
  `verifyRoot` / `checkStudentAnswer` / `exprToLatex` (AST→LaTeX, reusable) / `makeRng`.
- **Генераторы** `frontend/js/trainer/generators.js`: 5 типов (линейное `ax+b=c`, скобки,
  переменная с двух сторон, дробь `x/a+b=c`, дробный коэффициент `ax/b=c`). Приём
  «корень-вперёд» → гарантированно целые ответы, самопроверка всегда проходит.
- **Страница** `frontend/trainer.html`: KaTeX-рендер уравнений и шагов, чипы-темы,
  мгновенная проверка, подсказка/решение, авто-выбор первого неосвоенного навыка.
- **Прогресс на сервере**: `practice_progress` (мигр.081), `practiceController` +
  `routes/practice` (`/api/practice/progress|attempt`), клиент `LS.practiceProgressList/Submit`.
  Мастерство = серия 5 верных подряд (липкое).
- **Фича-флаг** `trainer`: тумблер в админке (Модули), `requireFeature('trainer')`,
  скрытие из сайдбара + редирект страницы (`FEATURE_HREFS`), запись в `MODULE_CATALOG`.
- Тесты: `practice.test.js` (10/10), headless-смоуки движка/страницы. lint:routes 0.

---

## Phase 1 — Ширина контента (генераторы)

**Цель:** перестать быть «демкой одной темы». Структура `класс → предмет → тема → навык`.

- Реестр генераторов: вынести в данные с метаданными `{ grade, subject, topic, skill, order, difficulty }`.
  Группировка чипов по темам/классам; выбор класса/предмета вверху.
- Новые генераторы 7 кл: пропорции, раскрытие скобок с обеих сторон `a(x+b)=c(x+d)`,
  уравнения с дробью-уравнением `(ax+b)/c = d`, простые буквенные преобразования.
- Соседние темы (параметрические, без LLM): упрощение выражений, степени, проценты,
  линейные неравенства (расширить `checkStudentAnswer` под интервалы — см. P5).
- **Acceptance:** ≥3 темы × ≥3 навыка, у каждого generateBatch(50) даёт 50 разных корректных
  задач; solvability-смоук на сетке параметров.

## Phase 2 — Адаптивность и интервальное повторение

**Цель:** вести ученика, а не давать случайное.

- Диагностика на входе (по 1–2 задачи на навык) → стартовый уровень.
- Подбор следующего навыка по мастерству (escalate при серии, откат при ошибках).
- Ошибки уходят в очередь повторения (свой лёгкий SR или reuse flashcards Tier-1).
- «Продолжить тренировку», дневная норма/цель, сводка сессии (что освоено, над чем работать).
- Сервер: расширить `practice_progress` (или новая `practice_review_queue`); агрегаты для аналитики.
- **Acceptance:** сессия из N задач сама ведёт от простого к сложному; промахнутый навык
  всплывает повторно; прогресс переживает перезаход.

## Phase 3 — Уровень 1: LLM-задачи с верификацией

**Цель:** текстовые/контекстные задачи, которых не даёт параметрика.

- LLM (через провайдеров админки) генерирует `{ lhs, rhs, answer, story }`; сервер прогоняет
  `verifyRoot`; расхождение → авторетрай с фидбэком («корень не удовлетворяет, исправь»).
- Кэш-пул `practice_problems` (предгенерация, ревью учителем) — не платить за каждый показ.
- Генерация «по теме урока» (связка с theory/exam-prep).
- **Acceptance:** доля задач, прошедших верификацию с 1–2 ретраев, ≥95%; пул кэшируется;
  ни одна неверная задача не доходит до ученика (гарантирует инвариант).

## Phase 4 — Авторинг учителем

**Цель:** учитель создаёт свои наборы и раздаёт классу (как sim-builder/Quantik Ф5).

- Конструктор генераторов: шаблон `lhs/rhs`, диапазоны параметров, формула ответа, шаги
  решения; превью + клиентская валидация через `SimExpr.compile`.
- Хранение (таблица по образцу `custom_sims`), серверная `validateSpec` без исполнения,
  раздача классу + уведомление, привязка к ДЗ/уроку.
- **Acceptance:** учитель собирает рабочий генератор без кода; ученик решает; права/видимость
  как у custom-sim (own + раздано).

## Phase 5 — Типы ответов и проверки

**Цель:** не только «корень-число».

- Множество корней (квадратные/факторизация), интервалы (неравенства), упрощение выражений
  (эквивалентность через численный сэмплинг по диапазону, а не строковое равенство).
- Пошаговый ввод (проверять каждый шаг подстановкой), несколько форматов ответа.
- **Acceptance:** квадратное уравнение принимает оба корня в любом порядке; `(x+1)^2` ≡
  `x^2+2x+1` через сэмплинг; неравенство принимает `x>3` и эквивалент.

## Phase 6 — Геймификация, аналитика, UX

- XP/энергия/стрики (reuse инфраструктуры Квантика), бейджи мастерства на чипах (есть основа).
- Учительская аналитика: кто на каком навыке застрял, тепловая карта класса, отчёты.
- UX: виртуальная клавиатура для дробей/степеней, «почему неверно» (разбор ошибки),
  сократические подсказки через Квантик-ассистента, мобильная раскладка, доступность.

---

## Сквозное

- **Безопасность:** только `SimExpr`; авторские генераторы — серверная `validateSpec` без
  исполнения (длины/лимиты, escape текста), как `custom_sims`.
- **Тесты:** на каждый генератор — solvability-смоук (сетка параметров → есть корректные
  задачи + достижим целевой ответ); бэкенд-тесты на новые роуты; headless-смоук страницы.
- **Контент = данные:** генераторы и темы — JS-данные/таблицы, не код.

## Рекомендуемый следующий шаг

**Phase 1** (ширина контента) — даёт наибольшую пользу при минимальном риске и переиспользует
готовый движок/проверку/страницу. Затем **Phase 2** (адаптивность) для удержания.