HackAlem AI · EKT product assistant

Локальный MVP для торгового кейса HackAlem AI: помогает найти товар в каталоге EKT по артикулу или названию, показать сведения о товаре, характеристики и остаток, ответить на вопросы о сертификате и условиях покупки, предложить альтернативу и провести подтверждаемое добавление в demo-корзину.

Реальная интеграция каталога обращается к двум endpoint’ам EKT, описанным в клиенте проекта. Реальный API в рамках этого README не считается проверенным; demo-режим предназначен для демонстрации сценария без реального API.

Архитектура

Браузер: UI и чат
    │ POST /api/chat
    ▼
app.py: разбор запроса, поиск, ответ и сценарий корзины
    ├── --demo → синтетический каталог, demo-сертификат/условия,
    │            корзина в памяти сессии; запросов к EKT API нет
    └── live   → ekt_api_client.py → GET /products
                                  → GET /products/detail?id=…

В demo-режиме каталог и корзина хранятся в памяти процесса. Товар сначала предлагается с количеством и доступным остатком. Корзина меняется только после явного подтверждения; после добавления доступна ссылка на страницу demo-корзины. Сервер обслуживает UI, чат и страницы demo-корзины/сертификата на loopback-адресе.

В live-режиме app.py получает каталог и карточку товара через ekt_api_client.py. Клиент использует Basic Authentication и ожидает параметры окружения, перечисленные ниже. Реальное оформление заказа и изменение корзины через EKT API в этом MVP не подключены.

Технологии и зависимости

• Python 3.10 или новее.
• HTTP-сервер и UI реализованы в app.py на стандартном HTTP-сервере Python; интерфейс — HTML, CSS и JavaScript без frontend-фреймворка.
• HTTP-запросы, JSON и Basic Authentication реализованы в ekt_api_client.py стандартной библиотекой Python.
• Внешних Python-пакетов нет. requirements.txt не требуется.
• Тесты используют стандартный модуль unittest.

Основные файлы

Файл	Назначение
app.py	Веб-интерфейс, HTTP-обработчики, нормализация каталога, demo-логика условий/сертификатов и корзины
ekt_api_client.py	Клиент endpoint’ов каталога EKT и безопасная обработка ошибок API
test_app.py	Regression-тесты сценариев сертификатов и demo-корзины
.env.example	Имена параметров с фиктивными примерами для локальной настройки
.gitignore	Исключает .env, секреты, ключи и Python-кэш из Git

Требования и подготовка окружения

Нужен Python 3.10+ и браузер. Внешние библиотеки устанавливать не нужно. Убедитесь, что Python доступен:

python --version

Если команда python не найдена, в Windows можно проверить launcher:

py -3 --version

Для изолированной среды (необязательно) создайте и активируйте виртуальное окружение:

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1

Зависимости через pip install устанавливать не требуется. Если Python отсутствует, установите Python 3.10+ подходящим для вашей Windows способом. В текущей среде Codex также может быть доступен bundled-интерпретатор, если python/py не зарегистрированы в PATH.

Запуск demo

Из корня проекта выполните:

python app.py --demo

Откройте http://127.0.0.1:8000. В заголовке страницы будет явная отметка demo-режима.

В среде Codex Windows, где Python не добавлен в PATH, можно запустить demo через bundled-интерпретатор из PowerShell:

& "$env:USERPROFILE\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" app.py --demo

Проверка основного demo-сценария

В чате выполните действия по порядку:

1. Найдите товар: DEMO-101.
2. Проверьте карточку — название, характеристики и demo-остаток.
3. Спросите сертификат DEMO-101 и откройте ссылку на синтетический макет. Для проверки честного отсутствия сертификата запросите сертификат DEMO-102.
4. Проверьте альтернативы запросом лэптоп: это синоним категории, которого нет в названиях demo-товаров. Для проверки неподдерживаемых требований запросите laptop RTX 4090 — система не должна предлагать неподтверждённую модель.
5. Спросите оплата, доставка и минимальная партия.
6. Предложите товар в корзину: добавь 2 DEMO-101. Бот покажет товар, количество и доступный остаток, но пока не изменит корзину.
7. Подтвердите отдельным сообщением: да, добавь.
8. Выполните покажи корзину: проверьте позиции, количества, итог по позициям/единицам и ссылку на demo-корзину.

Для проверки ограничения количества попробуйте предложить добавь 9 DEMO-101: demo-остаток этого товара — 8 штук, поэтому предложение будет отклонено без изменения корзины.

Ограничения demo-режима

• Каталог, остатки, характеристики, сертификат и условия покупки синтетические. Они не описывают реальные товары, остатки, документы или условия EKT.
• Demo-сертификат — текстовый макет, не официальный документ и не подтверждение соответствия.
• Demo-корзина хранится только в памяти процесса и очищается при его перезапуске.
• Оплата, оформление настоящего заказа и резервирование товара не выполняются. Платёжные данные не запрашиваются.
• Demo-режим не вызывает EKT API. Для live-режима нужны действительные параметры доступа и доступность API; этот README не утверждает, что live API был протестирован.

Параметры реального EKT API

Live-режим читает следующие переменные окружения процесса:

Переменная	Назначение
EKT_API_BASE_URL	Базовый URL API, предоставленный EKT
EKT_API_USERNAME	Имя пользователя API
EKT_API_PASSWORD	Пароль API

Задайте значения локально в окружении процесса. Не публикуйте и не коммитьте реальные значения. Приложение не загружает .env автоматически; .env предназначен только для локальной работы и не должен попадать в Git. .gitignore исключает .env и .env.*, оставляя .env.example с фиктивными значениями-шаблонами.

Поддерживаемые клиентом запросы: GET /products (необязательный параметр page) и GET /products/detail?id=…. Поля фактического ответа EKT и доступность live API следует подтвердить отдельным smoke-test после безопасной настройки переменных.

Тесты и проверки

Из корня проекта:

python -m unittest discover -v
git diff --check