Система тестирования сотрудников клиники

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

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

---

Содержание

• Функциональные возможности
• Роли и права доступа
• Установка и запуск
• Данные, сотрудники, интеграция с HR
• Нефункциональные требования
• Вне scope

---

Функциональные возможности

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

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

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

Тест содержит:

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

Вопрос содержит:

• Текст вопроса
• Минимум 3 варианта ответа
• Один или несколько правильных ответов

Настройки теста:

• Разрешить возврат к предыдущему вопросу: да / нет

Версионирование:

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

Назначение теста

• Список получателей (отдел или конкретные сотрудники)
• Срок сдачи — дата дедлайна
• Допустимое количество попыток (1 или более)

Прохождение теста

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

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

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

Трекер попыток

Единый интерфейс просмотра всех попыток прохождения тестов:

• Фильтрация по подразделению, сотруднику, тесту, статусу, результату
• Пагинация и сортировка

AI-помощник

Интеграция с LLM для помощи при создании тестов:

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

---

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

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

---

Установка и запуск

База данных (как в HR_TG_Bot / Postgres_TG_Bots)

Используется тот же экземпляр PostgreSQL, что и в Postgres_TG_Bots (docker-compose.dev.yml, контейнер hr_postgres_dev, учётка hr_bot_user / сеть hr_postgres_dev_net — см. HR_TG_Bot docker-compose).

Схема приложения (таблицы users, tests, departments, …) не совмещается с БД hr_bot_test — для TestingWebApp заведена отдельная база clinic_tests.

1. Поднять Postgres из Postgres_TG_Bots (и при необходимости внешнюю сеть: docker network create hr_postgres_dev_net — как в compose этих репозиториев).
2. Один раз создать базу:
   psql "postgresql://hr_bot_user:hrbot123@localhost:5432/postgres" -c "CREATE DATABASE clinic_tests;"
3. Скопировать backend/.env.example в backend/.env, при необходимости поправить DATABASE_URL (внутри Docker кластера — хост hr_postgres_dev, порт 5432).
4. Миграции: из каталога backend/: npm run migrate, затем npm run start (и фронт из frontend/ — npm run dev).

Старый вариант только с локальным Postgres на порту 5433: корневой docker compose up -d в TestingWebApp и в .env порт 5433 (или отдельные DB_* без DATABASE_URL) — оставлен для разработки без общего Postgres_TG_Bots.

Данные, сотрудники, интеграция с HR

• Две роли кластера Postgres: в clinic_tests — только сущности модуля тестирования (тесты, версии, назначения, попытки, локальные технические учётки при необходимости). В hr_bot_test (Postgres_TG_Bots / hr_web_viewer) — штат, справочники, существующий RBAC и веб-логины. Так мы не смешиваем схемы и не дублируем «источник правды» по людям.
• Сотрудник в процессах (назначения, дашборды, доступ к результатам) — везде по staff_members.id. Ссылки в clinic_tests храним как тот же идентификатор (логическая связь с staff_members в hr_bot_test); ФИО, отдел, роли подтягиваем из HR при отображении или кэшируем по согласованной политике, а не ведём второй кадровый учёт.
• telegram_id в данных сотрудника не участвует в бизнес-логике модуля: ни вход, ни проверка прав, ни выбор сотрудника в сценариях, ни фильтрация — только справочная информация при необходимости (отображение, история).
• RBAC в перспективе: единая система разрешений — та, что уже в HR (роли, staff_role_assignments, permissions). Модуль тестирования не развивает отдельную полную копию матрицы; проверка действий в целевом виде — через HR (внутренний API / токен / согласованные запросы к БД). Пока договор и API не готовы — допустимы временные флаги в clinic_tests, явно помечаемые как MVP.

Детализация задач и варианты A.x: docs/revision_task/card1.md.

---

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

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

---

Вне scope (не реализуется в данной версии)

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