WooCommerce

WooCommerce (Интеграция)

Интеграция с WooCommerce REST API v3: синхронизация товаров, категорий и заказов в базу знаний для RAG-поиска.

Скриншот

Концепция

Интеграция с WooCommerce REST API v3 для автоматического импорта каталога интернет-магазина в систему знаний:

• Синхронизация товаров — названия, цены, описания, атрибуты, категории, наличие
• Синхронизация заказов — статистика, суммы, статусы, последние заказы
• Markdown-документы — данные конвертируются в markdown для индексации RAG
• Автоматический ежедневный sync — фоновая задача в 23:00 UTC (02:00 МСК)
• Знание для ассистента — ИИ использует каталог для ответов на вопросы о товарах и ценах

Страница WooCommerce

Управление интеграцией через WooCommerceView.vue. Две секции: подключение и синхронизация датасета.

---

Секция: Подключение

Параметр	Описание
Store URL	Адрес магазина (например, https://shop.example.com)
Consumer Key	API-ключ WooCommerce (маскируется: ***1234)
Consumer Secret	API-секрет WooCommerce (маскируется: ***5678)

Кнопки:

Кнопка	Описание
Сохранить	Сохраняет URL и ключи. Ключи очищаются из формы после сохранения (безопасность)
Проверить подключение	Тестирует соединение, показывает название магазина и версию WC
Отключить	Очищает ключи, сбрасывает статус подключения

При успешной проверке отображается зелёный индикатор «Подключено» и информация о магазине:

• Название магазина
• Версия WooCommerce
• URL

---

Секция: Синхронизация датасета

Появляется только после успешного подключения (is_connected=true).

Статистика (сетка 2×3)

Метрика	Описание
Товаров	Количество синхронизированных товаров
Категорий	Количество категорий
Заказов	Количество заказов
Документов	Количество markdown-документов в базе знаний
Секций	Суммарное количество секций (для RAG-индексации)
Последняя синхронизация	Дата и время последнего sync

Кнопки

Кнопка	Описание	Доступ
Синхронизировать	Запускает полную синхронизацию (товары + категории + заказы → markdown → RAG)	sales:edit
Очистить	Удаляет все markdown-документы и очищает RAG-индексы	sales:manage

Процесс синхронизации

При нажатии «Синхронизировать» или по расписанию:

1. Загрузка данных из WooCommerce:

   • GET /wp-json/wc/v3/products — все товары (автопагинация по 100)
   • GET /wp-json/wc/v3/products/categories — все категории
   • GET /wp-json/wc/v3/orders — все заказы (опционально, ошибка не фатальна)

2. Группировка товаров по категориям

3. Генерация markdown-документов в data/woocommerce-dataset/:

   Файл	Содержимое
   wc-category-{id}.md	Товары категории: название, SKU, цена (₸), наличие, описание, атрибуты
   wc-uncategorized.md	Товары без категории
   wc-orders.md	Статистика заказов: общее количество, выручка, статусы, последние 50 заказов
   wc-summary.md	Общая статистика: количество товаров, диапазон цен, категории

4. Индексация в RAG:

   • Создаётся/обновляется коллекция знаний с slug "woocommerce"
   • Удаляются старые документы коллекции
   • Загружаются новые документы с подсчётом секций
   • Перезагружаются RAG-индексы (BM25 + эмбеддинги)

5. Обновление статистики в конфиге (счётчики + timestamp)

Фоновая задача

Параметр	Значение
Имя	woocommerce-sync
Расписание	Ежедневно в 23:00 UTC (02:00 МСК)
Задержка запуска	120 секунд (прогрев)
Условие	Выполняется только если sync_enabled=true
При ошибке	Повтор через 1 час

Задача регистрируется в TaskRegistry при старте системы.

API

Метод	Путь	Описание	Доступ
GET	/admin/woocommerce/config	Получить конфиг (ключи замаскированы)	sales:view
POST	/admin/woocommerce/config	Сохранить/обновить конфиг	sales:edit
POST	/admin/woocommerce/test	Проверить подключение	sales:edit
POST	/admin/woocommerce/disconnect	Отключить (очистить ключи)	sales:edit
POST	/admin/woocommerce/dataset-sync	Запустить синхронизацию	sales:edit
GET	/admin/woocommerce/dataset-status	Статус датасета (документы, секции, файлы)	sales:view
DELETE	/admin/woocommerce/dataset	Очистить датасет	sales:manage

Ответ dataset-sync

{
  "status": "ok",
  "products": 150,
  "categories": 8,
  "orders": 42,
  "files_written": 5,
  "files_removed": 3,
  "collection_id": 7,
  "synced_at": "20.03.2026 14:30"
}

Ответ dataset-status

{
  "synced": true,
  "collection_id": 7,
  "collection_name": "WooCommerce",
  "documents": 5,
  "total_sections": 127,
  "last_sync": "20.03.2026 14:30",
  "files": ["wc-category-1.md", "wc-orders.md", "wc-summary.md"]
}

Модель данных

Таблица woocommerce_config (синглтон, id=1):

Поле	Тип	Описание
store_url	string	URL магазина
consumer_key	string	API-ключ (маскируется в API-ответах)
consumer_secret	string	API-секрет (маскируется)
is_connected	boolean	Статус подключения
sync_enabled	boolean	Включить автосинхронизацию
last_sync_at	string	Время последней синхронизации
products_count	integer	Количество товаров
categories_count	integer	Количество категорий
orders_count	integer	Количество заказов
workspace_id	integer	FK на workspace

Архитектура модуля

modules/ecommerce/
  ├── models.py          → WooCommerceConfig (SQLAlchemy)
  ├── router.py          → 7 API-эндпоинтов
  ├── service.py         → WooCommerceService (CRUD конфига)
  ├── sync.py            → run_woocommerce_sync() — основная логика
  └── tasks.py           → woocommerce_daily_sync() — фоновая задача

app/services/
  ├── woocommerce_service.py          → HTTP-клиент WC REST API v3
  └── woocommerce_dataset_service.py  → Генерация markdown из данных WC

Особенности

• Аутентификация — через query-параметры (consumer_key + consumer_secret), не HTTP Basic Auth (совместимость с хостингами)
• Маскирование секретов — API всегда возвращает ***{последние 4 символа}
• Устойчивость к ошибкам — сбой загрузки категорий/заказов не прерывает синхронизацию (товары обязательны)
• Автопагинация — REST-клиент автоматически обходит все страницы (по 100 записей)
• Цены в тенге — форматирование с разделителем тысяч и знаком ₸
• Очистка HTML — описания товаров очищаются от тегов, нормализуются пробелы

---

См. также: Wiki-RAG, Sales, FAQ