# Техническое задание
## Система тестирования сотрудников клиники

**Версия:** 1.3
**Дата:** 2026-04-23
**Статус:** Согласовано

---

## 1. Назначение системы

Веб-приложение для проведения внутреннего тестирования сотрудников клиники. Руководители подразделений и HR-менеджер создают тесты и назначают их сотрудникам. Сотрудники проходят тесты в браузере. Система фиксирует все попытки и результаты.

---

## 2. Роли и права доступа

| Роль | Кто | Создаёт тесты | Назначает тесты | Видит результаты |
|------|-----|:---:|:---:|:---:|
| **HR-менеджер** | Руководитель службы HR, Директор клиники | ✅ | Всем сотрудникам клиники | Всех сотрудников |
| **Руководитель подразделения** | Главный врач, рук. службы администраторов и др. | ✅ | Только своему подразделению | Только своего подразделения |
| **Сотрудник** | Все остальные работники | ❌ | ❌ | Только свои |

---

## 3. Авторизация

- Вход по логину и паролю
- Учётные записи создаются администратором системы вручную
- Сессия хранится на сервере (cookie-based или JWT — определить при выборе стека)
- Пароль хранится в зашифрованном виде (bcrypt или аналог)

---

## 4. Функциональные требования

### 4.1. Управление пользователями и подразделениями

- Создание/редактирование/деактивация учётных записей сотрудников
- Каждый сотрудник принадлежит одному подразделению
- Создание/редактирование справочника подразделений
- Назначение роли сотруднику: HR-менеджер / Руководитель подразделения / Сотрудник

### 4.2. Создание и редактирование тестов

**Тест содержит:**
- Название теста
- Описание (опционально)
- Список вопросов (минимум 7)
- Порог зачёта — минимальный % правильных ответов (задаётся автором)
- Таймер прохождения — лимит в минутах (опционально)

**Вопрос содержит:**
- Текст вопроса
- Минимум 3 варианта ответа
- Один или несколько правильных ответов (чекбокс или радио-кнопка в зависимости от типа)

**Настройки теста (задаются автором при создании):**
- Разрешить возврат к предыдущему вопросу: да / нет

**Правила работы с тестом (версионность):**

- Пока по тесту не было ни одной попытки, автор редактирует тест **на месте** — номер версии не меняется.
- Как только появилась хотя бы одна попытка, любое сохранение изменений создаёт **новую версию** теста (`version + 1`, связь со старой версией через `parent_id`). Старая версия становится неактивной, но сохраняется в истории.
- Все версии теста хранятся в виде связанной цепочки. Каждая попытка прохождения привязана к конкретной версии, по которой сотрудник проходил тест, — разбор ошибок по старым результатам остаётся корректным.
- В списке тестов сотрудникам и авторам показывается только **одна активная версия** каждой цепочки.
- Автор может открыть страницу истории версий теста и вручную переключить активную версию на любую из цепочки — остальные версии при этом автоматически становятся неактивными.
- Тест можно деактивировать целиком (скрыть цепочку из списка, данные не удаляются).

### 4.3. Назначение теста

При назначении задаются:
- Список получателей (отдел или конкретные сотрудники)
- Срок сдачи — дата дедлайна (задаётся в днях от даты назначения или конкретной датой)
- Допустимое количество попыток (1 или более — задаётся при назначении)

HR-менеджер может назначить тест сотрудникам любых подразделений.
Руководитель подразделения — только сотрудникам своего подразделения.

### 4.4. Прохождение теста (интерфейс сотрудника)

- На главной странице сотрудник видит список назначенных ему тестов со статусами:
  - `Не начат` — ещё не открывал
  - `В процессе` — начал, не завершил (если таймер — отсчёт продолжается)
  - `Завершён` — сдал/не сдал
  - `Просрочен` — дедлайн прошёл, не сдан
