Job Aggregator API

FastAPI приложение для агрегации вакансий с различных платформ.

Возможности

• 🔍 Поиск вакансий через API HeadHunter
• 📊 Полный CRUD API для управления вакансиями
• 🔧 Фильтрация и сортировка вакансий
• 📊 Полный CRUD API для управления вакансиями
• 🔧 Фильтрация и сортировка вакансий
• 🗄️ PostgreSQL база данных
• 🐳 Docker контейнеризация
• 📈 Автоматическое обновление данных
• 🧪 Полное тестовое покрытие (93%)
• 🧪 Полное тестовое покрытие (93%)

Технологии

• Backend: FastAPI, Python 3.13
• База данных: PostgreSQL 15
• ORM: SQLAlchemy 2.0
• Контейнеризация: Docker, Docker Compose
• Тестирование: pytest, coverage
• Планировщик: APScheduler

Быстрый старт

1. Клонирование репозитория

git clone <repository-url>
cd job_aggregator

2. Настройка окружения (локальный запуск)

Если вы запускаете через Docker, этот шаг не нужен — контейнер сам установит зависимости из requirements.txt согласно Dockerfile.

# Создание виртуального окружения
python -m venv venv

# Активация (Windows)
.\venv\Scripts\Activate.ps1

# Активация (Linux/Mac)
source venv/bin/activate

# Установка зависимостей (только для локального запуска без Docker)
pip install -r requirements.txt

3. Запуск с Docker

При запуске в Docker не требуется локально ставить зависимости и настраивать venv — всё выполнится внутри контейнера.

# Запуск всех сервисов
docker-compose up -d

# Проверка статуса
docker-compose ps

# Остановка всех сервисов без удаления контейнеров
docker-compose stop

# Остановка всех сервисов без удаления контейнеров
docker-compose stop

4. Запуск локально

# Запуск основной базы данных
docker-compose up -d db

# Применение миграций
alembic upgrade head

# Запуск приложения
uvicorn app.main:app --reload

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

После запуска приложения документация доступна по адресам:

• Swagger UI: http://localhost:8000/api/v1/docs
• ReDoc: http://localhost:8000/api/v1/redoc
• OpenAPI: http://localhost:8000/openapi.json

Настройка расписания сбора вакансий

Общая информация

Система автоматически собирает вакансии с HH.ru по расписанию. Все настройки можно изменить через конфигурационные файлы.

Конфигурация расписания

Файл: app/services/scheduler.py

scheduler.add_job(
    job_fetch_vacancies,
    "interval",
    minutes=60,            # ← Интервал в минутах
    next_run_time=datetime.now(),
    misfire_grace_time=30, # ← Допустимое время задержки
)

Доступные интервалы:

• seconds — секунды
• minutes — минуты
• hours — часы
• days — дни

Настройка параметров поиска

Файл: app/services/hh_api.py

def fetch_vacancies(
    keyword: str = "Python",  # ← Ключевое слово
    area: int = 1002,         # ← Регион
    per_page: int = 10        # ← Количество вакансий
):

Популярные коды регионов:

• 1 — Москва
• 2 — Санкт-Петербург
• 1002 — Санкт-Петербург (альтернативный)
• Полный список регионов: https://api.hh.ru/areas

Примеры конфигураций

Частый сбор (каждые 30 минут):

minutes = 30

Сбор для другого языка/технологии:

items = fetch_vacancies("JavaScript", area=1, per_page=20)

Увеличение количества вакансий:

per_page = 50  # до 100 вакансий за запрос

Примечания

• Расписание автоматически запускается при старте приложения
• При ошибках сбора подробности логируются в лог-файл
• Рекомендуемый интервал — не менее 10 минут для соблюдения лимитов API HH.ru
• При изменении параметров требуется перезапуск приложения

API Endpoints

Вакансии

• GET /vacancies - Получить список вакансий с фильтрацией
  • Параметры: company, location, skip, limit, sort_by
• POST /vacancies - Создать новую вакансию
• PUT /vacancies/{id} - Обновить вакансию
• DELETE /vacancies/{id} - Удалить вакансию

Системные

• GET /health - Проверка состояния приложения
• GET /health/db - Проверка состояния базы данных

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

Быстрый старт

# Полный цикл (запуск БД → тесты → остановка БД) - основная команда
python scripts/test_runner.py full

# Тесты с покрытием кода (требует предварительно запущенную БД)
python scripts/test_runner.py coverage

Покрытие тестами: 93%

📖 Подробная информация о тестировании: tests/README.md

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

job_aggregator/
├── app/                    # Основное приложение
│   ├── crud/              # CRUD операции (создание, чтение, обновление, удаление)
│   ├── crud/              # CRUD операции (создание, чтение, обновление, удаление)
│   ├── models/            # SQLAlchemy модели
│   ├── routes/            # API маршруты (REST endpoints)
│   ├── schemas/           # Pydantic схемы (валидация данных)
│   ├── services/          # Бизнес-логика (HH API интеграция)
│   ├── config.py          # Конфигурация приложения
│   ├── database.py        # Настройка БД и сессий
│   ├── main.py            # Точка входа FastAPI
│   ├── scheduler.py       # Планировщик задач
│   └── exceptions.py      # Обработка ошибок
│   ├── routes/            # API маршруты (REST endpoints)
│   ├── schemas/           # Pydantic схемы (валидация данных)
│   ├── services/          # Бизнес-логика (HH API интеграция)
│   ├── config.py          # Конфигурация приложения
│   ├── database.py        # Настройка БД и сессий
│   ├── main.py            # Точка входа FastAPI
│   ├── scheduler.py       # Планировщик задач
│   └── exceptions.py      # Обработка ошибок
├── tests/                 # Тесты
│   ├── conftest.py        # Конфигурация pytest и фикстуры
│   ├── test_settings.py   # Настройки для тестовой среды
│   └── test_vacancies.py  # Тесты API (CRUD операции)
│   ├── conftest.py        # Конфигурация pytest и фикстуры
│   ├── test_settings.py   # Настройки для тестовой среды
│   └── test_vacancies.py  # Тесты API (CRUD операции)
├── scripts/               # Вспомогательные скрипты
│   ├── test_runner.py     # Автоматизированный запуск тестов
│   └── test_db.py         # Тестирование БД
├── migrations/           # Alembic миграции БД
│   ├── test_runner.py     # Автоматизированный запуск тестов
│   └── test_db.py         # Тестирование БД
├── migrations/           # Alembic миграции БД
├── docker-compose.yml    # Основные сервисы
├── docker-compose.test.yml # Тестовая БД
├── .pre-commit-config.yaml # pre-commit хуки для автоматической проверки и форматирования кода
└── requirements.txt       # Зависимости Python

Конфигурация

Переменные окружения

• POSTGRES_USER - пользователь БД
• POSTGRES_PASSWORD - пароль БД
• POSTGRES_DB - имя БД
• POSTGRES_HOST - хост БД
• POSTGRES_PORT - порт БД

Разработка

Миграции базы данных

# Создание миграции
alembic revision --autogenerate -m "description"

# Применение миграций
alembic upgrade head

# Откат миграций
alembic downgrade -1

Добавление новых тестов

📖 Подробная информация: tests/README.md

Производительность

• Покрытие тестами: 93%
• Время выполнения тестов: ~6 секунд
• API Response Time: <100ms
• Database Connection Pool: 5-20 соединений

Лицензия

MIT License