Приложение для тестирования сотрудников клиники методом один вопрос - до пяти ответов один из которых правильный. Сотрудник должен выбрать правильный вариант ответа

32 KiB

Raw Permalink Blame History

Техническое задание на доработку

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

Версия: 1.0 Дата: 2026-04-23 Статус: Черновик Адресат: Константин Л. (разработчик) Базовый репозиторий: https://git.pirogov.ai/l_konstantin/TestingWebApp

1. Контекст и зачем это делается

Зачем клинике система тестирования

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

Что система даёт каждой роли:

Руководителю подразделения — единое место, где видно, кто из сотрудников прошёл обязательные тесты, кто не справился, у кого приближается дедлайн. Вместо рассылки регламентов «в чат и на почту» — проверяемая практика: назначил тест → увидел результат → понял, где у отдела пробелы. AI-помощник снимает главный барьер: придумать и сформулировать хороший тест — это отдельная работа, которой у руководителя обычно нет времени. С помощником создание теста занимает минуты, а не часы.
Сотруднику — понятный личный кабинет: какие тесты назначены, когда сдать, какой результат был в прошлый раз, какие ошибки стоит разобрать. Разбор ошибок после теста превращает проверку в короткий обучающий цикл. Если автор составит задорный тест — с живыми формулировками, неочевидными вариантами ответов, лёгким юмором, — прохождение перестаёт восприниматься как рутинная формальность и приобретает элементы фана и геймификации. Это снижает сопротивление и делает регулярные тесты нормальной частью рабочего дня.
Директору и его помощнику — объективная картина по всей клинике: какие подразделения сильнее, какие отстают, где нужно вмешательство. Это инструмент управленческих решений по обучению и кадрам, а не просто отчётность.
HR — структурированная история знаний каждого сотрудника, которая в будущем ляжет в общий HR-контур (онбординг, индивидуальные планы развития, кадровые решения).

Стратегическая роль: точка входа в HR-приложение в MAX

У модуля тестирования есть ещё одна важная роль — он становится одной из первых регулярно используемых частей общего HR-приложения в боте MAX. Тесты назначаются регулярно и требуют обязательного прохождения, а значит, сотрудник будет заходить в HR-приложение не время от времени, а стабильно. Это формирует привычку: открыть HR в MAX — привычное действие. Следом подтянутся и другие HR-сервисы (справочная информация, заявки, графики, отпуска, обратная связь), которые без точки притяжения могли бы оставаться «пустым модулем». Таким образом, система тестирования популяризует само HR-приложение внутри MAX и помогает ему стать ежедневным рабочим инструментом, а не редко открываемым разделом.

Отдельно важен формат взаимодействия. Внутри бота MAX система тестирования открывается как полноценное веб-приложение (мини-приложение) — с нормальной вёрсткой форм, навигацией, медиа в вопросах, удобными таблицами результатов. Это принципиально лучший пользовательский опыт, чем предыдущая реализация в Telegram, где интерфейс был ограничен форматом бота (сообщения, кнопки, линейные диалоги) и не давал ни удобного ввода, ни нормального отображения сложного контента. Перевод в веб-формат внутри MAX — это не просто смена канала, а качественный скачок в удобстве работы с тестами для всех ролей.

Текущее состояние

Уже реализовано: авторизация по логину/паролю, создание тестов автором, назначение теста сотрудникам из списка, прохождение теста сотрудником в браузере.

Доработка расширяет эту реализацию новыми возможностями и готовит её к встраиванию в общую HR-систему клиники. В HR-системе уже есть собственная авторизация и собственная система разграничения прав (кто какие разделы и данные видит), поэтому на более поздних этапах собственная авторизация модуля тестирования будет отключена в пользу HR-авторизации. До этого момента текущая авторизация используется как есть.

2. Ключевые дополнительные возможности

Помимо базового функционала (создание тестов, назначение, прохождение), который уже реализован, в этой доработке добавляются пять возможностей, радикально расширяющих ценность системы. Они перечислены в порядке значимости для пользователя.

2.1. AI-помощники при создании тестов — ключевая возможность

Это главный выигрыш всей доработки. Создание теста с нуля — это отдельная работа: нужно придумать вопросы, сформулировать варианты ответов, подобрать неочевидные неправильные ответы (дистракторы), проверить качество формулировок. У руководителя подразделения этого времени обычно нет. Без AI-помощника сама задача «писать тесты регулярно» фактически невыполнима — она превращается в проект.

AI-помощник меняет это кардинально:

Сокращение времени в разы. Вместо нескольких часов ручной работы — несколько минут на редактирование черновика, который сгенерировал AI.
Более удобный формат работы. Автор не пишет с пустого листа, а работает в режиме редактора: получает готовое, правит, подтверждает. Отдельные кнопки позволяют улучшить конкретный вопрос, добавить дистракторы, сгенерировать подсказку, проверить весь тест на качество.
Выше качество формулировок. AI предлагает варианты, о которых автор мог не подумать — правдоподобные дистракторы, более чёткие формулировки, корректную подсказку.

