Диагностика коннектора

Каждый CMS-модуль сам сообщает AACsearch о своём состоянии. Диагностика покрывает три задачи:

1. Тест соединения — ручная проверка из админки CMS, что токен коннектора, project ID и версия модуля настроены корректно.
2. Heartbeat — периодический keepalive, чтобы панель AACsearch могла отметить коннектор как online/offline.
3. Отчёт диагностики — структурированный payload с описанием последнего состояния синхронизации, версий окружения и любых ошибок, пойманных модулем локально.

На этой странице — все рабочие части и правила повторов, которые обязан реализовать каждый модуль.

Тест соединения

В каждом CMS-модуле в админке должна быть кнопка Test connection. Она вызывает POST /api/connectors/handshake с настроенным токеном и идентификатором платформы.

POST /api/connectors/handshake
Authorization: Bearer ss_connector_<token>
Content-Type: application/json

{
  "moduleVersion": "1.0.0",
  "platform": "prestashop"
}

Handshake проверяет четыре вещи за один запрос:

• Заголовок Authorization корректен, префикс токена — ss_connector_.
• Хеш токена существует в SearchApiKey, имеет область connector_write и не отозван.
• Указанный platform — известный идентификатор коннектора.
• У организации, владеющей токеном, есть хотя бы один активный поисковый индекс.

Ответ 200 — единственный сигнал, после которого мерчант может считать коннектор настроенным. В ответе приходят projectId и indexSlug — модуль обязан сохранить оба, так как они используются в URL всех последующих вызовов sync, delete и diagnostics.

Расшифровка ошибок handshake

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

Heartbeat

После успешного handshake модуль вызывает heartbeat каждые 5 минут из фоновой задачи (cron, плановое задание PHP, агент платформы).

POST /api/connectors/:connectorId/heartbeat
Authorization: Bearer ss_connector_<token>

Панель выводит статус коннектора по полю SearchApiKey.lastUsedAt:

Отсутствие heartbeat само по себе не ошибка — модуль просто offline. Мерчанты обычно замечают offline-коннектор, когда индекс начинает устаревать; здоровый график heartbeat снимает этот разговор с поддержки.

Отчёт диагностики

Более развёрнутый POST /api/projects/:projectId/diagnostics нужен для информации, по которой мерчант или поддержка могут принять решение. Шлите отчёт после каждой полной синхронизации, после неудачной дельта-синхронизации и раз в сутки независимо от активности.

{
  "moduleVersion": "1.2.3",
  "lastFullSync": "2025-01-15T09:00:00.000Z",
  "lastDeltaSync": "2025-01-15T09:55:00.000Z",
  "totalProducts": 4823,
  "phpVersion": "8.2.0",
  "shopUrl": "https://myshop.example.com",
  "errors": [
    {
      "code": "export_timeout",
      "message": "Product export timed out after 30s",
      "timestamp": "2025-01-15T09:54:30.000Z"
    }
  ]
}

Что класть в errors

Шлите только те ошибки, которые мерчант или инженер поддержки могут разобрать. Полезные примеры:

• export_timeout — экспорт товара упёрся в лимит времени скрипта.
• memory_limit_reached — PHP / Node не хватило памяти в середине батча.
• invalid_field_mapping — настроенное поле отсутствует у сущности.
• webhook_signature_mismatch — входящий webhook платформы не прошёл HMAC.
• db_query_failed — запрос к каталогу внутри модуля упал.

Не шлите транзитные HTTP-ошибки, которые уже обрабатывает цикл повторов — на стороне AACsearch вы создадите шум в логах.

Поллинг sync-джобов

Полная и дельта-синхронизация возвращают jobId. Состояние задачи можно опросить:

GET /api/projects/:projectId/sync/jobs/:jobId
Authorization: Bearer ss_connector_<token>

Переходы статусов: running → completed либо running → failed. В ответе — события по шагам и сводка itemsCount / failuresCount. Модули должны опрашивать не чаще, чем раз в 5 секунд, и прекращать поллинг через 30 секунд без перехода. В панели то же доступно в Connectors → Sync history.

Записи джобов хранятся в памяти (последние 50 на инстанс) и теряются при рестарте. 404 на поллинге — это не «синхронизация провалилась», а «статус неизвестен» — следующая полная или дельта-синхронизация сверит индекс.

Поведение при повторных попытках

Connector API ставит записи в очередь асинхронно. Ответ 200 означает «буферизовано для индексации», а не «уже в индексе». Модулю нужна стратегия повторов на разрыв между этими событиями.

Когда повторять

• Сетевые ошибки и 5xx → exponential backoff, потолок 5 минут между попытками.
• sync_failed (502) → повторять, потолок 5 минут.
• delete_failed (502) → повторять, потолок 5 минут.
• Другие 4xx, кроме auth-кодов → не повторять. Показать ошибку мерчанту.

Когда не повторять

• invalid_or_revoked_key (403) → токен мёртв; оповестите мерчанта.
• invalid_input (400) → исправить payload до следующего вызова; повторы с тем же телом только увеличивают шум.
• project_not_found (404) → токен не подходит к настроенному проекту; оповестить мерчанта.

Рекомендуемая схема backoff

Ограничьте общее время повторов одной джобы 30 минутами. После этого — лог, отправка диагностики, следующая плановая полная синхронизация сама всё сверит.

Статус коннектора в панели

В панели AACsearch:

• Connectors → список — каждый токен коннектора со статусом heartbeat, временем последней синхронизации и общим числом товаров (берётся из последнего отчёта диагностики).
• Connectors → sync history — берётся из in-memory джоб-стора. Фильтр по full / delta / delete и по статусу.
• Connectors → diagnostics — последний полученный payload диагностики на коннектор, включая версии окружения и массив errors.

Коннектор, который ни разу не вызвал handshake, в списке не появится — строка создаётся только при первом успешном handshake.

Связанные страницы

• Жизненный цикл Connector API
• Обзор коннекторов
• Custom Connector