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

Проект команды «Багоделы»: веб-каталог и Telegram-бот для поиска подрядчиков по базе хакатона.

• Открыть опубликованный сайт
• Открыть Telegram-бота @hackaton_Bags_bot

Краткое описание

HackAlem помогает организаторам мероприятий и частным заказчикам найти фотографа, ведущего, площадку или другого подрядчика по городу, формату события, дате и бюджету. Пользователь задаёт условия и получает подходящие анкеты из предоставленного датасета вместо ручного просмотра всего списка.

Текущая версия выполняет фильтрацию по явным условиям и сортировку по цене. Бот возвращает до трёх анкет, а сайт позволяет просматривать все совпадения. Индивидуальные объяснения, почему каждый подрядчик подходит конкретному заказу, пока не реализованы.

Что реализовано

Telegram-бот

• Подбор в личном чате за пять шагов: город → формат → категория → дата → бюджет.
• Необязательные уточнения: длительность мероприятия и язык работы.
• Исключение анкет, занятых на выбранную дату по календарю базы.
• До трёх карточек по возрастанию начальной цены; при одинаковой цене порядок определяется ID.
• В карточке: имя, категории, город, цена «от», языки, лимит часов, описание, ID и пометки о происхождении данных.
• Возврат на предыдущий шаг, изменение даты или бюджета, новый подбор и отмена.
• Команды /start, /help, /cancel; /skip на шаге выбора длительности.
• Проверка ввода и сообщение при отсутствии совпадений.

Веб-каталог

• Фильтры по городу, формату, категории, бюджету, дате, языку и длительности.
• Текстовый поиск по имени, ID, описанию и категориям.
• Сортировка по начальной цене или имени.
• Выдача по 12 карточек с кнопкой показа следующей порции.
• Открытие полной анкеты, сброс фильтров и переход в Telegram.
• Пометки синтетических анкет, оценочных цен и городов, заполненных при подготовке базы.
• Работа непосредственно из index.html без установки Python или запуска сервера.

Как работает решение

1. Пользователь открывает бота и отправляет /start.
2. Выбирает город, формат мероприятия и категорию. В боте список категорий уже ограничен выбранными городом и форматом.
3. Вводит дату и максимальный бюджет на одного подрядчика.
4. Алгоритм оставляет анкеты нужной категории и города, которые работают с выбранным форматом, не заняты на дату и имеют начальную цену не выше бюджета.
5. Если указаны язык и длительность, применяются дополнительные ограничения. Пустой max_hours означает «лимит не применим» и не исключает анкету по длительности.
6. Совпадения сортируются по паре «цена, ID». Бот отправляет сводку запроса и первые три карточки либо сообщение об отсутствии совпадений.
7. Пользователь может уточнить условия или начать новый поиск.

На сайте фильтры применяются сразу при изменении полей. Их можно оставлять пустыми; без даты проверка занятости не выполняется. Сайт показывает все совпадения порциями, а не ограничивает результат тремя.

Описание карточки берётся из датасета. В боте оно сокращается до 320 символов; на сайте полное описание доступно в окне анкеты. Совпадение по фильтрам не подтверждает бронирование.

Технологии

• Python 3.10+ — бот, подбор, импорт, локальный сервер и подготовка сайта к публикации.
• python-telegram-bot 22.8 — обработка сообщений и состояний диалога; версия закреплена в requirements.txt.
• Telegram Bot API — получение сообщений и отправка ответов через polling. Webhook-сервер не используется.
• HTML, CSS и JavaScript без фронтенд-фреймворка — веб-каталог с фильтрацией в браузере.
• CSV и JSON — файловое хранение исходных и преобразованных анкет. Отдельной СУБД нет.
• Стандартная библиотека Python — в том числе csv, json, dataclasses, datetime, http.server, unittest и unittest.mock.
• Sites — размещение статического сайта; конфигурация сохранена в .openai/hosting.json.

AI-модели, LLM API, эмбеддинги и обучение моделей в текущем коде не используются. Подбор основан на проверке полей анкеты. Поиск по описанию на сайте — текстовый, без анализа смысла моделью.

Архитектура проекта

data/contractors.csv
        │
        ▼
import_dataset.py ── проверка структуры через matching.py
        │
        ├── catalog.json ── matching.py ── bot.py ── Telegram Bot API
        │
        └── catalog-data.js ── app.js + index.html + styles.css ── браузер

Бот и сайт используют одинаковые импортированные данные, но работают независимо. Python-алгоритм находится в matching.py, а фильтры сайта реализованы отдельно в app.js. Сайт не обращается к боту или общему серверному API подбора.

Основные файлы:

