EKT AI — ассистент для каталога ekt.kz

Прототип на Go, HTML/CSS/JavaScript и OpenAI. Находит товары EKT, объясняет назначение, показывает проверенные цены и остатки и помогает собрать локальную корзину с явным подтверждением клиента.

Запуск

Нужны Docker Desktop и Docker Compose.

git clone https://github.com/BAITC-Hacks/hack-400d70df-donerka-house.git
cd hack-400d70df-donerka-house
cp .env.example .env
# Заполните .env своими серверными ключами и выданными EKT credentials
docker compose up --build -d
docker compose ps
curl http://localhost:8080/health

Откройте localhost:8080. Без ключа OpenAI работают серверные сценарии корзины и ответы по данным товаров. Без доступа к EKT доступны локальные карточки, но добавление блокируется, если актуальные цена и остаток не проверены.

Для запуска без Docker: Go 1.21+, переменные окружения из таблицы ниже, затем go run .. Сам Go-процесс не читает файл .env; Docker Compose подставляет его автоматически.

Переменная	Назначение
OPENAI_API_KEY	Ключ для консультаций OpenAI, модель gpt-4o-mini
EKT_API_BASE_URL	Официальный API, по умолчанию https://ekt.kz/api
EKT_API_USERNAME, EKT_API_PASSWORD	Выданные EKT логин и пароль Basic Auth
EKT_CATALOG_URL	Региональная публичная страница; по умолчанию https://nursultan.ekt.kz
ACCOUNT_STORE_PATH	Файл аккаунтов; по умолчанию data/accounts.json
PUBLIC_ORIGIN	Внешний origin за reverse proxy, например https://shop.example.kz; пустой для прямого localhost
PORT	HTTP-порт, по умолчанию 8080

Ключи не передаются браузеру и не включаются в Git или Docker-образ. Basic Auth EKT авторизует каталог, а не покупателя. OpenAI-ключ не заменяет credentials EKT.

Каталог и достоверность

При старте загружаются 40 записей из data/products.json и data/products2.json; detail.json — пример детализации. В фоне сервер читает до 1200 уникальных товаров официального API и публикует готовый набор одним обновлением. Обновление страницы не добавляет позиции; запросы AI не увеличивают публичный каталог. До окончания синхронизации или при её ошибке остаётся локальный снимок.

Используются GET /api/products?page=N и GET /api/products/detail?id=... на сервере EKT, а также публичные карточки регионального сайта. Публичный каталог — снимок: его цены помечены как требующие уточнения. Чат отмечает время проверки фактов; неподтверждённые цена и наличие не подаются как актуальные.

Перед предложением добавления и повторно при подтверждении сервер запрашивает данные EKT. Неизвестная цена, неизвестный/нулевой остаток, ошибка API или превышение доступного количества блокируют добавление. Изменение цены требует нового подтверждения. Нулевое значение из EKT заменяет старое, а не сохраняет прежнюю цену или остаток. Общий остаток API явно отделён от регионального; карточки могут содержать разбивку по складам.

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

Корзина: явное подтверждение

1. Напишите Добавь 2 шт 200300285_ или выберите товар кнопкой «В корзину».
2. Сервер показывает артикул, количество, цену за единицу и сумму.
3. Отправьте да, добавь или нажмите «Подтверждаю добавление».

До шага 3 корзина не меняется. Простое «да» не подтверждает покупку. «Отмена» снимает текущий выбор. Несколько позиций можно указать через точку с запятой: Добавь 1 шт ARTICLE1; 2 шт ARTICLE2 (до четырёх строк).

Подтверждение связано с серверным выбором, действует 10 минут и потребляется один раз под блокировкой. Повторные и параллельные запросы не дублируют добавление. Текст модели не восстанавливает разрешение на изменение корзины. Устаревшая кнопка подтверждения не применяется к новому выбору.

Для удаления или очистки сначала создаётся серверное предложение, затем пользователь подтверждает диалог. Его токен действует 5 минут, связан с владельцем и снимком корзины. Если корзина изменилась, нужно новое подтверждение. Прямое добавление через POST /api/cart и удаление без токена запрещены.

Гостевая корзина переносится в аккаунт только при отмеченном согласии в форме входа. Вход и чтение корзины сами по себе не объединяют товары.

Заказы и платежи не выполняются. Этот прототип изменяет только локальную корзину помощника. Нет endpoint создания заказа, списания денег или формы ввода платёжных реквизитов.

9. Ограничения и реализованные меры

Требование	Реализация
Не изменять корзину без явного подтверждения	Серверное предложение, точная сводка, отдельное подтверждение добавления/удаления/очистки, одноразовые токены и сроки действия
Не оформлять заказ без подтверждения	Оформление заказа отсутствует; добавление явно сообщает, что заказ не оформлен
Не сообщать недостоверные цену и наличие	Проверка источника EKT, отметка времени, блокировка непроверенного добавления, повторное подтверждение изменившейся цены
Не запрашивать/хранить платёжные данные	Нет платёжной формы; запрет в инструкции модели; фильтры входа в браузере и на сервере до истории и внешних запросов, проверка ответа модели
Приватность	Минимальный контекст, маскирование распознаваемых email/телефона, очистка истории, ограниченное время хранения, private API без браузерного кэширования
Защита корзины и аккаунта	Зарегистрированные случайные сессии, HttpOnly/SameSite cookies, Secure на HTTPS, CSRF-токен и проверка origin для всех изменяющих запросов
Объяснимость аналогов	В карточке перечислены совпавшие свойства или слова названия; сходство по названию не объявляется технической совместимостью
Совместимость с платформой	Отдельный сервис с JSON API, серверный EKT Basic Auth, относительные URL фронтенда, размещение на одном origin через reverse proxy
Десктоп и мобильный	Адаптивные каталог/чат/вход/корзина, видимая мобильная корзина, прокрутка в ограниченной высоте, кнопки подтверждения и удаления

