added README

2026-03-21 16:52:11 +05:00
parent 986fb00a32
commit ccec6ef950
1 changed files with 455 additions and 0 deletions
@@ -0,0 +1,455 @@
+# Система тестирования сотрудников клиники
+
+Веб-приложение для проведения внутреннего тестирования сотрудников клиники. Руководители подразделений и HR-менеджеры создают тесты и назначают их сотрудникам. Система фиксирует все попытки и результаты.
+
+**Версия ТЗ:** 1.2  
+**Дата:** 2026-03-21  
+**Статус:** Согласовано
+
+---
+
+## Содержание
+
+- [Технологический стек](#технологический-стек)
+- [Функциональные возможности](#функциональные-возможности)
+- [Роли и права доступа](#роли-и-права-доступа)
+- [База данных](#база-данных)
+- [API Endpoints](#api-endpoints)
+- [Структура проекта](#структура-проекта)
+- [Установка и запуск](#установка-и-запуск)
+- [План разработки](#план-разработки)
+
+---
+
+## Технологический стек
+
+| Компонент | Выбор |
+|-----------|-------|
+| Backend | Node.js + Express |
+| Frontend | React (SPA) |
+| Database | PostgreSQL |
+| Authentication | JWT (токен в httpOnly cookie) |
+| Password | bcrypt |
+
+---
+
+## Функциональные возможности
+
+### 4.1 Управление пользователями и подразделениями
+
+- Создание/редактирование/деактивация учётных записей сотрудников
+- Каждый сотрудник принадлежит одному подразделению
+- Создание/редактирование справочника подразделений
+- Назначение роли сотруднику: HR-менеджер / Руководитель подразделения / Сотрудник
+
+### 4.2 Создание и редактирование тестов
+
+**Тест содержит:**
+- Название теста
+- Описание (опционально)
+- Список вопросов (минимум 7)
+- Порог зачёта — минимальный % правильных ответов
+- Таймер прохождения — лимит в минутах (опционально)
+
+**Вопрос содержит:**
+- Текст вопроса
+- Минимум 3 варианта ответа
+- Один или несколько правильных ответов
+
+**Настройки теста:**
+- Разрешить возврат к предыдущему вопросу: да / нет
+
+**Версионирование:**
+- Автор может редактировать тест пока никто его не проходил
+- Если тест уже проходили — создаётся новая версия (`version + 1`), старая сохраняется
+- Все версии теста хранятся; результаты привязаны к конкретной версии
+- Активная версия — та, которую видят сотрудники; автор может вручную переключить активную версию
+- Тест можно деактивировать (скрыть из списка, не удалять)
+
+### 4.3 Назначение теста
+
+- Список получателей (отдел или конкретные сотрудники)
+- Срок сдачи — дата дедлайна
+- Допустимое количество попыток (1 или более)
+
+### 4.4 Прохождение теста
+
+- На главной странице сотрудник видит список назначенных тестов со статусами:
+  - `Не начат` — ещё не открывал
+  - `В процессе` — начал, не завершил
+  - `Завершён` — сдал/не сдал
+  - `Просрочен` — дедлайн прошёл, не сдан
+- Если задан таймер — отображается обратный отсчёт, по истечении тест завершается автоматически
+- Порядок вопросов **случайный** при каждом прохождении
+- Возможность вернуться к предыдущему вопросу — определяется настройкой теста
+
+### 4.5 Результаты после завершения теста
+
+- Итоговый балл и процент правильных ответов
+- Факт зачёта: **сдал / не сдал**
+- Разбор ошибок: по каждому вопросу — его ответ и правильный ответ
+
+### 4.6 Трекер попыток
+
+Единый интерфейс просмотра всех попыток прохождения тестов:
+- Фильтрация по подразделению, сотруднику, тесту, статусу, результату
+- Пагинация и сортировка
+
+### 4.7 AI-помощник (DeepSeek)
+
+Интеграция с LLM DeepSeek для помощи при создании тестов:
+
+| Функция | Описание |
+|---------|----------|
+| Генерация теста | AI генерирует готовый набор вопросов с вариантами ответов по теме |
+| Улучшение формулировки | AI переформулирует выбранный вопрос более чётко |
+| Добавление дистракторов | AI генерирует правдоподобные неправильные варианты ответов |
+| Проверка качества | AI анализирует весь тест и выдаёт рекомендации |
+
+---
+
+## Роли и права доступа
+
+| Роль | Кто | Создаёт тесты | Назначает тесты | Видит результаты |
+|------|-----|:---:|:---:|:---:|
+| **HR-менеджер** | Руководитель службы HR, Директор клиники | ✅ | Всем сотрудникам клиники | Всех сотрудников |
+| **Руководитель подразделения** | Главный врач, рук. службы администраторов | ✅ | Только своему подразделению | Только своего подразделения |
+| **Сотрудник** | Все остальные работники | ❌ | ❌ | Только свои |
+
+---
+
+## База данных
+
+### Схема таблиц
+
+#### `departments` — Подразделения
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| name | VARCHAR(255) | Название подразделения |
+| created_at | TIMESTAMP | Дата создания |
+| updated_at | TIMESTAMP | Дата обновления |
+
+#### `users` — Пользователи
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| login | VARCHAR(100) | Уникальный логин |
+| password_hash | VARCHAR(255) | Хеш пароля |
+| full_name | VARCHAR(255) | ФИО |
+| role | ENUM | 'hr', 'manager', 'employee' |
+| department_id | UUID | FK -> departments |
+| is_active | BOOLEAN | Активна ли учётная запись |
+| created_at | TIMESTAMP | Дата создания |
+| updated_at | TIMESTAMP | Дата обновления |
+
+#### `tests` — Тесты
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| title | VARCHAR(255) | Название теста |
+| description | TEXT | Описание (опционально) |
+| passing_threshold | INTEGER | Порог зачёта (%) |
+| time_limit | INTEGER | Таймер в минутах (nullable) |
+| allow_back | BOOLEAN | Возврат к предыдущему |
+| is_active | BOOLEAN | Активен |
+| is_versioned | BOOLEAN | Есть версии |
+| created_by | UUID | FK -> users |
+| created_at | TIMESTAMP | Дата создания |
+| updated_at | TIMESTAMP | Дата обновления |
+
+#### `test_versions` — Версии тестов
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| test_id | UUID | FK -> tests |
+| version | INTEGER | Номер версии |
+| is_active | BOOLEAN | Активная версия |
+| created_at | TIMESTAMP | Дата создания |
+
+#### `questions` — Вопросы
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| test_version_id | UUID | FK -> test_versions |
+| text | TEXT | Текст вопроса |
+| question_order | INTEGER | Порядок вопроса |
+| has_multiple_answers | BOOLEAN | Несколько правильных |
+
+#### `answer_options` — Варианты ответов
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| question_id | UUID | FK -> questions |
+| text | TEXT | Текст варианта |
+| is_correct | BOOLEAN | Правильный ответ |
+| option_order | INTEGER | Порядок варианта |
+
+#### `test_assignments` — Назначения тестов
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| test_version_id | UUID | FK -> test_versions |
+| assigned_by | UUID | FK -> users |
+| deadline | DATE | Срок сдачи |
+| max_attempts | INTEGER | Допустимое число попыток |
+| created_at | TIMESTAMP | Дата назначения |
+
+#### `test_assignment_targets` — Получатели назначений
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| assignment_id | UUID | FK -> test_assignments |
+| target_type | ENUM | 'department', 'user' |
+| target_id | UUID | FK (department или user) |
+
+#### `test_attempts` — Попытки прохождения
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| test_version_id | UUID | FK -> test_versions |
+| user_id | UUID | FK -> users |
+| attempt_number | INTEGER | Номер попытки |
+| status | ENUM | 'in_progress', 'completed', 'expired' |
+| started_at | TIMESTAMP | Начало |
+| completed_at | TIMESTAMP | Завершение |
+| correct_count | INTEGER | Правильных ответов |
+| total_questions | INTEGER | Всего вопросов |
+| passed | BOOLEAN | Зачёт |
+
+#### `user_answers` — Ответы пользователя
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| id | UUID | PK |
+| attempt_id | UUID | FK -> test_attempts |
+| question_id | UUID | FK -> questions |
+| selected_options | UUID[] | Выбранные варианты |
+
+#### `settings` — Настройки
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| key | VARCHAR(100) | PK |
+| value | TEXT | Значение |
+
+---
+
+## API Endpoints
+
+### Аутентификация
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| POST | `/api/auth/login` | Вход в систему |
+| POST | `/api/auth/logout` | Выход из системы |
+
+### Подразделения
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/api/departments` | Список подразделений |
+| POST | `/api/departments` | Создать подразделение |
+| PUT | `/api/departments/:id` | Редактировать |
+| DELETE | `/api/departments/:id` | Деактивировать |
+
+### Пользователи
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/api/users` | Список сотрудников |
+| POST | `/api/users` | Создать сотрудника |
+| GET | `/api/users/:id` | Карточка сотрудника |
+| PUT | `/api/users/:id` | Редактировать |
+| DELETE | `/api/users/:id` | Деактивировать |
+
+### Тесты
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/api/tests` | Список тестов |
+| POST | `/api/tests` | Создать тест |
+| GET | `/api/tests/:id` | Тест с вопросами |
+| PUT | `/api/tests/:id` | Редактировать |
+| DELETE | `/api/tests/:id` | Деактивировать |
+
+### Назначения тестов
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/api/assignments` | Список назначений |
+| POST | `/api/assignments` | Назначить тест |
+| GET | `/api/assignments/:id` | Детали назначения |
+| PUT | `/api/assignments/:id` | Редактировать |
+| DELETE | `/api/assignments/:id` | Удалить |
+| GET | `/api/my-assignments` | Назначенные тесты (для сотрудника) |
+
+### Прохождение теста
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| POST | `/api/attempts/start` | Начать попытку |
+| GET | `/api/attempts/:id` | Получить вопросы |
+| POST | `/api/attempts/:id/answers` | Отправить ответ |
+| GET | `/api/attempts/:id/answers` | Получить текущий прогресс |
+| POST | `/api/attempts/:id/complete` | Завершить тест |
+
+### Результаты
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/api/attempts/:id/result` | Получить результат |
+| GET | `/api/attempts/:id/review` | Получить разбор |
+
+### Трекер попыток
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/api/tracker` | Список всех попыток |
+
+### AI-помощник
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| POST | `/api/ai/generate-test` | Сгенерировать тест |
+| POST | `/api/ai/improve-question` | Улучшить вопрос |
+| POST | `/api/ai/add-distractors` | Добавить неправильные варианты |
+| POST | `/api/ai/check-quality` | Проверить качество теста |
+
+### Настройки
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/api/settings` | Получить настройки |
+| PUT | `/api/settings` | Обновить настройки |
+| POST | `/api/settings/test-connection` | Проверить подключение к DeepSeek |
+
+---
+
+## Структура проекта
+
+```
+TestingWebApp/
+├── docs/                    # Документация
+│   ├── ТЗ.md               # Техническое задание
+│   └── шаги/               # План разработки (11 шагов)
+├── backend/                 # Node.js + Express
+│   ├── src/
+│   │   ├── index.js       # Точка входа
+│   │   ├── db/            # Работа с БД
+│   │   │   ├── db.js      # Подключение к PostgreSQL
+│   │   │   ├── migrate.js # Миграции
+│   │   │   └── migrations/
+│   │   │       └── 001_initial.sql
+│   │   ├── routes/        # API роуты
+│   │   │   └── auth.js
+│   │   ├── middleware/    # Промежуточное ПО
+│   │   │   └── auth.js
+│   │   └── utils/         # Утилиты
+│   │       └── auth.js
+│   └── package.json
+├── frontend/               # React SPA
+│   ├── src/
+│   │   ├── main.jsx      # Точка входа
+│   │   └── App.jsx       # Главный компонент
+│   ├── index.html
+│   ├── vite.config.js
+│   └── package.json
+├── docker-compose.yml     # PostgreSQL
+└── README.md              # Этот файл
+```
+
+---
+
+## Установка и запуск
+
+### Требования
+
+- Node.js 18+
+- PostgreSQL 14+
+- Docker (для PostgreSQL)
+
+### Шаги
+
+1. **Клонировать репозиторий**
+
+2. **Настроить окружение**
+
+   Создать файл `backend/.env`:
+   ```env
+   DATABASE_URL=postgresql://user:password@localhost:5432/clinic_tests
+   JWT_SECRET=your-secret-key
+   PORT=3000
+   ```
+
+3. **Запустить PostgreSQL**
+   ```bash
+   docker-compose up -d
+   ```
+
+4. **Установить зависимости и запустить backend**
+   ```bash
+   cd backend
+   npm install
+   npm run dev
+   ```
+
+5. **Запустить frontend**
+   ```bash
+   cd frontend
+   npm install
+   npm run dev
+   ```
+
+6. **Открыть приложение**
+   - Frontend: http://localhost:5173
+   - Backend API: http://localhost:3000
+
+---
+
+## План разработки
+
+| Шаг | Название | Описание |
+|-----|----------|----------|
+| 1 | Проект и инфраструктура | Структура проекта, Docker, настройка окружения |
+| 2 | Проектирование БД | Создание всех таблиц и миграций |
+| 3 | Аутентификация и авторизация | JWT, login/logout, RBAC |
+| 4 | Управление пользователями | CRUD сотрудников и подразделений |
+| 5 | Управление тестами | Создание, редактирование, версионирование |
+| 6 | Назначение тестов | Выбор получателей, дедлайн, лимит попыток |
+| 7 | Интерфейс прохождения | Прохождение с таймером, случайный порядок вопросов |
+| 8 | Результаты и разбор | Итоговый балл, разбор ошибок |
+| 9 | Трекер попыток | Единый интерфейс просмотра попыток |
+| 10 | AI-помощник | Интеграция с DeepSeek |
+| 11 | Страница настроек | Управление API ключами |
+
+---
+
+## Нефункциональные требования
+
+| Параметр | Значение |
+|----------|----------|
+| Количество пользователей | 50–200 человек |
+| Платформа | Веб-приложение, браузер (desktop-first) |
+| Доступность | Внутренняя сеть клиники |
+| Язык интерфейса | Русский |
+| Время отклика | < 2 секунды |
+
+---
+
+## Вне scope (не реализуется в данной версии)
+
+- Интеграция с AD/LDAP
+- Мобильное приложение
+- Вопросы с вложениями (изображения, видео)
+- Экспорт отчётов в Excel / PDF
+- Уведомления в MAX (отдельный спринт)