Тихая сосна — помощник по каталогу EKT

Прототип для пользователей каталога EKT: помогает найти товар по запросу, артикулу или ID, посмотреть доступные сведения о нём и получить текстовый ответ. Проект состоит из FastAPI-сервера и расширения для Chromium, которое показывает чат прямо на страницах EKT.

Состояние текущей версии. Серверный API реализован как отдельный компонент, а расширение содержит чат и карточки товаров. После последнего изменения серверного /api/v1/chat их товарные ответы не совпадают по схеме: сервер отдаёт id, name, price, quantity, url, а валидатор расширения ожидает поля прежнего ответа ProductListItem либо более полный канонический формат. Ответ с найденными товарами сейчас может завершиться в расширении ошибкой BACKEND_INVALID_RESPONSE. Ниже приведён проверяемый сценарий для API; сквозную демонстрацию поиска через расширение нельзя считать завершённой.

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

Компонент	Возможности в репозитории
Backend	Поиск каталога по ID, артикулу и тексту; выдача списка и деталей товара; получение деталей и складских данных через EKT API при настроенном доступе; подбор альтернатив и ответы на запросы о наличии с учётом подтверждённых данных.
Ассистент	Обработка текстового запроса, обращение к поиску и каталогу, формирование ответа и списка товаров. Ответ собирается по правилам из данных каталога; запущенная конфигурация не подключает генеративную модель.
Расширение	Чат на страницах EKT в Shadow DOM, отправка запроса через фоновый процесс, сессия в хранилище браузера, карточки товаров для поддерживаемого ответа, безопасная обработка ссылок, состояния загрузки и ошибки, защита от двойной отправки.
Корзина	На сервере есть создание, проверка и отмена предложения действия после проверки остатков. Расширение не добавляет товар в корзину: подтверждение и вызов add2basket не включены.

Сервер также содержит маршруты GET /health, GET /api/v1/products/, GET /api/v1/products/search, GET /api/v1/products/{id}, GET /api/v1/products/{id}/detail и POST /api/v1/chat. Интерактивная схема доступна по /docs после запуска API.

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

1. Пользователь открывает страницу EKT и вводит вопрос в чат расширения. Расширение отправляет текст, идентификатор сессии и минимальный контекст страницы в свой фоновый процесс.
2. Фоновый процесс делает POST /api/v1/chat на указанный при сборке адрес FastAPI. Cookies EKT и учётные данные EKT в этот запрос не включаются.
3. Серверный оркестратор разбирает запрос, ищет товары в локальном каталоге или PostgreSQL. Для отдельных запросов он обращается к деталям EKT API и проверяет наличие по доступным данным.
4. API возвращает текст и список товаров. Расширение проверяет ответ перед показом карточек. На текущем main шаг отображения найденных товаров блокируется несовпадением схем, указанным выше; отсутствие совпадений может отображаться без карточек.

Страница EKT → content script (React, Shadow DOM)
             → сообщения расширения → background service worker
             → FastAPI /api/v1/chat → оркестратор → каталог / PostgreSQL / EKT API
             ← проверенный ответ ← JSON

Технологии и интеграции

• Сервер: Python, FastAPI, Pydantic, Uvicorn, HTTPX, python-dotenv, Psycopg 3. PostgreSQL 16 доступен через docker-compose.yml; его можно не подключать для базового запуска API.
• Расширение: TypeScript, React 19, WXT, Chrome Manifest V3, Zod; сборка через pnpm, тесты написаны на Vitest и React Testing Library.
• Внешние данные: EKT API для списка и деталей товаров. Его учётные данные используются только сервером и задаются локально через переменные окружения. База PostgreSQL хранит синхронизированный каталог и данные действий корзины, если настроена.
• AI-модель: в текущем запуске не используется. Класс оркестратора допускает внешний генератор текста, но backend/app/main.py создаёт его без генератора; интеграции с OpenAI или другой моделью в рабочем маршруте нет.

Установка и запуск локально

Нужны Python 3.10+, Node.js 20+, pnpm и браузер на Chromium. Docker Compose нужен, если используется пример подключения к PostgreSQL. Команды ниже выполняются из корня репозитория.

