1. Назначение и принцип работы

Bussol SmartSearch — модуль интеллектуального поиска для «1С-Битрикс: Управление сайтом». Он помогает находить элементы инфоблоков по названию, тексту, символьным кодам, артикулам и настраиваемым свойствам, даже если запрос введён с ошибочной раскладкой или содержит простые опечатки.

Версия документации: 2.0.10. Основана на исходных файлах сборки bussol.smartsearch-2.0.10-security-fixed.zip.

2. Что нового в версии 2.0.10

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

3. Системные требования и зависимости

Поиск по изображениям не требует передачи загружаемого изображения стороннему API: dHash рассчитывается внутри PHP-приложения.

4. Установка и первое включение

Новая установка

1. Распакуйте дистрибутив, убедитесь, что каталог модуля называется bussol.smartsearch.
2. Разместите каталог в /local/modules/bussol.smartsearch/ (рекомендуемый вариант) либо /bitrix/modules/bussol.smartsearch/.
3. Войдите в админку Битрикс с правами администратора, установите модуль через раздел установленных модулей.
4. В левом меню откройте Bussol → Умный поиск → Настройки. Если раздел не появился после обновления — обновите интерфейс админки с очисткой её кэша.
5. На вкладке нужного сайта включите модуль, выберите инфоблоки и поисковые поля, сохраните изменения.
6. Запустите полную переиндексацию для выбранного сайта и дождитесь выполнения агента.
7. Разместите компонент на странице или в шаблоне сайта и выполните контрольные запросы.

Обновление с 2.0.9 до 2.0.10

• Сделайте резервную копию и проверьте активные настройки всех сайтов.
• Обновите файлы модуля через штатный механизм распространения или замену каталога с сохранением его расположения.
• Убедитесь, что обновились файл версии, скрипт компонента и административные файлы.
• Перезапустите переиндексацию, если менялись индексируемые поля, свойства или поиск изображений.
• Повторно проверьте ввод текста, загрузку изображения и права пользователей.

Не удаляйте и не переустанавливайте модуль исключительно ради обновления: удаление может затронуть данные индекса в зависимости от выбранного режима удаления.

5. Меню администрации и права доступа

В версии 2.0.10 модуль добавляет собственный пункт в общее левое меню Bussol, аналогично другим решениям разработчика.

Bussol
  └── Умный поиск
       └── Настройки

Общая иконка раздела Bussol используется совместно с другими модулями; пункт SmartSearch содержит собственную иконку на основе логотипа поиска.

6. Настройки по сайтам: полный справочник

Для каждого сайта Битрикс интерфейс показывает отдельную вкладку. Идентификатор сайта состоит из двух символов. Набор параметров хранится по сайту, поэтому настройки разных сайтов не смешиваются.

Какие поля поддерживаются

Допустимые поля в интерфейсе: NAME, PREVIEW_TEXT, DETAIL_TEXT, SEARCHABLE_CONTENT, CODE, XML_ID. Свойства указываются по символьным кодам, например ARTICLE,CML2_ARTICLE.

7. Подключение компонента на сайт

Форма поиска подключается стандартным компонентом bussol:smartsearch. Размещайте её в нужной области шаблона сайта или на обычной странице.

<?php
$APPLICATION->IncludeComponent(
    'bussol:smartsearch',
    '',
    [
        'SITE_ID' => SITE_ID,
        'PLACEHOLDER' => 'Название, артикул или модель',
        'SHOW_SCOPE' => 'Y',
        'CACHE_TIME' => 3600,
    ]
);

Шаблон по умолчанию располагается в install/components/bussol/smartsearch/templates/.default/. При оформлении сайта рекомендуется переопределять шаблон штатными средствами Битрикс.

8. Текстовый поиск и исправление запросов

Посетитель вводит запрос и нажимает кнопку «Найти». Клиент обращается к серверному действию bussol:smartsearch.search.query, передавая текст, сайт, выбранную область и признак голосового ввода.

Как обрабатывается запрос

1. Нормализация текста (в том числе раскладки и смешанной кириллицы/латиницы).
2. Выбор настроенных инфоблоков и, если указано, одного инфоблока из списка областей.
3. Поиск соответствий по нормализованному индексу; при необходимости — приближённый поиск по ошибкам.
4. Проверка активности элементов, актуальности дат и прав доступа при получении карточек.
5. Если индекс не дал результат — резервный поиск по элементам инфоблоков.

Сервер ограничивает длину текстового запроса до 200 символов. Если ввод короче установленного минимума, поисковая выдача не формируется.

9. Голосовой ввод: работа и ограничения

Кнопка с микрофоном показывается, если параметр «Разрешить голосовой ввод» включён. При её нажатии модуль запускает браузерное распознавание через Web Speech API.

• Откройте страницу через HTTPS.
• Разрешите сайту использование микрофона в настройках браузера.
• Нажмите кнопку микрофона и произнесите название или артикул.
• Проверьте текст, подставленный в строку; поиск запускается после распознавания.

