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

Проект команды Paradox для HackAlem AI, трек «Торговля». Покупателю ekt.kz бывает трудно самостоятельно проверить характеристики и наличие электротоваров или подобрать замену позиции без остатка. EKT AI помогает пройти этот путь в чате: находит товары в каталоге, показывает проверяемые сведения и готовит добавление в демонстрационную корзину только после явного подтверждения человека.

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

• Поиск по названию и артикулу, карточки товаров с ценой, характеристиками и остатками по городам из API EKT.
• Подбор кандидата-аналога с таблицей совпадающих, отличающихся и неизвестных параметров. Кандидат не объявляется гарантированно совместимой заменой.
• Ответы на вопросы об условиях покупки из ограниченного набора сведений с указанием источника.
• Загрузка PDF, DOCX, XLSX и JPEG до 10 МБ: модель извлекает товарные позиции в черновик для проверки и отправки пользователем.
• Подготовка предложения с товаром, артикулом, количеством, городом, ценой и сроком действия. Подготовка не меняет корзину; для добавления нужен отдельный клик «Да, добавить в корзину».
• Демо-корзина с повторной проверкой цены, остатка и кратности при подтверждении; cookie-сессия, проверка CSRF и защита от повторного подтверждения одного предложения.
• Адаптивный чат, локальные история запросов и избранное. Сохранённые ответы служат справкой, а не подтверждением актуальной цены или наличия.
• Отдельный ekt-ai-frontend/demo.html для офлайн-показа на образцовых, а не на живых данных.

Как работает основной сценарий

1. Покупатель пишет запрос — например, артикул товара, которого нет в наличии, и нужный город.
2. Backend ищет товар в предварительно построенном индексе EKT, затем получает актуальные детали из API каталога. AI-ассистент вызывает ограниченные инструменты поиска, получения характеристик и подбора кандидатов.
3. Интерфейс показывает исходный товар, одного или нескольких кандидатов, городской остаток, цену и сравнение. Противоречия в источнике и недостающие параметры остаются видимыми.
4. Покупатель выбирает товар, количество и город. Backend создаёт предложение, но корзина пока не меняется.
5. После просмотра предложения покупатель нажимает «Да, добавить в корзину». Backend повторно проверяет условия и обновляет демо-корзину; результат доступен по ссылке /cart.

Решение не оформляет реальный заказ на ekt.kz.

Технологии

Часть	Используется
Backend	Node.js, TypeScript, Fastify, Zod, @fastify/cookie, @fastify/multipart
AI	OpenAI SDK и Responses API: вызовы инструментов для чата, структурированный ответ для извлечения позиций из вложений; модель по умолчанию gpt-6-sol, задаётся через OPENAI_MODEL
Frontend	JavaScript, HTML, CSS без UI-фреймворка; сборка автономного index.html скриптом Node.js; локальный HTTP proxy
Тесты и запуск	Vitest для backend, Node.js Test Runner и LinkeDOM для frontend, tsx для запуска TypeScript
Данные	Каталог ekt.kz через защищённые Basic Auth запросы к API; сведения об условиях покупки в src/knowledge/ekt-terms.ts

Архитектура

