Employee Task Tracker

---

Серверное приложение для отслеживания задач сотрудников, реализованное на Django и Django REST Framework. Приложение предоставляет REST API для CRUD-операций с сущностями "Сотрудник" и "Задача", а также включает специальные эндпоинты для анализа загруженности персонала и выявления критически важных задач.

Ключевые возможности

• Управление сотрудниками: Полный набор CRUD-операций для сущности "Сотрудник".
• Управление задачами: Полный набор CRUD-операций для сущности "Задача" с поддержкой иерархической структуры (родительские/дочерние задачи).
• Анализ загруженности: Специализированный эндпоинт для получения списка сотрудников, отсортированного по количеству активных задач.
• Выявление важных задач: Эндпоинт, реализующий бизнес-логику для поиска незаблокированных задач, от которых зависят другие, и подбора оптимальных исполнителей.
• Контейнеризация: Полная поддержка Docker и Docker Compose для быстрой и изолированной установки и развертывания.
• Автодокументация API: Интерактивная документация API, сгенерированная с использованием OpenAPI 3 (Swagger).

Стек технологий

• Бэкенд: Python 3.11, Django 5.2, Django REST Framework
• База данных: PostgreSQL 16
• Управление зависимостями: Poetry
• Контейнеризация: Docker, Docker Compose
• Тестирование: Pytest, pytest-django, pytest-cov
• Качество кода: Flake8, Black, isort
• Документация API: drf-spectacular

Структура проекта

.
├── config/             # Настройки проекта Django
├── employees/          # Приложение для управления сотрудниками
├── tasks/              # Приложение для управления задачами
├── static/             # Пустая директория для статических файлов
├── .dockerignore       # Файлы, игнорируемые Docker
├── .env.example        # Шаблон файла с переменными окружения
├── .gitignore
├── Dockerfile          # Инструкция по сборке Docker-образа приложения
├── docker-compose.yml  # Файл для оркестрации контейнеров
├── manage.py           # Утилита управления Django
├── poetry.lock         # Файл с зафиксированными версиями зависимостей
├── pyproject.toml      # Файл с описанием проекта и зависимостей
└── README.md           # Этот файл

Установка и запуск с помощью Docker

Это основной и рекомендуемый способ запуска проекта.

Предварительные требования

• Установленный Docker
• Установленный Docker Compose (обычно поставляется вместе с Docker)

Порядок действий

1. Клонируйте репозиторий:

   git clone https://github.com/MaxBarulin/employee_task_tracker.git
   cd employee_task_tracker

2. Создайте файл .env: В корневой директории проекта создайте файл .env на основе шаблона .env.example или скопируйте содержимое ниже. Этот файл содержит переменные окружения, необходимые для работы приложения.

   # Настройки базы данных PostgreSQL
   POSTGRES_DB=ett
   POSTGRES_USER=user
   POSTGRES_PASSWORD=password
   POSTGRES_HOST=db
   POSTGRES_PORT=5432
   
   # Ключ Django (для продакшена должен быть сгенерирован заново)
   SECRET_KEY=django-insecure-your-secret-key
   
   # Режим отладки (False для продакшена)
   DEBUG=True

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

   docker-compose up --build -d

4. Примените миграции базы данных: Дождитесь запуска контейнеров (10-15 секунд), после чего выполните команду для создания таблиц в базе данных.

   docker-compose exec web python manage.py migrate

5. (Опционально) Создайте суперпользователя: Для доступа к административной панели Django (/admin/) создайте суперпользователя.

   docker-compose exec web python manage.py createsuperuser

Приложение будет доступно по адресу http://127.0.0.1:8000.

Тестирование

Тесты написаны с использованием pytest и могут быть запущены как локально, так и внутри Docker-контейнера.

Запуск тестов (локально)

Для локального запуска используется база данных SQLite, что не требует запущенного PostgreSQL.

1. Установите dev-зависимости:

   poetry install --with dev

