EventMatch

EventMatch — рабочее MVP для кейса «Умный подбор подрядчиков (#79-lite)». Оно выбирает до трёх подрядчиков из переданного каталога и объясняет каждый результат конкретными, проверяемыми фактами. Интерфейс и документация русскоязычные.

Публичное демо: eventmatch-hackalem.vercel.app

1. Что решает EventMatch и для кого

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

2. Соответствие кейсу #79-lite

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

3. Что реализовано сейчас

• Next.js App Router и строгий TypeScript;
• проверенный CSV-импорт, Zod-контракты и диагностические ошибки;
• детерминированные фильтры, сортировка и три доменных исхода;
• программные evidence и серверная сборка объяснений;
• один серверный OpenAI Agent с тремя read-only инструментами и структурированным ответом;
• fallback без ключа, общий AI-timeout 7 секунд, ограниченный LRU-кеш, лимит двух одновременных AI-вызовов;
• лимит 30 HTTP-запросов в минуту на IP в памяти процесса и предел тела 8 KiB;
• адаптивный экран подбора с формой на первом экране, горизонтальным выбором категории, раскрываемыми дополнительными условиями, сценариями A–H и диагностикой;
• карточки показывают две проверяемые причины «Почему подходит» и статус даты; происхождение профиля и дополненные цену или город отмечают отдельные метки;
• Vitest, Playwright и GitHub Actions CI.

4. Что не входит в проект

Бронирование, оплата, заявки, уведомления, личные кабинеты, внешний поиск, обучение модели, рейтинги и отзывы не реализованы. Фотографии подрядчиков не используются; изображение на первом экране — оригинальная демонстрационная иллюстрация атмосферы мероприятия. AI не определяет допустимость и не ранжирует профили.

5. Быстрый запуск из чистого клона

PowerShell (Windows):

npm ci
Copy-Item .env.example .env.local
npm run dev

macOS/Linux:

npm ci
cp .env.example .env.local
npm run dev

Откройте http://localhost:3000. Копирование env-файла необязательно: без ключа OpenAI работает полноценный fallback.

6. Проверенные версии среды и зависимости

Локальная реализация проверяется на Node.js 24.17.0, npm 11.13.0. Минимальная версия Node в package.json — 20.9.0. Основные зафиксированные версии: Next.js 16.3.6, React 19.3.0, TypeScript 6.0.3, Zod 4.6.5, csv-parse 7.0.2, OpenAI Agents SDK 0.18.0, Vitest 5.0.1, Playwright 1.63.0. Полный граф фиксирует package-lock.json.

7. Переменные окружения без секретов

Переменная	Назначение	По умолчанию
OPENAI_API_KEY	серверный ключ OpenAI	отсутствует
OPENAI_MODEL	модель для выбора evidence	gpt-6-luna
AI_ENABLED	false принудительно отключает AI	true

Локальный .env.local:

OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-6-luna
AI_ENABLED=true

Создать ключ можно на странице API Keys. Ключ не имеет префикса NEXT_PUBLIC_, не отправляется клиенту, не выводится в логи и не должен попадать в Git. Официальный OpenAI quickstart также рекомендует передавать ключ через переменную окружения.

8. Запуск с OpenAI и без него

Без ключа кандидаты, порядок, доказательства и объяснения полностью формируются локально. С ключом один агент из OpenAI Agents SDK может только выбрать 1–2 существующих evidenceId для каждой уже отобранной карточки. Модель настраивается через OPENAI_MODEL. После изменения .env.local перезапустите npm run dev.

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

app/                 страницы и HTTP-маршруты
components/          клиентский интерфейс и защита от гонок
lib/domain/          импорт, запрос, фильтрация, evidence и контракты
lib/ai/              один агент, проверка ответа, кеш и fallback
lib/server/          in-memory rate limit
data/raw/            неизменённая копия исходного CSV
tests/               unit, integration и browser-сценарии
scripts/             проверки датасета, документации, качества, benchmark
docs/spec.md         компактная рабочая спецификация

10. Датасет: источник, поля, флаги и версия

Первичный источник: hackathon dataset anonymized .csv, переданный пользователем 23.09.2026. HTML-превью найдено, но не используется как источник полного календаря. Лицензия набору не назначается, независимая проверка происхождения не заявляется.

• фактическое число профилей: 66;
• SHA-256 и версия: 6a724b6b7dfb5973343e68ba18dadb60fc807d87e3d78f03ee86fb26cb089f7d;
• поля: id, anon_name, categories, city, price_from_kzt, event_formats, languages, max_hours, busy_dates, description, synthetic, city_imputed, price_imputed;
• списки разделяются |; True/False разбираются явно; пустой max_hours становится null;
• synthetic=true означает синтетический профиль исходного набора; city_imputed и price_imputed отмечают дополненные исходные поля и не влияют на место.

11. Правила фильтрации

Дата — календарная строка YYYY-MM-DD в фиксированном окне 2026-09-23—2026-12-31. Сначала выбираются точные канонические город и категория. Затем профиль проходит, только если дата отсутствует в busy_dates, формат входит в event_formats, цена «от» не превышает бюджет, выбранный язык указан, а max_hours не меньше длительности или равен null. Пустые необязательные поля не ограничивают поиск. Границы цены и времени включительны; цена не умножается на часы.

12. Ранжирование и детерминизм

Все прошедшие варианты сортируются по price_from_kzt, затем по id; возвращаются первые три. Это не рейтинг качества. Состав и порядок не зависят от AI, кеша, нового экземпляра сервиса или порядка строк CSV. Версия правила: price-id-v1.

13. Три исхода и Диагностика

• matched: есть хотя бы один прошедший профиль;
• no_category_in_city: в городе вообще нет профилей категории, проверяется до ограничений;
• no_matches: категория есть, но все кандидаты исключены.

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

14. Роль AI и ограничения

AI не видит файловую систему, shell, GitHub, web search и внешние действия. Три инструмента возвращают только evidence выбранной карточки, текущую диагностику и рассчитанную бюджетную альтернативу. Контекст неизменяем и привязан к проверенному запросу. Agent не может добавить кандидата, переставить карточки, изменить дату или ослабить фильтр.

AI-бюджет ожидания — 7 секунд на весь agent loop, maxTurns=4. Независимый таймер возвращает fallback даже если провайдер не реагирует на отмену; запоздалый ответ не попадает в кеш. Слот параллельности освобождается, когда вызов провайдера действительно завершится. Ошибки авторизации, лимита, провайдера, timeout, отказ и невалидная структура приводят к fallback. In-memory кеш ограничен 100 ключами и учитывает запрос, версию данных, ранжирования, модели и объяснений. Он не является общей памятью между serverless-инстансами.

Поле ai.mode объясняет фактический режим ответа:

Значение	Значение для пользователя
ai	агент успешно выбрал проверенные evidence
ai_cache	использован ранее проверенный выбор evidence
fallback_no_key	ключ не настроен
fallback_disabled	AI отключён через AI_ENABLED=false
fallback_timeout	agent loop не уложился в 7 секунд
fallback_invalid	структурированный ответ не прошёл серверную проверку
fallback_error	ошибка провайдера, авторизации, лимита или конкурентности

Любой fallback сохраняет тот же состав и порядок карточек; меняется только способ выбора оснований для объяснения.

15. Как проверяются основания объяснений

Каждое evidence имеет ID и поле-источник. Числа рассчитывает программа. Цитата может быть только точной короткой фразой из description; фразы с числовыми/календарными утверждениями или инструкционным текстом не используются. После AI проверяются ID профилей, принадлежность evidence, отсутствие повторов и полнота ответа. Текст собирает сервер из прошедших проверку evidence.

16. API

GET /api/catalog/meta возвращает значения списков, окно календаря, число профилей и версию данных.

POST /api/recommend принимает:

{"city":"Алматы","date":"2026-10-12","eventType":"корпоратив","category":"Ведущий","budgetKzt":1000000,"durationHours":6,"language":"русский"}

Успешный ответ содержит request, status, cards, counts, summary, diagnosis, datasetVersion, rankingVersion и ai. Сокращённый пример ответа:

{"status":"matched","cards":[{"id":"HK-88430","name":"Куррапика","priceFromKzt":500000,"explanation":"Цена от 500 000 ₸; запас до бюджета — 500 000 ₸."}],"counts":{"cityCategoryCandidates":10,"eligible":6,"shown":3},"rankingVersion":"price-id-v1","ai":{"mode":"fallback_no_key"}}

Нормальный пустой исход возвращает HTTP 200; ошибка входа — 400; слишком большой запрос — 413; rate limit — 429; повреждение источника — отдельный 500 без stack trace. Если CSV не читается уже при открытии страницы, пользователь видит отдельное состояние «Каталог недоступен».

17. Команды проверок и фактические результаты

npm run verify:dataset
npm test -- --run
npm run lint
npm run typecheck
npm run build
npm run test:e2e
npm run verify:docs
npm run benchmark

Аудит 23.09.2026 на Windows, Node 24.15.0, npm 11.12.1: dataset — 66 профилей и ожидаемый SHA-256; Vitest — 44/44 (включая реальные обработчики HTTP); ESLint — без ошибок; строгий tsc --noEmit — успешно; production build — успешно (страница и два API-маршрута); Playwright — 14/14 в Chromium (desktop и 375 px, включая отмену запросов, ошибки сервера и reduced motion). Локальный next start также проверен: главная и API возвращают HTTP 200, сценарий A — ожидаемые три ID; тёплый HTTP-запрос без AI занял 11 мс. В этой проверке реальный OpenAI не вызывался; ошибки, таймаут и кеш проверены с управляемым провайдером.

Регрессионные тесты воспроизводят пустой/нечитаемый CSV, провайдера, игнорирующего отмену, превышение 8 KiB потоковым запросом и устаревшие карточки после смены сценария. API прекращает чтение сразу при превышении лимита, пустой CSV считается ошибкой источника. При любом новом поиске предыдущая выдача очищается, а до ответа показывается состояние загрузки.

GitHub Actions runs, включая подтверждённый run 35844687347, не начинают ни одного шага: GitHub блокирует job сообщением The job was not started because your account is locked due to a billing issue. Это ограничение аккаунта организации, а не падение команды проекта; локально выполнен тот же набор проверок. Workflow не отключён и запустится после восстановления runner-доступа.

npm run benchmark в локальном fallback-режиме (без сети, один процесс) измерил первый вызов вместе с чтением/разбором CSV в 28.280 мс; 1000 тёплых вызовов заняли 38.663 мс, в среднем 0.0387 мс. Это измерение доменного модуля, а не гарантия HTTP/AI-задержки.

23.09.2026 отдельно проверен реальный OpenAI-доступ без раскрытия ключа: прямой Responses API-запрос к gpt-6-luna завершился успешно за 1 387 мс. Сквозной POST /api/recommend вернул HTTP 200, статус matched и три карточки, но полный multi-turn agent loop превысил внутренний бюджет 7 секунд и завершился в безопасном fallback_timeout. Это подтверждает исправность ключа и доступ к модели, но не подтверждает стабильное завершение агента в текущий timeout.

18. Сценарии A–H

Кнопки интерфейса запускают настоящий backend:

• A: Алматы, ведущие, 12 октября — 6 прошедших, первые HK-88430, HK-44923, HK-29829;
• B: 13 октября — HK-29829 занят, третьим становится HK-35215;
• C: два флориста HK-39372 и HK-90001, max_hours=null не исключает их;
• D: 14 ноября остаётся HK-90001;
• E: в Астане нет категории «Декоратор»;
• F: при 450 000 ₸ нет результатов, точный полезный порог — 500 000 ₸;
• G: зал HK-90012 занят 14 ноября;
• H: 15 ноября он свободен, цена от 2 800 000 ₸, видны synthetic и price_imputed.

19. Развёртывание

Публичная production-версия развёрнута в Vercel: eventmatch-hackalem.vercel.app. Проект использует пресет Next.js; production-переменные OPENAI_API_KEY, OPENAI_MODEL и AI_ENABLED сохранены в настройках Vercel без публикации их значений в репозитории.

Стандартный локальный production-запуск: npm run build и npm start. next.config.ts включает CSV в output file tracing, сервер читает его из data/raw. Build и запуск не требуют OpenAI. Для ручного обновления текущего Vercel-проекта выполните npx vercel deploy --prod; автоматический deploy при каждом git push пока не подключён.

23.09.2026 публичный smoke-тест подтвердил: главная страница возвращает HTTP 200, GET /api/catalog/meta видит 66 профилей, POST /api/recommend возвращает статус matched и три карточки. В проверочном запросе production-агент завершился в режиме ai на модели gpt-6-luna примерно за 7,5 секунды.

Что делать дальше — по шагам

1. Забрать актуальную ветку: git switch main, затем git pull --ff-only origin main.
2. Проверить Node.js: node --version. Рекомендуется 24.17.0, допустимо не ниже 20.9.0.
3. Установить точные зависимости: npm ci.
4. Для режима без AI ничего не настраивать. Для AI скопировать .env.example в .env.local, добавить OPENAI_API_KEY только в локальный env или секреты хостинга и при необходимости выбрать доступную модель через OPENAI_MODEL.
5. Выполнить локальную проверку: npm run verify:dataset, npm test -- --run, npm run verify:quality и npm run test:e2e.
6. Запустить npm run dev, открыть http://localhost:3000 и пройти сценарии A–H. Для короткой демонстрации особенно полезны A, B, F и H.
7. Для обновления production выполнить npx vercel deploy --prod. Проект уже связан с eventmatch-hackalem; локальная папка .vercel и .env.local не должны попадать в Git.
8. Если проект создаётся заново на другом хостинге, добавить там OPENAI_API_KEY, OPENAI_MODEL=gpt-6-luna и AI_ENABLED=true. Без этих значений публичное демо продолжит работать в fallback-режиме.
9. После каждого deploy проверить главную страницу, сценарии A и H, GET /api/catalog/meta и один POST /api/recommend.
10. Попросить владельца GitHub-организации снять billing lock для Actions. После этого повторно запустить CI и убедиться, что все шаги зелёные.

20. Ограничения

Цена является стартовой и не обещает финальную стоимость. Календарь ограничен 2026-09-23—2026-12-31. Каталог содержит исходные синтетические и дополненные записи. Нет бронирования. In-memory rate limit, кеш и ограничение параллельности действуют только внутри одного процесса/serverless-инстанса. Доступность конкретной модели зависит от аккаунта OpenAI и не может быть гарантирована приложением.

21. Известные проблемы и дальнейшие улучшения

Обязательно перед публичным демо

• Повторно открыть публичный адрес непосредственно перед выступлением и проверить основной сценарий; production-deploy и работа режима ai уже подтверждены.
• Владельцу GitHub-организации нужно снять billing lock: workflow существует, но runner не начинает job.

Желательно до презентации

• Подтвердить право на публичное использование и показ исходного датасета.
• Повторить замер полной HTTP- и AI-задержки перед презентацией: текущий production-замер успешен, но время ответа внешней модели может меняться.
• Добавить минимальный health-check и наблюдаемость хостинга: ошибки API, latency и долю AI/fallback-ответов.
• Подготовить короткий сценарий выступления, резервные скриншоты или запись демо на случай проблем с сетью.

Можно добавить после MVP

• Внешнее хранилище для общего rate limit и кеша, если приложение будет работать в нескольких инстансах или получит заметную нагрузку.
• Смысловое ранжирование — только после набора примеров качества и сравнения с текущей детерминированной сортировкой.

Не требуется для текущего кейса

Бронирование и оплата, аккаунты и авторизация, внешний поиск подрядчиков, отзывы и рейтинги, а также multi-agent архитектура не нужны для демонстрации заявленного MVP.

22. Журнал разработки

2026-09-23 — ссылка на публичное демо

• В начало README добавлена заметная ссылка на работающую production-версию EventMatch.
• Затронут только README.md; код, данные и правила подбора не менялись.

2026-09-23 — проверка фронтенда и бэкенда, исправление аварийных сценариев

• Запрос: изучить проект и материалы хакатона, протестировать фронтенд и бэкенд, исправлять найденные ошибки.
• Исправлено: старые карточки оставались во время нового демо-запроса и после ошибки сервера; пустой CSV принимался за рабочий каталог; ошибка чтения файла возвращала internal_error вместо catalog_error; AI-таймаут не завершал запрос при игнорировании отмены; лимит тела проверялся только после полного чтения. Главная иллюстрация теперь загружается сразу, устранено предупреждение Next.js о lazy-loading LCP.
• Проверки: новые регрессионные проверки сначала воспроизвели сбои; после исправлений Vitest 44/44, Playwright 14/14 на desktop/mobile, ESLint, TypeScript, production build, проверка датасета и локальный production HTTP smoke прошли. CSV совпадает с предоставленным пользователем файлом по SHA-256; сортировка и правила допустимости сохранены.
• Ограничения: повторный реальный OpenAI-вызов и deployment в Vercel в этот аудит не входят; локально проверены fallback и контролируемые сбои AI. Изменения сайта появятся в production после отдельного deploy.

2026-09-23 — форма как центр первого экрана

• Запрос: сделать существующий EventMatch удобнее для быстрого подбора, сохранив данные, API, демо-сценарии и детерминированные результаты.
• Изменено: форма и CTA размещены на первом экране; добавлены прокручиваемые чипы всех категорий из каталога, раскрываемые язык и длительность с видимой сводкой активных условий, компактная навигация и нейтральное изображение атмосферы события. Карточки используют абстрактную графику категории, показывают две проверенные причины и уточняют статус даты. При изменении формы прежняя выдача очищается, после ответа виден раздел результатов.
• Затронуто: components/event-match-app.tsx, app/globals.css, public/event-atmosphere.png, README. Исходный CSV, доменная фильтрация и API не менялись.
• Проверки: ESLint, TypeScript, production build, Vitest 30/30 и браузерные сценарии 10/10 в локально установленном Chrome; визуальный осмотр на 1440 и 375 px, отсутствие горизонтальной прокрутки на 360/768/1024/1440 px, работа чипа категории и раскрытия дополнительных условий. Стандартный Chromium Playwright в этой среде не установлен.

2026-09-23 — обновление интерфейса подбора

• Запрос: обновить визуальный стиль EventMatch с энергичной подачей событий, сохранив логику подбора и фактические объяснения.
• Изменено: первый экран, форма, адаптивная сетка результатов и карточки в существующих components/event-match-app.tsx и app/globals.css; созданы только CSS-визуалы типов событий, без сторонних изображений и вымышленных фотографий профилей.
• Решение: обязательные пять полей оставлены в основной форме, язык и длительность выделены как дополнительные условия. Факты из серверного evidence видны без раскрытия, а метки синтетического профиля и дополненных полей расположены перед основаниями.
• Подбор, API, сортировка, сценарии A–H и диагностика пустой выдачи не менялись. Никакие данные каталога не дополнялись в интерфейсе.
• Проверки: CSV (66 профилей и ожидаемый SHA-256), ESLint, TypeScript, production build и 30 модульных тестов прошли; 10 браузерных сценариев прошли в установленном Chrome на десктопе и ширине 375 px. Выполнен визуальный осмотр обоих размеров. Стандартный запуск Playwright потребовал бы скачать Chromium, но CDN несколько раз не ответил, поэтому для браузерной проверки использован локально установленный Chrome.

2026-09-23 14:16 +05:00 — первоначальная реализация MVP

• Запрос: реализовать EventMatch целиком на предоставленном CSV, с fallback, одним AI-агентом, тестами, документацией и подготовкой к deployment.
• Изменено: создано Next.js-приложение, доменный модуль подбора, CSV-импорт, HTTP API, UI, AI evidence selector, защита endpoint, тесты и CI.
• Затронуто: app, components, lib, data, tests, scripts, .github, документация и конфигурация.
• Решение: фильтры и сортировка полностью детерминированы; AI выбирает только уже рассчитанные факты, поэтому его отсутствие не влияет на кандидатов.
• Проверки: hash и 66 строк датасета подтверждены; Vitest 30/30, ESLint, строгий typecheck, production build, Playwright 10/10, docs-check и ручная проверка 1440/375 px прошли; ledger подтвердил 6/6 критериев.
• Review: устранены незавершённые записи README, no-op поля AI теперь валидируются и влияют только на безопасную серверную формулировку, причины исключения централизованы, частичная выдача объясняется, а сбой CSV имеет отдельное состояние интерфейса.
• Ограничения: публичный deploy не настроен; реальный OpenAI-вызов без пользовательского ключа не выполнялся; GitHub Actions не начал job из-за billing lock аккаунта организации (run 35843253867).

2026-09-23 14:33 +05:00 — инструкция следующего запуска и публикации

• Запрос: объяснить, что делать дальше пошагово.
• Изменено: в раздел развёртывания добавлен последовательный маршрут от git pull и npm ci до локальной демонстрации, deploy и восстановления GitHub Actions.
• Затронуто: README.md.
• Решение: OpenAI оставлен необязательным, чтобы отсутствие ключа не блокировало локальный запуск или публичное демо.
• Проверки: выполнены проверка документации, staged diff и проверка на секреты.
• Ограничения: создание проекта на хостинге, настройка секретов и снятие billing lock требуют доступа владельца соответствующих аккаунтов.

2026-09-23 14:42 +05:00 — аудит готовности к демонстрации

• Запрос: определить, что ещё не готово и что следует добавить.
• Изменено: оставшиеся задачи разделены на блокеры публичного демо, желательные улучшения, задачи после MVP и функции, которые сознательно не входят в текущий кейс.
• Затронуто: README.md.
• Решение: код MVP считается готовым; приоритет отдан deploy, проверке AI с действительным ключом, восстановлению CI и production smoke-тесту.
• Проверки: выполнены проверка документации, staged diff и проверка на секреты.
• Ограничения: deploy, действительный OpenAI-ключ, права на публикацию датасета и снятие GitHub billing lock требуют действий или доступа владельца соответствующего аккаунта.

2026-09-23 15:02 +05:00 — подготовка README после проверки OpenAI

• Запрос: подготовить README к передаче и презентации.
• Изменено: разделены команды Windows и macOS/Linux, добавлены безопасный пример .env.local, ссылка на официальный OpenAI quickstart, таблица режимов ai.mode, актуальный CI run и результаты реальной проверки OpenAI.
• Затронуто: README.md.
• Решение: исторические записи сохранены, а текущее состояние вынесено в актуальные разделы; подтверждённый ключ больше не указан как блокер.
• Проверки: проверка документации, git diff --check, staged secret scan и сверка локальной/удалённой веток выполнены перед публикацией.
• Ограничения: прямой запрос к gpt-6-luna успешен, но multi-turn agent loop пока уходит в fallback_timeout при бюджете 7 секунд; публичный deploy и восстановление GitHub Actions ещё не выполнены.

2026-09-23 16:25 +05:00 — production-deploy в Vercel

• Запрос: опубликовать текущий проект в Vercel.
• Изменено: создан и связан проект eventmatch-hackalem, выбран пресет Next.js, production-переменные окружения сохранены в Vercel, а локальная служебная папка .vercel добавлена в .gitignore.
• Публичный адрес: https://eventmatch-hackalem.vercel.app.
• Проверки: production build завершился успешно; главная страница вернула HTTP 200; каталог содержит 66 профилей; POST /api/recommend вернул matched, три карточки и режим ai на gpt-6-luna примерно за 7,5 секунды.
• Решение: Git-интеграция Vercel пока не подключена, поэтому следующий production-релиз выполняется командой npx vercel deploy --prod.
• Ограничения: GitHub Actions по-прежнему заблокирован billing lock организации и не влияет на уже работающий Vercel-deploy.