Jarvis — ИИ-консультант по электротехнике EKT

Проект для HackAlem AI, кейс ТОО «Электрокомплект»: ИИ-ассистент для сайта ekt.kz.

Демо на Vercel: jarvis-ekt.vercel.app

Демо-вход: user1 / password123 — общий тестовый аккаунт, только для вымышленных данных. Чат, каталог и корзина доступны также без входа.

Репозиторий · Пошаговый пользовательский тест · Сверка с ТЗ и положением · Результаты проверок

1. Проблема и назначение

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

Jarvis объединяет консультацию, поиск по каталогу и подготовку корзины в одном интерфейсе. Пользователь описывает задачу, указывает артикул или прикрепляет спецификацию/фото, проверяет найденные позиции и подтверждает добавление. Цель — сократить время подбора и количество повторяющихся консультаций; экономический эффект текущего прототипа пилотом не измерен.

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

• Каталог EKT: поиск по наименованию, ID, артикулу и параметрам; карточки с ценой, остатком, складами, характеристиками и ссылкой на источник. Сертификаты показываются, если каталог предоставляет допустимые ссылки.
• Чат на русском и казахском: контекст переписки в рамках сессии, ответы по товарам и условиям покупки, ограничение бюджета за единицу.
• Подбор аналогов: сравнение критических характеристик для поддерживаемых категорий, объяснение совпадений и отказ от подтверждения замены при недостаточных или противоречивых данных.
• Фотографии: предварительное чтение типа и маркировки; фильтрация кандидатов по распознанным признакам. Чтение маркировки требует проверки пользователем.
• Спецификации: извлечение текста из файлов, разбор до 12 позиций за запрос, отображение точных артикулов, кандидатов и ненайденных строк. Пользователь выбирает позиции и редактирует количество.
• Сравнение: таблица до четырёх выбранных товаров с фильтром отличий, ценами, остатками и временем получения данных.
• Корзина прототипа: добавление, изменение количества и удаление только после отдельного подтверждения. Перед добавлением/изменением проверяются актуальные цена, остаток и кратность.
• Результат подбора: прямая ссылка /cart и скачивание TXT со списком товаров для передачи менеджеру.
• Аккаунт и история: регистрация с email и паролем, подтверждение почты шестизначным кодом, последующий вход по паролю; восстановление пароля через почту. При создании нового или открытии прежнего диалога текущая переписка автоматически сохраняется в аккаунте. Продолжение сохранённого диалога сохраняется автоматически; доступны ручное сохранение и удаление. Сервер проверяет подтверждение почты и владельца записи.
• Сопутствующие товары: фактические карточки из каталога с объяснением рекомендации; электрическая совместимость автоматически не обещается.
• Связь с менеджером: выбор отдела EKT по городу, редактируемый запрос, копирование/скачивание, открытие письма или звонка. Письмо отправляет сам пользователь.
• Обработка ошибок: повторная отправка с сохранением вложений, обновление просроченного предложения, предупреждения об ограничениях документов и отказ от распознавания пустых изображений.
• Интерфейс: десктопная и мобильная компоновка, переключение RU/KK, матовая панель чата, каталог с фотографиями.

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

1. Покупатель открывает ассистента и вводит запрос, например артикул, либо прикрепляет файл или фото.
2. Сервер проверяет входные данные. Для документов извлекается текст, для изображений используется мультимодальный запрос к OpenAI.
3. Точные артикулы, однозначные уточнения и таблицы с явными колонками «Артикул;Количество» обрабатываются правилами без обращения к AI. Для свободного подбора и остальных вложений AI формирует структурированный план поиска. Сервер находит карточки в индексе EKT, получает доступные подробные данные и формирует результат с источниками. Аналоги проверяются отдельными правилами сравнения характеристик.
4. Пользователь изучает карточки, сравнивает товары или проверяет строки спецификации и указывает количество.
5. Сервер подготавливает предложение. На этом этапе корзина не меняется.
6. После нажатия «Подтвердить» сервер проверяет предложение, сессию, цену, количество и остаток, затем сохраняет изменение.
7. Покупатель открывает текущую корзину или скачивает подборку. Оформление заказа в действующем магазине в эту версию не входит.

