Бот Прагматика — документация

Версия для сдачи этапа. Чтобы сохранить в PDF — «Печать» → «Сохранить как PDF».

1. Блок-схема 2. Описание API 3. Добавление поставщика

1. Блок-схема работы бота: от запроса до КП

A. Заранее (раз в сутки, по расписанию)

[cron: ежедневное обновление]
        │
        ▼
Скачать выгрузки 6 поставщиков (~300 МБ)
   portobello · oasis · oceangifts · happygifts · gifts.ru(p111) · prag196
        │
        ▼
Разобрать в единый формат (название, цена, остаток, фото, нанесение…)
   → data/catalog_<сайт>.json
        │
        ▼
Собрать быстрый поисковый индекс (77 000 товаров)
   → data/catalog.sqlite (полнотекстовый поиск)
        │
        ▼
Автопроверка (self-qa): всё ли импортировалось корректно

B. В момент запроса менеджера (в чате)

[Менеджер пишет боту в Битрикс24]
        │
        ▼
Бот ведёт АНКЕТУ (9 шагов):
  продукция → цвета → бюджет → тираж → нанесение →
  компания → ЦА → цель → пожелания
        │
        ▼
ПОИСК (этап 1):
  1) быстрый отбор кандидатов из индекса (~200 шт.)
  2) ранжирование: соответствие запросу, цвет, материал,
     бюджет (−20%/+5%), цель, аудитория
  3) перемешивание по сайтам (чтобы не было «всё с одного»)
        │
        ▼
ВЫДАЧА превью (до 12 на странице):
  фото · название · цена · ссылка · кнопка «+ В подборку»
        │
        ├──「Показать ещё」──► следующая страница
        │
        ├──「Уточнить запрос」──► «только металл», «без пластика» → пересборка
        │
        ├──「Новый поиск」──► другая категория, корзина сохраняется
        │
        ▼
Менеджер отмечает нужные товары (корзина копится)
        │
        ▼
「Создать КП」 (этап 2):
        │
        ▼
Сборка PPTX:
  • титул (компания клиента + данные менеджера из Битрикса)
  • по слайду на товар (название, артикул, фото, цена, описание)
  • финал (контакты Прагматики)
        │
        ▼
Готовый файл → ссылка на скачивание в чат
        │
        ▼
Запись запроса в смарт-процесс Битрикса (история для аналитики)

Будущие узлы (после согласования)

Перед поиском: разбор свободного промта / файла-брифа через Яндекс-ИИ.
Перед выдачей: пометка «под заказ», скрытие товаров без наличия.
Перед КП: точечная проверка свежей цены/остатка по выбранным позициям.

2. Описание API: внутренние точки и внешние сервисы

«API» — это «окошки», через которые бот общается с внешним миром и через которые Битрикс общается с ботом.

2.1. Наши точки входа (сервер testzorin.na4u.ru/fomenko-bot)

Адрес	Зачем	Кто вызывает
`/bot.php`	Главный мозг: сообщения и кнопки из чата, анкета, поиск, сборка КП	Битрикс24 (вебхук бота)
`/events.php`	Прочие события Битрикса	Битрикс24
`/download.php?t=…`	Отдаёт готовый файл КП по одноразовой ссылке	Менеджер (из чата)
`/img.php?u=…`	Прокси для фото поставщиков (напр. gifts.ru отдаёт фото только по паролю)	Битрикс (показ карточек)
`/health.php`	Проверка «жив ли сервис»	мониторинг
`/install.php`	Разовая установка приложения в портал	Битрикс24

2.2. Битрикс24 (REST API портала)

imbot.message.add — отправить сообщение/карточку товара в чат.
imbot.command.register — зарегистрировать кнопки бота.
user.get — данные менеджера (ФИО, должность, телефон, email) для титула КП.
crm.item.add / crm.item.get — запись запроса в смарт-процесс (история).

2.3. Выгрузки поставщиков (раз в сутки)

Поставщик	Что берём	Доступ
Portobello	товары + отдельный файл остатков	открытый
Oasis	общий XML (товары и остаток вместе)	открытый
Ocean	JSON-каталог	открытый
HappyGifts	общий XML	открытый
gifts.ru (Project 111)	товары + остатки + фото	логин/пароль + белый список IP
prag196	разбор карточек с сайта	открытый