1. Запустить API

python -m venv .venv
source .venv/bin/activate
python -m pip install -r backend/requirements.txt
cp .env.example .env
docker compose up -d postgres
python -m uvicorn app.main:app --app-dir backend --reload

В PowerShell используйте .venv\Scripts\Activate.ps1 и Copy-Item .env.example .env вместо source и cp. Файл .env храните только локально. Для доступа к реальному каталогу заполните в нём EKT_API_USERNAME и EKT_API_PASSWORD выданными команде значениями. Пример .env.example также задаёт подключение к PostgreSQL: если база не запущена, удалите или отключите DATABASE_URL перед стартом API. Без EKT-доступа, синхронизированной базы или локальных файлов data/products.json каталог может быть пустым; эти файлы данных в репозиторий не включены.

При наличии EKT-доступа и PostgreSQL каталог можно предварительно загрузить командой:

PYTHONPATH=backend python -m app.db.sync_catalog

В PowerShell сначала задайте $env:PYTHONPATH = 'backend', затем выполните python -m app.db.sync_catalog. Синхронизация обращается к EKT API и требует настроенных учётных данных.

2. Собрать и открыть расширение

pnpm --dir apps/extension install --frozen-lockfile
WXT_BACKEND_BASE_URL=http://localhost:8000 pnpm --dir apps/extension run build

В PowerShell задайте $env:WXT_BACKEND_BASE_URL = 'http://localhost:8000' и выполните pnpm.cmd --dir apps/extension run build. Затем откройте chrome://extensions, включите режим разработчика, выберите «Загрузить распакованное расширение» и укажите apps/extension/.output/chrome-mv3. Значение WXT_BACKEND_BASE_URL должно быть только адресом backend без /api/v1/chat; при смене адреса нужна новая сборка. Для удалённого адреса конфигурация расширения требует HTTPS.

Как проверить

1. После запуска API откройте http://localhost:8000/health: ожидаемый ответ — {"status":"ok"}. Откройте http://localhost:8000/docs для проверки маршрутов через Swagger UI.

2. Если EKT-доступ настроен, вызовите в /docs GET /api/v1/products/?page=1 и возьмите ID из полученного списка. Если доступ не настроен и локальных данных нет, список может быть пустым — это не демонстрация поиска.

3. В /docs вызовите POST /api/v1/chat, заменив ID_ИЗ_СПИСКА реальным числом:

   {
     "session_id": "jury-demo",
     "message": "Найди товар id:ID_ИЗ_СПИСКА",
     "attachment_ids": [],
     "page_context": {}
   }
   

   Проверьте текст ответа и products в JSON. Поле quantity может быть null, если наличие не подтверждено; это не нулевой остаток.

4. Откройте ekt.kz с установленным расширением: должен появиться чат, который можно открыть и закрыть. Текущую сквозную выдачу карточек через этот чат не следует использовать как успешный критерий до согласования формата ответа backend и расширения. Проверка в настоящем браузере и с живым EKT в рамках подготовки этого README не проводилась.

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

• Формат товарного ответа текущего /api/v1/chat не поддерживается валидатором расширения. API и UI следует проверять отдельно до исправления контракта.
• В репозитории нет готового каталога. Поиск по названию без EKT-доступа, локальных данных или предварительной синхронизации PostgreSQL может не вернуть товары.
• Корзина из расширения недоступна: текущая проверка действия не возвращает подтверждённое значение kratnost, необходимое для безопасного EKT add2basket. Никакая покупка или оформление заказа не выполняются.
• Загрузка вложений не доступна: backend/app/api/files.py пуст, маршрут не подключён, а расширение отправляет пустой список attachment_ids. Наличие парсеров PDF, DOCX, XLSX и изображений в исходниках не означает работающий пользовательский сценарий загрузки.
• Сессия расширения не является пользовательской аутентификацией. Публичное развёртывание требует отдельной проверки доступа и защиты backend.
• Подтверждённой ссылки на опубликованную версию в репозитории нет; проект запускается локально по инструкции выше.

Дополнительные инструкции по сборке: README расширения.