4. Технологии

Версии основных пакетов ниже взяты из package-lock.json; полное дерево зависимостей воспроизводится через npm ci.

Область	Используется
Языки	TypeScript, JavaScript, CSS
Приложение и серверные маршруты	Next.js 16.3.6, App Router, Node.js runtime
Интерфейс	React 19.3.0, Lucide React
Типизация и валидация	TypeScript 5.9.3, Zod
AI	OpenAI SDK 6.49.0; модель по умолчанию gpt-4.1-mini, настраивается через OPENAI_MODEL
Документы и изображения	pdf-parse 2.4.5, Mammoth для DOCX, ExcelJS для XLSX, Sharp для проверки изображений
Аккаунты и история	Neon Auth (@neondatabase/auth 0.5.0-beta), собственные формы регистрации/входа, Neon Postgres и @neondatabase/serverless 1.1.0
Анимации	GSAP, Lenis, OGL, Motion; адаптированные компоненты описаны в UI-SOURCES.md
Защита корзины	node:crypto, HMAC-SHA256, подписанные cookies и предложения
Проверки	node:test через tsx, Playwright 1.63.0, HTTP-сценарии на Node.js
Интеграции	API каталога EKT, официальная страница условий покупки, OpenAI API
Публикация	Vercel; исходный код — GitHub

Диалоги авторизованных пользователей хранятся в Neon Postgres. Поисковый индекс и подробная выборка каталога находятся в JSON-файлах репозитория; кратковременный кэш карточек — в памяти процесса.

5. Архитектура

