RedRed — AI-консультант для каталога ЕКТ

1. Название проекта

RedRed — веб-приложение с AI-консультантом для покупателей электротехнической продукции ЕКТ.

Репозиторий: BAITC-Hacks/hack-63e62cb7-redred.

2. Какую проблему решает проект

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

Решение предназначено для покупателей и специалистов, подбирающих электротехнические товары. Результат покупки в прототипе — сохранённая корзина приложения; оформление заказа на ekt.kz не выполняется.

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

Компонент	Возможности
Каталог	Поиск по названию и артикулу, категории, фильтры характеристик, наличия и документов, сортировка по цене, страницы по 20 товаров.
Карточка товара	Цена, общий остаток, характеристики, изображения и ссылки на документы, если они доступны в источнике.
AI-консультант	Диалог на русском, казахском и английском; поиск товаров, запрос характеристик и условий покупки, подбор кандидатов в аналоги, подготовка предложения для корзины.
Чат	История сообщений, HTTP- и WebSocket-транспорт, статусы обработки, передача частей ответа, подтверждение или отмена предложения.
Вложения	PDF, JPEG, DOCX и XLSX: до трёх файлов в сообщении, до 10 МБ каждый.
Корзина	Добавление после подтверждения, изменение количества и удаление позиций; проверка актуальной цены и наличия перед подтверждением.
Аккаунты	Гостевой режим, регистрация, вход и выход клиента; сохранение данных и обработка конфликта гостевой корзины с корзиной аккаунта. Избранное реализовано на уровне API.
React-админка	Обзор показателей, просмотр диалогов, управление синхронизацией каталога и её настройками, проверка и выбор AI-модели.
Синхронизация	Полный обход каталога ЕКТ или обновление загруженных карточек, запуск вручную и по расписанию, остановка, счётчики и история ошибок.

Администратор входит по отдельному серверному паролю. Регистрация клиента не предоставляет административный доступ.

4. Как работает решение

1. Пользователь открывает каталог и чат. Для начала диалога регистрация не требуется: приложение создаёт гостевую сессию.
2. Пользователь вводит название, артикул, вопрос о товаре или прикладывает файл со спецификацией.
3. FastAPI передаёт запрос и ограниченный контекст диалога AI-сервису. Модель вызывает серверные инструменты поиска, получения карточек, аналогов, условий покупки и истории.
4. Бэкенд проверяет структуру результата и ссылки на товары. Фронт показывает ответ, карточки и, при запросе покупки, предложение с количеством и стоимостью.
5. Пользователь явно подтверждает предложение. Бэкенд повторно получает цену и остаток из ЕКТ.
6. При успешной проверке товары записываются в корзину одной транзакцией. Пользователь видит результат на странице /cart. Если цена изменилась или товара недостаточно, приложение сообщает об этом.

Сам ответ модели не означает, что товар добавлен: изменение корзины требует отдельного подтверждения.

5. Технологии

Область	Используемые технологии
Фронтенд	TypeScript, React 19, Vite 8, Tailwind CSS 4, компоненты shadcn/ui и Radix UI, иконки Lucide, шрифт Geist.
Бэкенд	Python, FastAPI, Uvicorn, Pydantic, HTTPX, WebSocket.
Хранение	PostgreSQL 17, SQLAlchemy 2, asyncpg; вложения хранятся в серверной файловой системе.
AI	OpenAI Responses API, вызовы инструментов, структурированный результат и потоковая передача текста.
Модель	По умолчанию в конфигурации указана gpt-6-sol. Модель задаётся через OPENAI_MODEL; администратор может выбрать доступную модель после успешной проверки.
Внешние данные	API каталога ЕКТ с серверной Basic Auth, ссылки на документы и сведения об оплате и доставке ЕКТ.
Проверки	Python unittest, HTTPX ASGI-транспорт и подмены внешних API; TypeScript и сборка Vite.
Локальная инфраструктура	Docker Compose для PostgreSQL. Фронтенд и бэкенд запускаются отдельными процессами.