- Если задан таймер — отображается обратный отсчёт, по истечении тест завершается автоматически
- Порядок вопросов **случайный** при каждом прохождении
- Возможность вернуться к предыдущему вопросу — определяется настройкой теста

### 4.5. Результаты после завершения теста

Сотрудник сразу после сдачи видит:
- Итоговый балл и процент правильных ответов
- Факт зачёта: **сдал / не сдал** (относительно порога)
- Разбор ошибок: по каждому вопросу — его ответ и правильный ответ

### 4.6. Трекер попыток

Система фиксирует каждую попытку прохождения теста:

| Поле | Описание |
|------|----------|
| Сотрудник | ФИО, подразделение |
| Тест | Название |
| Попытка № | Порядковый номер попытки |
| Начало | Дата и время начала |
| Завершение | Дата и время окончания |
| Результат | Количество правильных ответов / всего, % |
| Зачёт | Да / Нет (преодолён ли порог) |

Руководитель видит трекер по своему подразделению.
HR-менеджер видит трекер по всей клинике.
Сотрудник видит только свои попытки.

### 4.7. AI-помощник при создании и редактировании тестов

Интеграция с LLM (DeepSeek) доступна авторам тестов в форме создания и редактирования. AI работает на двух уровнях: **над всем тестом целиком** и **над отдельным вопросом с блоком его вариантов ответов**.

**Функции уровня всего теста:**

| Функция | Описание |
|---------|----------|
| Сгенерировать тест | На основе названия теста AI генерирует готовый набор вопросов с вариантами ответов. Кнопка доступна только когда название теста заполнено; отдельный ввод темы не требуется. Результат показывается превью, автор применяет его целиком кнопкой «Применить все вопросы». |
| Проверить тест | AI анализирует весь тест и выдаёт структурированные рекомендации по улучшению (чёткость формулировок, качество дистракторов, охват темы). Показывается в модальном окне. |
| Предложить вариант (улучшить весь тест) | AI предлагает улучшенные формулировки всех вопросов и всех вариантов ответов. Результат отображается как **постатейное сравнение** (старая версия → новая) с чекбоксами — автор выбирает, какие изменения применить. |

**Функции уровня одного вопроса:**

| Функция | Описание |
|---------|----------|
| Улучшить вопрос | AI переформулирует выбранный вопрос и его варианты ответов более чётко и однозначно. Результат показывается в модале **с постатейным сравнением и чекбоксами** (вопрос + каждый вариант ответа отдельно), прямой замены без подтверждения не происходит. |
| Дистракторы | AI генерирует 3 новых правдоподобных неправильных варианта ответа к вопросу; они добавляются к существующим, а не заменяют их. |

**Настройки:**
- API-ключ DeepSeek вводится на странице `/settings` и хранится в базе данных.
- Страница настроек содержит кнопку «Проверить подключение» — выполняет тестовый запрос к API.
- Ключ хранится только на бэкенде, на фронтенд не передаётся.
- Все AI-функции требуют настроенного ключа: при его отсутствии возвращается понятная ошибка с предложением перейти в «Настройки».

---

## 5. Нефункциональные требования

| Параметр | Требование |
|----------|-----------|
| Количество пользователей | 50–200 человек |
| Платформа | Веб-приложение, браузер (desktop-first) |
| Доступность | Внутренняя сеть клиники |
| Язык интерфейса | Русский |
| Время отклика | < 2 секунды для основных операций |

---

## 6. Уведомления

Уведомления реализуются в одном из последних спринтов.

- Канал: мессенджер **MAX**
- События для уведомления:
  - Сотруднику назначен новый тест
  - Приближается дедлайн сдачи теста
- Интеграция с MAX API — отдельная задача спринта

---

## 7. Вне scope (не реализуем в данной версии)

- Интеграция с AD/LDAP
- Мобильное приложение
- Вопросы с вложениями (изображения, видео)
- Экспорт отчётов в Excel / PDF