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

Веб-приложение для кейса ТОО «Электрокомплект» на HACKALEM AI. Помогает покупателю подобрать товары ekt.kz в одном чате: описать задачу обычными словами, приложить фото или спецификацию, проверить характеристики и наличие, выбрать количество и собрать корзину.

Текущий результат — работающий прототип с настоящими API каталога и OpenAI. Корзина демонстрационная: она не оформляет заказ в ekt.kz.

Что умеет консультант

• Ищет товары по названию, артикулу, описанию задачи и контексту диалога.
• Принимает фото JPEG/PNG, Excel XLS/XLSX, Word DOCX, текстовые и сканированные PDF. Старый DOC нужно сохранить как DOCX.
• Показывает карточки с фото, описанием, характеристиками, ценой, наличием и прямой ссылкой на товар. Сертификат доступен, если его ссылка есть в API.
• По фото определяет видимый тип, форму, бренд и читаемую маркировку, затем предлагает кандидатов из каталога. Похожие модели могут потребовать дополнительного фото этикетки: точный артикул по внешнему виду не гарантируется.
• Предлагает аналоги с объяснением совпадающих характеристик. Если доказательств совместимости мало, честно сообщает об этом.
• Отвечает об оплате, доставке и минимальной партии со ссылками на источники EKT.
• Добавляет выбранное количество только после явного подтверждения, повторно проверяет цену и остаток. Позволяет удалить позицию и перейти к текущей корзине.
• Отвечает на русском и казахском. Сохраняет переписку и черновик при обновлении текущей вкладки; прокручивает чат к новому ответу.

Пример: «Нужен светильник для офиса» → уточнение параметров → карточки → выбор количества → «Да, добавить» → ссылка на корзину.

Почему настоящая корзина ekt.kz не подключена

Партнёр предоставил BasicAuth-доступ только к чтению каталога:

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

В полученном комплекте нет API корзины и оформления заказа, документации покупательской авторизации и тестовой сессии покупателя. Логин каталога позволяет читать товары; он не предоставляет подтверждённого способа изменять корзину посетителя сайта. Поэтому по переданным данным корректно реализовать запись в настоящую корзину мы не смогли.

Для демонстрации реализована отдельная корзина прототипа с проверкой остатков, количества и явного согласия. Она открывается по /cart, а её статус явно показан в интерфейсе. Она не изменяет корзину ekt.kz, не резервирует товар и не отправляет заказ или оплату. Это незакрытая внешняя интеграция, а не подключённый checkout магазина.

Чтобы подключить настоящую корзину, от партнёра нужны:

1. Документация чтения, добавления, изменения количества и удаления позиций.
2. Способ связывать чат с покупательской сессией и тестовая среда/учётная запись.
3. Правила складов, цены, кратности, резервирования, ошибок и повторных запросов.
4. Ссылка на оформление заказа и разрешённый способ встраивания чата в сайт.

Запуск за несколько шагов

Нужны Git, Python 3.12 и Node.js 22.12+ с npm. GPU и база данных для прототипа не нужны. Для клонирования приватного репозитория необходим выданный доступ.

git clone https://github.com/BAITC-Hacks/hack-08ee446c-apexsoft.git
cd hack-08ee446c-apexsoft
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\python.exe -m pip install -r requirements.lock
npm --prefix frontend ci
npm --prefix frontend run build
.\.venv\Scripts\python.exe scripts/run.py --prompt-secrets

Linux/macOS:

.venv/bin/python -m pip install -r requirements.lock
npm --prefix frontend ci
npm --prefix frontend run build
.venv/bin/python scripts/run.py --prompt-secrets

Введите логин/пароль EKT и ключ OpenAI в приглашениях терминала. Пароль и ключ вводятся скрыто и остаются в памяти процесса. Откройте http://127.0.0.1:8000.

Для демонстрации без внешних сервисов запустите без --prompt-secrets: будут использоваться явно обозначенные синтетические товары и ограниченный текстовый поиск. Полноценное понимание диалога, фото и сканов требует OpenAI.

Настройки окружения

Переменная сервера	Назначение
EKT_API_USERNAME, EKT_API_PASSWORD	Доступ к живому каталогу; без полной пары — синтетический режим
OPENAI_API_KEY	Ключ для интерпретации текста, фото и сканов
OPENAI_MODEL	По умолчанию gpt-4.1-mini; нужна поддержка изображений и строгого JSON в Responses API
HOST	Локально 127.0.0.1; в облаке 0.0.0.0
PORT	По умолчанию 8000; в облаке — значение платформы
EKT_SECURE_COOKIE	false для локального HTTP, true для публичного HTTPS
EKT_INDEX_PAGES	Предел фоновой индексации, по умолчанию 1000 страниц

