TestingWebApp/docs/QA-versioning-and-ai.md

# Инструкция для тестировщика: версионирование тестов и AI

Сайт: **[https://edullm.pirogov.ai/](https://edullm.pirogov.ai/)**

Учётка: подойдёт **любая** учётная запись на сайте — никаких особых ролей
не требуется. Любой залогиненный пользователь, который создаёт тест,
автоматически становится его автором и может его редактировать. Если
учётки нет — попросите её у разработчика.

> Всё, что описано ниже, проверяется **только через сайт**. Если в каком-то
> сценарии написано «недоступно сейчас» — это **не баг**, это значит, что
> функция UI ещё не сделана и появится позже. Просто пропускайте.

---

## Часть 1. Версии теста — что меняется при правках

### О чём вообще задача

Когда автор правит тест, в системе важно не сломать историю прохождений
сотрудников. Поэтому правила такие:

- Пока **никто не прошёл** тест — автор правит на месте, версия одна.
- Как только **хотя бы один сотрудник прошёл** тест — следующее сохранение
  изменений создаёт **новую версию** (v2, v3, …), старая сохраняется.
- В каталоге всегда видна **только одна** активная версия.
- Автор может **скрыть** тест целиком (чекбокс «Цепочка активна»).
- Автор может **переключить** активную версию на другую из истории.

> Сейчас на сайте нельзя пройти тест сотруднику и нельзя из UI открыть
> историю версий — это будет в следующих спринтах. Поэтому из шести
> правил тестировщик пока проверяет четыре, остальные помечены ниже.

---

### 1.1. Создание нового теста

**Что проверяем:** автор может создать тест с нуля.

**Как проверять:**
1. Откройте [https://edullm.pirogov.ai/](https://edullm.pirogov.ai/) и войдите.
2. Нажмите в шапке иконку **«Тесты»** (список) → попадаете в каталог.
3. Нажмите кнопку **«Создать тест»**.
4. В появившемся окне заполните **Название** (например, «Тест A»),
   при желании — Описание.
5. Нажмите **«Создать»**.

**Что должно произойти:**
- Открывается экран редактора нового теста.
- В поле «Название» — то, что вы ввели.
- Список вопросов пуст, счётчик «Вопросы (0)».
- Внизу — кнопка **«Сохранить»** и чекбокс **«Цепочка активна»** (по
  умолчанию включён).

**Если что-то не так — баг:**
- Окно «Создать тест» не открывается.
- После «Создать» никуда не перенаправило.
- В поле «Название» в редакторе пусто, хотя ввели текст.
- Список тестов в каталоге не обновился (не появилась новая карточка).

---

### 1.2. Правка теста до прохождений (версия не растёт)

**Что проверяем:** пока никто не проходил тест, автор может править его
сколько угодно — это всё одна и та же версия.

**Как проверять:**
1. Откройте только что созданный «Тест A» (если уже не открыт): шапка → **«Тесты»** → нажмите на карточку теста.
2. Нажмите **«Добавить вопрос»** — появится карточка вопроса.
3. Введите текст вопроса.
4. Заполните 3–4 варианта ответа в поле «Вариант ответа», у одного из них поставьте чекбокс «Правильный» (квадратик слева от текста).
5. Добавьте ещё один-два вопроса тем же способом.
6. Нажмите **«Сохранить»** в нижней панели.

**Что должно произойти:**
- Под шапкой появляется надпись **«Сохранено.»** (без слов про новую версию).
- Если перезагрузить страницу — все вопросы и варианты на месте.

**Повторите правку:**
1. На том же экране **измените** текст одного вопроса, **добавьте** ещё один вариант к другому, **удалите** третий вопрос (кнопка «корзина» справа в карточке вопроса).
2. Нажмите **«Сохранить»**.

**Что должно произойти:**
- Снова надпись **«Сохранено.»**.
- Никаких слов «создана новая версия».
- Перезагрузка страницы — изменения сохранились.

**Если что-то не так — баг:**
- Появляется сообщение про «новую версию» (его быть не должно — попыток ещё нет).
- Изменения не сохранились после перезагрузки страницы.
- Сообщение «Сохранено.» не появилось вовсе.

---

### 1.3. Правка после прохождений (создаётся v2)

> ⏳ **Сейчас недоступно для проверки.**
>
> На сайте пока нет страницы для прохождения теста сотрудником, поэтому
> тестировщик не может «накопить» попытки и проверить эту логику через UI.
> Сценарий вернётся в инструкцию вместе со следующим спринтом, когда
> появится страница прохождения.

---

### 1.4. Каталог показывает только активные тесты

**Что проверяем:** в каталоге нет неактивных/скрытых тестов.

**Как проверять:**
1. На экране редактора любого теста снимите внизу чекбокс
   **«Цепочка активна»** и нажмите **«Сохранить»**.
2. Перейдите в шапке на **«Тесты»** (каталог).

**Что должно произойти:**
- Карточки этого теста в основном списке нет.
- Внизу страницы каталога есть раскрывающийся блок **«Скрытые вами цепочки (N)»**. Раскройте его — там видно ваш тест.
- Нажмите **«Открыть»** рядом с тестом — снова попадаете в редактор.
- Поставьте обратно галку **«Цепочка активна»** → **«Сохранить»**.
- Снова перейдите в **«Тесты»** — тест опять в основном списке каталога.

**Если что-то не так — баг:**
- После снятия галки тест остаётся в обычном каталоге.
- Тест полностью пропал и его не видно нигде, даже в «Скрытых».
- После возврата галки тест не вернулся в основной каталог.

---

### 1.5. Ручное переключение активной версии

> ⏳ **Сейчас недоступно для проверки.**
>
> Страница с историей версий теста (где можно нажать «сделать активной»)
> ещё не сделана. Появится в следующем спринте.

---

### 1.6. История прохождений после правок

> ⏳ **Сейчас недоступно для проверки** — см. 1.3 и 1.5.

---

## Часть 2. AI-функции в редакторе теста

### Как проверять, что AI вообще работает

**Что проверяем:** ключ к AI задан и сервис отвечает.

**Как проверять:**
1. В шапке нажмите иконку **«Настройки»** (шестерёнка).
2. Посмотрите блок «Подключение к LLM»:
   - **Статус ключа** — должно быть зелёное **«Задан»**.
   - **Провайдер** и **Модель** — заполнены.
3. Нажмите кнопку **«Проверить подключение»**.

**Что должно произойти:**
- В течение 1–10 секунд под кнопкой появляется **зелёный** блок
  с текстом вида **«OK · deepseek / deepseek-chat · 1234 мс»**.

**Если что-то не так:**
- Если статус **«Не задан»** (красный) — сообщите разработчику, не задан ключ. Тестировать AI-функции в этом режиме не нужно, кроме одного сценария ниже (2.7).
- Если кнопка отдала **красный** блок «Ошибка» при заданном ключе — это баг, прикладывайте текст ошибки к тикету.

---

### 2.1. Сгенерировать тест по названию

**Простыми словами:** автор пишет только тему, AI сам придумывает вопросы.

**Как проверять:**
1. **«Тесты»** → **«Создать тест»** → название, например, **«Гигиена рук»**, описание можно оставить пустым → **«Создать»**.
2. В редакторе нажмите кнопку **«По названию»** (фиолетовая, в блоке «AI-помощник» → «Создать вопросы»).
3. На вопрос «Сколько вопросов сгенерировать?» введите, например, `8` → **OK**.
4. На вопрос «Сколько вариантов в каждом вопросе?» введите, например, `4` → **OK**.
5. Подождите 5–20 секунд.
6. Появится подтверждение «Готово: «…», вопросов — N. Применить как черновик? Текущие вопросы будут заменены». Нажмите **OK**.

**Что должно произойти:**
- В списке появилось примерно 8 вопросов на тему гигиены рук, в каждом примерно 4 варианта ответа на русском языке.
- В каждом вопросе хотя бы один вариант помечен как «Правильный» (галка слева от текста варианта).
- Внизу можно нажать **«Сохранить»** — тест сохраняется.

**Дополнительно (что блокировка названия работает):**
1. Создайте ещё один тест, в редакторе **очистите поле «Название»**.
2. Нажмите **«По названию»**.
3. Должен появиться алерт **«Сначала заполните название теста.»**, курсор перейдёт в поле «Название». Никакой генерации не происходит.

**Если что-то не так — баг:**
- Кнопка **«По названию»** работает при пустом названии (без алерта).
- Сгенерированные вопросы — не на русском или не по теме названия.
- В вопросе нет ни одного правильного варианта.
- Подтверждение «Применить?» не появилось — вопросы заменились молча.
- Отказ в подтверждении (Cancel) всё равно заменил вопросы.

---

### 2.2. Сгенерировать тест по сетке

**Простыми словами:** автор сам задаёт «скелет» — сколько вопросов и
сколько вариантов; AI заполняет вопросы по этому скелету.

**Как проверять:**
1. Создайте новый тест с названием **«Тест по сетке»**.
2. Нажмите **«Добавить вопрос»** пять раз — получится 5 пустых карточек.
3. В **третьей и пятой** карточках поставьте галку **«Несколько правильных ответов»**.
4. В каждом вопросе по умолчанию 0 вариантов — нажмите **«Добавить вариант»** в каждом вопросе по 3 раза, чтобы стало по 3 варианта.
5. Нажмите кнопку **«По текущей сетке»** в блоке «AI-помощник».

**Что должно произойти:**
- В списке снова 5 вопросов (не больше, не меньше).
- В каждом — по 3 варианта.
- В третьем и пятом вопросах несколько вариантов помечены правильными;
  в остальных — ровно один.
- Тексты — на русском, по теме названия.

**Если что-то не так — баг:**
- Стало другое число вопросов или вариантов (не 5×3).
- В третьем/пятом вопросе только один правильный ответ, а в остальных — несколько.
- Пришла ошибка типа **«AI: ошибка»** без понятного объяснения.

---

### 2.3. Проверить тест

**Простыми словами:** AI читает весь тест и пишет, что в нём не так.

**Как проверять:**
1. Откройте любой тест с 3+ вопросами (например, «Гигиена рук» из 2.1).
2. Желательно специально испортить пару вопросов: переписать
   формулировку расплывчато («что-то про что-то»), сделать варианты
   ответа очень похожими друг на друга или явно дурацкими.
3. Нажмите **«Сохранить»**.
4. Нажмите кнопку **«Проверить»** в блоке «AI-помощник» → «Улучшить существующее».

**Что должно произойти:**
- Открывается окно «Проверка теста».
- Сверху — цветная плашка с одним из вердиктов: **«Годен»** (зелёный),
  **«Есть замечания»** (жёлтый) или **«Серьёзные проблемы»** (красный)
  + одно-два предложения резюме.
- Ниже — список разделов: «Чёткость формулировок», «Качество дистракторов»,
  «Охват темы», «Сбалансированность сложности». Под каждым — конкретные
  пункты, что улучшить.
- Закрытие крестиком сверху или кнопкой «Закрыть» внизу — работает.
- В тесте при этом **ничего не меняется**, AI только советует.

**Если что-то не так — баг:**
- Окно пустое или текст не на русском.
- Все вопросы AI признал хорошими, хотя вы их специально испортили.
- После закрытия окна в тесте появились/исчезли вопросы.

---

### 2.4. Улучшить весь тест

**Простыми словами:** AI предлагает улучшенные формулировки и варианты;
автор отмечает галками, что применить.

**Как проверять:**
1. Откройте тест из 2.3 (с теми же намеренно слабыми вопросами).
2. Нажмите **«Сохранить»** на всякий случай.
3. Нажмите кнопку **«Улучшить»**.

**Что должно произойти:**
- Открывается окно «Улучшение теста».
- Сверху подпись «Отметьте вопросы… N из M» (M — всего вопросов, N — где AI предложил изменения).
- Каждый изменённый вопрос — отдельный блок:
  - Чекбокс **«Вопрос #N»** (по умолчанию **отмечен**).
  - Слева — «Было» (старый текст и варианты, изменённые куски зачёркнуты).
  - Справа — «Стало» (новые формулировки, выделены).
  - Правильные варианты помечены галочкой **✓**.
- Внизу — две кнопки: **«Отмена»** и **«Применить выбранное»**.

**Проверьте применение по выбору:**
1. Снимите галки у двух вопросов из списка.
2. Нажмите **«Применить выбранное»**.

**Что должно произойти:**
- Окно закрывается.
- В редакторе **только** отмеченные вопросы заменены на улучшенные;
  два вопроса, у которых вы сняли галки, остались в прежнем виде.
- Появляется подсказка «Изменения применены. Не забудьте сохранить.»
- После **«Сохранить»** — обычное «Сохранено.»

**Если что-то не так — баг:**
- Поменялось **число** вопросов или вариантов в каких-то вопросах
  (должно остаться как было).
- В вопросе изменилось значение «Несколько правильных ответов» (галка
  переключилась сама).
- Изменились вопросы, у которых вы сняли галку.
- Кнопка «Отмена» всё равно применила изменения.
- В колонках «Было» и «Стало» одинаковый текст (нет смысла предлагать).

---

### 2.5. AI: вопрос/переформулировать

**Простыми словами:** работа с одним вопросом. Если поле пустое — AI его
придумает; если уже заполнено — переформулирует красивее, варианты не трогает.

**Как проверять (новый вопрос):**
1. В любом тесте нажмите **«Добавить вопрос»** — появилась пустая карточка.
2. **Не трогайте** поле «Формулировка вопроса».
3. Нажмите **«Добавить вариант»** 4 раза — должно стать 4 пустых варианта.
4. Нажмите кнопку **«AI: вопрос/переформулировать»** в этой карточке.

**Что должно произойти:**
- Поле «Формулировка вопроса» заполнено осмысленным текстом по теме теста.
- Все 4 варианта заполнены.
- Ровно один помечен как правильный.
- Внизу появляется строка статуса **«AI: вопрос сгенерирован.»**

**Как проверять (переформулировать существующий):**
1. Возьмите готовый вопрос с уже заполненной формулировкой.
2. Нажмите **«AI: вопрос/переформулировать»** в его карточке.

**Что должно произойти:**
- Меняется **только текст вопроса** — варианты ответа остаются прежними,
  правильные варианты те же.
- Статус **«AI: формулировка обновлена.»**

**Если что-то не так — баг:**
- На пустом вопросе AI ничего не сгенерировал.
- На заполненном вопросе AI поменял варианты ответа или правильность —
  должен трогать только формулировку.
- Получилось 0 или 1 правильных вариантов в новом вопросе (надо ровно 1
  для одиночного выбора).

---

### 2.6. Импорт документа

**Простыми словами:** автор загружает PDF/Word/текст со статьёй —
AI читает файл и сам предлагает черновик теста.

**Подготовьте файл:** возьмите PDF или DOCX на 1–3 страницы со связным
русским текстом (например, любую методичку или статью). Лимит — 16 МБ.

**Как проверять:**
1. В редакторе любого нового теста (можно пустого) → блок «AI-помощник»
   → **«Импортировать»** → нажмите большую кнопку **«Загрузить документ (PDF, DOCX, TXT, MD)»** → выберите файл.
2. Подождите 5–30 секунд.

**Что должно произойти:**
- Появляется подтверждение «Сгенерировано: «…», вопросов: N. Применить как новый черновик? Текущие вопросы будут заменены». Нажмите **OK**.
- Тест заполнен вопросами по содержанию загруженного документа.
- Можно сохранить кнопкой **«Сохранить»**.

**Дополнительно — отказ:**
1. Повторите загрузку, но в подтверждении нажмите **«Отмена»**.
2. Тест должен остаться **в прежнем виде**, ничего не подменилось.

**Дополнительно — большой файл:**
1. Возьмите файл больше 16 МБ.
2. Загрузите его.

**Что должно произойти:** ошибка о слишком большом файле; вопросы не
подменились.

**Дополнительно — неподдерживаемый тип:**
1. Возьмите файл `.xlsx` или картинку `.png`.
2. Попробуйте загрузить.

**Что должно произойти:** алерт «Неподдерживаемый формат…»; вопросы не
подменились.

**Если что-то не так — баг:**
- Подтверждение не появилось — вопросы заменились молча.
- Отказ в подтверждении всё равно подменил вопросы.
- Большой файл не вызвал ошибку, а как-то «прошёл».
- Файл не на русском дал тест с непонятной кашей вместо вопросов.

---

### 2.7. Поведение, если ключа AI нет

> Этот сценарий обычно проверять не нужно — он сработает автоматически, если разработчик уберёт ключ.
> Но если в каталоге AI вообще не работает, то проверьте именно это, чтобы понять — это баг или просто ключ не настроен.

**Как проверять:**
1. **«Настройки»** → если статус **«Не задан»** (красный) — это и есть тестируемая ситуация.
2. Откройте любой тест и нажмите по очереди:
   - **«По названию»**
   - **«По текущей сетке»**
   - **«Проверить»**
   - **«Улучшить»**
   - **«AI: вопрос/переформулировать»** в любой карточке
   - **«Загрузить документ»**

**Что должно произойти:** в каждом случае появляется понятное сообщение,
что AI не настроен, **и предложение открыть «Настройки»**. После согласия
— открывается страница `/settings`. Никакого «AI: ошибка» без объяснений.

**Если что-то не так — баг:**
- Сообщение об ошибке без слов «Настройки».
- Ссылка/кнопка «Открыть Настройки» не ведёт на нужную страницу.
- Сайт молча ничего не делает после нажатия AI-кнопки.

---

## Памятка: общий алгоритм отчёта о баге

Если что-то идёт не так, к тикету приложите:

1. **URL страницы**, на которой воспроизвели баг (полностью, из адресной
   строки).
2. **Шаги** — что именно нажимали по порядку (1-2-3).
3. **Что увидели** против **что ожидали увидеть** (по описанию выше).
4. **Скриншот** экрана с проблемой (для модалок — со всем содержимым окна).
5. Если ошибка — **точный текст** сообщения.
6. **Учётная запись**, под которой воспроизвели (логин, без пароля).

Этого достаточно — лезть в консоль/код/базу не нужно и не надо.