EKT Match — SAQ Digital

Помощник для подбора электротехники: принимает запрос по характеристикам или артикулу, показывает цену и остаток, предлагает кандидатов в аналоги и добавляет товар в корзину после явного подтверждения.

Проект объединяет React-интерфейс, Express API и каталог: в offline это 40 синтетических SKU, а в live с доступом партнёра — товары из API ekt.kz. Основной offline-сценарий работает локально без интернета, аккаунтов и API-ключей после установки зависимостей или сборки Docker-образа.

Запуск одной кнопкой через Docker

Установите и запустите Docker Desktop с Linux-контейнерами и Docker Compose v2+. В Windows откройте start.cmd двойным кликом: он соберёт приложение, запустит его в фоне и дождётся успешной проверки готовности. Локальные Node.js и npm для этого не нужны. Первый запуск загружает образ Node.js и зависимости.

Та же команда для Windows, macOS, Linux и сервера:

docker compose up --build --wait --remove-orphans

Откройте http://localhost:8080. В Docker Desktop появится проект ekt-match с двумя сервисами: frontend (Nginx и интерфейс) и backend (Express, каталог, OpenAI и корзина). Backend доступен внутри сети Docker; Frontend передаёт ему запросы /api. Повторный запуск применяет изменения к тому же проекту и удаляет прежний общий контейнер app. После первой сборки запускать и останавливать проект можно кнопками Docker Desktop.

docker compose logs -f frontend backend
docker compose down

Если порт занят, измените APP_PORT в корневом .env и повторите запуск. Есть эквивалентные команды npm: docker:up, docker:logs, docker:down. Подробности образа, окружения и размещения на сервере: docs/deployment.md.

Разработка без Docker

Требуется Node.js 22.10+ и npm. Проверено на Node.js 24.11.1 и npm 11.6.2. Команды выполняются из корня репозитория в Windows, macOS или Linux:

npm run setup
npm run dev

Откройте http://localhost:5173. Команда запускает Backend и Vite вместе; запросы /api проксируются на Backend. Остановка — Ctrl+C. Frontend обновляется через Vite; после изменения Backend перезапустите общую команду. Отдельный режим watch Backend: npm --prefix backend run dev.

setup устанавливает Frontend через существующий lock-файл, а Backend — без создания lock-файла, согласно правилам репозитория. Backend нужен также для интеграционных тестов Frontend.

Собранное приложение

npm run build
npm start

Откройте http://localhost:3001. Express раздаёт API и готовый Frontend, включая /cart. Vite для этого режима не требуется. npm run preview запускает тот же режим. Открывайте сборку через сервер, а не как локальный HTML-файл: интерфейс обращается к API.

Структура проекта

frontend/                 React + TypeScript + Vite
  src/components/         Чат, карточка товара, страница корзины
  src/lib/                Клиент API и форматирование
  src/test/               Подключение Backend для тестов интерфейса
  config.json             Порт UI, адрес API и demo-запрос
  package-lock.json       Существующий lock-файл Frontend
backend/                  Express + Zod, JavaScript ESM
  src/                    API, каталог, подбор, сессии, корзина, адаптеры
  test/                   Тесты Backend и интеграция с demo-данными
  config.json             Порт, пути данных, настройки адаптеров
  purchase-terms.json     Локальный снимок условий со ссылкой на источник
data/catalog.json         Общий каталог: 40 синтетических SKU
docs/                     Контракты, сценарии, описание интеграции
deploy/Dockerfile          Отдельные образы Frontend и Backend
deploy/nginx.conf.template Раздача UI и proxy /api к Backend
scripts/dev.mjs           Общий запуск приложения в разработке
compose.yaml              Запуск Docker, порт, окружение, перезапуск
start.cmd                 Запуск Docker двойным кликом в Windows
package.json              Команды разработки, проверок и Docker
.env.example              Необязательные настройки окружения

Браузер → frontend (Nginx) → /api → backend (Express)
                                      ├── data/catalog.json и правила подбора
                                      ├── OpenAI: вопросы о сайте и диалог
                                      └── сессии и корзины в памяти

Backend валидирует каталог через Zod и преобразует price → priceKzt, breakingCapacity → breakingCapacityKa. Frontend получает товары только от API и переводит числовые параметры в подписи карточек. Отдельного каталога заглушек в интерфейсе нет.

Проверка демо

В live можно начать с «что по товарам есть», «Как выбрать товар на сайте?» или «Чем отличаются характеристики B и C?». Помощник получает факты каталога и историю диалога, отвечает на вопросы магазина и отклоняет посторонние темы. Для подбора можно написать «Нужны трёхполюсные автоматы C16 на десять килоампер», затем ответить «восемь штук» на вопрос о количестве. Сначала проверяются известные локальные сценарии, остальные вопросы понимает OpenAI.

