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

Сайт на FastAPI с чатом, поиском реальных товаров EKT и локальной корзиной. Главная страница — /, чат — /chat.html, корзина — /cart.html, документация API — /docs.

Стек технологий

• Backend: Python 3.11+, FastAPI, Uvicorn.
• ИИ: OpenAI API, OpenAI Agents SDK; модель по умолчанию — gpt-4.1-mini.
• Интеграция с каталогом: EKT API, HTTPX и Basic Auth.
• Данные и настройки: Pydantic, pydantic-settings, переменные окружения из .env.
• Frontend: HTML, CSS и JavaScript без фреймворка.
• Хранение: сессии, корзина и временный поисковый индекс находятся в памяти процесса.
• Тестирование: unittest.

Что умеет

• ИИ отвечает на вопросы о товарах EKT, помогает подобрать оборудование, показывает характеристики, цену и остаток из API EKT. На посторонние вопросы кратко возвращает разговор к товарам магазина.
• Для поиска по обычному описанию («вилка с прямым вводом») сервер читает страницы /api/products?page=N и создаёт временный индекс. EKT API игнорирует параметры текстового поиска. Первый поиск по словам может занять десятки секунд; индекс хранится 10 минут. Русские окончания и ё/е приводятся к общей форме.
• Запросы вроде «недорогой шуруповёрт» сортируются по цене из списка товаров. Перед ответом о цене и остатке ИИ запрашивает свежую карточку /api/products/detail?id=.... Если достигнут лимит EKT_SEARCH_PAGES, результат относится только к просмотренной части каталога.
• Числовой ID ищется сразу через карточку без обхода страниц.
• Корзина хранится только в памяти приложения. Добавление сначала создаёт предложение, затем пользователь подтверждает его кнопкой. Заказ и резерв на ekt.kz не создаются.

Требования

Python 3.11+, доступ к EKT API по выданным Basic Auth данным, ключ OpenAI и сеть. Зависимости перечислены в requirements.txt. Пароли и ключи находятся только на сервере в .env; браузеру они не передаются. Файл .env исключён из Git.

Запуск на Windows

В PowerShell из корня проекта:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
if (-not (Test-Path .env)) { Copy-Item .env.example .env }

Заполните в .env:

OPENAI_API_KEY=ваш_ключ_OpenAI
EKT_USERNAME=логин_Basic_Auth
EKT_PASSWORD=пароль_Basic_Auth

Если .env уже заполнен, сохраните его. Остальные параметры можно оставить как в шаблоне. Запустите:

.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Откройте http://127.0.0.1:8000/ и перейдите в чат. После изменения .env перезапустите сервер. Используйте один worker: сессии, корзины и индекс поиска хранятся в памяти процесса.

Как пользоваться

1. Напишите «Найди вилку с прямым вводом» или «Найди недорогой шуруповёрт». Первый поиск по названию сканирует каталог; следующие используют индекс.
2. Уточните параметры: «Нужна вилка 16 А, IP44» или «Покажи характеристики артикула …». Можно спросить по числовому ID, например «Какая цена у товара 515291?».
3. При запросе на добавление укажите товар и количество. Проверьте карточку и нажмите «Подтвердить добавление». В корзине отображаются только локально подтверждённые позиции.
4. Для документов загрузите PDF, JPEG, DOCX или XLSX размером до 5 МиБ. ИИ сопоставит найденные в файле позиции с каталогом.

Чат помогает только с темами EKT и электротоваров. Условия оплаты и доставки, отсутствующие в выданном API, он предлагает уточнить у менеджера. Цена и наличие могут измениться после ответа; при подтверждении корзины они проверяются снова.

Настройки

Переменная	Значение по умолчанию	Назначение
OPENAI_API_KEY	пусто	Ключ OpenAI, обязателен
OPENAI_MODEL	gpt-4.1-mini	Модель для диалога и инструментов
EKT_USERNAME, EKT_PASSWORD	пусто	Basic Auth EKT, обязательны
EKT_BASE_URL	https://ekt.kz	Зафиксированный HTTPS-хост
EKT_SEARCH_PAGES	400	Максимум страниц для текстового поиска
CHAT_TIMEOUT_SECONDS	120	Общий лимит времени ответа чата
REQUEST_TIMEOUT_SECONDS	15	Лимит одного запроса к EKT
SESSION_TTL_SECONDS	3600	Срок сессии
MAX_SESSIONS	1000	Лимит одновременных сессий
CORS_ORIGINS	localhost:5500 и 127.0.0.1:5500	Разрешённые адреса отдельного frontend

Если ключи отсутствуют, приложение завершает запуск с ошибкой конфигурации. Список товаров загружается с EKT через Basic Auth на сервере. Переадресации HTTP отключены. Пустой остаток и неизвестный остаток различаются.

API

Все пути начинаются с /api/v1.

Метод и путь	Назначение
GET /health	Проверка процесса
GET /products?page=1	Страница каталога EKT
GET /products?q=вилка+с+прямым+вводом	Поиск по описанию
GET /products?q=шуруповерт&sort=price_asc	Поиск с сортировкой по цене
GET /products/515291	Свежая карточка товара
GET /products/{id}/alternatives	Проверенные аналоги, если хватает свойств
GET /purchase-terms	Известные условия и пометка источника
POST /sessions	Создать сессию и получить Bearer-токен
POST /sessions/{id}/chat	Сообщение: {"message":"Найди недорогой шуруповёрт"}
POST /sessions/{id}/chat/attachment	Файл как raw body с его Content-Type
GET /sessions/{id}/cart	Локальная корзина
POST /sessions/{id}/cart/proposals	Предложение: {"product_id":"515291","quantity":"2"}
POST /sessions/{id}/cart/proposals/{action_id}/confirm	Подтверждение: {"confirmed":true}

Маршруты с /sessions/{id} требуют заголовок Authorization: Bearer <access_token>. Токен создаётся через POST /sessions и хранится браузером в sessionStorage. В Swagger на /docs его можно указать через кнопку Authorize. Сессия и корзина исчезают после истечения срока или перезапуска процесса.

Проверка

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Автоматические тесты используют подменённый EKT-клиент и модель, поэтому не расходуют внешний API. Для ручной проверки откройте /api/v1/health, затем /api/v1/products/515291 и задайте в чате вопрос о том же ID. Для поиска по описанию попробуйте примеры выше и проверьте, что карточки содержат реальные ID и артикулы EKT.