Модель не обучается в этом проекте. Ключи AI и учётные данные ЕКТ используются на сервере.

6. Архитектура проекта

flowchart LR
    U[Покупатель / администратор] --> F[React: каталог, чат, корзина, админка]
    F -->|HTTP / WebSocket| B[FastAPI]
    B --> D[(PostgreSQL)]
    B --> S[AI-сервис и серверные инструменты]
    S --> O[OpenAI Responses API]
    S --> C[Сервис каталога]
    B --> C
    C --> E[API ЕКТ]
    C --> D
    B --> A[Файлы вложений]

Основные директории и модули:

• frontend/src/components/store — каталог, карточки и корзина; chat — виджет консультанта; admin — панель администратора.
• backend/main.py — приложение FastAPI и подключение маршрутов.
• backend/chat.py и backend/assistant/ — обработка диалога, интеграция с моделью и разбор вложений.
• backend/catalog.py, ekt_client.py, catalog_sync.py — поиск по сохранённым карточкам, запросы ЕКТ и фоновое обновление.
• backend/cart.py, auth.py, sessions.py — корзины, аккаунты и сессии.
• backend/admin.py, admin_ai.py, ai_control.py — административный API и управление моделью.
• backend/models.py, migrate.py — модели данных и начальное создание схемы.
• backend/data/ — сохранённые карточки и справочные данные; backend/tests/ и tests/ — тесты; ai/ — диагностические скрипты AI.

PostgreSQL хранит каталог, сессии, аккаунты, сообщения, предложения, корзины и настройки. Приложение использует cookie и CSRF-токены для изменяющих запросов. В режиме разработки Vite перенаправляет /api на FastAPI.

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

Инструкция рассчитана на Windows PowerShell. Нужны Python 3.12, Node.js 22.12 или новее, npm, Git и работающий Docker с Compose. Для полного сценария требуются ключ OpenAI и учётные данные API ЕКТ.

В командах используется абсолютный путь C:\HackAlem\redred. Если репозиторий уже клонирован в другое место, замените этот префикс во всех командах. Порты 5432, 8000 и 5173 должны быть свободны.

Шаг 1. Получить проект и подготовить зависимости

git clone https://github.com/BAITC-Hacks/hack-63e62cb7-redred.git 'C:\HackAlem\redred'
py -3.12 -m venv 'C:\HackAlem\redred\backend\.venv'
& 'C:\HackAlem\redred\backend\.venv\Scripts\python.exe' -m pip install -r 'C:\HackAlem\redred\backend\requirements.txt'
npm --prefix 'C:\HackAlem\redred\frontend' ci

Шаг 2. Настроить окружение

В новом клоне создайте локальный файл конфигурации:

Copy-Item -LiteralPath 'C:\HackAlem\redred\.env.example' -Destination 'C:\HackAlem\redred\.env'

Заполните в .env следующие параметры:

Переменная	Значение / назначение
DATABASE_URL	postgresql+asyncpg://hackalem:[email protected]:5432/hackalem для PostgreSQL из Compose.
POSTGRES_PASSWORD, REDRED_DB_PORT	Для этого локального примера: hackalem и 5432; для сервера задайте собственный пароль.
SECURE_COOKIE	false для локального HTTP; для опубликованного HTTPS — true.
APP_ORIGIN	http://localhost:5173.
ADMIN_ORIGIN	Установите http://localhost:5173 для входа в админку через фронтенд.
ADMIN_PASSWORD	Задайте собственный пароль администратора; логин не требуется.
OPENAI_API_KEY	Ключ OpenAI с доступом к выбранной модели.
OPENAI_MODEL	Идентификатор модели; значение в примере — gpt-6-sol.
OPENAI_FALLBACK_API_KEY	Необязательный резервный ключ.
EKT_API_USERNAME, EKT_API_PASSWORD	Учётные данные API ЕКТ.
CATALOG_SYNC_ENABLED	Для первого запуска с сохранённой выборкой установите false. Ручная синхронизация доступна в админке.
UPLOAD_DIR	Каталог вложений; по умолчанию backend/uploads относительно корня проекта.

