Rio — умный подбор подрядчиков

Рабочее решение HackAlem AI, кейс #79-lite. Для заказчика мероприятия в Казахстане Rio сокращает каталог до трёх подходящих подрядчиков и объясняет выбор условиями запроса и цитатами из профилей. Поддерживаются люди, коллективы и площадки.

Цель и решаемая задача

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

Продукт помогает:

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

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

• Город, дата, формат, категория и бюджет; необязательные язык, длительность и пожелания.
• Строгая проверка занятости, бюджета, формата, языка и часов.
• До трёх карточек с ценой, конкретными причинами, цитатой и полным описанием.
• Стабильное текстовое ранжирование, затем цена и ID.
• Три отдельных исхода: подобрали; категории в городе нет; кандидаты не проходят условия.
• Объяснение короткой выдачи, причины исключения каждого кандидата и сравнение двух дат.
• Пометки синтетических профилей и проставленных при подготовке цен и городов.
• Шесть демонстрационных сценариев и адаптивный русский интерфейс.
• SQLite-каталог, портфолио подрядчиков и клиентские оценки работ.
• Светлый фирменный стиль Rio, интерактивные 3D-карточки, favicon и метаданные для поисковой выдачи и превью ссылок.

Публичная демонстрация

Открыть Rio

Параметр	Значение
URL	rio-hackalem-podium.vercel.app
Окружение	Vercel Production
Статус	READY
Стек	Static HTML/CSS/JS + Python Functions

Проверено

• главная страница и API работают;
• поиск возвращает до трёх подходящих подрядчиков;
• первое место отображается по центру золотой карточкой;
• второе место — серебряной карточкой справа;
• третье место — бронзовой карточкой слева;
• портфолио и рейтинги отображаются;
• мобильная версия адаптирована;
• 17 автоматических тестов успешно пройдены;
• ошибок в консоли браузера нет.

Production deployment

Параметр	Значение
URL	rio-hackalem-podium.vercel.app
Окружение	Vercel Production
Статус	READY
Стек	Static HTML/CSS/JS + Python Functions

Контрольная проверка production от 23 сентября 2026:

• главная страница, favicon и description-метаданные загружаются;
• /api/v1/health возвращает 200, database: ok, 200 подрядчиков и схему 002_portfolio_and_ratings.sql;
• все шесть демонстрационных запросов возвращают ожидаемые состояния, не более трёх карточек и объяснение каждого результата;
• смена даты заменяет всю предыдущую тройку и показывает причину изменения;
• состояния no_match и no_category отображаются раздельно и предлагают релевантный следующий шаг;
• оценка 1★–5★ сохраняется через API и мгновенно обновляет рейтинг карточки; повторная оценка того же клиента меняет голос без увеличения счётчика;
• при ширине 390 px горизонтальной прокрутки нет: форма, сценарии и колода карточек помещаются в viewport;
• ошибок и предупреждений в консоли браузера не обнаружено.

Сценарий пользователя

Укажите параметры события и нажмите «Подобрать подрядчиков». Сервис проверит обязательные условия и покажет до трёх карточек. Цитаты помогают увидеть отличия; раскрывающиеся секции показывают исходное описание и причины исключения альтернатив. Для сравнения дат измените только дату и повторите запрос: интерфейс объяснит, кто из прежней тройки теперь занят.

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

1. Откройте production-сайт и дождитесь автоматической загрузки первого сценария.
2. Убедитесь, что показаны три карточки с ценой, доступностью, объяснением и портфолио.
3. Выберите «02 · Другая дата» и проверьте, что состав тройки меняется, а интерфейс объясняет замену.
4. Выберите «04 · Бюджет не проходит» и проверьте состояние no_match с причинами исключения.
5. Выберите «05 · Нет категории» и проверьте отдельное состояние no_category.
6. Поставьте оценку 1★–5★ демонстрационной работе и убедитесь, что рейтинг обновился сразу.
7. Откройте сайт на телефоне или уменьшите окно до 390 px: форма, сценарии и карточки должны помещаться без горизонтальной прокрутки.
8. Для полной локальной проверки запустите python -m unittest discover -s tests -v и python tools/audit_data.py --include-synthetic --markdown.