Язык распознавания задаётся для сайта (по умолчанию ru-RU). Если распознавание не запускается, проверьте HTTPS, разрешение микрофона, версию браузера и настройки приватности.

10. Поиск по похожему изображению

Функция включается отдельно для каждого сайта. Для элементов индекса используется изображение DETAIL_PICTURE, а при его отсутствии — PREVIEW_PICTURE. У загружаемого файла и изображений каталога вычисляется компактный хеш dHash.

Настройка и использование

1. Убедитесь, что на сервере установлено расширение GD.
2. В параметрах нужного сайта включите «Поиск похожих изображений».
3. Запустите полную переиндексацию, чтобы сформировать хеши изображений элементов.
4. Откройте страницу с компонентом, нажмите иконку изображения и выберите файл.
5. Просмотрите выдачу; при слишком широкой области выберите более узкий инфоблок.

Браузер передаёт изображение вашему сайту; сторонний облачный API модулем для этого действия не вызывается.

11. Индексация и обновление данных

Модуль создаёт служебную таблицу b_bussol_smartsearch_index. В ней для связки сайта и элемента сохраняются три текстовых представления поиска, ID инфоблока, ID элемента, опциональный хеш изображения и время обновления.

Автоматическая актуализация

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

Полная переиндексация

1. Сохраните настройки поиска на вкладке сайта.
2. Нажмите «Запустить переиндексацию сайта».
3. Битрикс ставит агент с обработкой до 100 элементов за проход; агент продолжает работу до завершения.
4. Проверьте, что система агентов на сайте реально выполняется, и протестируйте поиск после окончания процесса.

При полной перестройке индекс соответствующего сайта очищается и формируется заново. Поэтому на загруженном проекте лучше планировать переиндексацию на время низкой активности.

12. Интерфейс выдачи и внешний вид

В составе стандартного шаблона доступны поисковая строка, кнопка «Найти», опциональный список областей, микрофон, выбор файла и контейнер AJAX-результатов.

Настройка палитры производится на вкладке сайта и проверяется форматом #RRGGBB. В шаблоне значения подключаются через CSS-переменные --bussol-submit-bg, --bussol-submit-color, --bussol-input-border.

13. Техническая архитектура и интеграция

Публичные действия

bussol:smartsearch.search.query
bussol:smartsearch.search.image

Текстовый поиск выполняется посредством AJAX с проверкой входных параметров; изображение отправляется POST + FormData с токеном CSRF. Оба действия возвращают ответ, который обрабатывается стандартным JavaScript шаблона.

Структура успешного результата

{
  "query": "насос",
  "correctedQuery": null,
  "source": "index",
  "count": 1,
  "items": [
    { "id": 123, "iblockId": 7, "name": "Название",
      "url": "/catalog/item/", "picture": "", "score": 100 }
  ]
}

14. Безопасность, доступ и конфиденциальность

• Данные поиска формируются по выбранным администратором инфоблокам; перед выдачей результатов выполняется проверка активности, дат и прав доступа к элементам.
• Для загруженного изображения проверяются сам факт загрузки, MIME-подобная сигнатура изображения, размер файла и разрешение перед декодированием.
• Для загрузки файла применяется CSRF-проверка Битрикс, запрос ограничен POST.
• В шаблоне выдачи ссылки ограничены схемами http: и https:; текст результата вставляется безопасными DOM-операциями.
• Подсказки исправления формируются с учётом реально доступных посетителю элементов.
• В административной форме используется проверка сессии; вводимые настройки проходят проверку допустимых типов, полей и инфоблоков.

Версия 2.0.10 прошла локальную проверку кода с выпуском отдельного security-journal.json; она не заменяет независимую проверку Marketplace и проверку на вашей конфигурации сервера.

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

15. Диагностика: типичные вопросы

При обращении в техническую поддержку полезно приложить версию модуля, идентификатор сайта, PHP-версию, версию Битрикс и обезличенный ответ AJAX-запроса.

16. Чек-лист приёмки и эксплуатации

• Модуль bussol.smartsearch версии 2.0.10 установлен и корректно отображается в списке модулей.
• В левом меню открывается Bussol → Умный поиск → Настройки.
• Для каждого сайта заданы требуемые инфоблоки, поля и свойства; сохранение настроек проходит без ошибок.
• Переиндексация запущена, агент завершает обработку элементов.
• Обычный поиск находит известный активный элемент по названию и артикулу.
• Проверено поведение для опечаток, неверной раскладки и короткого запроса.
• В гостевой сессии не видны элементы, к которым отсутствует доступ.
• Проверена форма на мобильном устройстве и работа AJAX в композитном режиме.
• Если включён голосовой ввод — проверены HTTPS и разрешение микрофона.
• Если включён поиск изображений — есть GD, хеши после переиндексации, проверены ограничения файла и узкая область поиска.
• Цвета кнопки и поля соответствуют оформлению каждого сайта.
• Создана резервная копия перед обновлением; сохранена проверенная конфигурация и журнал изменений.

Версия: 2.0.10 · ID: bussol.smartsearch · Документ: техническая и пользовательская документация.