Объяснение аналога строится из данных: например, «совпадают характеристики: Полюсов=3, Ток=80 A». Наличие само по себе не делает товар аналогом. Перед технической заменой нужно проверить все необходимые параметры по документации производителя; алгоритм не сертифицирует совместимость.

Приватность и хранение

• История: последние 12 сообщений, только в памяти. Через 30 минут бездействия она удаляется плановой очисткой (раз в минуту). «Очистить» и выход из аккаунта удаляют соответствующую историю.
• Сессии: случайные серверные идентификаторы, срок 24 часа. Произвольная гостевая cookie, включая идентификатор аккаунта, не даёт доступ к чужой корзине.
• Корзины: в памяти сервера. Гостевые корзины очищаются по окончании сессии; аккаунтные — при перезапуске или подтверждённой очистке пользователем. Перезапуск сбрасывает все корзины и сессии.
• Аккаунты: имя, email, соль и хеш пароля в data/accounts.json, доступ к файлу 0600. Этот файл исключён из Git и Docker build context. В Docker он сохраняется в локальном volume ./data:/app/data. Удаление аккаунта пока выполняет администратор.
• Приложение не пишет сообщения чата и тела запросов в логи. На reverse proxy также нельзя включать запись тел запросов или секретных заголовков.
• Для ответа OpenAI передаются очищенный вопрос, короткая история и контекст товаров; данные аккаунта и credentials EKT не включаются. Запрос принудительно содержит store:false. По стандартным правилам OpenAI журналы предотвращения злоупотреблений могут сохраняться до 30 дней; локальная очистка не удаляет их. См. официальную документацию по данным OpenAI API.
• Фильтры распознают длинные номера карт, типичные IBAN и подписанные CVV/PIN/SMS-коды; скрытые или необычно записанные реквизиты могут не распознаться. Это не универсальная DLP-система и не заявление о PCI DSS-сертификации. Пользовательская памятка: приватность.

HTTP API

Все изменяющие запросы требуют cookie сессии, X-CSRF-Token, Content-Type: application/json и допустимый origin. Чужой origin получает 403. Для первого запроса получите токен через GET /api/session.

Метод	Путь	Действие
GET	/api/session	Создать сессию и вернуть csrf_token
GET	/api/catalog	Опубликованный каталог
POST	/api/chat	message, опционально confirmation_token от кнопки; поиск/подтверждение
DELETE	/api/chat	Удалить историю и ожидающий выбор
GET	/api/cart	Корзина текущей сессии/аккаунта
POST	/api/cart	409: прямое добавление запрещено
POST	/api/cart/confirmation	action: remove/clear, для remove — article; получить сводку и токен
DELETE	/api/cart	confirmation_token; применить подтверждённое удаление
GET	/api/auth	Состояние аккаунта
POST	/api/auth	action: login/register, email, password, name; merge_cart: true только с согласием
DELETE	/api/auth	Выход и очистка истории аккаунта
GET	/health	Статус и количество опубликованных товаров

Пример для локальной проверки (нужен jq):

csrf=$(curl -fsS -c /tmp/ekt-cookies.txt http://localhost:8080/api/session | jq -r .csrf_token)
curl -fsS -b /tmp/ekt-cookies.txt http://localhost:8080/api/chat \
  -H "X-CSRF-Token: $csrf" -H 'Content-Type: application/json' \
  -d '{"message":"Добавь 1 шт 200300285_"}'
# Прочитайте полученную сводку. Только если согласны:
curl -fsS -b /tmp/ekt-cookies.txt http://localhost:8080/api/chat \
  -H "X-CSRF-Token: $csrf" -H 'Content-Type: application/json' \
  -d '{"message":"да, добавь"}'

Интеграция с настоящим ekt.kz

Проверенная интеграция в этом проекте — чтение товаров/деталей и публичных страниц EKT. Локальный аккаунт не равен кабинету EKT; локальная корзина не синхронизируется с серверной корзиной ekt.kz.

Для production владелец платформы должен предоставить customer-auth/cart/order API и контракт идентификации покупателя. При подключении этих API необходимо сохранить серверные подтверждения, идемпотентность, проверку владельца и повторную проверку цены. Не пересылайте сервисный пароль каталога покупателям.

Сервис рассчитан на один экземпляр. Для нескольких экземпляров нужны общее хранилище сессий/корзин/подтверждений, транзакции и лимиты запросов на reverse proxy. Размещайте UI и API на одном origin, установите PUBLIC_ORIGIN и HTTPS. Сквозная совместимость с производственной платформой EKT требует проверки владельцем сайта; здесь она не заявляется как завершённая.

Проверка и структура

go test -race ./...
go vet ./...
node --check static/chat.js
docker compose up --build -d

Регрессионные тесты проверяют запрет неподтверждённых действий, подмену cookie, CSRF, одноразовость и срок подтверждения, параллельный повтор, изменение цены, сбой EKT, нулевой/неизвестный остаток, блокировку платёжных данных и обоснование аналогов.

Для ручной проверки откройте сайт на десктопе и узком мобильном экране: выберите товар, отклоните/подтвердите добавление, повторите подтверждение, отмените удаление, затем подтвердите его. Убедитесь, что отмена сохраняет корзину и кнопка корзины доступна на мобильном.

Основные файлы: main.go — сервер; handlers/chat.go и quotes.go — диалог и проверка цен; security.go — CSRF и подтверждение удаления; privacy.go — фильтры данных; conversation.go — ограниченная история и одноразовый выбор; ekt_api.go/live_catalog.go — источники EKT; static/ — адаптивный интерфейс.