1. Введите в помощнике запрос Нужен автомат 3P C16, 10 kA, 8 штук. Если нет — совместимый аналог. и нажмите Отправить.
2. Точный товар DEMO-MCB-001 имеет остаток 3 штуки и недоступен для этого количества. Есть два кандидата с 15 kA: DEMO-MCB-003 и DEMO-MCB-004.
3. Выберите DEMO-MCB-003. До подтверждения корзина остаётся пустой; Отмена также ничего в неё не добавляет.
4. Нажмите Да, добавить. После подтверждения сервером откроется корзина.
5. На /cart проверьте SKU DEMO-MCB-003, 8 штук, цену 7 900 ₸ и сумму 63 200 ₸.
6. Обновление страницы в той же вкладке сохраняет корзину, пока работает Backend. После перезапуска Backend создаётся новая пустая сессия.

Дополнительные запросы: Есть DEMO-MCB-013, 4 штуки?, Какие условия доставки и оплаты?, 4P D63, 15 kA, 1 штука. Все десять сценариев: docs/demo-catalog.md.

Для отсутствующего автомата подбор учитывает и другие SKU с такими же номиналами, и варианты с большей отключающей способностью. Для ламп, светильников и кабелей используются параметры соответствующей категории; помощник не требует у светильника параметры автомата. Результаты — кандидаты из каталога с объяснением совпадений, требующие проверки совместимости, монтажа и единицы продажи. Произвольный кабель не считается безопасной заменой только по совпадению названия категории.

Настройки

Файл .env необязателен. При необходимости скопируйте .env.example в .env в корне. Команды dev, start и Docker Compose читают настройки из него. Существующий .env обновляйте вручную, чтобы сохранить свои значения.

Переменная	По умолчанию	Назначение
APP_MODE	offline	live разрешает настроенные внешние адаптеры
PORT	3001	Порт Backend внутри контейнера и в локальной разработке
APP_PORT	8080	Опубликованный порт Docker на хосте
FRONTEND_PORT	5173	Порт Vite
CATALOG_PATH	data/catalog.json	Абсолютный путь или путь относительно рабочей директории процесса
FRONTEND_DIST_PATH	frontend/dist	Путь для общего сервера без Docker, относительно backend/
CART_URL	/cart	Путь страницы корзины Frontend
VITE_API_BASE_URL	/api	Адрес API для отдельно размещённого Frontend при локальной сборке; Docker использует общий /api
OPENAI_API_KEY	Не задан	Необязательный ключ OpenAI в live
OPENAI_MODEL	gpt-4.1-mini	Модель диалога и извлечения параметров с Structured Outputs
OPENAI_RESPONSES_URL	Из backend/config.json	Endpoint OpenAI Responses API
FRONTEND_IMAGE	ekt-match-frontend:local	Образ интерфейса
BACKEND_IMAGE	ekt-match-backend:local	Образ API; старый APP_IMAGE принимается как fallback
BACKEND_ORIGIN	http://backend:3001	Адрес API для Nginx в Docker; порт берётся из PORT
EKT_API_USERNAME, EKT_API_PASSWORD	Не заданы	Basic Auth для загрузки каталога ekt.kz в live
EKT_PRODUCT_DETAIL_URL	Из backend/config.json	Endpoint карточки партнёра

Для OpenAI укажите в .env:

APP_MODE=live
OPENAI_API_KEY=ваш_ключ_OpenAI

Повторите docker compose up --build --wait --remove-orphans после изменения .env. Ранее использовавшиеся NVIDIA_* больше не нужны. OPENAI_MODEL и endpoint можно не задавать: значения по умолчанию находятся в backend/config.json. Ключ передаётся только Backend во время запуска и не попадает в Docker-образ или JavaScript интерфейса.

В offline работают локальные подбор, вопросы по артикулу и условиям покупки. В live свободные вопросы классифицирует OpenAI: получает текущий каталог, условия покупки, состояние корзины текущей сессии, последние 8 сообщений и уже уточнённые параметры. Формулировки о товарах, ценах, корзине и проверенных технических сведениях сервер строит из этих данных; неподтверждённые факты из свободного текста модели не показываются покупателю. Это диалог по данным сайта, без перебора заранее записанных вопросов. Посторонние темы перенаправляются к магазину и не попадают в дальнейшую историю модели. При подборе неизвестные характеристики остаются null; помощник спрашивает только о недостающих данных. Карточки и цены формирует поиск Backend. Модель не может изменять корзину текстовым ответом. Подбор использует только характеристики, которые пользователь явно назвал в текущем запросе или сохранил при уточнении; новый подбор сбрасывает прежние параметры.