hackalem/
├── bot.py                    # Диалог и запуск Telegram-бота
├── main.py                   # Альтернативная точка запуска бота
├── matching.py               # Валидация, фильтры, сортировка, текст карточек
├── import_dataset.py         # Импорт CSV в оба каталога
├── catalog.json              # Анкеты для Python-бота
├── catalog-data.js           # Анкеты и границы календаря для браузера
├── index.html                # Страница каталога
├── app.js                    # Фильтры и взаимодействие на сайте
├── styles.css                # Оформление сайта
├── data/
│   ├── contractors.csv       # Исходный датасет
│   └── original-preview.html # Исходный HTML-обзор
├── tests/                    # Проверки данных, подбора и диалога
├── setup.bat                 # Создание .venv и установка зависимостей
├── start.bat                 # Запуск бота в Windows
├── open-site.bat             # Открытие index.html без сервера
├── preview-site.bat          # Запуск локального HTTP-предпросмотра
├── serve_site.py             # HTTP-сервер только для файлов сайта
├── build_site.py             # Подготовка файлов сайта в dist/
├── requirements.txt          # Зависимости Python
├── .env.example              # Шаблон настройки токена
└── .openai/hosting.json       # Конфигурация публикации в Sites

Состояние диалога хранится в памяти процесса бота. После его перезапуска необходимо начать подбор заново через /start.

Установка и запуск

Требования

Для просмотра сайта нужен современный браузер с JavaScript. Для бота и тестов — Python 3.10+ и pip. Для установки зависимостей и работы бота требуется интернет; для бота также нужен свой токен Telegram.

Команды ниже выполняются в PowerShell из корневой папки проекта. Сценарии .bat предназначены для Windows. Готовые каталоги включены в проект: перед первым запуском импортировать CSV не требуется.

1. Открыть сайт

Откройте index.html в браузере или выполните:

.\open-site.bat

Python, токен Telegram и установка зависимостей для этого способа не нужны.

2. Подготовить окружение бота

Установите Python 3.10+ с доступом к команде py или python, затем выполните:

.\setup.bat

Сценарий создаст .venv, установит зависимости из requirements.txt и скопирует .env.example в .env, если .env ещё не существует. В конце нажмите любую клавишу для завершения сценария.

3. Настроить токен

Откройте локальный файл .env и заполните настройку токеном своего бота:

TELEGRAM_BOT_TOKEN=ваш_токен_бота

Замените ваш_токен_бота настоящим значением. .env исключён из Git; .env.example должен оставаться пустым шаблоном. Если переменная TELEGRAM_BOT_TOKEN уже задана в окружении процесса, она имеет приоритет над .env.

4. Запустить бота

.\start.bat

Или напрямую:

.\.venv\Scripts\python.exe bot.py

Альтернативная точка входа — main.py. После подключения в терминале появится Бот подключён: @.... Откройте именно этого бота в Telegram и отправьте /start: при использовании своего токена вы запускаете своего бота, а не опубликованного @hackaton_Bags_bot.

Оставьте процесс работающим. Для остановки нажмите Ctrl+C. Не запускайте несколько копий с одним токеном. При переходе на собственного бота также обновите ссылки на Telegram в index.html.

5. При необходимости запустить локальный HTTP-предпросмотр

После подготовки .venv выполните:

.\.venv\Scripts\python.exe serve_site.py

Откройте локальный каталог. Другой способ запустить тот же сервер — preview-site.bat. Адрес доступен только на этом компьютере и пока работает процесс; для остановки используйте Ctrl+C.

Сервер отдаёт только файлы из разрешённого списка сайта. .env, исходники бота и содержимое Git через него недоступны.

Как проверить решение

Ожидаемые результаты ниже относятся к датасету, включённому в текущий репозиторий. После изменения данных результаты могут отличаться.

Быстрая проверка без Telegram

После установки зависимостей выполните:

$env:PYTHONIOENCODING = "utf-8"
.\.venv\Scripts\python.exe bot.py --demo

Команда не требует токена и подключения к Telegram. Она выполняет один фиксированный запрос: Алматы, 10.10.2026, свадьба, Фотограф, бюджет 600 000 ₸. Ожидаемый порядок:

1. HK-53108 — Альфонс Элрик, от 300 000 ₸; цена помечена как заполненная при подготовке базы.
2. HK-30583 — Леорио Паради, от 350 000 ₸.
3. HK-16628 — Нобара Кугисаки, от 600 000 ₸.

Сценарий для жюри в боте или на сайте

1. В боте отправьте /start и задайте параметры примера выше. На сайте нажмите «Сбросить», заполните те же фильтры и оставьте порядок «Сначала дешевле».
2. Проверьте три анкеты с ID из примера. В боте ID виден в карточке; на сайте — в окне «Об анкете».
3. Повторите запрос: порядок должен сохраниться.
4. Измените только дату на 11.10.2026. Ожидаются две другие анкеты: HK-68220 — Рок Ли, от 190 000 ₸; HK-76268 — Сацуки Кусакабэ, от 200 000 ₸. Так можно проверить влияние календаря.
5. Для редкой категории начните новый подбор: Алматы, 10.10.2026, свадьба, Флорист, 1 000 000 ₸. Ожидается одна анкета: HK-39372 — Тони Тони Чоппер, от 200 000 ₸.
6. Для пустого результата повторите исходный запрос с фотографами, но установите бюджет 1 ₸. Карточек быть не должно; интерфейс сообщает об отсутствии совпадений.