2.4. Безопасность (OWASP 2026)

Файрвол ufw — пропускает только 22 (SSH), 80, 443.
fail2ban — бан IP после 5 неудачных попыток (SSH, Basic Auth). Активно отбивает SSH-брутфорс.
Авто-обновления безопасности ОС — unattended-upgrades.
Rate-limit nginx: 30 r/s (общий) и 5 r/s на /admin (отдельный лимит против брутфорса).
Webhook authenticity: проверка member_id в bot.php и events.php.
HTTP-заголовки безопасности: Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy, Permissions-Policy.
Скрыты версии nginx, PHP, X-Powered-By.
phpinfo() заблокирован через disable_functions.
Санитизация API: ключи в URL, токены, пароли поставщиков маскируются.
Bcrypt cost 12 для паролей панели (OWASP 2026 рекомендация).
Журнал входов с алертами в чат на новый IP / нового пользователя / брутфорс.
Бэкап data/ ежедневно в 03:00, хранение 14 дней, права 600.
Роли: admin (полный доступ) и viewer (только чтение). Владелец user_id=2332 — всегда admin.
Принятый риск: CVE-2025-54370 в PhpSpreadsheet (косвенная зависимость PhpPresentation) — НЕприменим, так как мы не читаем HTML-документы (vulnerable code path).

2.5. Автопочинка

В панели — карточка «Автопочинка» с 7 безопасными операциями: пересборка индекса, снятие зависшего лока, очистка кэша картинок, обновление токена Битрикса, чистка старых файлов, запуск ночного обновления, сброс антиспама. Каждая требует подтверждения, пишет в историю и шлёт алерт об успехе/неудаче. Опасные операции НЕ автоматизированы.

2.6. Яндекс-ИИ (в планах)

Понимание свободного запроса, синонимы, продающие тексты, умный подбор. Доступ — по ключу и folder_id (ждём от клиента).

2.5. Единый формат товара

id, источник, ссылка, название, артикул, цена, цвета,
остаток, фото (1+), описание, вид нанесения, характеристики

3. Как добавить новый сайт-поставщик

Что нужно получить заранее

Способ выгрузки: ссылка на файл (XML/YML/JSON/CSV) или доступ к API.
Доступы, если выгрузка закрытая: логин/пароль, ключ, при необходимости — наш IP в «белый список».
Понимание полей: где название, цена (с НДС!), остаток, фото, нанесение, мин. тираж.

Шаги разработчика

Написать импортёр b2b_import_<имя>() в lib/importer_b2b.php (по образцу существующих): скачивает выгрузку, проходит по товарам, приводит к единому формату, сохраняет в data/catalog_<имя>.json.
Зарегистрировать в двух списках: cron/import-b2b.php и cron/daily-update.php.
Индекс пересоберётся сам в конце импорта.
Проверить: товары появились, есть цена/фото/остаток, фото открывается (если под паролем — добавить в прокси img.php).
Готово — сайт автоматически в поиске и КП, ежедневное обновление подхватит его.

Нюансы из практики

Цена — с НДС в рублях, проверять поле.
Остаток иногда в отдельном файле (это хорошо — обновляется быстро).
Картинки иногда под паролем (как gifts.ru) — идут через прокси.
Файлы бывают большими (90–120 МБ) — поэтому парсим раз в сутки, а не на каждый запрос.
У части поставщиков есть лимит на частоту запросов (gifts.ru — не более 5/сек с IP). Для таких хостов вызываем proposal_rate_limit('host', 220) — кросс-процессный лимитер через файловый lock в /tmp/.

Автообновление каталога

Бот сам обновляет всю базу товаров с 6 сайтов поставщиков каждый день в 04:00 по Москве. За одно ночное обновление он скачивает свежие выгрузки, разбирает их и пересобирает поисковый индекс — чтобы менеджеры утром уже работали с актуальными ценами и остатками.

Полная цепочка занимает ~1,5 минуты. Лог каждого запуска — в logs/cron.log. В панели управления видно ✓/✗ по каждому сайту.

В любой момент можно запустить обновление вручную из панели управления (кнопка «Обновить все сайты»). Также есть фоновый сторож (watchdog) — он раз в 10 минут проверяет, что бот живой, индекс свежий, авторизация в Битриксе на месте, и пишет тревогу в чат, если что-то сломалось.