Бэкенд не загружает .env автоматически. В терминале, где будут запускаться миграция и FastAPI, выполните следующую команду. Она читает строки KEY=VALUE без вывода значений:

Get-Content -Encoding UTF8 -LiteralPath 'C:\HackAlem\redred\.env' | ForEach-Object { if ($_ -match '^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$') { [Environment]::SetEnvironmentVariable($matches[1], $matches[2].Trim().Trim([char]34).Trim([char]39), 'Process') } }

После изменения .env повторите загрузку переменных и перезапустите бэкенд. Реальные ключи и пароли не входят в репозиторий.

Шаг 3. Поднять PostgreSQL и загрузить начальные данные

docker compose -f 'C:\HackAlem\redred\compose.yaml' up -d db
docker compose -f 'C:\HackAlem\redred\compose.yaml' ps

Дождитесь состояния healthy у базы, затем в том же терминале выполните:

Set-Location 'C:\HackAlem\redred'; & 'C:\HackAlem\redred\backend\.venv\Scripts\python.exe' -m backend.migrate
Set-Location 'C:\HackAlem\redred'; & 'C:\HackAlem\redred\backend\.venv\Scripts\python.exe' -m backend.import_catalog --demo

Импорт добавляет 21 сохранённую карточку и не обращается к ЕКТ. Чтобы расширить каталог, после запуска откройте админку и выберите полный обход. Число товаров зависит от загруженных данных.

Шаг 4. Запустить бэкенд

В том же терминале с загруженными переменными окружения:

Set-Location 'C:\HackAlem\redred'; & 'C:\HackAlem\redred\backend\.venv\Scripts\python.exe' -m uvicorn backend.main:app --host 127.0.0.1 --port 8000

Шаг 5. Запустить фронтенд

В отдельном терминале:

npm --prefix 'C:\HackAlem\redred\frontend' run dev -- --host localhost --port 5173 --strictPort

Адрес	Назначение
http://localhost:5173	Каталог и чат.
http://localhost:5173/cart	Корзина.
http://localhost:5173/admin	Админка; пароль из ADMIN_PASSWORD.
http://127.0.0.1:8000/docs	Интерактивная документация API.
http://127.0.0.1:8000/health/	Проверка доступности процесса.
http://127.0.0.1:8000/ready	Проверка подключения к PostgreSQL.

Сборка фронтенда:

npm --prefix 'C:\HackAlem\redred\frontend' run build

Результат — frontend/dist. FastAPI может отдавать собранную админку по /admin и её ресурсы; для входа напрямую через порт 8000 нужно соответствующее значение ADMIN_ORIGIN. Без сборки этот маршрут возвращает FRONTEND_NOT_BUILT.

8. Как проверить решение

Сценарий для жюри

Предварительно запустите приложение, импортируйте начальную выборку и настройте действующие ключ OpenAI и доступ к ЕКТ.

1. Откройте http://localhost:5173 и найдите артикул 200300285_ из начальной выборки. Откройте карточку и посмотрите характеристики.
2. Откройте чат и отправьте: «Расскажи о товаре 200300285_: характеристики, наличие и документы». Ожидаемый результат — ответ консультанта с данными товара и доступными ссылками.
3. Отправьте: «Добавь 2 штуки товара 200300285_ в корзину». Если актуальные цена и остаток позволяют покупку, приложение должно показать предложение.
4. Проверьте, что до подтверждения корзина не изменилась. Подтвердите предложение кнопкой в чате.
5. Перейдите в корзину: должны отображаться товар, количество и стоимость. При недостатке остатка, изменении цены или ошибке внешнего API приложение должно показать отказ, а не успешную покупку.
6. Откройте http://localhost:5173/admin, войдите по заданному паролю. В разделе «Каталог» запустите обновление и проверьте прогресс и историю; в «Чатах» найдите диалог.
7. Для проверки расширенного каталога запустите полный обход и перейдите на следующую страницу витрины. API возвращает до 20 товаров за запрос, а total содержит общее число совпадений.

