Модуль 1С-Битрикс

aacworkflow.aacsearch работает внутри сайта на Битриксе: читает каталог, складывает изменения в очередь и отправляет их в AACSearch через коннектор, а на витрине даёт поиск, умный фильтр, подсказки, рекомендации и аналитику запросов. Сам модуль не ищет: индекс, морфология, опечатки и рекомендации живут на стороне AACSearch, поэтому без ключа модуль устанавливается, но простаивает.

Требования

В редакциях без catalog («Старт») индексируются элементы инфоблоков, но цен и остатков там нет — правила о них ничего не делают и скрываются.

Установка

Модуль собирается для Маркетплейса Битрикса, но пока там не опубликован. После публикации: Маркетплейс → Установленные решения → Установить. Сборка модуля (marketplace/build-last-version.sh --archive) создаёт полный пакет и пакет обновления с тем же содержимым.

Установка:

• создаёт таблицы модуля;
• копирует компоненты в /bitrix/components/aacsearch/, страницы админки — в /bitrix/admin/, публичные эндпоинты — в /bitrix/tools/aac.search/;
• регистрирует обработчики событий и фоновые агенты;
• добавляет правило ЧПУ для прокси витрины /aacsearch/api/.

Меню — Сервисы → AACSearch. Обновление из Маркетплейса заменяет файлы модуля, но установщик не запускает: на ближайшем хите админки модуль замечает смену версии и повторяет идемпотентные шаги установки — файлы, правило ЧПУ, события, агенты, настройки по умолчанию. Если что-то из этого пропало, Диагностика предлагает Дообновить установку.

Агенты работают на штатном механизме агентов Битрикса — на хитах или через настроенный cron. Сайт без посещений и без cron не синхронизируется.

Подключение

Способов два, и какой из них использует модуль, решает вставленный ключ.

Ключ установки (1.8.1+, рекомендуется)

С ключом установки страница настроек сводится к кнопкам Подключить, Проверить настройки Console и Включить модуль / Отключить модуль, применённой ревизии конфигурации и последней ошибке: настройки каталога, поиска, рекомендаций и оплаты находятся в консоли. Агент InstallationAgent (каждые 30 секунд) читает опубликованную конфигурацию, применяет её, подтверждает ревизию, запускает первую полную выгрузку каждого привязанного источника и выполняет команды консоли.

Что переключатели консоли делают на сайте:

Существующие установки с ключом aac_sk_… сохраняют классическую страницу настроек, описанную ниже. Ключ установки нельзя использовать для API тенанта или на другом домене.

Классический API-ключ и коннектор

Старые установки используют серверный API-ключ из Settings → API keys и Мастер настройки из пяти шагов: ключ, проверка связи, каталог, первая выгрузка, витрина. Кнопка Подключить на первом шаге делает всё сразу: проверяет связь, подключает все инфоблоки с товарами, создаёт коллекцию, заводит модели рекомендаций и помощника (без блокировки при ошибке), создаёт коннектор и ставит первую выгрузку в очередь.

Мастер создаёт push-коннектор bitrix для основной коллекции и сохраняет его id и секрет. Если на платформе уже есть bitrix-коннектор для этой коллекции, а локальный секрет потерян, мастер останавливается — вставьте id и секрет из Sources в настройках. Пока коннектор не настроен, модуль выгружает прямым импортом (запасной путь), и диагностика показывает маршрут выгрузки предупреждением.

Страница настроек

Классическая страница настроек задаётся по сайтам (над формой появляется переключатель, если сайтов больше одного) и состоит из пяти вкладок.

Основные настройки

Маппинг инфоблоков — какой инфоблок в какую коллекцию, поля поиска (query_by) и свойства-фасеты; у каждой строки есть кнопка Переиндексировать.

Что не выгружать — применяется при каждой выгрузке; после изменения правил запустите переиндексацию, чтобы они коснулись уже выгруженных товаров.

Безопасность

Один коннектор обслуживает одну коллекцию. Магазину с несколькими каталогами нужен коннектор на каждую коллекцию; заполненное поле Коллекция коннектора не даёт инфоблокам других коллекций уехать не туда, и они идут прежним путём, пока им не заведут свой коннектор.