Дополнительно: в исходном запросе с фотографами выберите 10 часов и английский. В боте это доступно через «⚙️ Уточнить подбор», на сайте — через «Дополнительные параметры». Останется HK-16628 — Нобара Кугисаки.

Автоматические проверки

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

В текущем наборе 10 тестов. Они проверяют сохранность данных и флагов при импорте, одинаковое содержимое каталогов бота и сайта, известную выдачу, ограничения календаря, несколько категорий у анкеты, пустой лимит часов, переходы диалога, возврат назад, уточнение и отмену поиска. Отдельно проверяются команды с именем бота, пробелы в бюджете, редактированные сообщения и команды из групп.

Тесты используют подмену отправки сообщений и не обращаются к Telegram. Они не проверяют доступность опубликованного сайта, реальную доставку сообщений или время ответа через сеть.

Данные и интеграции

Источник — предоставленный датасет хакатона, сохранённый в data/contractors.csv. Обзор данных находится в data/original-preview.html.

В текущей базе:

• 66 анкет, 17 категорий; города: Алматы, Астана и значение «Зарубежье».
• 13 синтетических анкет с флагом synthetic.
• 18 анкет с ценой, заполненной при подготовке данных (price_imputed).
• 8 анкет с городом, заполненным при подготовке данных (city_imputed).
• Календарь занятости: 23.09.2026–31.12.2026 включительно.

CSV содержит ID, анонимизированное имя, категории, город, начальную цену, форматы, языки, лимит часов, занятые даты, описание и флаги происхождения данных. Поля с несколькими значениями разделены символом |. Контактов подрядчиков в базе нет.

При импорте anon_name преобразуется в name, price_from_kzt — в price_kzt, event_formats — в formats; списки и флаги приводятся к типам приложения. Отсутствующий max_hours становится null и означает, что ограничение по времени присутствия не применяется.

Обновление каталога

После изменения исходного CSV выполните:

.\.venv\Scripts\python.exe import_dataset.py

Команда проверяет структуру данных и перезаписывает catalog.json и catalog-data.js. Не редактируйте эти два файла независимо: следующий импорт заменит изменения. Затем перезапустите бота и обновите локальную страницу. Для обновления публичного сайта потребуется новая публикация.

Границы календаря заданы в matching.py; ограничения полей и поясняющие тексты также присутствуют в index.html, app.js и bot.py. При замене датасета на другой период их нужно согласованно обновить.

Внешние интеграции — Telegram Bot API для общения с ботом и Sites для размещения сайта. Синхронизации с реальными календарями, CRM или системами бронирования нет.

Ограничения текущей версии

• Нет индивидуальных объяснений рекомендаций. Карточки показывают исходное описание, но не формируют объяснение соответствия конкретному заказу.
• Нет объяснения причин выдачи менее трёх анкет. Количество показывается, но причины исключения остальных кандидатов не выводятся.
• Не различаются два вида пустого результата: отсутствие категории в городе и наличие кандидатов, не прошедших условия. В боте недоступные для города и формата категории заранее убраны из вариантов выбора.
• Сайт остаётся каталогом: он показывает все совпадения порциями по 12; ограничение до трёх действует только в боте.
• Нет смыслового ранжирования или оценки качества подрядчика. После строгих фильтров бот выбирает самые дешёвые совпадения; описание не влияет на порядок.
• Цена указана «от». Она сравнивается с бюджетом как нижняя граница; окончательная стоимость пакета не рассчитывается.
• Доступность ограничена учебным календарём. Отсутствие даты в busy_dates не подтверждает реальную свободную дату. Даты за пределами периода отклоняются; прошедшие даты внутри периода допускаются для воспроизводимого демо.
• Нет бронирования, заявок, оплаты, уведомлений подрядчику и контактов. Решение предназначено для просмотра и подбора анкет.
• Нет постоянного хранения диалогов и автоматического запуска бота на сервере. Для его работы нужен запущенный Python-процесс с интернетом; публикация сайта не запускает бота.
• Скорость ответа через Telegram не измеряется автоматическими тестами. Гарантия ответа за конкретное время не заявляется.

Опубликованная версия

Сайт: hackalem-bags-catalog.karavaevk906.chatgpt.site.

Telegram: @hackaton_Bags_bot. Доступность ответов зависит от того, запущен ли процесс бота. Для воспроизводимой проверки без него используйте сайт или bot.py --demo.

Конфигурация Sites в .openai/hosting.json указывает на каталог dist/. Подготовить файлы для размещения можно командой:

.\.venv\Scripts\python.exe build_site.py

Скрипт копирует в dist/ пять файлов: index.html, styles.css, app.js, catalog-data.js и data/original-preview.html. Токен и исходники бота в этот список не входят. Команда только подготавливает файлы: она не загружает их на хостинг. Изменения локального проекта не публикуются автоматически.