EKT AI Assistant

ИИ-консультант для сайта ekt.kz, подготовленный командой binary brains для кейса HackAlem AI.

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

Проект помогает клиентам интернет-магазина ekt.kz быстрее получать информацию об электротехнических товарах: искать позиции по каталогу, смотреть наличие и характеристики, получать кандидатов на замену при отсутствии товара, уточнять условия покупки и добавлять выбранные позиции в демонстрационную корзину только после подтверждения.

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

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

• Серверный модуль каталога ekt.kz с Basic Auth.
• Поиск товаров по артикулу и словам из названия.
• Получение свежей карточки товара через detail API.
• Нормализация цены, остатка, категории, свойств, складов и ссылок на сертификаты в поддерживаемых полях.
• Обработка категории из KATEGORIYA и KATEGORIYA_SVETILNIKA.
• Обнаружение части противоречий в характеристиках, например конфликт номинального тока в карточке.
• Подбор кандидатов на замену с объяснением совпадений и отличий.
• Сравнение эквивалентных единиц измерения для тока и напряжения.
• HTTP-сервис каталога для подключения серверного Python-блока.
• Базовый модуль ассистента: сессии, определение намерений, ответы про оплату/доставку, карточки товаров и подтверждение перед добавлением.
• API чата и загрузки файлов:
  • POST /api/chat
  • POST /api/upload
• Заготовки обработки Excel, Word, PDF и JPEG.
• Адаптивный чат-интерфейс на Next.js.
• Демонстрационная корзина с серверным подтверждением, одноразовым токеном и повторной проверкой остатка перед добавлением.
• Страница корзины /cart.
• Демо-каталог и демо-корзина для автономной проверки без живого API.
• Автоматические тесты каталога и аналогов на встроенных фикстурах.

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

Основной сценарий:

1. Пользователь открывает чат и пишет запрос, например артикул или описание товара.
2. Ассистент определяет намерение: поиск товара, подбор аналога, вопрос об оплате/доставке или подтверждение добавления.
3. Для поиска товара серверный код обращается к каталогу ekt.kz или демо-источнику.
4. Каталог возвращает карточку товара: название, артикул, цену, остаток, свойства, категорию, склады, сертификаты и предупреждения.
5. Если товар отсутствует или нужен аналог, модуль src/lib/alternatives/ проверяет кандидатов по категории и критическим характеристикам.
6. Интерфейс показывает ответ ассистента и карточки товаров.
7. Пользователь выбирает количество. Сервер подготавливает добавление, проверяет товар и выдаёт одноразовый токен подтверждения.
8. После явного подтверждения сервер повторно проверяет карточку товара и остаток, затем добавляет позицию в демонстрационную корзину.
9. Пользователь переходит на /cart и видит актуальное состояние демо-корзины.

Для файлов пользовательский путь заложен через POST /api/upload: файл попадает в обработчик документов, из текста извлекаются возможные позиции, после чего их можно передавать в поиск каталога. Полноценное OCR/чтение PDF пока не подключено.

Технологии

• TypeScript
• Node.js 24+
• Next.js 16
• React 19
• Встроенный node:test
• REST API ekt.kz
• Basic Auth
• Fetch API
• HTTP-сервис на Node.js для локального подключения Python-клиента
• Python-пример клиента без внешних зависимостей

AI-модель в репозитории не подключена. Текущий ассистент использует правиловую маршрутизацию намерений и серверные инструменты каталога.

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

src/app/
  page.tsx                         # главная страница с чат-интерфейсом
  cart/page.tsx                    # страница демо-корзины
  api/chat/route.ts                # API чата
  api/upload/route.ts              # API загрузки файлов
  api/cart/route.ts                # чтение корзины
  api/cart/prepare/route.ts        # подготовка добавления
  api/cart/confirm/route.ts        # подтверждение добавления

src/components/
  ChatWorkspace.tsx                # UI чата, карточек и загрузки файлов

src/lib/catalog/
  api.ts                           # источник ekt.kz с Basic Auth
  service.ts                       # индекс каталога, поиск и получение карточек
  normalize.ts                     # нормализация API-ответов
  certificates.ts                  # извлечение сертификатов
  demo.ts                          # синтетические демо-данные
  http.ts                          # локальный HTTP-сервис каталога

src/lib/alternatives/
  index.ts                         # поиск кандидатов на замену
  compare.ts                       # сравнение характеристик
  profiles.ts                      # профили критических свойств
  rank.ts                          # ранжирование кандидатов

src/lib/assistant/
  assistantService.ts              # логика диалога
  sessionManager.ts                # контекст сессии
  intentRouter.ts                  # определение намерения
  catalogClient.ts                 # клиент каталога ассистента
  ektCatalogClient.ts              # прямой клиент ekt.kz для ассистента
  cartClient.ts                    # демо-корзина ассистента

src/lib/cart/
  cartStore.ts                     # серверное хранилище демо-корзины
  http.ts                          # HTTP-ответы и cookie сессии корзины

src/lib/documents/
  documentParser.ts                # маршрутизация файлов по типу
  excelParser.ts                   # заготовка обработки Excel
  wordParser.ts                    # заготовка обработки Word
  pdfParser.ts                     # заготовка обработки PDF
  imageParser.ts                   # заготовка обработки изображений