Все ручные запросы доступны кнопками над результатами:

Сценарий	Параметры	Ожидаемое поведение
01 · Осенний корпоратив	Алматы, ведущий, корпоратив, 04.10.2026, 1 500 000 ₸, 4 ч, русский; пожелания «интеллигентный юмор импровизация»	4 подходящих профиля, показаны 3; ранжирование реально выбирает из большего пула
02 · Другая дата	Тот же запрос, 01.10.2026	Прошлая тройка занята; выдача меняется, причины видны над карточками
03 · Редкая категория	Алматы, флорист, свадьба, 02.10.2026, 500 000 ₸, 8 ч	1 карточка с объяснением, почему меньше трёх; max_hours=null не исключает флориста
04 · Бюджет не проходит	Запрос 01, бюджет 10 000 ₸	Кандидаты есть, но подходящих нет; перечислены причины
05 · Нет категории	Зарубежье, флорист	Отдельное состояние отсутствующей категории
06 · Банкетный зал	Алматы, корпоратив, 14.11.2026, 7 000 000 ₸	Площадки проходят тот же календарь и фильтры

Повторите запрос — порядок не изменится. Сравнение дат использует предыдущий успешный запрос с теми же остальными параметрами.

Технологии и архитектура

Backend: Python и стандартная библиотека (http.server, sqlite3, csv, json, unittest). Frontend: HTML, CSS, JavaScript без сборщика. Данные: CSV как seed-источник и SQLite во время работы. Подбор выполняется локально прозрачным детерминированным алгоритмом.

Браузер → POST /api/v1/recommendations → валидация
        → выбор города/категории → жёсткие фильтры
        → лексическое ранжирование → top-3 + факты + портфолио + аудит

Компонент	Назначение
app.py	Точка запуска HTTP-сервера и обратная совместимость API
back/	SQLite, репозиторий, REST API, фильтры, ранжирование, портфолио и оценки
web/	Форма, 3D-карточки, портфолио, рейтинги и адаптивный дизайн
data/contractors.csv	Runtime-каталог на 200 профилей и 30 категорий; исходные 66 сохранены
data/contractors.xlsx	Excel-копия расширенного каталога с фильтрами и закреплённой строкой
data/synthetic_profiles.csv	Отдельный аудит-артефакт с 12 профилями команды, не добавляемый повторно в runtime
tests/test_app.py	Исходный алгоритм подбора, правила фильтрации, детерминизм и демосценарии
tests/test_backend.py	SQLite, портфолио, оценки и HTTP-контракты API v1
docs/	Исходное задание, превью, инструкция, речь и текст для сдачи
start.ps1	Запуск на Windows

Как принимается решение

1. Проверяются обязательные поля, положительные бюджет и часы, известные форматы/языки и календарная дата. Вне 23.09–31.12.2026 запрос отклоняется: отсутствие данных нельзя считать свободным днём.
2. Выбирается пул по точному городу и наличию категории в массиве. Упоминание поездок в описании не расширяет географию автоматически.
3. Исключаются занятые, превышающие бюджет по цене «от», не берущие формат, не поддерживающие указанный язык или часы. max_hours=null означает отсутствие привязки к присутствию. Все заданные условия применяются последовательно.
4. Пожелания разбиваются на слова; ё заменяется на е, короткие и служебные слова удаляются. Первые 6 букв используются для приблизительного сопоставления форм. Балл — сумма ln(1 + N/(1 + df)) по уникальным совпавшим основам, где N — размер загруженного каталога, df — число описаний с основой. Редкие совпадения весят больше. Затем меньшая цена, затем строковый ID. Суммирование идёт в отсортированном порядке. Случайности нет.
5. Первое предложение объяснения перечисляет выполненные условия. Затем идёт точная цитата из описания с наибольшим количеством текстовых совпадений, до 240 символов. Полный источник можно раскрыть.
6. Возвращаются карточки и аудит исключений. Счётчики причин могут пересекаться: один профиль может одновременно быть занят и превышать бюджет.

