HackAlem — подбор подрядчиков для мероприятий

Сервис помогает найти подрядчиков по городу, категории, дате мероприятия, формату и бюджету. Бэкенд проверяет анкеты, исключает занятых и неподходящих по условиям исполнителей и возвращает до трёх рекомендаций. В проекте есть веб-интерфейс на React и API на FastAPI.

Каталог содержит 66 подготовленных профилей. Подбор детерминированный: одинаковый запрос при тех же данных даёт одинаковый результат. Внешние AI-сервисы не используются. Это демонстрационный проект: он не отправляет заявки и не оформляет бронирования.

Что нужно установить

• Python 3.10 или новее
• Node.js 22.22 или новее для фронтенда и его тестов

Запуск всего приложения в Windows

Откройте два окна PowerShell в корневой папке проекта.

В первом окне установите зависимости и запустите API:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn app:app --reload

Во втором окне установите зависимости фронтенда и запустите сайт:

cd frontend
npm ci
npm run dev

Откройте адрес, который Vite покажет в терминале (обычно http://localhost:5173). В режиме разработки фронтенд направляет запросы /api/* в API на http://127.0.0.1:8000; отдельная настройка CORS не нужна.

Оба сервера должны оставаться запущенными, пока вы пользуетесь сайтом. Остановить каждый можно сочетанием Ctrl+C в соответствующем окне.

Запуск в macOS и Linux

В первом терминале из корня проекта:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m uvicorn app:app --reload

Во втором терминале:

cd frontend
npm ci
npm run dev

API

Интерактивная документация FastAPI доступна по адресу http://127.0.0.1:8000/docs. Основные маршруты:

• GET /health — проверяет, что API запущен, и возвращает количество загруженных профилей.
• POST /match — подбирает подрядчиков.

Пример тела запроса к POST /match:

{
  "city": "Алматы",
  "event_date": "2026-10-17",
  "event_format": "свадьба",
  "category": "Ведущий",
  "budget_kzt": 1000000,
  "duration_hours": 5,
  "language": "русский"
}

Поля city, event_date, event_format, category и budget_kzt обязательны. duration_hours и language можно не указывать. Названия города, категории и формата должны соответствовать значениям в каталоге. Допустимый диапазон дат по умолчанию: 23 сентября — 31 декабря 2026 года включительно. Неверный запрос получает HTTP 422.

API возвращает статус (matched, no_category_in_city или no_matches), число подходящих профилей, причины исключения кандидатов и до трёх рекомендаций. price_from_kzt — цена «от», а не итоговая смета. Флаги synthetic, city_imputed и price_imputed отмечают синтетические или дополненные данные.

Проверки

Backend-тесты из корневой папки:

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Для macOS/Linux замените путь к Python на .venv/bin/python.

Frontend-тесты и production-сборка из папки frontend:

npm run check

Команда проверяет TypeScript, запускает тесты и собирает production-версию.

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

Путь	Назначение
app.py	FastAPI-маршруты /health и /match
matching.py	Валидация запроса, фильтрация и ранжирование профилей
profiles.json	Каталог из 66 подготовленных профилей для бэкенда
prepare_profiles.py	Подготовка каталога из исходного CSV
data/hackathon_dataset_anonymized.csv	Исходный анонимизированный набор данных
frontend/	React-интерфейс и HTTP-адаптер к API
tests/	Backend-тесты

Для локального предварительного просмотра UI предусмотрена страница /preview. Она доступна при запуске Vite в режиме разработки и использует фиксированные демонстрационные сценарии.