scripts/
  catalog-demo.ts
  catalog-live.ts
  catalog-live-alternative.ts
  catalog-server.ts
  catalog-client-example.py

tests/
  catalog*.test.ts

Взаимодействие компонентов:

Next.js UI
  -> /api/chat или /api/upload
  -> assistantService / documentParser
  -> catalogClient или catalog service
  -> ekt.kz API / demo source
  -> карточки товаров и ответ в чате
  -> /api/cart/prepare
  -> /api/cart/confirm
  -> /cart

Корзина хранится в памяти одного серверного процесса. Это демонстрационный режим, а не реальная корзина ekt.kz.

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

Требования:

• Node.js >=24.12.0
• npm

Установка зависимостей:

npm ci

Локальный запуск приложения:

npm run dev

Откройте:

http://localhost:3000

Проверка сборки:

npm run build

Проверка TypeScript:

npm run typecheck
npm run typecheck:catalog

Запуск тестов:

npm test

Демо каталога без живого API:

npm run demo:catalog

Запуск локального HTTP-сервиса каталога на демо-данных:

npm run start:catalog:demo

Во втором терминале можно проверить Python-клиент:

python scripts/catalog-client-example.py

Настройка живого API ekt.kz

Скопируйте пример переменных окружения:

cp .env.example .env.local

Заполните .env.local локальными серверными учетными данными:

EKT_API_USERNAME=...
EKT_API_PASSWORD=...
EKT_API_BASE_URL=https://ekt.kz/api
EKT_API_USER=...
EKT_API_SEARCH_PAGES=10

.env.local исключен из Git. Не добавляйте к секретам префикс NEXT_PUBLIC_.

Команды для живого API:

npm run check:catalog-live
npm run check:catalog-live -- --id=515291
npm run check:alternative-live
npm run start:catalog

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

Проверка интерфейса без доступа к ekt.kz

1. Установить зависимости:

npm ci

2. Запустить приложение:

npm run dev

3. Открыть http://localhost:3000.
4. Написать в чат запрос о товаре, например:

Есть автомат 16А?

5. Выбрать товарную карточку и количество.
6. Нажать кнопку выбора товара.
7. Подтвердить добавление в корзину.
8. Перейти по ссылке /cart.

Без .env.local используются демонстрационные данные. Корзина также демонстрационная.

Проверка каталога и аналогов

npm test
npm run demo:catalog

Ожидаемый результат: поиск демо-товара, получение карточки с нулевым остатком и кандидат на замену с объяснением.

Проверка с живым API

После заполнения .env.local:

npm run check:catalog-live
npm run check:alternative-live

Сценарий check:alternative-live проверяет реальную пару светильников:

• исходный товар: KAMELYA MAXI, id 18161, артикул 150100708_;
• кандидат: AKASYA MAXI, id 23181, артикул 150100705_.

Алгоритм проверяет совпадение категории, 2xE27, диаметра 400 мм, IP20, способа монтажа, материала корпуса и типа источника света. Отличия светового потока и рассеивателя выводятся явно и требуют согласования с покупателем.

Подробный сценарий описан в docs/demo-scenario.md. Интерфейс и корзина описаны в docs/chat-cart.md.

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

Используется API ekt.kz:

• GET https://ekt.kz/api/products
• GET https://ekt.kz/api/products?page=2
• GET https://ekt.kz/api/products/detail?id=515291

Доступ выполняется через Basic Auth на сервере. Учетные данные не должны попадать в клиентский код или публичный репозиторий.

Дополнительные материалы:

• docs/catalog-integration.md — контракт каталога для ассистента, Python-клиента и корзины.
• docs/catalog-review.md — заметки по проверке каталога.
• docs/demo-scenario.md — демонстрационный сценарий.
• docs/chat-cart.md — запуск интерфейса и контракт демо-корзины.

Тестовые фикстуры находятся в tests/fixtures/ekt-sample.json. Они используются для регрессий и не заменяют свежие данные ekt.kz.

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

• AI-модель не подключена. Текущая логика диалога правиловая.
• Ассистент пока использует собственный поисковый клиент; проверенный сервис src/lib/catalog/ подключен к корзине и доступен отдельно.
• JPEG/PDF распознавание подготовлено как адаптеры; полноценное OCR и PDF-извлечение не реализованы.
• Excel/Word-парсеры используют базовую текстовую обработку и не являются полноценным разбором офисных форматов.
• Корзина демонстрационная и не меняет реальную корзину сайта ekt.kz.
• Покупка, резервирование склада и оплата не выполняются.
• Демо-корзина хранится в памяти процесса и сбрасывается после перезапуска сервера.
• Полная техническая взаимозаменяемость товаров не гарантируется: аналоги возвращаются как кандидаты с объяснением совпадений и различий.
• Валюта, правила KRATNOST_MIN, доступность складов и полный контракт сертификатов требуют дополнительного уточнения.
• Индекс каталога хранится в памяти процесса и требует перезагрузки после рестарта.
• Живой API иногда отвечает с таймаутом; код обрабатывает это как ошибку внешнего сервиса.

Deployment

Deployed-версия отсутствует.

Локально приложение запускается командой:

npm run dev

Локальный HTTP-сервис каталога запускается командами:

npm run start:catalog:demo
npm run start:catalog

По умолчанию сервис каталога доступен на http://127.0.0.1:3001 и предназначен для локальной серверной интеграции.