Ранжирование детерминировано и проверяемо: пожелания используются как мягкий лексический сигнал, а в деталях карточки доступны численный балл и совпавшие основы слов.

API

GET /api/v1/meta — варианты полей, статистика, границы календаря и готовые запросы.

POST /api/v1/recommendations, Content-Type: application/json:

{
  "city": "Алматы",
  "date": "2026-10-04",
  "event_format": "корпоратив",
  "category": "Ведущий",
  "budget": 1500000,
  "hours": 4,
  "language": "русский",
  "preferences": "интеллигентный юмор импровизация"
}

Ответ: status (matched, no_category, no_match), message, cards (0–3), pool_count, eligible_count, rejected, exclusion_counts, elapsed_ms. Ошибка входных данных — HTTP 400 с error. Пустая выдача — штатный HTTP 200. Время измеряет серверный подбор, не сетевую задержку.

Полный контракт API, включая каталог, карточки подрядчиков, календарь, портфолио, оценки и OpenAPI, описан в docs/backend-api.ru.md.

В runtime-каталоге 200 профилей по 30 категориям, включая 147 синтетических. Исходные 66 записей сохранены без изменений; ещё 134 демонстрационные записи добавляют 13 категорий. Синтетические записи имеют synthetic=True, а подготовленные цены — price_imputed=True. Отдельный файл data/synthetic_profiles.csv сохраняется для аудита и не добавляется повторно.

Данные, источники и внешние сервисы

В исходном CSV и HTML-превью — 66 профилей организаторов. Расширенный runtime-каталог находится в data/contractors.csv; его локальная Excel-копия — в data/contractors.xlsx.

• Задание
• CSV
• HTML-превью
• Инструкция участникам

Подбор полностью локальный и не требует API-ключей. Для фирменной типографики браузер загружает Manrope через Google Fonts, а системный шрифт используется как автоматический fallback.

Проверки

Всего 17 автоматических тестов:

• 10 тестов исходного алгоритма: целостность датасета; 100 дней × 30 категорий; детерминизм; три состояния ответа; смена даты; граничный бюджет; null-часы; дополнительные фильтры; неверные запросы; достоверность объяснений и быстродействие;
• 7 backend-тестов: миграции и идемпотентный импорт SQLite; фильтры и календарь; сохранность портфолио при синхронизации; обновление оценки без дубля; рейтинг работ; HTTP-контракты; OpenAPI и обработка ошибок.

Контрольный запуск 23 сентября 2026: 17/17 тестов прошли со статусом OK примерно за 1,1 с. Аудит данных также завершился со статусом PASS: 212 проверенных записей с учётом отдельного synthetic-файла, 30 категорий, 8 008 записей занятости, ошибок нет. Production API обработал шесть демосценариев за 0,10–2,78 мс серверного времени.

Персональные чек-листы команды

Участник	Зона ответственности	Чек-лист
Темирлан Досмухамбетов	Frontend, адаптивный интерфейс, 3D-карточки, портфолио и пользовательские сценарии	README Темирлана
Мирас Ринатулы	SQLite-бэкенд, API v1, фильтрация, ранжирование, портфолио и оценки	README Мираса
Айназ Абитай	Данные, аудит, тестовые сценарии, документация и воспроизводимость	README Айназ

Дополнительные рабочие чек-листы: frontend, backend, данные и аудит.

Сдача на платформе

Инструкция требует разместить итоговый код в выданном командном GitHub-репозитории, затем выбрать кейс и нажать «Сдать решение». Готовые название и описание находятся в docs/submission.md. Публичный deployment не обязателен; ссылку на него указывают, только если он существует. Активация сторонних API не нужна текущей реализации и не выполняется проектом.

Англоязычная техническая спецификация: Rio Technical Specification.