В backend/config.json → openai настроены 60 попыток за скользящие 60 секунд (maxCalls, windowMs), до 4 одновременных вызовов (maxConcurrent), 768 выходных токенов и таймаут 15 секунд для чата. Кеш ответов учитывает контекст, использует хеши ключей и ограничен 200 записями на 5 минут (maxCacheEntries, cacheTtlMs). Одинаковые одновременные запросы используют один вызов. Ошибки расходуют квоту окна; автоматических повторов нет. Квота возобновляется без перезапуска сервера, общая для чата и распознавания файлов. При временном ограничении чат указывает время повтора; локальный поиск продолжает работать. Денежный бюджет отдельно не рассчитывается.

действуют лимиты на сессию и источник запроса: 6 AI-вызовов на сессию и 10 на IP за минуту, для анонимного поиска — 2 на IP. Параметры находятся в backend/config.json и имеют значения по умолчанию в коде. Денежный бюджет

Создание ограничено 30 запросами в минуту на IP, заполненная ёмкость отвечает SESSION_CAPACITY без удаления активной корзины. В Docker Backend принимает X-Forwarded-For только от адреса сервиса frontend, определённого через DNS по trustedProxyHost; адрес обновляется каждые 30 секунд. При ошибке DNS доверие отключается. Для дополнительного внешнего прокси настройте его цепочку доверия и подходящие лимиты в backend/config.json. При недоступности AI локальный поиск по артикулу и параметрам продолжает работать.

Реальный каталог ekt.kz

Для загрузки укажите APP_MODE=live, EKT_API_USERNAME и EKT_API_PASSWORD в локальном .env или окружении Backend и перезапустите приложение. Доступ к каталогу не требует ключа OpenAI. Значения учётных данных не коммитьте.

Backend читает /api/products?page=1, затем следующие страницы и получает подробности каждого товара через /api/products/detail?id=.... Остаток берётся только из quantity подробной карточки: в списке товаров его нет. Конец списка определяется по неполной/пустой странице или повтору первой страницы — так API ekt.kz отвечает на запрос за пределами каталога. Локальные DEMO-* позиции в реальный каталог не добавляются, CATALOG_PATH в этом режиме не используется.

Первая загрузка без сохранённого каталога по-прежнему занимает время: контрольный импорт примерно 15 тысяч товаров занял около 12 минут. После успешного импорта Backend атомарно сохраняет каталог в backend/.cache/ekt-catalog.json. При повторном запуске данные читаются с диска и поиск доступен сразу после запуска сервера. Свежий кэш не вызывает повторного импорта. По умолчанию через час каталог обновляется в фоне; устаревший кэш при запуске обновляется сразу, также в фоне. Во время обновления остаётся доступен предыдущий снимок; при ошибке он сохраняется. Если при обновлении часть карточек недоступна или не прошла проверку, рабочий снимок также сохраняется целиком, чтобы временный сбой не удалил товары из поиска.

Даже при первом запуске без кэша доступны создание сессии, чтение корзины, приветствие и условия оплаты/доставки. Запрос товара в режиме диалога получает понятный ответ о загрузке; классический поиск, добавление в корзину и загрузка файлов ждут готовности каталога (CATALOG_LOADING / CATALOG_UNAVAILABLE). При недоступном каталоге AI-диалог продолжает отвечать на вопросы о сайте, корзине и условиях покупки; сведения о товарах, ценах и остатках остаются недоступными до загрузки. Сессии продолжают работать после её завершения. Демо-цены не подставляются.

После ошибки импорта первая повторная попытка выполняется через 30 секунд (partner.retryDelayMs); дальнейшие интервалы удваиваются до пяти минут. Успешная загрузка возвращает обычный интервал обновления. /api/health показывает catalog.upstreamStatus при HTTP-ошибке поставщика и время catalog.nextRetryAt.

GET /api/health → catalog показывает status, loadedAt, cached, stale, refreshing, прогресс и необязательный refreshError. Ответ по устаревшему снимку содержит дату данных. Настройки: backend/config.json → partner.cache.path (относительно backend) и maxAgeMs (3600000). EKT_CATALOG_CACHE_PATH заменяет путь к файлу. Кэш проверяется на соответствие источнику API и учётной записи; пароль в него не записывается, файл исключён из Git. Повреждённый кэш приводит к новой загрузке. Ошибка сохранения не мешает работе, но видна как cacheSaved: false.

Для запуска через npm кэш сохраняется между перезапусками. В текущем Docker постоянное хранилище кэша не настроено: при пересоздании контейнера файл теряется. Production требует постоянного хранилища каталога; текущая реализация предназначена для одного процесса Backend. Для нескольких экземпляров нужна общая синхронизация.

