EKT AI

HackAlem AI — кейс ТОО «Электрокомплект»

EKT AI — ИИ-консультант для ekt.kz, который помогает найти реальный товар из каталога, проверить наличие и характеристики, подобрать альтернативу и безопасно добавить товар в корзину.

Проблема

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

Решение

Запрос пользователя → OpenAI → server-side tools → EKT API → реальный товар → подтверждение пользователя → корзина.

OpenAI управляет диалогом и объясняет результат, но не является источником цены, остатка, характеристик или сертификатов. Эти данные backend получает из EKT API.

Возможности

• Поиск товара по названию, артикулу или EKT ID.
• Получение актуальной цены, остатка, характеристик и сертификатов, если они есть в API.
• До трёх объяснимых аналогов для недоступного товара.
• Детерминированное ранжирование аналогов по реальным характеристикам EKT и исключение товаров без остатка.
• Диалог на русском языке и краткие ответы по вопросам оплаты и доставки без выдумывания неизвестных условий.
• Безопасный двухшаговый add-to-cart через Cart Proposal и явное подтверждение.
• Повторная проверка остатка перед добавлением и запрет количества выше доступного.
• Страница /cart с товарами, количеством, ценой и итогом.
• Удаление товара из корзины только после отдельного подтверждения.

Как это работает

1. Пользователь пишет название товара, артикул или ID.
2. POST /api/chat вызывает OpenAI Responses API.
3. Модель использует tools search_products и get_product_details; backend обращается к EKT API.
4. UI показывает только фактические данные каталога. Для отсутствующего товара tool find_analogues возвращает доступные и ранжированные backend-кодом аналоги.
5. Просьба добавить товар создаёт Cart Proposal, но не меняет корзину.
6. После клика «Да, добавить» backend повторно запрашивает карточку EKT, проверяет остаток и только затем обновляет demo-cart.

Архитектура

flowchart TD
    U[Пользователь] --> UI[Next.js UI]
    UI --> CHAT[/api/chat]
    CHAT --> AI[OpenAI Responses API]
    AI --> TOOLS[Server-side Tools]
    TOOLS --> EKT[EKT API]
    EKT --> TOOLS
    TOOLS --> AI
    AI --> UI

    UI --> P[Cart Proposal]
    P --> C{Подтверждение пользователя}
    C -->|Да| V[Повторная проверка остатка]
    V --> CART[Demo Cart]
    C -->|Нет| X[Без изменений]

Защита от галлюцинаций

• цена — только из EKT API;
• остаток — только из EKT API;
• характеристики и сертификаты — только из EKT API;
• AI не может самостоятельно изменить корзину;
• если данных нет, система не должна их придумывать.

Безопасность корзины

1. Backend создаёт Cart Proposal с server-side данными товара.
2. До явного клика пользователя корзина не меняется.
3. Confirmation endpoint повторно получает товар из EKT API.
4. Backend проверяет, что количество целое, больше нуля и не превышает актуальный остаток.
5. Только после успешной проверки изменяется demo-cart.

Frontend не передаёт доверенные цену, название или остаток. Удаление товара также требует отдельного подтверждения «Да, удалить» и выполняется backend по productId.

Технологии

• Next.js 16, App Router, React 19;
• TypeScript 5.9;
• Tailwind CSS 4;
• официальный OpenAI SDK и Responses API с function calling;
• EKT API с server-side Basic Auth;
• Vitest и jsdom для автоматических тестов.

Используемые данные

EKT API:

• GET /products
• GET /products?page=N
• GET /products/detail?id=...

Basic Auth используется только server-side. Credentials не передаются во frontend и не хранятся в репозитории.

Переменные окружения

Создайте .env.local:

OPENAI_API_KEY=
EKT_API_URL=https://ekt.kz/api
EKT_API_USER=
EKT_API_PASSWORD=

Адрес API: https://ekt.kz/api. Файл .env.local исключён из Git.

Запуск

npm install
npm run dev

Приложение будет доступно на http://localhost:3000.

Проверки и production-запуск:

npm test
npm run typecheck
npm run lint
npm run build
npm run start

Demo

1. Найти товар по названию, артикулу или ID.
2. Показать актуальные цену, характеристики и наличие из EKT.
3. Для товара без остатка запросить аналог и показать объяснение совпадений и различий.
4. Попросить добавить конкретное количество товара.
5. Показать, что Cart Proposal появился, но корзина ещё не изменилась.
6. Нажать «Да, добавить» и открыть /cart.
7. Нажать «Удалить», показать confirmation и подтвердить удаление.

Ограничения

Настоящий cart API EKT не был предоставлен, поэтому используется server-side demo-cart adapter в памяти процесса. Корзина очищается после перезапуска приложения.

Развитие

• Production cart API EKT.
• Обработка Excel/PDF/Word/JPEG.
• Казахский язык.
• Передача диалога менеджеру.