Browse Source
Новый документ DOC/ТЗ_доработка_v1.md описывает расширение параллельной реализации Кости: контекст и польза для ролей, раздел с ключевыми возможностями (AI-помощники, версионирование, медиа, подсказки и режимы, дашборды), 5 этапов (редактор → дашборды → интеграция с HR → mini-app MAX → уведомления) и порядок приёмки. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>dev-new-design-page-createtest
Aleksey Razorvin
2 weeks ago
1 changed files with 272 additions and 0 deletions
@ -0,0 +1,272 @@ |
|||||||
|
# Техническое задание на доработку |
||||||
|
## Система тестирования сотрудников клиники |
||||||
|
|
||||||
|
**Версия:** 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. **Этап 1** — по мере готовности каждой из пяти функций (4.1–4.5) руководители подразделений вручную проходят по ней сценарии использования, заводят замечания, разработчик их исправляет. Этап принят, когда все пять функций прошли приёмку. |
||||||
|
2. **Этап 2** — дашборды тестируются по ролям: сотрудник → руководитель подразделения → директор. Проверяется, что каждая роль видит только разрешённые данные и что переходы между уровнями (клиника → подразделение → сотрудник) работают корректно. |
||||||
|
3. **Этапы 3–5** — приёмка проводится совместно с командой большой HR-системы, критерии и сценарии определяются в начале каждого этапа. |
||||||
|
|
||||||
|
Подробные чек-листы тестирования для каждой функции готовятся перед стартом соответствующего этапа и ведутся в отдельных документах в папке `DOC/`. |
||||||
Loading…
Reference in new issue