EKT AI-консультант

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

Какую проблему решает проект

Пользователю каталога не нужно вручную просматривать множество карточек товаров и сопоставлять их характеристики. Он может сформулировать запрос в чате и получить подходящие позиции на основе данных каталога.

Чтобы снизить риск ошибочной покупки, добавление товара в корзину выполняется только после явного подтверждения пользователя и повторной проверки остатка.

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

• плавающее окно чата поверх страницы каталога;
• поиск товаров по артикулу и названию;
• загрузка товаров из API ekt.kz;
• серверный поиск по первым страницам каталога;
• получение цены, остатка, списка складов и характеристик из детальной карточки товара;
• ответы на вопросы об оплате и доставке;
• подбор кандидатов-аналогов при отсутствии товара;
• краткое описание каждого альтернативного товара для клиента;
• вызов функций через OpenAI Responses API;
• безопасный сценарий добавления товара: предложение, подтверждение, повторная проверка остатка, добавление в корзину;
• адаптивная страница /cart с демонстрационной корзиной;
• хранение демонстрационной корзины в localStorage браузера.

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

ekt-ai-assistant/
├── .env.example
├── .gitignore
├── README.md
├── package.json
├── next.config.ts
├── tsconfig.json
├── postcss.config.js
├── tailwind.config.ts
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── cart/
│   │   │   │   └── confirm/
│   │   │   ├── catalog/
│   │   │   └── chat/
│   │   ├── cart/
│   │   │   └── page.tsx
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   ├── assistant-widget.tsx
│   │   ├── catalog.tsx
│   │   └── product-card.tsx
│   └── lib/
│       ├── alternatives.ts
│       ├── cart.ts
│       ├── ekt.ts
│       ├── types.ts
│       └── alternatives.test.ts
└── public/

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

1. Пользователь вводит в чате артикул, название товара или вопрос.
2. Браузер отправляет запрос в серверный маршрут Next.js.
3. Сервер выполняет поиск через API ekt.kz и при необходимости запрашивает детальную карточку товара.
4. Модель получает только подходящие результаты и формирует ответ пользователю.
5. При запросе на добавление товара ассистент ожидает явного подтверждения.
6. После подтверждения сервер повторно проверяет остаток.
7. Доступная позиция добавляется в демонстрационную корзину на странице /cart.

Технологии

• Next.js — пользовательский интерфейс и серверные маршруты;
• JavaScript / Node.js 20+ — среда запуска приложения;
• OpenAI Responses API — обработка диалога и вызов функций;
• gpt-4.1-mini — используемая AI-модель;
• API ekt.kz — каталог и детальные данные товаров;
• Basic Auth — авторизация при обращении к API каталога;
• localStorage — хранение демонстрационной корзины в браузере.

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

Браузер обращается только к серверным маршрутам Next.js. Сервер хранит данные доступа к API ekt.kz и OpenAI, выполняет поиск, получает сведения о товарах и передаёт модели только релевантные результаты. Ключ OpenAI и данные Basic Auth не передаются в браузер.

Пользователь
    ↓
Интерфейс чата в браузере
    ↓
Серверные маршруты Next.js
    ├──→ API ekt.kz: поиск и карточки товаров
    └──→ OpenAI Responses API: диалог и вызов функций

Браузер
    └──→ localStorage: демонстрационная корзина

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

Требования

• Node.js 20 или новее;
• доступ к API ekt.kz;
• ключ OpenAI API.

Шаги

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

   npm install
   

2. Скопируйте .env.example в .env.local:

   cp .env.example .env.local
   

3. Заполните переменные окружения:

   EKT_API_USER=имя_пользователя
   EKT_API_PASSWORD=пароль
   OPENAI_API_KEY=ключ_openai
   EKT_MAX_PAGES=число_страниц
   

   EKT_MAX_PAGES ограничивает количество страниц каталога, просматриваемых сервером при поиске.

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

   npm run dev
   

5. Откройте http://localhost:3000.

6. Для проверки production-сборки выполните:

   npm run build
   

.env.local исключён из Git. Не публикуйте его содержимое и не передавайте секреты в браузер, README, скриншоты или презентацию.

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

1. Откройте чат и отправьте: Есть ли 027228? Покажи характеристики.
2. Попросите предложить аналог отсутствующего товара.
3. Задайте вопрос об оплате или доставке.
4. Напишите: Добавь 3 штуки в корзину.
5. Убедитесь, что до подтверждения корзина не изменилась.
6. Подтвердите действие и откройте /cart.
7. Повторите добавление с количеством больше остатка. Приложение должно остановить добавление и сообщить доступное количество.

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

• каталог товаров: https://ekt.kz/api/products;
• детальная карточка: https://ekt.kz/api/products/detail?id=ID;
• OpenAI Responses API.

Цена, остаток и характеристики отображаются на основе ответов API ekt.kz. Если поля противоречат названию или описанию товара, ассистент должен предупредить пользователя.

Ограничения

• поиск ограничен первыми страницами каталога; их количество задаётся через EKT_MAX_PAGES;
• корзина демонстрационная и хранится локально в браузере;
• изменение настоящей корзины ekt.kz не реализовано, поскольку соответствующий API не предоставлен;
• для внедрения на рабочий сайт нужны внутренний endpoint корзины ekt.kz и проверка пользовательской сессии;
• загрузка файлов Excel, Word, PDF и JPEG не входит в текущую версию MVP.

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

Подтверждённая ссылка на развёрнутую версию не указана.