Trust ME (EventMatch) — подбор подрядчиков для мероприятий

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

Trust ME помогает организаторам мероприятий в Казахстане быстро найти подрядчика под конкретную дату и бюджет. Вместо просмотра всего каталога пользователь задаёт условия события и получает до трёх подходящих вариантов с объяснением выбора. Это прототип для задачи HackAlem «Умный подбор подрядчиков (#79-lite)».

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

• Мобильный интерфейс с тремя шагами: событие и дата → категория подрядчика и бюджет → дополнительные пожелания (язык и длительность).
• Подбор по городу, категории, свободной дате, стартовой цене, формату мероприятия, языку и длительности.
• Детерминированная выдача до трёх карточек: повторный запрос с теми же данными сохраняет порядок.
• В каждой карточке: анонимизированное имя, категория, город, цена «от», объяснение и отметки о синтетических или дополненных данных.
• Отдельные состояния для отсутствующей категории в городе, отсутствия совпадений и ошибки сети; можно изменить условия или повторить запрос.
• HTTP API и интеграционный тест для проверки подбора без мобильного приложения.

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

1. Пользователь выбирает формат, город, дату, категорию и бюджет; при необходимости добавляет язык и длительность.
2. Приложение отправляет JSON-запрос в POST /recommendations.
3. Сервер читает каталог из backend/src/data/contractors.json, исключает неподходящие профили и ранжирует оставшиеся по фиксированным правилам. При равенстве баллов учитываются цена и ID.
4. Приложение показывает до трёх карточек с объяснением на основе данных профиля либо сообщает, почему результатов нет. Бронирование и связь с подрядчиком в этом сценарии не выполняются.

Технологии

Компонент	Используется
Интерфейс	JavaScript/JSX, React Native, Expo SDK 57, Expo Router, NativeWind 4 / Tailwind CSS 3, Lucide
Состояние и запросы	Zustand, Axios, HTTP/JSON
Сервер	Node.js 22+, JavaScript, встроенный модуль node:http (без сторонних npm-зависимостей)
Проверки	Встроенный node:test для интеграционного теста сервера
AI-модели	В текущей версии не подключены: фильтры, оценка и объяснения реализованы программно; совпадение с описанием проверяется лексически

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

Путь	Роль
frontend/src/app/, frontend/src/components/	Форма из трёх шагов и экран результатов
frontend/src/store/useOrderStore.js, frontend/src/services/api.js	Состояние запроса, вызов API и обработка ответа
backend/server.js	HTTP-маршруты /health, /catalog, /recommendations и валидация HTTP-запросов
backend/recommendations.js	Загрузка и нормализация каталога, проверка условий, ранжирование и объяснения
backend/src/data/contractors.json	Каталог подрядчиков, загружаемый сервером при старте

Цепочка данных: форма → Axios → HTTP API → каталог и алгоритм подбора → JSON-ответ → карточки или причина отсутствия результатов. В backend/src/services/ есть сохранённые модули, но запущенный HTTP API использует backend/recommendations.js.

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

Нужны Git, npm и Node.js 22.13 или новее. Из терминала:

git clone https://github.com/BAITC-Hacks/hack-3fa15a7b-fact-check.git
cd hack-3fa15a7b-fact-check

1. Выберите API. Для быстрого демо можно использовать развёрнутый сервер. Для локального запуска в первом терминале из корня репозитория:

cd backend
npm start

Проверка локального сервера: откройте http://localhost:3000/health. Ожидается {"status":"ok","contractor_count":66}. В backend/ нет внешних npm-зависимостей, установка пакетов там не требуется. По умолчанию сервер слушает порт 3000; его можно изменить переменной PORT.

2. Настройте адрес сервера. Откройте frontend/.env (или создайте файл, если его нет) и задайте публичный адрес для демо:

EXPO_PUBLIC_API_URL=https://trustme-production.up.railway.app
EXPO_PUBLIC_RECOMMENDATIONS_PATH=/recommendations

Для локального API вместо публичного адреса используйте http://localhost:3000 в браузере или iOS Simulator, http://10.0.2.2:3000 в Android Emulator, либо http://IP_КОМПЬЮТЕРА:3000 на физическом телефоне в той же сети. localhost на телефоне указывает на сам телефон. После изменения .env перезапустите Expo.

3. Запустите интерфейс. Во втором терминале из корня репозитория:

cd frontend
npm i
npm run web

Для приложения на устройстве или эмуляторе вместо npm run web выполните одну из команд:

npm run android
npx expo run:android --device
# или на macOS с Xcode:
npm run ios
npx expo run:ios --device

Эти команды собирают и устанавливают Expo development build; для Android нужны Android SDK/эмулятор или подключённый телефон, для iOS — macOS и Xcode. После первой установки можно запускать Metro командой npm start из frontend/ и открывать установленное приложение.

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

1. Проверьте API по адресу /health: ожидается contractor_count: 66 (при локальном запуске используйте http://localhost:3000/health).
2. В интерфейсе выберите Алматы, корпоратив, Ведущий, бюджет 800 000 ₸, дату 17.10.2026; язык и длительность оставьте пустыми. Нажмите «Найти моих людей». Ожидается сообщение об отсутствии совпадений (no_matches в API).
3. Измените только дату на 19.10.2026 и повторите поиск. Ожидается одна карточка: Аня Форджер, цена от 700 000 ₸, с объяснением (matched в API).
4. Повторите запрос с теми же условиями: результат и порядок должны совпасть. Для автоматической проверки сервера выполните cd backend && npm test из корня репозитория.

API можно проверить отдельно (пример для Bash, URL можно заменить на http://localhost:3000):

curl -sS -X POST https://trustme-production.up.railway.app/recommendations \
  -H 'Content-Type: application/json' \
  --data '{"city":"Алматы","date":"2026-10-19","event_type":"корпоратив","category":"Ведущий","budget":800000}'

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

• Единственный источник профилей — включённый в репозиторий backend/src/data/contractors.json: 66 анонимизированных профилей. Часть профилей синтетическая; флаги synthetic, city_imputed и price_imputed обозначают происхождение или дополнение данных.
• Даты занятости представлены в каталоге только на период 23.09.2026–31.12.2026. Город, категории, форматы и языки можно посмотреть через GET /catalog.
• Интерфейс обращается к собственному API через Axios. API размещён на Railway; внешние сервисы поиска подрядчиков, платёжные API и LLM для выдачи не используются.

Ограничения

• Каталог и календарь статические: доступность и цены не синхронизируются с подрядчиками. Запросы вне указанного периода возвращают date_out_of_range (HTTP 422).
• Цена «от» — ориентир, итоговая смета и доступность требуют подтверждения у подрядчика.
• Интерфейс предлагает заранее заданные города, форматы и категории; API работает только с профилями из включённого каталога.
• Нет регистрации, бронирования, оплаты, уведомлений и отправки заявок. Настоящая AI-модель и смысловой поиск по описаниям пока не реализованы.

Развёрнутая версия

• Публичный API: trustme-production.up.railway.app (проверка: /health).
• Публичной ссылки на готовое мобильное приложение в репозитории нет; интерфейс запускается по инструкции выше.