Цена, наличие, документы и время ответа зависят от внешних сервисов. Для проверки только интерфейса предусмотрен явный режим VITE_DEMO_MODE=true в frontend/.env.local; он не подтверждает работоспособность AI или интеграции ЕКТ и по умолчанию выключен.

Точечные проверки

Проверка контракта ассистента без реальных запросов к OpenAI и без БД:

Set-Location 'C:\HackAlem\redred'; & 'C:\HackAlem\redred\backend\.venv\Scripts\python.exe' -m unittest tests.test_assistant_service -v

Проверка входа администратора, CSRF, запуска и отмены синхронизации на тестовой БД с созданной схемой и собранным фронтендом; синхронизатор подменяется, обращения к ЕКТ не выполняются:

Set-Location 'C:\HackAlem\redred'; & 'C:\HackAlem\redred\backend\.venv\Scripts\python.exe' -m unittest backend.tests.test_admin_sync.AdminSyncTest.test_login_access_csrf_trigger_cancel_logout -v

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

• Каталог ЕКТ: https://ekt.kz/api/products и https://ekt.kz/api/products/detail. Сервер получает карточки через Basic Auth, сохраняет их в PostgreSQL и обновляет по запросу или расписанию.
• OpenAI: https://api.openai.com/v1/responses для диалога и обработки поддерживаемых вложений; /v1/models для списка моделей в админке. Используется store=false.
• Начальные данные: backend/data/demo_products.json содержит 21 сохранённую карточку ЕКТ с датой снимка 23 сентября 2026 года. Это снимки внешнего источника, а не собственный каталог команды и не гарантия актуальных остатков.
• Документы: backend/data/demo_documents.json содержит дополнительные ссылки на документы; карточки также используют сведения, полученные от ЕКТ.
• Условия покупки: backend/data/purchase_terms.json — сохранённые сведения со страницы https://ekt.kz/checkout-delivery/. В источнике отмечено расхождение порогов бесплатной доставки; приложение сохраняет это предупреждение.
• Внешние материалы: UI использует React, Tailwind, shadcn/ui, Radix UI, Lucide и Geist. Изображения, характеристики и документы товаров происходят из источников ЕКТ. Предобученная AI-модель предоставляется OpenAI.

PDF и JPEG передаются модели; из DOCX и XLSX извлекается ограниченный текст. Метаданные вложений хранятся в БД, сами файлы — на сервере.

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