Браузер: React UI / чат / каталог / сравнение / корзина
  │
  ├─ /api/upload ─────────── проверка вложений → текст или изображение
  │
  ├─ /api/auth/* ─────────── Neon Auth → проверенная сессия
  ├─ /api/history/* ──────── проверка владельца → Neon Postgres
  ├─ /api/chat ───────────── точный запрос / план OpenAI → каталог → ответ
  │                                    │
  ├─ /api/products ─────────────────────┤
  │                                    └─ индекс JSON / снимок / API EKT
  │
  ├─ /api/cart/propose ───── проверка позиций → подписанное предложение
  │                                      (без изменения корзины)
  └─ /api/cart/confirm ───── подтверждение + повторная проверка → cookie

Файлы и каталоги	Назначение
src/components/JarvisApp.tsx	Основной интерфейс, диалог и взаимодействие с API
src/components/SpecificationReview.tsx, Comparison.tsx	Проверка спецификации и таблица сравнения
src/app/api/	Серверные маршруты каталога, чата, вложений и корзины
src/lib/assistant.ts	Планирование AI-запроса, получение данных и формирование ответа
src/lib/catalog.ts, evidence.ts	Поиск, адаптер EKT, правила аналогов и фильтрация визуальных кандидатов
src/lib/cart.ts, cart-http.ts	Подпись, валидация и применение изменений корзины
src/lib/auth-server.ts, history-store.ts, history-types.ts	Авторизация, SQL-хранилище и схема истории
src/components/account/, ManagerHandoff.tsx	Аккаунт, восстановление переписки и обращение к менеджеру
src/lib/related.ts, attachment-parser.ts	Сопутствующие товары и проверка вложений
src/lib/policies.ts, i18n.ts	Условия покупки и локализация
src/lib/cart-brief.ts	Формирование TXT-подборки
data/, scripts/	Снимки каталога и скрипты их обновления
tests/, docs/	Проверки, отчёты и сценарии демонстрации

Модель не имеет инструмента изменения корзины. Предложение связано с сессией, ревизией корзины и одноразовым идентификатором, действует 10 минут. Сервер отклоняет неподтверждённые, просроченные и повторно использованные предложения. Cookies имеют HttpOnly, SameSite, а в production — Secure; проверяется источник запросов на изменение корзины.

Корзина хранится в подписанном cookie на 7 дней и переживает обновление страницы при сохранении cookie и серверного CART_SECRET. Гостевая история хранится в sessionStorage вкладки, язык — в localStorage. У вошедшего пользователя текущий диалог сохраняется в Neon перед переходом к новому или прежнему; пустые диалоги не архивируются. Если сохранение не удалось, переключение отменяется и переписка остаётся открытой. Вход сам по себе не загружает гостевую переписку в аккаунт. Каждый маршрут истории проверяет серверную сессию и владельца записи; ревизия предотвращает перезапись изменений из другой вкладки. Корзина остаётся отдельной браузерной сессией и не переносится между устройствами через аккаунт.

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

Требования

• Node.js 24.x и npm — проект проверен на Node.js 24.16.0.
• Git для получения репозитория.
• Интернет для установки зависимостей и обращений к внешним API.
• Для полного локального сценария: серверный ключ OpenAI и тестовые реквизиты API EKT, предоставляемые партнёром. Они не включены в репозиторий.

Жюри может проверить настроенную публичную версию без собственного ключа OpenAI и без входа в личные аккаунты участников.

Шаг 1. Получить проект и установить зависимости

git clone https://github.com/BAITC-Hacks/hack-05846c56-jarvis.git
cd hack-05846c56-jarvis
npm ci

Шаг 2. Настроить окружение

На свежем клоне создайте .env.local из шаблона:

node -e "require('node:fs').copyFileSync('.env.example', '.env.local', require('node:fs').constants.COPYFILE_EXCL)"

Команда не перезаписывает существующий .env.local. Если файл уже есть, отредактируйте его.

Переменная	Что указать
EKT_API_URL	https://ekt.kz/api
EKT_API_USERNAME	Логин тестового API EKT
EKT_API_PASSWORD	Пароль тестового API EKT
OPENAI_API_KEY	Серверный API-ключ OpenAI
OPENAI_MODEL	gpt-4.1-mini по умолчанию; для фото необходима модель с поддержкой изображений и структурированного ответа
CART_SECRET	Случайная строка длиной не менее 32 символов
DATABASE_URL	Подключение к Neon Postgres для истории; только на сервере
NEON_AUTH_BASE_URL	URL сервиса Neon Auth для своего проекта
NEON_AUTH_COOKIE_SECRET	Отдельная случайная строка не менее 32 символов для cookies авторизации
NEXT_PUBLIC_DEMO_LOGIN_ENABLED	true только после создания отдельного демонстрационного аккаунта; по умолчанию выключено

Создать значение CART_SECRET:

node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

Скопируйте результат в .env.local. Не публикуйте реальные значения переменных: .env.local исключён из Git. Используйте один постоянный CART_SECRET для сохранения действительности корзин в выбранной среде.

Для аккаунтов создайте проект Neon с включённым Neon Auth и укажите его DATABASE_URL и NEON_AUTH_BASE_URL. При подключении через Vercel Marketplace эти значения добавляет интеграция. NEON_AUTH_COOKIE_SECRET сгенерируйте отдельно. Таблица jarvis_conversations и индекс создаются при первом обращении авторизованного пользователя; роль БД должна иметь право CREATE TABLE. Не используйте ключи от чужого проекта.

В Neon → Settings → Auth включите Sign-up with Email, Verify at Sign-up с методом Verification code и Sign-in with Email. Подтверждение должно отправляться при регистрации. Добавьте адрес приложения в Domains; для разработки разрешите localhost. Интерфейс после проверки кода возвращает пользователя ко входу по паролю. Для аккаунта, который раньше использовал только одноразовый код, предусмотрен пункт «Установить / восстановить пароль».

Для отдельного демостенда scripts/seed-demo-account.ts создаёт только общий тестовый аккаунт [email protected] с опубликованным паролем password123 и ролью user. Скрипт рассчитан на текущую схему Neon Auth, требует права записи в неё и не перезаписывает существующие аккаунты. Запуск: node --env-file=.env.local --conditions=react-server --import tsx scripts/seed-demo-account.ts. После проверки входа включите NEXT_PUBLIC_DEMO_LOGIN_ENABLED=true и пересоберите приложение — это покажет псевдоним user1 и кнопку заполнения демоданных.

Шаг 3. Запустить разработку

npm run dev

Откройте http://localhost:3000. Сервер остаётся работающим в этом терминале. Диагностический маршрут: http://localhost:3000/api/health — показывает наличие настроек, но не заменяет проверку доступности внешних API.

Шаг 4. Собрать production-версию локально

Остановите dev-сервер перед запуском production-сервера на том же порту:

npm run build
npm start

Адрес по умолчанию — http://localhost:3000.

Если нет внешних ключей

Без OpenAI остаётся режим ответов по каталогу и правилам; AI-разбор файлов и фото недоступен. Без реквизитов EKT можно изучать сохранённую подробную выборку, но добавление и изменение количества в корзине требуют свежих данных и блокируются. Без CART_SECRET маршруты корзины не работают. Без настроек Neon недоступны вход и общая история, остальные функции работают независимо. Полный сквозной сценарий без этих настроек проверяйте на публичном демо.

7. Как проверить решение жюри

Откройте демо в отдельном приватном окне. Цены и остатки меняются, поэтому сверяйте показанные значения с источником и временем проверки, а не с заранее заданной суммой.

Быстрый вход для жюри: вход, логин user1, пароль [скрыто]. Это отдельный общий аккаунт только для тестовых данных; его история доступна всем, кто знает опубликованные реквизиты. Для личной истории зарегистрируйтесь своей почтой и подтвердите код.

Шаг	Действие	Что проверить
1. Данные товара	Напишите «Покажи характеристики и сертификаты 515291»	Карточка Legrand, цена, остаток и характеристики. В сохранённых данных есть конфликт 160/250 А — ассистент должен его отмечать. Отсутствующая ссылка на сертификат не выдумывается.
2. Аналог	«Подбери аналог отсутствующего товара 18412»	В проверенной выборке исходный остаток нулевой; доступны кандидаты с объяснением совпадений критических параметров. Их текущее наличие зависит от EKT.
3. Условия	«Какие условия оплаты, доставки и минимальной партии?»	Содержательный ответ с официальным источником; кратность относится к конкретному товару.
4. Отмена	Выберите доступный товар с минимальной партией 1 → «В корзину» → количество 1 → «Проверим ваш выбор» → «Отмена»	Корзина не изменилась.
5. Подтверждение	Повторите выбор, нажмите «Подтвердить», перейдите в корзину и обновите страницу	Нужное количество сохранено; ссылка /cart открывает текущее состояние той же сессии.
6. Спецификация	Сохраните пример TXT, прикрепите его к чату и попросите разобрать по строкам	Два точных артикула и одна ненайденная позиция. Выбор строк и изменение количества доступны до общего подтверждения.
7. Сравнение	Отметьте две карточки значком сравнения → «Сравнить товары» → «Только отличия»	Таблица исходных характеристик; неизвестные значения обозначены «—».
8. Результат	В корзине нажмите «Скачать подборку»	TXT содержит реальные позиции корзины, количества, суммы, ссылки и замечания.
9. Менеджер	Нажмите «Связаться с менеджером», выберите город, отредактируйте запрос	Правильные телефон/почта отдела, скачивание текста. «Открыть письмо» запускает почтовое приложение; автоматической отправки нет.
10. История	Войдите, задайте вопрос A → «Новый диалог» → вопрос B → откройте A из истории → вернитесь к B	Оба диалога сохранены автоматически, текст и карточки восстановлены. Перезагрузка сохраняет выбранный диалог; удаление требует подтверждения.
11. Язык и устройство	Переключите «Қаз», спросите «Алматыға жеткізу шарттары қандай?», откройте сайт на телефоне	Казахский ответ, читаемые символы и доступные основные действия.

Для фото прикрепите хорошо читаемую маркировку товара и попросите найти его. Проверьте, что ответ отделяет предварительное чтение от кандидатов и не объявляет электрическую совместимость по внешнему сходству.

Дополнительные отрицательные сценарии: нулевое/отрицательное количество, превышение остатка, неизвестный артикул, файл больше 3 МБ. Подробный маршрут — USER-TEST.md.

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

Без запущенного сервера и внешних ключей:

npm test
npm run build
npm run typecheck

Сборка также создаёт служебные типы Next.js, используемые проверкой TypeScript на свежем клоне.

На уже запущенном, настроенном сервере — из второго терминала:

node tests/integration.mjs --chat
npx playwright install chromium
npm run test:browser

Браузерные тесты используют отдельные сессии и тестовые корзины. Скриншоты сохраняются в test-results/, исключённый из Git. Для установленного Chrome можно задать PLAYWRIGHT_CHANNEL=chrome.

Чтобы проверить публичную версию вместо localhost, задайте TEST_BASE_URL. Например, в PowerShell:

$env:TEST_BASE_URL = 'https://jarvis-ekt.vercel.app'
node tests/integration.mjs --chat
npm run test:browser

В Bash переменная задаётся перед командой:

TEST_BASE_URL=https://jarvis-ekt.vercel.app npm run test:browser

Результаты конкретных прогонов записаны в RELEASE-CHECK.md. Браузерные проверки разделяют реальные запросы к каталогу и сценарии с подменой ответов для воспроизведения сбоев. Завершение входа через личную почту проверяется пользователем; автоматические проверки не отправляют письма.

Отдельная проверка реального SQL-хранилища (требует настроенной базы, создаёт и удаляет одну синтетическую запись):

node --env-file=.env.local --conditions=react-server --import tsx scripts/history-check.ts

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

Каталог EKT

Используются партнёрские маршруты с серверной Basic-аутентификацией:

• GET https://ekt.kz/api/products?page=N — страницы каталога.
• GET https://ekt.kz/api/products/detail?id=ID — подробная карточка и остатки.

В репозитории сохранены реальные данные EKT от 23.09.2026:

Файл	Содержимое
data/catalog-index.json	Поисковый индекс 15 035 товаров; не является набором актуальных остатков всех товаров
data/catalog-snapshot.json	608 подробных карточек с характеристиками и временем получения

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

Обновление данных — отдельная необязательная операция при наличии настроенного .env.local; команды перезаписывают соответствующие JSON-файлы:

node scripts/catalog-sync.mjs
node scripts/catalog-index.mjs

Условия покупки и AI

Условия оплаты и доставки записаны в src/lib/policies.ts по официальной странице доставки и оплаты EKT. Это сохранённая информация со ссылкой, а не автоматическое обновление страницы при каждом вопросе.

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

Обработка вложений и история

Файлы читаются в памяти сервера и не записываются приложением в постоянное файловое хранилище. Текст/изображения передаются OpenAI при AI-запросе. В браузере сохраняется история текущей вкладки; в аккаунте — диалоги, сохранённые вручную или при переключении, с последующим автосохранением продолжения. В БД записываются текст, имена файлов и ID товаров, но не содержимое файлов и не полные карточки. Старые цены в сообщениях не являются актуальной офертой; карточки при восстановлении загружаются заново. Диалог можно удалить из аккаунта. У гостя «Новый диалог» запрашивает подтверждение очистки; у вошедшего пользователя сначала сохраняет переписку.

Распознаваемые платёжные реквизиты маскируются в тексте до отправки модели и сохранения: номера карт с проверкой Luhn в поддерживаемом формате, явно подписанные CVV/CVC/PIN и казахстанские IBAN. Это ограниченная текстовая защита, не полноценная DLP: изображения, исходные байты файлов и все возможные персональные сведения она не анализирует. Не загружайте платёжные реквизиты и лишние личные данные; в общем демоаккаунте используйте только вымышленные запросы.

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

• Это самостоятельный прототип. Он не встроен в действующий ekt.kz. API корзины и сессии магазина не подключён; совместимость с ними не проверена. Заказ, оплата и резервирование товаров не выполняются.
• Корзина привязана к браузеру: /cart не переносит подборку другому человеку или на другое устройство. Для передачи состава есть TXT. Максимум — 35 позиций.
• История: до 100 диалогов на аккаунт, до 100 последних сообщений и 400 КБ на диалог. Восстанавливаются текст, ссылки и карточки (до 40 уникальных ID); старые предложения на изменение корзины и таблицы разбора спецификаций не восстанавливаются как действующие операции.
• Менеджер: готовится письмо/файл для ручной отправки, доступны телефоны. CRM, назначение сотрудника и ответ менеджера внутри чата не подключены.
• Перенос в EKT: кнопка открывает настоящую страницу корзины EKT, но не добавляет туда товары. Разрешённый API импорта/доступ к стороне магазина не предоставлен; подробности — EKT-CART-INTEGRATION.md.
• Файлы: до 3 вложений суммарно 3 МБ. Поддерживаются XLSX, DOCX, PDF, CSV/TXT в UTF-8, JPG/JPEG, PNG и WEBP. Старые XLS/DOC нужно преобразовать. PDF-сканы без текста следует загрузить изображениями страниц.
• Объём извлечения ограничен: PDF — первые 20 страниц; XLSX — до 8 листов, 400 строк и 24 ячеек строки; извлечённый текст — до 16 000 символов на файл с явным предупреждением при обрезке. Изображения — до 16 мегапикселей; повреждённые и почти одноцветные пустые кадры отклоняются. Структурированный разбор — до 12 товарных строк за запрос.
• Распознавание фото приблизительное: мелкие обозначения могут читаться неверно. Совпадение маркировки или характеристик не заменяет проверку электрической совместимости специалистом.
• Аналоги не гарантированы для каждой позиции. Правила проверяют поддерживаемые характеристики; при отсутствии данных или конфликте безопасная замена может не быть найдена.
• Каталог зависит от источника: возможны противоречия, пропуски сертификатов и недоступность API. Загрузка всех 15 035 подробных карточек и их остатков в реальном времени не реализована.
• Контекст: в один запрос передаются до 24 последних сообщений; при больших вложениях старые сообщения исключаются, чтобы уложиться в лимит тела запроса. Последний запрос и вложения сохраняются целиком.
• Задержка и масштабирование: в записанном публичном прогоне отдельные ответы занимали около 3,6–6,1 секунды, но SLA и нагрузочная устойчивость не подтверждены. Лимит чата — 15 запросов в минуту на IP в пределах процесса; распределённого лимитера нет.
• Полный аудит безопасности и приватности, пилот с покупателями и измерение экономического эффекта не проводились.

10. Публичная версия и развёртывание

Демо: https://jarvis-ekt.vercel.app

Приложение опубликовано на Vercel напрямую через CLI. Для собственного развёртывания нужно авторизоваться в Vercel, связать свой проект и задать серверные переменные из таблицы окружения для нужной среды. Затем из корня репозитория:

npx vercel deploy --prod --yes

GitHub-интеграция для такого способа не обязательна. Секреты задаются в окружении Vercel, а не в исходном коде. next.config.ts включает файлы PDF-worker и native canvas в серверный пакет обработки вложений.

11. Материалы проекта

• Аргументы и сценарий демонстрации по критериям.
• Журнал фактически завершённой работы.
• Отчёт первого часа и отчёт второго часа.
• Последние улучшения и границы самооценки.
• Результаты проверок.
• Источники и адаптация визуальных компонентов.

Основная функциональность создавалась во время хакатона с помощью OpenAI Codex и AI-агентов. Предоставленные участником HTML/CSS/JS-заготовки сохранены в references/ui и адаптированы к React. Товарные данные и изображения — EKT. Для PP Neue Machina сохранено уведомление в public/fonts/COPYRIGHT.txt; для казахского текста используется Noto Sans с лицензией public/fonts/NotoSans-OFL.txt. Лицензии зависимостей находятся в соответствующих npm-пакетах.