docs: update ТЗ to v1.3 — детализировать версионность и AI-помощник
- §4.2: развернуто описание поведения версионности (правка in-place до
первой попытки, создание новой версии после, переключение активной,
привязка попыток к версии)
- §4.7: AI-функции разделены на два уровня — над всем тестом
(сгенерировать / проверить / предложить вариант) и над отдельным
вопросом (улучшить / дистракторы); описана механика постатейного
сравнения с чекбоксами
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
**Настройки теста (задаются автором при создании):**
- Разрешить возврат к предыдущему вопросу: да / нет
**Правила работы с тестом:**
- Автор может редактировать тест пока никто его не проходил
- Если тест уже проходили — создаётся новая версия (`version + 1`), старая сохраняется
- Все версии теста хранятся; результаты привязаны к конкретной версии
- Активная версия — та, которую видят сотрудники; автор может вручную переключить активную версию
- Тест можно деактивировать (скрыть из списка, не удалять)
**Правила работы с тестом (версионность):**
- Пока по тесту не было ни одной попытки, автор редактирует тест **на месте** — номер версии не меняется.
- Как только появилась хотя бы одна попытка, любое сохранение изменений создаёт **новую версию** теста (`version + 1`, связь со старой версией через `parent_id`). Старая версия становится неактивной, но сохраняется в истории.
- Все версии теста хранятся в виде связанной цепочки. Каждая попытка прохождения привязана к конкретной версии, по которой сотрудник проходил тест, — разбор ошибок по старым результатам остаётся корректным.
- В списке тестов сотрудникам и авторам показывается только **одна активная версия** каждой цепочки.
- Автор может открыть страницу истории версий теста и вручную переключить активную версию на любую из цепочки — остальные версии при этом автоматически становятся неактивными.
- Тест можно деактивировать целиком (скрыть цепочку из списка, данные не удаляются).
### 4.3. Назначение теста
@ -113,21 +115,28 @@ HR-менеджер видит трекер по всей клинике.
### 4.7. AI-помощник при создании и редактировании тестов
Интеграция с LLM (DeepSeek) доступна авторам тестов в форме создания и редактирования.
Интеграция с LLM (DeepSeek) доступна авторам тестов в форме создания и редактирования. AI работает на двух уровнях: **над всем тестом целиком** и **над отдельным вопросом с блоком его вариантов ответов**.
**Функции уровня всего теста:**
| Функция | Описание |
|---------|----------|
| Сгенерировать тест | На основе названия теста AI генерирует готовый набор вопросов с вариантами ответов. Кнопка доступна только когда название теста заполнено; отдельный ввод темы не требуется. Результат показывается превью, автор применяет его целиком кнопкой «Применить все вопросы». |
| Проверить тест | AI анализирует весь тест и выдаёт структурированные рекомендации по улучшению (чёткость формулировок, качество дистракторов, охват темы). Показывается в модальном окне. |
| Предложить вариант (улучшить весь тест) | AI предлагает улучшенные формулировки всех вопросов и всех вариантов ответов. Результат отображается как **постатейное сравнение** (старая версия → новая) с чекбоксами — автор выбирает, какие изменения применить. |
**Функции AI-помощника:**
**Функции уровня одного вопроса:**
| Функция | Описание |
|---------|----------|
| Генерация теста | Автор вводит тему — AI генерирует готовый набор вопросов с вариантами ответов |
| Улучшение формулировки | AI переформулирует выбранный вопрос более чётко и однозначно |
| Добавление дистракторов | AI генерирует правдоподобные неправильные варианты ответов к вопросу |
| Проверка качества | AI анализирует весь тест и выдаёт рекомендации по улучшению |
| Улучшить вопрос | AI переформулирует выбранный вопрос и его варианты ответов более чётко и однозначно. Результат показывается в модале **с постатейным сравнением и чекбоксами** (вопрос + каждый вариант ответа отдельно), прямой замены без подтверждения не происходит. |
| Дистракторы | AI генерирует 3 новых правдоподобных неправильных варианта ответа к вопросу; они добавляются к существующим, а не заменяют их. |
**Настройки:**
- API-ключ DeepSeek вводится на странице `/settings` и хранится в базе данных
- Страница настроек содержит кнопку «Проверить подключение» — выполняет тестовый запрос к API
- Ключ хранится только на бэкенде и не передаётся на фронтенд
- API-ключ DeepSeek вводится на странице `/settings` и хранится в базе данных.
- Страница настроек содержит кнопку «Проверить подключение» — выполняет тестовый запрос к API.
- Ключ хранится только на бэкенде, на фронтенд не передаётся.
- Все AI-функции требуют настроенного ключа: при его отсутствии возвращается понятная ошибка с предложением перейти в «Настройки».
Aleksey Razorvin
2 weeks ago