Без этой возможности регулярное создание тестов останется узким местом и система не заработает в полную силу. С ней — создание теста становится быстрой повседневной операцией, которую может делать любой руководитель.

2.2. Версионирование тестов

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

2.3. Медиа в вопросах

К вопросу можно прикрепить изображение или видео: фото инструмента, рентгеновский снимок, ролик с правильной техникой манипуляции. Тесты перестают быть «только про текст» — это особенно важно в медицинской тематике.

2.4. Подсказки и режимы прохождения (таймер, мгновенная оценка)

Один и тот же тест можно проводить как строгую проверку (с таймером, без подсказок, итог в конце) или как мягкий обучающий тренажёр (с подсказками, без таймера, мгновенная обратная связь по каждому вопросу). Набор режимов — независимые настройки, автор комбинирует их под задачу.

2.5. Дашборды для всех ролей

Замена ручного сбора статистики на один экран с нужным срезом: сотрудник видит свои тесты и историю, руководитель — своё подразделение, директор — всю клинику с возможностью посмотреть любое подразделение и любого сотрудника.

3. Этапы

№	Этап	Формат	Кто принимает
1	Доработка редактора тестов	Web desktop	Руководители подразделений
2	Дашборды (сотрудника / руководителя / директора)	Web desktop	Руководители подразделений + директор
3	Интеграция с HR-системой	Backend-интеграция + изменения авторизации	Совместно с командой HR
4	Адаптация под мини-приложение в боте MAX	Mini-app	Совместно с командой HR
5	Уведомления	В рамках общей системы HR	Совместно с командой HR

Этапы 1 и 2 реализуются как отдельные desktop-приложения и принимаются независимо друг от друга. Этапы 3–5 выполняются позже, совместно с командой большой HR-системы — в этом ТЗ описаны верхнеуровнево.

4. Этап 1 — Доработка редактора тестов

Этап расширяет существующий редактор пятью возможностями. Все пять — независимые фичи, могут реализовываться в любом порядке и приниматься отдельно.

4.1. Версионирование тестов

Цель: сохранить корректность истории прохождений, когда автор правит тест после первых попыток.

Правила:

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

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

Цель: ускорить и повысить качество создания тестов силами LLM.

Интеграция:

Используется DeepSeek API (совместим с форматом OpenAI — подключается через библиотеку openai с base_url=https://api.deepseek.com, модель deepseek-chat).
Для структурированных ответов использовать response_format={"type": "json_object"}.
API-ключ DeepSeek вводится на отдельной странице настроек (/settings) и хранится в БД. На фронтенд ключ не передаётся.
На странице настроек — кнопка «Проверить подключение», которая выполняет тестовый запрос к API.
Все AI-функции требуют настроенного ключа; при его отсутствии возвращается понятная ошибка со ссылкой на «Настройки».

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

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

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

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

4.3. Медиа в вопросах

Цель: к вопросу можно прикрепить изображение или видео, которое сотрудник увидит при прохождении.

Требования:

К одному вопросу может быть прикреплён один медиа-файл (изображение или видео).
Поддерживаемые форматы:
- изображения: JPG, PNG, WebP;
- видео: MP4, WebM.
Ограничения по размеру:
- изображение — до 5 МБ;
- видео — до 50 МБ.
Файлы хранятся локально на сервере (например, в папке uploads/). Внешние хранилища (S3/MinIO) не используются.
В редакторе вопроса — отдельное поле «Медиа» с загрузкой файла и превью, кнопкой удаления.
При прохождении теста медиа отображается над текстом вопроса. Видео — с нативным плеером браузера.
Имена файлов на диске должны быть непредсказуемыми (например, UUID), чтобы исключить угадывание ссылок.

4.4. Подсказки к вопросам

Цель: при прохождении теста в режиме с подсказками сотрудник может запросить подсказку к вопросу.

Требования:

Каждый вопрос имеет одно необязательное текстовое поле «Подсказка».
Заполнение подсказки — на усмотрение автора. Три способа:
1. Автор пишет подсказку вручную.
2. Автор нажимает «Сгенерировать подсказку» — AI генерирует текст подсказки; автор может сохранить как есть, отредактировать или удалить.
3. Оставить поле пустым — подсказки по этому вопросу не будет даже в режиме с подсказками.
Подсказка показывается сотруднику только если тест запущен в режиме с подсказками (см. 4.5) и автор её заполнил.

4.5. Режимы прохождения теста

Цель: автор при создании теста выбирает, как именно сотрудник будет его проходить.

Три независимых настройки теста (устанавливаются при создании, сохраняются в версии теста):

Настройка	Варианты	Поведение при прохождении
Подсказки	Включены / выключены	Если включены и у вопроса заполнена подсказка — сотруднику доступна кнопка «Показать подсказку» под вопросом. Факт использования подсказки фиксируется в попытке (в будущем может влиять на балл).
Таймер	Выключен / N минут	Если задан — отображается обратный отсчёт. По истечении — тест автоматически завершается, попытка считается сданной с тем, что ответил сотрудник.
Мгновенная оценка	Включена / выключена	Если включена — после ответа на каждый вопрос сразу показывается правильный ответ и комментарий (разбор по этому вопросу), затем переход к следующему. Если выключена — разбор и итог только после завершения всего теста.

Настройки отображаются на странице прохождения так, чтобы сотрудник заранее понимал условия (есть ли таймер, будет ли сразу виден правильный ответ и т. д.).

5. Этап 2 — Дашборды

Цель: предоставить каждой роли индивидуальный экран с релевантной для неё информацией. Этап реализуется отдельным desktop-приложением (или отдельным разделом того же приложения — на усмотрение разработчика).

5.1. Дашборд сотрудника

Что видит сотрудник на своей главной странице:

Назначенные тесты — таблица или карточки со статусом (Не начат, В процессе, Завершён, Просрочен) и датой дедлайна.
График дедлайнов — визуализация (таймлайн или календарь) по ближайшим срокам сдачи.
История попыток — все попытки сотрудника: тест, версия, дата начала/завершения, результат, зачёт/незачёт.
Из строки истории — переход на разбор ошибок конкретной попытки.

5.2. Дашборд руководителя подразделения

Что видит руководитель подразделения — только по своему подразделению:

Сводка по сотрудникам: список сотрудников с колонками — назначено тестов / сдано / просрочено / средний балл.
По клику на сотрудника — его история попыток и назначенных тестов.
Сводка по назначенным тестам: по каждому тесту, назначенному подразделению — процент сдавших, список сдавших и несдавших.
Фильтры: по диапазону дат, по конкретному тесту.

5.3. Дашборд директора и помощника директора

Что видят директор и его помощник — по всей клинике:

Общая сводка: число активных тестов, число сотрудников, общий процент сдачи, средний балл.
Сравнение подразделений: таблица подразделений с колонками — число сотрудников, процент сдачи, средний балл. Сортировка по любой колонке.
По клику на подразделение открывается вид как у руководителя этого подразделения (см. 5.2).
По клику на сотрудника (из любого уровня) — его история попыток.

6. Этап 3 — Интеграция с HR-системой

Цель: модуль тестирования становится частью большой HR-системы клиники.

Ключевые изменения:

Собственная авторизация модуля тестирования отключается. Вход выполняется через HR (SSO, JWT или другой механизм, который будет определён командой HR).
Пользователи, подразделения и роли приходят из HR — не хранятся в локальной БД модуля тестирования (или хранятся как кэш, синхронизируемый с HR).
Разграничение прав доступа (кто что видит и что может делать) выполняется по ролям, приходящим из HR. Соответствие ролей HR-системы и возможностей модуля тестирования определяется отдельно в начале этапа.
Назначение тестов остаётся внутри модуля тестирования (а не в HR). Это отдельный пользовательский сценарий, который удобнее оставить рядом с редактором и трекером.
Дашборды используют ФИО, подразделения и иерархию из HR.

Детальные контракты (API HR, формат токена, справочники) будут описаны отдельным документом совместно с командой HR перед стартом этапа.

7. Этап 4 — Мини-приложение для бота MAX

Цель: сотрудник может проходить назначенные тесты прямо из бота MAX, без перехода в браузер.

Верхнеуровневые требования:

Desktop-интерфейс сотрудника адаптируется под размер мини-приложения MAX (адаптивная вёрстка, упрощённая навигация, без многоуровневого меню).
Внутри мини-приложения доступны: список назначенных тестов, прохождение теста, результат и разбор ошибок.
Функции авторов тестов и руководителей в mini-app не выносятся — для них остаётся полноценный desktop-интерфейс.
Авторизация в mini-app — через MAX → HR (конкретная схема определяется на старте этапа).

8. Этап 5 — Уведомления

Реализуются в рамках общей системы уведомлений большой HR-системы, а не как отдельный модуль системы тестирования.

События, которые должна знать система тестирования и передавать в общую систему уведомлений:

Сотруднику назначен новый тест.
Приближается дедлайн сдачи теста (за N дней, N — настраивается).
Дедлайн теста просрочен без сдачи.

Канал (MAX / e-mail / другое) и формат сообщений определяются общей системой HR.

9. Вне scope

В рамках этой доработки не реализуются:

Экспорт отчётов в Excel / PDF.
Собственная система уведомлений внутри модуля тестирования — уведомления будут реализованы в общей HR-системе.

10. Порядок приёмки

Общий принцип: каждый этап принимается отдельно. Следующий этап не начинается, пока предыдущий не принят.

Этап 1 — по мере готовности каждой из пяти функций (4.1–4.5) руководители подразделений вручную проходят по ней сценарии использования, заводят замечания, разработчик их исправляет. Этап принят, когда все пять функций прошли приёмку.
Этап 2 — дашборды тестируются по ролям: сотрудник → руководитель подразделения → директор. Проверяется, что каждая роль видит только разрешённые данные и что переходы между уровнями (клиника → подразделение → сотрудник) работают корректно.
Этапы 3–5 — приёмка проводится совместно с командой большой HR-системы, критерии и сценарии определяются в начале каждого этапа.

Подробные чек-листы тестирования для каждой функции готовятся перед стартом соответствующего этапа и ведутся в отдельных документах в папке DOC/.

32 KiB Raw Permalink Blame History