Константин Лебединский
160 lines
12 KiB
Markdown
160 lines
12 KiB
Markdown
# Система тестирования сотрудников клиники
|
||
|
||
Веб-приложение для проведения внутреннего тестирования сотрудников клиники. Руководители подразделений и HR-менеджеры создают тесты и назначают их сотрудникам. Система фиксирует все попытки и результаты.
|
||
|
||
**Версия ТЗ:** 1.2
|
||
**Дата:** 2026-03-21
|
||
**Статус:** Согласовано
|
||
|
||
---
|
||
|
||
## Содержание
|
||
|
||
- [Функциональные возможности](#функциональные-возможности)
|
||
- [Роли и права доступа](#роли-и-права-доступа)
|
||
- [Установка и запуск](#установка-и-запуск)
|
||
- [Данные, сотрудники, интеграция с HR](#данные-сотрудники-интеграция-с-hr)
|
||
- [Нефункциональные требования](#нефункциональные-требования)
|
||
- [Вне scope](#вне-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](../Postgres_TG_Bots) (`docker-compose.dev.yml`, контейнер `hr_postgres_dev`, учётка `hr_bot_user` / сеть `hr_postgres_dev_net` — см. [HR_TG_Bot docker-compose](../HR_TG_Bot/docker-compose.dev.yml)).
|
||
|
||
Схема приложения (таблицы `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 start` (и фронт из `frontend/` — `npm run dev`).
|
||
|
||
**Docker (UI + API + общий Postgres):** поднять `Postgres_TG_Bots` (сеть `hr_postgres_dev_net`), создать БД `clinic_tests`, затем из корня `TestingWebApp`:
|
||
`docker compose -f docker-compose.dev.yml up --build` — интерфейс **http://localhost:8080** (Nginx проксирует `/api` в backend), API с хоста **http://localhost:3002** (внутри сети контейнера `3001`; см. [docker-compose.dev.yml](docker-compose.dev.yml), миграции в entrypoint). В БД `clinic_tests` для локального логина нужен активный `users` с bcrypt-паролем, либо включите `HR_AUTH=1` + `HR_DATABASE_URL` в compose/`.env` (см. `backend/.env.example`).
|
||
|
||
`docker compose -f docker-compose.dev.yml down` — остановка.
|
||
|
||
**Без общего кластера** (только отладка): `docker compose --profile standalone up -d` в TestingWebApp — Postgres на **5433**, тогда в `.env` укажите `DATABASE_URL=...localhost:5433/clinic_tests` или `DB_PORT=5433` с `DB_NAME`/`DB_USER` из compose.
|
||
|
||
**Если `npm run migrate` пишет `ECONNREFUSED ...:5433`:** в `backend/.env` нет (или кривой) `DATABASE_URL` на **5432**, и сработал старый `DB_PORT=5433`. Задайте `DATABASE_URL` как в `backend/.env.example` для общего Postgres.
|
||
|
||
### Данные, сотрудники, интеграция с 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](docs/revision_task/card1.md).
|
||
|
||
---
|
||
|
||
## Нефункциональные требования
|
||
|
||
| Параметр | Значение |
|
||
|----------|----------|
|
||
| Количество пользователей | 50–200 человек |
|
||
| Платформа | Веб-приложение, браузер (desktop-first) |
|
||
| Доступность | Внутренняя сеть клиники |
|
||
| Язык интерфейса | Русский |
|
||
| Время отклика | < 2 секунды |
|
||
|
||
---
|
||
|
||
## Вне scope (не реализуется в данной версии)
|
||
|
||
- Интеграция с AD/LDAP
|
||
- Мобильное приложение
|
||
- Вопросы с вложениями (изображения, видео)
|
||
- Экспорт отчётов в Excel / PDF
|
||
- Уведомления в MAX (отдельный спринт)
|