2. Запустите тесты:

   poetry run pytest

3. Запустите тесты с отчетом о покрытии:

   • В консоли:

     poetry run pytest --cov=.

   • С генерацией HTML-отчета (результат будет в папке htmlcov/):

     poetry run pytest --cov=. --cov-report=html

Запуск тестов (в Docker)

Этот способ гарантирует запуск тестов в окружении, идентичном продакшену.

# Убедитесь, что контейнеры запущены
docker-compose exec web pytest

Качество кода (Линтинг)

Для проверки стиля и качества кода используются isort, black и flake8.

# Автоматическая сортировка импортов
poetry run isort .

# Автоматическое форматирование кода
poetry run black .

# Проверка на соответствие стандартам PEP8
poetry run flake8 .

Документация API

Проект использует drf-spectacular для автоматической генерации документации OpenAPI 3. Интерактивный интерфейс Swagger UI доступен после запуска проекта.

• Swagger UI: http://127.0.0.1:8000/api/docs/
• Файл схемы OpenAPI: http://127.0.0.1:8000/api/schema/

Описание API эндпоинтов

Базовый URL для всех запросов: /api/v1/

Сотрудники (/employees/)

• GET /employees/

  • Описание: Получение списка всех сотрудников.
  • Ответ: 200 OK

• POST /employees/

  • Описание: Создание нового сотрудника.
  • Тело запроса: { "full_name": "string", "position": "string" }
  • Ответ: 201 CREATED

• GET /employees/{id}/

  • Описание: Получение детальной информации о сотруднике.
  • Ответ: 200 OK

• PUT /employees/{id}/, PATCH /employees/{id}/

  • Описание: Полное или частичное обновление данных сотрудника.
  • Ответ: 200 OK

• DELETE /employees/{id}/

  • Описание: Удаление сотрудника.
  • Ответ: 204 No Content

Задачи (/tasks/)

• GET /tasks/

  • Описание: Получение списка всех задач.
  • Ответ: 200 OK

• POST /tasks/

  • Описание: Создание новой задачи.
  • Тело запроса: { "name": "string", "parent": integer | null, "assignee": integer | null, "status": "string", "deadline": "YYYY-MM-DD" }
  • Ответ: 201 CREATED

• GET /tasks/{id}/, PUT /tasks/{id}/, DELETE /tasks/{id}/

  • Аналогично эндпоинтам для сотрудников.

Специальные эндпоинты

• GET /employees/busy-employees/

  • Описание: Возвращает список сотрудников, отсортированный по убыванию количества их активных задач (статус "В работе"). Включает полный список задач для каждого сотрудника.
  • Ответ: 200 OK

    [
        {
            "id": 1,
            "full_name": "Петров Петр",
            "position": "Тестировщик",
            "tasks": [
                { "id": 10, "name": "Задача 1", ... },
                { "id": 12, "name": "Задача 2", ... }
            ]
        },
        {
            "id": 2,
            "full_name": "Иванов Иван",
            "position": "Разработчик",
            "tasks": []
        }
    ]

• GET /tasks/important-tasks/

  • Описание: Реализует сложную бизнес-логику для поиска "важных" задач. Важной считается задача, которая не взята в работу (todo), но от которой зависит как минимум одна другая задача, находящаяся в работе (in_progress). Для каждой такой задачи эндпоинт предлагает список подходящих исполнителей.
  • Критерии подбора исполнителей:
    1. Наименее загруженный сотрудник в компании (по количеству активных задач).
    2. Сотрудник, выполняющий дочернюю задачу, если его текущая нагрузка не более чем на 2 активные задачи превышает нагрузку наименее загруженного сотрудника.
  • Ответ: 200 OK

    [
        {
            "task_name": "Настроить CI/CD",
            "deadline": "2025-12-31",
            "suitable_employees": [
                "Иванов Иван",
                "Петров Петр"
            ]
        }
    ]