.env.example показывает названия настроек. Файл .env автоматически не загружается. Передавайте переменные окружением процесса или через настройки хостинга. Не помещайте ключи в frontend, Git, аргументы команд или публичные документы.

Развёртывание на своём хостинге

Пошаговая инструкция: docs/DEPLOYMENT_RU.md.

Платформа	Подход
Railway	Всё приложение одним сервисом из корневого Dockerfile
VPS / контейнерный хостинг	Тот же Docker-образ за HTTPS-прокси
Vercel / CDN	Интерфейс как статика, а /api/* проксируется на постоянно работающий backend в Railway или на VPS

Для текущего прототипа нужны один серверный процесс и одна реплика: сессии, корзины и индекс находятся в оперативной памяти. Перезапуск очищает их. Полный backend в масштабируемых Functions требует общего хранилища и отдельной индексации; один только CDN серверную часть не выполняет.

Dockerfile и конфигурация Railway входят в репозиторий. Облачное развёртывание и сборка Docker-образа этой версии ещё не проверены: локальные тесты не выдаются за проверку облака. В инструкции приведена обязательная проверка после деплоя.

Проверка после запуска

1. Откройте /api/health: посмотрите режимы catalog, ai, cart, число indexed_products и index_complete. Индекс загружается в фоне. status: ok подтверждает работу процесса, а не доступность внешних API.
2. В демо-режиме найдите 900001: ожидается отсутствующий товар и аналог 900002. В живом режиме попробуйте артикул 150200334_ и сравните текущие данные с магазином.
3. Прикрепите фото маркировки или документ с артикулом. Ответ должен относиться к вложению; корзина сама не меняется.
4. Выберите количество, отмените предложение, затем повторите и подтвердите. Проверьте состав по /cart и удаление позиции.
5. Обновите страницу: переписка и черновик должны сохраниться. Проверьте интерфейс в мобильном размере.

Автоматические проверки не требуют внешних ключей:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts/check_secrets.py
npm --prefix frontend test -- --maxWorkers=2
npm --prefix frontend run build

На Linux/macOS используйте .venv/bin/python. Тесты проверяют подтверждения, остатки, повторные запросы, изоляцию сессий, вложения, ошибки API и интерфейс. Реальные OpenAI/EKT проверяются отдельно. Методика · Матрица требований.

Архитектура

React + TypeScript: чат, карточки, вложения, корзина
                    │ /api по одному домену
FastAPI: сессии, CSRF, поиск, правила подтверждения
    ├── OpenAI: понимание текста и изображений
    ├── EKT API: карточки, цены и остатки
    └── память процесса: индекс, контекст, демо-корзина

ИИ интерпретирует запрос. Цены и остатки берутся из каталога; изменение корзины выполняет сервер после подтверждения. Модель самостоятельно заказ не оформляет.

backend/ — сервер; frontend/ — интерфейс; tests/ — серверные проверки; scripts/ — запуск и проверка секретов. Версии библиотек закреплены в requirements.lock и frontend/package-lock.json. Контракт API · Подробная локальная настройка.

Ограничения и данные

• Фото даёт кандидатов по видимым признакам; аналог не означает гарантированную электрическую совместимость.
• API и региональная витрина могут показывать разные цены/остатки. При недоступном источнике данные не выдумываются. Сертификат показывается только при наличии ссылки.
• Один файл — до 8 MiB. PDF — до 30 страниц, до 4 страниц со сканами/графикой распознаются как изображения; об ограничении сообщается. Автоматического пакетного заказа по спецификации нет.
• Переписка хранится в текущей вкладке; серверная сессия — до двух часов бездействия. Перезапуск сервера очищает контекст и корзину. Это не постоянная история авторизованного клиента.
• Текст и выбранные вложения передаются OpenAI с store:false. Не отправляйте платёжные или конфиденциальные данные. Проверка платёжных форматов в тексте не является универсальным DLP изображений.
• Одиночные живые запросы проверены в пределах нескольких секунд; это не SLA под нагрузкой. Промышленная установка на ekt.kz, долговременное хранилище и реальная корзина требуют дальнейшей интеграции.

Данные каталога и условий принадлежат EKT. Синтетический набор создан для воспроизводимой демонстрации; собственная языковая модель не обучалась. Сторонние библиотеки и подробные пределы.