Браузер: чат, карточки, сравнение, история, подтверждение
  │ /api/* и /cart через same-origin proxy при локальной разработке
  ▼
Fastify API: сессия, CSRF, маршруты чата, вложений и корзины
  ├── AssistantRunner ──► OpenAI Responses API
  │     └── инструменты: поиск, детали, аналоги, условия, предложение
  ├── EktCatalogReader ─► поисковый индекс + EKT API (Basic Auth)
  ├── AttachmentExtractor ─► OpenAI Responses API
  └── DemoCartProvider ─► корзина в памяти; запись только по подтверждению

Секреты EKT и OpenAI используются только на backend. Frontend обращается к своему origin, а сервер разработки проксирует API-запросы на порт 3000. Формат запросов и ответов описан в docs/API.md; особенности интерфейса — в ekt-ai-frontend/README.md.

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

Нужны Node.js 20.19+, npm, доступ к EKT API и действующий ключ OpenAI API. При старте backend загружает страницы каталога в индекс, поэтому первый запуск может занять время. Для локального запуска используйте 127.0.0.1 и не смешивайте его с localhost в адресах браузера.

1. Склонируйте репозиторий и настройте backend:

   git clone https://github.com/BAITC-Hacks/hack-ca5ddf34-paradox.git
   cd hack-ca5ddf34-paradox
   npm ci
   cp .env.example .env
   

2. В локальном .env заполните EKT_API_PASSWORD и OPENAI_API_KEY. При необходимости измените EKT_API_USER и OPENAI_MODEL. Для запуска ниже оставьте PUBLIC_APP_URL=http://127.0.0.1:5173. Не публикуйте .env и ключи: этот файл исключён из Git.

3. В первом терминале соберите, проверьте и запустите backend:

   npm run build
   npm test
   npm run dev
   

4. Во втором терминале, из корня того же репозитория, запустите frontend:

   cd ekt-ai-frontend
   npm ci
   npm run build
   npm test
   npm run check
   npm run dev
   

5. Откройте http://127.0.0.1:5173. Для быстрой проверки backend: http://127.0.0.1:3000/health должен вернуть {"status":"ok"}.

npm run build в корне проверяет TypeScript; запуск backend в режиме разработки выполняет tsx. Сборка frontend обновляет отслеживаемый ekt-ai-frontend/index.html из исходников. Чтобы изменить число индексируемых страниц каталога, задайте EKT_INDEX_MAX_PAGES в .env (по умолчанию 20).

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

1. Откройте локальный интерфейс и отправьте: «Подбери один кандидат-аналог с наличием в Алматы для Legrand DPX3 160, артикул 310100077_. Покажи совпадения, противоречия и что нужно проверить».
2. Выберите Алматы в верхнем меню. У исходной позиции проверьте остаток, у кандидата — артикул, цену, доступное количество и таблицу сравнения. Данные каталога меняются: конкретные остаток, цена и найденный кандидат не гарантированы в будущий момент.
3. На карточке доступного кандидата нажмите «Выбрать количество», укажите количество и город, затем «Проверить наличие и цену». Убедитесь, что предложение показано, а корзина ещё не изменилась.
4. Нажмите «Проверить и подтвердить», просмотрите поля предложения и только затем «Да, добавить в корзину». Проверьте строку товара в /cart.

Если нет доступа к внешним API, отдельный ekt-ai-frontend/demo.html можно открыть локально для показа интерфейса. Его товары, ответы и корзина — офлайн-образцы, не доказательство работы живых интеграций.

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

• EKT API: список GET /api/products?page=N и детали GET /api/products/detail?id=...; серверная авторизация Basic Auth. По умолчанию индексируются первые 20 страниц, подробности товаров запрашиваются отдельно.
• OpenAI API: Responses API для ответов с ограниченными вызовами инструментов и структурированного извлечения позиций из вложений. Ключ хранится на backend.
• Условия покупки: конечный набор утверждений и ссылок на страницы ekt.kz находится в исходном коде; он не заменяет проверку актуальных условий у продавца.
• Локальные данные: история и избранное хранятся в браузере; сессии, предложения и демо-корзина — в памяти процесса backend.

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

• Индекс ограничен числом страниц: отсутствие товара в поиске не означает отсутствие товара во всём каталоге.
• Кандидат в аналоги требует проверки электрической и механической совместимости. Если характеристики источника противоречат друг другу, система не считает их совпадением.
• Демо-корзина не связана с настоящей корзиной или оплатой ekt.kz; данные в памяти исчезают после перезапуска backend.
• Для живого сценария нужны доступные EKT API и OpenAI API. Локальный офлайн-показ использует образцовые данные.
• Публичная развёрнутая версия не указана в репозитории. GitHub-репозиторий содержит исходный код, но не является ссылкой на deployed-приложение.