Дополнительные

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

Первая и дельта-индексация

Любой путь в индекс идёт через очередь модуля; страница Очередь синхронизации показывает, сколько строк ждёт, обрабатывается и завершилось ошибкой.

Деактивация элемента и выход из окна дат активности снимают его с индекса. Обмен с 1С (OnSuccessCatalogImport1C) запускает полную сверку — после него поштучные события ненадёжны; изменение определения свойства переиндексирует инфоблок.

Неудачная строка повторяется через 0 с, 1 мин, 5 мин, 30 мин и 2 ч (разброс ±25%), не больше пяти раз. Ответы, которые повтор не исправит (400, 401, 402, 403, 404, 409, 413, 422), не повторяются — строка остаётся с ошибкой, пока причину не устранят и не повторят её со страницы очереди.

Для крупных каталогов разбирайте очередь из cron, а не на хитах (только CLI; HTTP-запрос получает 404):

*/5 * * * * php /path/to/site/bitrix/tools/aac.search/queue_worker.php 1000

Воркер и агент используют общую блокировку, двойной обработки не будет.

Режим pull, если хостинг закрывает исходящие соединения

Задайте Токен доступа на вкладке «Безопасность», затем создайте в Sources коннектор с режимом pull, адресом https://ваш-сайт/bitrix/tools/aac.search/pull-outbox.php и тем же токеном. Платформа опрашивает этот адрес по расписанию коннектора — см. Pull. pull-export.php — другой протокол, задача pull платформы его не читает.

Компоненты

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

Остальные: instant.search, search.app, assistant.chat, ai.assistant, no.results.assistant, product.advisor, image.search, voice.search, similar.products, seo.filter, seo.links, search.analytics, search.funnel.

Ключевые параметры (все компоненты принимают также SITE_ID; пустые COLLECTION или IBLOCK_ID — основные из настроек):

Все компоненты поддерживают композитный режим; выдача и фасеты объявлены динамическими зонами, чтобы статический кеш не отдавал устаревшие цены. В режиме правки («Эрмитаж») у результатов появляются кнопки Изменить и Удалить с проверкой прав на инфоблок.

Ключи на витрине

Серверный ключ модуля (API-ключ или ключ установки) на страницу не попадает никогда. Витрина обращается к AACSearch одним из двух способов:

• Напрямую, с браузерным ключом. Виджет, чат помощника и блоки с UI=Y используют ключ, который модуль выпускает через POST /browser-keys: область search, только коллекции и адреса сайта, срок жизни не больше семи дней; ежечасный агент самопроверки продлевает его, когда до истечения остаётся меньше двух суток. Состояние ключа — на странице Виджеты.
• Через сайт. Серверные компоненты обращаются к AACSearch из PHP; голос и фото отправляются в /bitrix/tools/aac.search/media.php, прокси виджета — в /aacsearch/api/. Эти входы ограничены по частоте с IP и принимают только закрытый список действий.

Полного ключа в браузере нет, и напрямую к поисковому движку браузер не обращается.

Виджеты без правки шаблона. Автоподключение на странице Виджеты (widget_autoinject, в классическом режиме включено по умолчанию) добавляет на каждую публичную страницу один скрипт. Он вешает подсказки на штатную строку bitrix:search.title, а на странице поиска заменяет выдачу bitrix:search.page выдачей виджета. Страницы с aacsearch:instant.search не трогаются; если автоопределение промахнулось, селекторы задаются вручную.

Умный фильтр

Получить счётчики фасетов из AACSearch можно двумя способами.

Подмена без правки шаблонов. На странице Штатный поиск настройка Считать умный фильтр в AACSearch (native_filter, по умолчанию выключена; в режиме установки — переключатель Smart filters) ставит тонкого наследника штатного компонента в /local/components/bitrix/catalog.smart.filter. Битрикс ищет компонент сначала там, при том же вызове bitrix:catalog.smart.filter. Наследник подключает штатный класс и файл компонента и подменяет только источник фасетов — шаблоны, вёрстка и параметры остаются ядра.

