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

До трёх доступных подрядчиков под дату и бюджет — с объяснением каждого выбора и причин отказа остальных.

Production: https://qorgan-xi.vercel.app

Case: HackAlem AI 2026 #79-lite

Пользователь уже имеет каталог подрядчиков своего города. Qorgan помогает выбрать из него, объясняя рекомендации и причины отсева, а не выдаёт новый длинный список.

Проверка за 2 минуты

Откройте production и нажмите один из шести примеров над формой: каждый отправляет реальный POST /api/recommend. В таблице вход дан как город / дата / формат / категория / бюджет в тенге.

{"city":"Астана","date":"2026-09-23","eventType":"свадьба","category":"Ведущий","budgetKzt":1000000,"durationHours":8,"language":"казахский"}

Почему это не просто фильтр

Код проверяет все жёсткие ограничения и детерминированно выбирает top-3. AI анализирует только описания уже выбранных профилей: он не меняет допуск, рейтинг или порядок. Неподтверждённый AI-факт отбрасывается, карточка получает объяснение по данным каталога.

Как работает

flowchart TD
  Input["Форма / пресет"] --> Zod["Zod: проверка ввода"]
  Zod --> Catalog["CSV: город + категория"]
  Catalog -->|Категории нет| NoCategory["no_category"]
  Catalog --> Filters["Жёсткие условия и все причины отсева"]
  Filters --> Split["eligible[] + rejected[]"]
  Split -->|Нет подходящих| NoEligible["no_eligible"]
  Split --> Rank["Детерминированный порядок"]
  Rank --> Top["Top-3"]
  Top --> AI["AI: факт + цитата из description"]
  AI --> Verify["Zod + проверка цитаты и фактов"]
  Verify --> Result["Карточки или fallback"]
  Split --> Notes["pipeline, shortfall, availabilityNote"]
  Rank --> More["rankingNote"]
  Notes --> Result
  More --> Result
  NoCategory --> Result
  NoEligible --> Result

Вход: обязательны city, date, eventType, category, budgetKzt; durationHours и language необязательны. Даты: 2026-09-23 — 2026-12-31. Бюджет — целое число от 1 до 1 000 000 000 000 ₸, длительность — 1–24 часа. Сервер проверяет типы и допустимые значения. API принимает Content-Type: application/json; неверный тип содержимого, неизвестная категория и лишние поля дают HTTP 400.

Правила: сначала точное совпадение города и категории, затем дата, формат, бюджет, язык и длительность. rejected[] хранит все причины для каждого отклонённого профиля; pipeline показывает последовательное уменьшение каталога. max_hours: null не отсекает по длительности.

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

Ключевые файлы: lib/catalog.ts (PapaParse), lib/search.ts (Zod), lib/match.ts (отбор и порядок), lib/explanations.ts (проверка фактов и fallback), lib/openai.ts (единственный вызов модели), lib/prompts.ts, app/api/recommend/route.ts, components/SearchForm.tsx. lib/demo-presets.ts хранит входные параметры, не ответы.

Три исхода

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

shortfall: при 1–2 результатах сообщает, сколько найдено и почему нет трёх. availabilityNote: объясняет влияние занятости; кандидаты с единственной причиной busy сравниваются тем же порядком, чтобы утверждение «вошёл бы в тройку» было проверяемым. Остальные busy-only перечисляются отдельно. rankingNote: при более чем трёх подходящих объясняет показ первых трёх и называет остальных.

Форма различает загрузку, ошибки ввода и сервера. Некорректный запрос получает 400 с понятным сообщением, ошибка каталога — безопасный 500 без секретов.

Интерфейс живой проверки

Шесть пресетов заполняют форму и отправляют реальный запрос; незаданные optional-поля очищаются. Активный пример выделен. После ответа страница прокручивается к результату; при reduced motion анимации нет.

Четыре баннера различают полную тройку, shortfall и оба пустых исхода. Ниже видны влияние даты, правило порядка, этапы отбора и карточки; остальных подходящих и отклонённых можно увидеть после них.

Карточка показывает позицию, стартовую цену, полное объяснение, флаги происхождения данных, языки, часы и форматы. Форматы берутся серверной страницей из CSV по ID без нового API-запроса. Контекст результата относится к отправленному запросу, даже если форма уже изменена. У AI-дополнения видна проверенная цитата; fallback обозначен как объяснение по данным профиля.

Загрузка блокирует повторную отправку и показывает три скелетона; ошибка предлагает повторить запрос с текущими полями. Ниже 640 px форма одноколоночная. Визуальный проход браузера остаётся ручной проверкой: отсутствие обрезания и горизонтального скролла автоматическими тестами не подтверждено.

Роль AI и надёжность

OpenAI Responses API вызывается одним запросом для top-3. responses.parse() и zodTextFormat требуют structured output:

{ explanations: { id: string; distinctiveFact: string | null; evidence: string | null }[] }

Первое предложение объяснения составляет код из цены, бюджета и других проверяемых различий. Второе AI-предложение допускается только после проверки. AI не меняет IDs, порядок, фильтры или счётчики.

Zod повторно валидирует ответ. evidence длиной 10–150 символов ищется в description после Unicode, регистровой и пробельной нормализации. Неизвестные/повторные ID, неподтверждённые цитаты, многофразовые, рекламные и личные факты отклоняются. Пользовательский текст отделён от инструкций. explanationSource равен ai только для принятого факта, иначе fallback; explanationEvidence содержит цитату или null.