• Корзина принадлежит RedRed: приложение не создаёт заказ на ekt.kz, не резервирует товар и не принимает оплату.
• Поиск охватывает загруженные карточки. До завершения синхронизации локальная база может содержать только часть каталога.
• Для автоматов и коробок единица — штука, шаг продажи берётся из положительной целой кратности KRATNOST_MIN карточки EKT. Четыре ранее проверенных товара сохраняют запасное правило при отсутствии кратности. Неизвестные категории и некорректная кратность блокируются. Проверены артикул 200300276_, 20 исходных карточек, кратность упаковки и отказ при неверном шаге; внешняя корзина после этого исправления ещё не проверена.
• Аналоги подбираются по заданным характеристикам для поддерживаемых категорий автоматических выключателей. Это кандидаты для проверки, а не гарантия инженерной взаимозаменяемости.
• Отображается общий остаток; выбор склада и бронирование не реализованы. Свежесть сохранённой карточки ограничена временем последнего обновления.
• Ответы AI и запросы ЕКТ зависят от доступности, прав доступа и задержек внешних API. Лимит обычного сообщения — 28 секунд, сообщения с вложениями — 40 секунд; внутренний лимит ассистента — 27,4 секунды, ожидание фронта — 50 секунд. Это предельные ожидания, а не обещанное время ответа.
• В контекст модели передаётся ограниченная история; поиск более ранних сообщений выполняется по словам внутри текущей сессии. Полная история не помещается в каждый запрос.
• Гостевая сессия по умолчанию действует 24 часа; вложения доступны в течение часа. Очистка истёкших данных запускается отдельной командой backend.cleanup.
• Подтверждение email и восстановление пароля не реализованы. Аккаунты RedRed не являются аккаунтами ekt.kz.
• XLSX-формулы не пересчитываются. Разбор офисных файлов ограничен объёмом текста; распознавание изображения не гарантирует точную идентификацию товара.
• Команда создания схемы не заменяет полноценное управление миграциями для произвольных будущих изменений БД. Нагрузочные гарантии и отказоустойчивый кластер в репозитории не заявлены.

11. Развёрнутая версия

Публичная версия: staffvision.ttvs.kz/red-red/.

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

Доступ для жюри

Данные входа в опубликованную версию предоставлены командой:

Роль	Адрес	Логин	Пароль
Клиент	Открыть сайт → кнопка входа в аккаунт	client	client
Администратор	Открыть админку	Не требуется	admin

В клиентском аккаунте можно проверить чат и корзину, в админке — каталог, диалоги, настройки синхронизации и AI-модели. Эти данные относятся к демонстрационному развёртыванию; для локального запуска пароль администратора задаётся через ADMIN_PASSWORD. Серверные ключи OpenAI и учётные данные API ЕКТ посетителю не нужны и в README не публикуются.

Локальный запуск описан в разделе 7. Публичное приложение размещено по префиксу /red-red/; фрагмент обратного прокси находится в deploy/red-red.nginx.conf.