Карточки с ошибками загрузки/валидации и товары с неоднозначным одинаковым SKU исключаются; их количество отражается в catalog.failed и логах. Цены и остатки являются снимком на время импорта (catalog.loadedAt), обновляются фоновым импортом. Перед новым подтверждённым добавлением в live Backend запрашивает актуальную карточку партнёра и проверяет цену, количество и кратность. Frontend передаёт цену выбранной карточки через expectedUnitPriceKzt. При изменении цены возвращается PRODUCT_PRICE_CHANGED (409): нужно повторить поиск и подтвердить новую цену. При недоступности API возвращается PRODUCT_VERIFICATION_UNAVAILABLE (503). Обе ошибки оставляют корзину без изменений. Повтор уже успешного подтверждения не добавляет товар второй раз и не вызывает API повторно. Корзина остаётся локальной: API партнёра используется только для чтения, резервирования и оформления заказа на ekt.kz нет.

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

Лимит страниц, число параллельных запросов и таймаут находятся в backend/config.json → partner (2000, 4 и 5000 мс). Достижение лимита до конца списка считается ошибкой загрузки. URL списка выводится из адреса карточки; при нестандартной схеме адресов задайте partnerProductsUrl в том же JSON. AI получает размер всего каталога и ограниченный фрагмент, а поиск по артикулу и техническим параметрам работает по всем загруженным товарам.

Загрузка спецификаций и фотографий

Backend принимает PDF, Word (doc, docx), Excel (xls, xlsx), JPEG и PNG через POST /api/uploads. Нужны действующая сессия (X-Session-Id), APP_MODE=live и OPENAI_API_KEY. Файлы передаются в OpenAI для распознавания; цены и остатки берутся из загруженного каталога. В чате откройте Прикрепить файл: выберите файл, нажмите Распознать файл, проверьте позиции и количество. Добавление происходит только через отдельное явное подтверждение. В offline-режиме распознавание недоступно; текстовый поиск продолжает работать. Контракт API, сценарии проверки интерфейса.

Обработка асинхронная: отправка → опрос статуса → проверка извлечённых строк → отдельное подтверждение добавления в корзину. Повторная отправка с тем же requestId возвращает прежнее задание. Отмена доступна через DELETE. По умолчанию один файл до 900 КиБ, до 50 строк, два параллельных распознавания. Оригинал хранится в памяти до завершения обработки; результат — до 15 минут. Лимиты задаются в backend/config.json → uploads; вызовы делят общий бюджет openai.maxCalls с чатом. После перезапуска задания теряются.

Платёжные данные

Чат не запрашивает платёжные реквизиты. Обнаруженные номера карт/IBAN, CVV/CVC, PIN, коды подтверждения, срок действия карты и банковский пароль отклоняются с PAYMENT_DATA_NOT_ALLOWED (400) до записи в историю и отправки текстового запроса в AI. Проверяется также имя загружаемого файла. Обнаруженные значения в ответах модели, истории и извлечённых строках маскируются. Это проверка по шаблонам и контрольным суммам, она не гарантирует обнаружение всех способов записи. Не загружайте документы с платёжными реквизитами: исходный PDF, изображение или Office-файл передаётся провайдеру для распознавания.

Тесты

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

npm test
npm run build

Backend проверяется встроенным node:test, Frontend — Vitest и Testing Library. Тесты интерфейса поднимают настоящий Express API с общим каталогом. Проверяются все 10 demo-запросов в одной сессии, единицы измерения, изоляция корзин, явное подтверждение, отсутствие мутаций при отмене и ошибках, повтор после потери ответа, восстановление сессии и страница корзины. В обычный запуск включены регрессии из аудита; результаты исправлений описаны в проверке после исправлений.

Технологии и данные

Компонент	Использование
React 19, TypeScript 5.7, Vite 6	Интерфейс и сборка
Express 5, Zod 4	HTTP API и валидация
Vitest 2, Testing Library, jsdom 25	Проверки интерфейса
Node.js node:test	Проверки Backend
Phosphor Icons	Иконки интерфейса
OpenAI Responses API	Диалог по сайту и извлечение параметров в live
Docker Compose, Nginx	Отдельные сервисы UI и API, запуск одним действием
data/catalog.json	Синтетические данные команды, не выгрузка ekt.kz
backend/purchase-terms.json	Снимок условий; ссылка на источник содержится в файле и ответе API

Границы демо

В offline товары, цены и остатки вымышлены; в live используются данные партнёра. Упрощённые правила подбора не устанавливают реальную техническую взаимозаменяемость оборудования. Корзина хранится в памяти Backend, не резервирует склад и не оформляет заказ на ekt.kz. Оплата, авторизация покупателя и сохранение в БД не реализованы. Окружение витрины служит контекстом для работающего помощника и локальной корзины.

Команда: SAQ Digital. Описание интеграции, контракт API.