Общий deadline — 7 секунд, допускается одна повторная попытка в оставшееся время. Ошибка модели, отсутствие ключа и невалидный ответ переключают на детерминированный fallback; no_category и no_eligible не вызывают AI. Если структурированные данные совпали, fallback может указать проверяемое различие календарей, не меняя выдачу.

Кеш в памяти хранит до 200 успешных ответов, учитывая нормализованный запрос, модель и top-3; ошибки не кешируются, цитата перепроверяется при чтении. Между экземплярами Vercel текст AI может отличаться, порядок карточек — нет.

Диагностика: X-AI-Attempts, X-AI-Retry, X-AI-Verified, X-AI-Cache и Server-Timing для matched. Цитата подтверждает наличие текста в профиле, но не доказывает полностью смысловую связь AI-вывода.

Локальный запуск

Стек: Next.js 16.3.6 App Router, React 19.3.0, TypeScript strict, Tailwind, Zod, PapaParse, OpenAI SDK. Проверено с Node.js 24.11.1 и npm 11.6.2.

macOS/Linux:

git clone https://github.com/BAITC-Hacks/hack-9ac93bf8-qorgan.git
cd hack-9ac93bf8-qorgan
npm ci
cp .env.example .env.local
npm run dev

Windows PowerShell:

git clone https://github.com/BAITC-Hacks/hack-9ac93bf8-qorgan.git
cd hack-9ac93bf8-qorgan
npm ci
Copy-Item .env.example .env.local
npm run dev

Открыть http://localhost:3000. OpenAI key необязателен: без ключа детерминированные рекомендации работают с fallback. Для AI заполнить локально OPENAI_API_KEY; OPENAI_MODEL=gpt-5.4-mini уже указан в .env.example. Модель читается только из env, OpenAI вызывается сервером. Реальные env-файлы и .vercel/ игнорируются Git; .env.example не содержит ключа.

Проверки

npm run typecheck
npm run lint
npm test
npm run build

Последний прогон: 45/45 offline-тестов, сетка инвариантов по датасету и 43/43 HTTP smoke локально и на production. Проверяются реальные 66 профилей, все девять демо, граничные условия, CSV, объяснения и отказы AI. npm run smoke по умолчанию обращается к http://localhost:3000; для production укажите BASE_URL=https://qorgan-xi.vercel.app.

OPENAI_API_KEY=' ' OPENAI_MODEL=' ' npm run start
# Во втором терминале:
EXPECT_FALLBACK=1 npm run smoke
# Production:
BASE_URL=https://qorgan-xi.vercel.app EXPECT_FALLBACK=0 npm run smoke

$env:OPENAI_API_KEY=' '; $env:OPENAI_MODEL=' '; npm run start
# Во втором терминале:
$env:EXPECT_FALLBACK='1'; npm run smoke
# Production:
$env:BASE_URL='https://qorgan-xi.vercel.app'; $env:EXPECT_FALLBACK='0'; npm run smoke

Данные

data/contractors.csv — CSV-версия официального набора 66 анонимизированных профилей, включая 13 синтетических; собственные профили не добавлены. PapaParse читает CSV с header: true, сохраняя кавычки, запятые и многострочные описания. Списки, включая busy_dates, разделены |; True/False становятся boolean, пустой max_hours — null без ограничения длительности.

Карточки показывают флаги synthetic, city_imputed, price_imputed. busy_dates используется как статичный календарь занятости; имена вымышленные.

Деплой

Production: https://qorgan-xi.vercel.app. Vercel-проект maxots-projects/qorgan. Production env: OPENAI_API_KEY (Secret), OPENAI_MODEL=gpt-5.4-mini. Развёртывание привязанного проекта: npx vercel --prod.

Публичный GET / и POST API работают без авторизации; CSV читается в serverless runtime. Production smoke 23.09.2026 прошёл 43/43. Примеры отдельных замеров: D1 с AI 2593 мс, C без AI 226 мс; это не гарантии задержки. Без credentials работает детерминированный fallback.

Ограничения и развитие

Проверка evidence подтверждает присутствие цитаты в описании, но не полностью проверяет смысловую связь с выводом модели. Список запрещённых фактов не охватывает все перефразирования. Если структурированные данные не различают профили, fallback сообщает об этом. Календарь статичен и ограничен окном датасета; стартовая цена не равна окончательной смете. Визуальный проход UI остаётся ручной проверкой.

Не реализовано: бронирование, БД, авторизация, embeddings и семантическое ранжирование. Возможное развитие, не реализовано: свободный текст предпочтений и семантический поиск, синхронизация календарей, подбор пакета «зал + ведущий на одну дату».

Использованные внешние материалы

• Официальное ТЗ HackAlem AI 2026 case #79-lite и официальный анонимизированный CSV-датасет.
• Runtime npm: next, react, react-dom, papaparse, zod, openai.
• Dev npm: @tailwindcss/postcss, tailwindcss, typescript, tsx, eslint, eslint-config-next, @types/node, @types/react, @types/react-dom, @types/papaparse; точные версии в package-lock.json.
• OpenAI Responses API и официальная документация Structured Outputs.
• AGENTS.md подготовлен заранее как набор правил для AI-агентов.
• AI-инструменты подготовки и разработки: Codex, ChatGPT, Claude.
• Скиллы: docx для чтения официального условия, OpenAI Docs для сверки API, frontend-design для изменений формы без redesign; не runtime-зависимости.