Для публикации compose.yaml собирает и запускает PostgreSQL, backend и frontend с Nginx. Nginx раздаёт React, проксирует /api с поддержкой WebSocket и возвращает index.html для /cart, /admin и /admin/*. Инструкция запуска из архива приведена ниже.

Быстрый запуск из архива на сервере

Создание тестового клиента и настройка администратора скриптом

После заполнения .env выполните из корня проекта:

CLIENT_LOGIN='<логин>' CLIENT_PASSWORD='<пароль>' ADMIN_PASSWORD='<пароль администратора>' sh scripts/create-demo-accounts.sh

Скрипт обновляет только ADMIN_PASSWORD в .env, пересобирает контейнеры и создаёт клиента с отдельной сессией и корзиной. Повторный запуск не меняет пароль существующего клиента. Для admin-пароля скрипт принимает латинские буквы, цифры, _ и -. Клиент входит через «Логин или электронная почта»; публичная регистрация по-прежнему требует email и пароль минимум 8 символов. Админка использует только пароль, отдельного admin-логина нет. Проверены сборка frontend и четыре проверки валидации/хеширования; создание аккаунта на целевой БД ещё не проверено.

Публикация через Staffvision в /red-red/

Целевой адрес: https://staffvision.ttvs.kz/red-red/, админка: https://staffvision.ttvs.kz/red-red/admin/catalog. В .env: VITE_BASE_PATH=/red-red/, APP_ORIGIN=https://staffvision.ttvs.kz, ADMIN_ORIGIN=https://staffvision.ttvs.kz, SECURE_COOKIE=true, REDRED_BIND_ADDRESS=127.0.0.1, REDRED_FRONTEND_PORT=8083. Origin не содержит путь. Заполните пароли и ключи, затем выполните docker compose up -d --build --wait --wait-timeout 180.

На том же сервере скопируйте location-фрагмент:

sudo mkdir -p /etc/nginx/snippets
sudo install -m 644 deploy/red-red.nginx.conf /etc/nginx/snippets/red-red.conf
sudo grep -Rl 'server_name.*staffvision.ttvs.kz' /etc/nginx/sites-enabled /etc/nginx/conf.d

В найденном конфигурационном файле добавьте внутрь существующего HTTPS-блока server для Staffvision строку include /etc/nginx/snippets/red-red.conf;. Существующие location и конфигурацию Staffvision сохраняйте. Фрагмент рассчитан на Nginx, установленный непосредственно на сервере; для Nginx в контейнере нужен доступный ему upstream вместо 127.0.0.1.

sudo nginx -t && sudo systemctl reload nginx
curl -fsS https://staffvision.ttvs.kz/red-red/ready
curl -fsS 'https://staffvision.ttvs.kz/red-red/api/products?limit=1'

Прокси снимает /red-red/ перед передачей контейнеру, сохраняет WebSocket Upgrade и ограничивает cookie путём /red-red/. Frontend собирается с этим префиксом, админка определяет префикс из своего URL. После изменения VITE_BASE_PATH нужна пересборка frontend. Публикация на внешнем сервере пока не проверена.

Прямой запуск по IP (альтернатива)

Для этого варианта дополнительно задайте VITE_BASE_PATH=/ и REDRED_BIND_ADDRESS=0.0.0.0; origin и cookie настройте как указано ниже.

Нужен Linux-сервер с Docker Engine и Docker Compose v2, доступом к интернету для сборки и открытым TCP-портом 8083. Python, Node.js и PostgreSQL на сервер вручную устанавливать не нужно.

unzip redred-server.zip
cd redred
cp .env.example .env
nano .env
docker compose up -d --build --wait --wait-timeout 180

В .env задайте POSTGRES_PASSWORD (длинный случайный пароль из букв и цифр), APP_ORIGIN=http://SERVER_IP:8083, ADMIN_ORIGIN=http://SERVER_IP:8083, ADMIN_PASSWORD, OPENAI_API_KEY, EKT_API_USERNAME и EKT_API_PASSWORD. Origin должен точно совпадать с адресом в браузере, без пути и завершающего /. Для HTTP оставьте SECURE_COOKIE=false; для HTTPS за внешним прокси задайте оба HTTPS-origin и SECURE_COOKIE=true. При изменении порта измените REDRED_FRONTEND_PORT и оба origin. Внешний прокси должен пропускать WebSocket Upgrade для /api/chat/ws. TLS-сертификат в этот Compose не входит.

Откройте http://SERVER_IP:8083/, корзину /cart, админку /admin/catalog. Nginx раздаёт frontend и проксирует API, WebSocket и админку; backend ждёт готовности PostgreSQL, создаёт схему и загружает 21 исходную карточку только в пустой каталог. База и вложения сохраняются в Docker volumes при перезапуске. Не выполняйте docker compose down -v, если нужно сохранить данные. DATABASE_URL из .env заменяется в контейнере адресом внутренней БД. Пароль уже созданной БД нельзя сменить простым изменением .env.

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

docker compose ps
curl -fsS http://localhost:8083/ready
curl -fsS 'http://localhost:8083/api/products?limit=1'
docker compose logs --tail=50 backend

В браузере проверьте каталог, отправку сообщения в чат и подтверждение добавления в корзину. Живые ответы AI требуют действующего ключа и квоты, свежие карточки и подтверждение корзины — доступного EKT API. Без этих доступов начальный каталог не означает работоспособность внешних интеграций.

Повторная упаковка актуальных исходников из репозитория: python scripts/package_release.py. Результат — release/redred-server.zip. Архив содержит исходники и .env.example, исключает рабочие .env, зависимости, локальные загрузки и отчёты. Передавайте рабочий .env отдельно либо заполните его на сервере. Контейнерные образы собираются на сервере; архив не является офлайн-поставкой Docker images.