• Перечисляемые свойства считает AACSearch с учётом уже выбранного посетителем; диапазоны (цена, числовые свойства) остаются за ядром.
• Счётчики приходят только для инфоблоков, выгруженных в AACSearch; для остальных фильтр показывает штатные числа.
• Если платформа не ответила или свойство неизвестно, фильтр всё равно рисуется со штатными счётчиками.
• Если по этому пути уже лежит чужая подмена, модуль её не перезаписывает и предупреждает. Снятая галочка удаляет наследника.

Соседняя настройка Отбирать товары каталога в AACSearch (native_catalog) так же ставит наследников catalog.section, catalog.top, catalog.element и news.list: страницу товаров выбирает индекс, а ядро по-прежнему загружает элементы и проверяет активность, даты и права. Если инфоблок не выгружен, сортировку нельзя воспроизвести индексом или платформа недоступна — выборку делает ядро.

Компонент. aacsearch:smart.filter рисует собственную форму по фасетам платформы. Рядом с aacsearch:search.results он получает фасеты параметром FACETS и лишнего запроса не делает; на странице раздела, где выдачи рядом нет, запрашивает AACSearch сам.

SEO-страницы фильтра

• SEO-страницы → метатеги страниц фильтра хранит правила по инфоблокам: шаблоны заголовка, описания и т. д. с подстановками вроде #SECTION#, #PROPERTY#, #VALUE#, #SECTION_CODE#, #SITE_DIR#. Правило с неизвестной подстановкой не сохраняется.
• aacsearch:seo.filter выводит посадочную страницу комбинации фильтров: находит подготовленную страницу для текущего адреса (или URL) и до вывода <head> ставит title, description, keywords, robots и <link rel="canonical">. Комбинация материализуется лениво при первом визите, поэтому метатеги действуют со второго.
• Адреса страниц строятся в ЧПУ-виде фильтра (/catalog/noutbuki/filter/brend-lenovo/apply/) от директории сайта, значения фильтра сортируются — одинаковые условия всегда дают одинаковый адрес.
• Страница админки SEO-страницы показывает сгенерированные страницы, запускает массовую генерацию и ревизию и выгружает файл карты сайта; aacsearch:seo.links показывает ссылки на связанные страницы фильтра.

Голосовой поиск

aacsearch:voice.search добавляет кнопку микрофона. Браузер записывает звук и отправляет его в /bitrix/tools/aac.search/media.php; модуль отправляет запись в POST /collections/{collection}/documents/search/by_voice серверным ключом и возвращает распознанный текст и результаты. Кнопка показывается, только если:

• включён Голосовой поиск (enable_voice_search, по умолчанию выключен);
• тариф включает voice_search и есть кредиты (голос тарифицируется по минутам аудио, см. кредиты);
• страница открыта по HTTPS — иначе браузер не даёт доступ к микрофону.

Рекомендации

aacsearch:recommendations показывает блок для PRODUCT_ID выбранного RECOMMENDATION_TYPE: similar, also_bought, personal, trending или recently_viewed. Нужна включённая enable_recommendations.

• С UI=Y (по умолчанию) блок — элемент платформы <aacsearch-recommendations>, который рисуется в браузере из моделей платформы по браузерному ключу.
• С UI=N или когда браузерного ключа нет, модуль получает идентификаторы на сервере и собирает карточки из Битрикса (CardReader) — с актуальными ценами и проверкой прав.

Мастер заводит модели под постоянными идентификаторами bitrix_<стратегия>, поэтому повторный прогон их не плодит: similar → looking_similar, also-bought → bought_together, personal → session, trending → trending. «Вы смотрели» — история визита посетителя, а не модель. aacsearch:similar.products подбирает похожие товары по названию и свойствам из поискового индекса.

Диагностика и типичные проблемы

Начните с Сервисы → AACSearch → Диагностика: проверки связи, окружения, редакции, инфоблоков, прав, очереди, секретов и маршрута выгрузки — с объяснением, что исправить, и кнопками Восстановить агенты, Зашифровать сейчас и Дообновить установку. Затем — Журнал: фильтр по уровню («этот и всё, что важнее»), источнику и тексту. Причины отказов выгрузки, сорванные обращения к API и ошибки секретов лежат там.

Поддержка: support@aacsearch.com.