TestingWebApp/docs/ТЗ.md

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

**Версия:** 1.2
**Дата:** 2026-03-21
**Статус:** Согласовано

*Реализация в ветке `dev` (не дословно ТЗ):* [PROJECT_STATUS.md](PROJECT_STATUS.md) · [инструкция dev-стенда](DEV_CONTOUR_USER_GUIDE.md).

---

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

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

---

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

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

---

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

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

---

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

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

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

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

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

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

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

**Правила работы с тестом:**
- Автор может редактировать тест пока никто его не проходил
- Если тест уже проходили — создаётся новая версия (`version + 1`), старая сохраняется
- Все версии теста хранятся; результаты привязаны к конкретной версии
- Активная версия — та, которую видят сотрудники; автор может вручную переключить активную версию
- Тест можно деактивировать (скрыть из списка, не удалять)

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

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

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

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

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

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

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

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

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

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

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

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

Интеграция с LLM (DeepSeek) доступна авторам тестов в форме создания и редактирования.

**Функции AI-помощника:**

| Функция | Описание |
|---------|----------|
| Генерация теста | Автор вводит тему — AI генерирует готовый набор вопросов с вариантами ответов |
| Улучшение формулировки | AI переформулирует выбранный вопрос более чётко и однозначно |
| Добавление дистракторов | AI генерирует правдоподобные неправильные варианты ответов к вопросу |
| Проверка качества | AI анализирует весь тест и выдаёт рекомендации по улучшению |

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

---

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

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

---

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

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

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

---

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

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