docs folder with steps

docs/ТЗ.md

@@ -0,0 +1,163 @@
+# Техническое задание
+## Система тестирования сотрудников клиники
+
+**Версия:** 1.2
+**Дата:** 2026-03-21
+**Статус:** Согласовано
+
+---
+
+## 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