EKT AI — умный консультант электротоваров

Прототип команды «Метрологи»: помогает покупателю или закупщику найти товар, сравнить характеристики и кандидатов в аналоги, узнать условия покупки и собрать корзину после явного подтверждения. Менеджер подключается там, где каталога недостаточно.

Статус: подготовлена интеграционная сборка на базе codex/ekt-site-v03 и Backend 0.3. Внешний стенд ещё не опубликован: ожидается доступ к Python/Docker-хостингу. http://127.0.0.1:5173 — локальный адрес, недоступный жюри с другого компьютера. Итоговая приёмка и блокеры · Развёртывание · Интерфейс · API · Корзина

Локальный запуск

Нужен Python 3.11+. Из корня репозитория в PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend/requirements.lock
.\.venv\Scripts\python.exe -m pip install --no-deps -e ./backend
.\.venv\Scripts\python.exe run_demo.py

Откройте http://127.0.0.1:5173. Один процесс FastAPI обслуживает /, /api/* и /cart. Ctrl+C останавливает сервис. В Linux/macOS замените .venv\Scripts\python.exe на .venv/bin/python.

Запуск создаёт отдельную backend/data/demo.sqlite3 с тремя синтетическими товарами, включает корзину и выключает EKT/OpenAI-вызовы. Ключи не нужны. Снимок актуален один час; для повторной демонстрации перезапустите процесс. Основная catalog.sqlite3 не меняется.

Альтернатива с Docker: docker compose up --build, тот же локальный адрес. Compose включает только синтетический режим и хранит SQLite в именованном volume. Не публикуйте эту локальную конфигурацию напрямую; для HTTPS используйте инструкцию развёртывания.

Сценарий демонстрации

1. Введите DEMO-001: покажутся нулевой остаток, характеристики и кандидат DEMO-002.
2. Объясните совпадения характеристик и предупреждение о проверке совместимости специалистом.
3. Для DEMO-002 выберите количество 2. Откроется предложение; корзина ещё не изменена.
4. Нажмите «Подтвердить»: появятся 2 единицы и ссылка /cart на актуальную корзину сессии.
5. Откройте корзину; изменение количества, удаление и очистка также требуют подтверждения.

Суммы KZT/шт в тестовой корзине — условные правила демонстрации. Это не предложения EKT. Корзина принадлежит прототипу: нет оплаты, резерва и оформления заказа на ekt.kz.

Архитектура и данные

Браузер: HTML/CSS/JS → один origin FastAPI
                     ├─ ChatService → OpenAI: намерение и краткий контекст (опционально)
                     ├─ Catalog → SQLite: факты, характеристики и время получения
                     ├─ EktClient → только GET: явное обновление реальной карточки
                     ├─ условия покупки → проверенный JSON со сроком действия
                     └─ DemoCart → предложение → явное подтверждение → корзина сессии

Модель не назначает цену/остаток и не изменяет корзину. Backend повторно проверяет предложение, цену и остаток; изменение данных требует нового подтверждения. Повтор запроса с тем же идентификатором не дублирует действие. request_id и message_id сохранены. Сессии, корзины и история находятся в памяти одного процесса и исчезают при перезапуске. Токен чата хранится только в памяти страницы; /cart использует HttpOnly cookie без токена в URL. При повторном открытии вкладки продолжается действующая сессия браузера без продления TTL. Явный «Новый диалог» завершает её для всех вкладок; независимые профили изолированы.

Источники: backend/examples/demo_catalog.json — синтетические данные; EKT API — опциональная репрезентативная выборка, требующая серверного доступа. В реальном API валюта и единица измерения не подтверждены; их нельзя подставлять по догадке. Общий остаток не гарантирует отгрузку: правила складов и минимальные партии ещё требуют согласования.

Условия — backend/examples/purchase_terms.ekt.json: снимок официального сайта, проверенный 23.09.2026, действует до 23.10.2026. Источники и расхождения указаны в JSON. Истёкшие/непроверенные условия не выдаются за актуальные. Отсутствие данных о сертификате не означает отсутствие сертификата. Вложения, эскалация менеджеру и встраивание в ekt.kz пока не реализованы.

OpenAI и реальный каталог

Из backend/ скопируйте .env.example в .env и настройте серверные значения. Ключи не отправляйте в браузер и Git. Без OPENAI_API_KEY работает базовый разбор (rules); точный артикул обрабатывается каталогом (catalog). При настроенном ключе используется OpenAI Responses API; модель задаёт OPENAI_MODEL (доступность зависит от аккаунта).

cd backend
Copy-Item .env.example .env
# После настройки EKT_USERNAME / EKT_PASSWORD:
..\.venv\Scripts\python.exe -m app.import_catalog --pages 6 --max-details 100 --concurrency 2 --timeout 10 --report data/import-report.json
# Подключить проверенный снимок условий:
Copy-Item examples/purchase_terms.ekt.json data/purchase_terms.json
..\.venv\Scripts\python.exe ../run_server.py

Откройте локальный http://127.0.0.1:8000. Frontend обслуживается тем же сервером. Для корзины реальных товаров нужны DEMO_CART_ENABLED=true и EKT_LIVE_ENABLED=true: сервер перепроверяет карточку перед предложением и подтверждением. Ошибка API блокирует действие. Частичный импорт завершается кодом 2; проверьте отчёт. Нет фоновой полной выгрузки каталога.

Проверки и выпуск

cd backend
..\.venv\Scripts\python.exe -m pytest -q
..\.venv\Scripts\python.exe -m ruff check . ../run_server.py ../run_demo.py
..\.venv\Scripts\python.exe -m pip check

GitHub Actions запускает backend-проверки и сборку Docker с проверкой основных маршрутов. Фактические результаты текущего прогона и ограничения находятся в docs/final-qa.md; исторические отчёты docs/backend-qa.md и docs/site-qa.md относятся к прежним ревизиям.

Публичный стенд требует HTTPS, PUBLIC_DEMO=true, серверных секретов входа, CART_COOKIE_SECURE=true и точного TRUSTED_PROXY_IPS. Защита включает общий лимит запросов, в том числе новых сессий, и максимальный размер тела. Лимиты сбрасываются при перезапуске и не заменяют денежный лимит провайдера. Один worker и одна реплика обязательны. Слияние интеграционного PR в main — после ревью команды.