# Boostchat – AI Assistant for WooCommerce

## Что это
AI-чат-виджет для WooCommerce: отвечает на вопросы по каталогу товаров,
рекомендует товары со ссылками, собирает лиды при неизвестных вопросах.
Плагин — тонкий клиент. Вся AI-логика (эмбеддинги, RAG, LLM) живёт на
внешнем бэкенде (репозиторий `woo-ai-backend`, деплой на Vercel).

API-контракт между плагином и бэкендом: см. `docs/api-contract.md`
(единый источник правды, НЕ менять формат без обновления обоих репо).

## Архитектура
- Плагин НЕ ходит в LLM API напрямую. Только в наш бэкенд.
  URL бэкенда: опция `woo_ai_backend_url`, для dev — константа
  `WOO_AI_BACKEND_URL` в wp-config.php (имеет приоритет).
- Синк каталога:
  - инкрементальный: хуки `save_post_product`, `woocommerce_update_product`,
    `wp_trash_post` → отправка одного товара на `/api/sync`
  - полный: WP-Cron раз в сутки, батчи по 50 товаров
  - debounce: не отправлять чаще 1 раза в 10 сек на товар (transient)
- Чат: `widget.js` → WP REST `/wp-json/woo-ai/v1/chat` → бэкенд `/api/chat`.
  Прокси через WP обязателен: лицензионный ключ не должен попадать
  во фронтенд.
- Лиды: бэкенд сам шлёт в Telegram; плагин только передаёт
  `telegram_chat_id` при синке настроек.

## Структура файлов
```
ai-assistant-for-woocommerce.php           # метаданные, загрузчик, активация
uninstall.php                  # удаление опций woo_ai_*
includes/
  class-plugin.php             # singleton, регистрация хуков
  class-catalog-sync.php       # синк товаров
  class-api-client.php         # wp_remote_post к бэкенду, retry x2
  class-settings.php           # Settings API
  class-widget-loader.php      # enqueue виджета на фронте
  class-rest-controller.php    # REST: /chat (прокси), /config
admin/settings-page.php        # ключ лицензии, язык, Telegram chat_id,
                               # цвет виджета, приветственное сообщение
public/js/widget.js            # vanilla JS, < 30KB, без зависимостей
public/css/widget.css
languages/                     # ai-assistant-for-woocommerce.pot, uk_UA, ru_RU
readme.txt                     # формат WordPress.org
```

## Стандарты кода
- PHP 7.4+ совместимость, WordPress 6.0+, WooCommerce 7.0+
- WordPress Coding Standards: `vendor/bin/phpcs --standard=WordPress includes/ admin/`
  должен проходить перед каждым коммитом
- Префикс ВСЕГО: `woo_ai_` (функции, опции, хуки, transients),
  классы `Woo_AI_*`, namespace не используем (совместимость с WP.org ревью)
- i18n: все строки через `__( 'text', 'ai-assistant-for-woocommerce' )`,
  текст-домен строго `ai-assistant-for-woocommerce`
- HTTP только через `wp_remote_post` / `wp_remote_get`, таймаут 15 сек
  для /chat, 30 сек для /sync
- Работа с товарами только через CRUD API WooCommerce
  (`wc_get_products`, `WC_Product`), никакого прямого SQL к таблицам Woo

## Безопасность (критично для ревью WordPress.org)
- Экранирование на выводе: `esc_html`, `esc_attr`, `esc_url` — везде
- Санитизация на входе: `sanitize_text_field`, `absint` и т.д.
- Nonce + `current_user_can( 'manage_woocommerce' )` на всех
  админ-действиях и настройках
- REST `/chat`: `permission_callback` => `__return_true` (публичный),
  но rate limit: max 20 запросов / 5 мин на IP через transients;
  при превышении — 429
- Лицензионный ключ: только в `wp_options`, никогда в HTML/JS фронта
- Никаких `eval`, `base64_decode` исполняемого кода, внешних трекеров

## Локальная разработка
- LocalWP сайт, плагин симлинком в `wp-content/plugins/ai-assistant-for-woocommerce`
- Тестовые данные: импорт WooCommerce `sample_products.xml` (есть в
  woocommerce/sample-data/), ~30 товаров
- Бэкенд локально: `cd ../woo-ai-backend && vercel dev` (порт 3000)
- В wp-config.php: `define( 'WOO_AI_BACKEND_URL', 'http://localhost:3000' );`

## Чек-лист ручного теста перед коммитом фичи
1. Активация/деактивация плагина без PHP notice/warning (WP_DEBUG on)
2. Синк: создать товар → товар появился на бэкенде (лог vercel dev)
3. Чат: вопрос на украинском и русском → релевантный ответ со ссылкой
4. Неизвестный вопрос → форма лида → лид дошёл
5. Удаление плагина → опции `woo_ai_*` удалены

## Не делать
- Не добавлять composer-зависимости в прод-код плагина
- Не подключать внешние JS-библиотеки в виджет (React, jQuery — нет)
- Не хранить историю разговоров в БД WordPress — всё на бэкенде
- Не реализовывать фичи из roadmap без явного запроса

## Roadmap
- v1.0 (текущий скоуп): синк каталога, чат с RAG, лиды, настройки
- v1.1 (НЕ делать сейчас): статус заказа в чате, аналитика вопросов,
  мультиязычная админка, выбор модели
