1. Назначение и архитектура

Региональный контекст без дублирования сайта

Модуль связывает выбранный посетителем регион с данными сайта: доменом или поддоменом, городом в справочнике местоположений, контактами, ценовыми типами, складами, контентом и SEO-переменными.

• Выбор региона хранится для соответствующего сайта и может происходить автоматически по GeoIP либо вручную через компонент.
• Для каждого сайта используется отдельный инфоблок регионов и собственные настройки.
• Регионы представлены элементами инфоблока, а округа и субъекты — его разделами.
• Интеграции с товарным каталогом работают через обработчики и вспомогательное PHP API.

2. Возможности версии 1.11.6

Ключевой функционал

• Два режима: единый домен с cookie или отдельные региональные домены/поддомены.
• GeoIP на основе механизмов платформы с уточнением местоположения у посетителя.
• Три вида интерфейса выбора региона: DROPDOWN, COLUMNS и SEARCH.
• Региональные телефоны, e-mail, адреса, графики, домены и пользовательские поля.
• Маркеры #REGION_...# для итогового HTML и REGION_* для почтовых событий.
• Региональная фильтрация товаров и разделов; ограничение типов цен и складов (опционально).
• Поддержка многосайтовости, Композита и динамических фреймов.
• Фоновая загрузка демонстрационного справочника регионов.
• Левое административное меню Bussol с собственным пунктом «Мультирегиональность».

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

До установки проверьте окружение

Компонент интерфейса написан без зависимости от jQuery. Для GeoIP нужен настроенный и работающий в Битрикс провайдер; точность определения зависит от провайдера и IP-адреса посетителя.

4. Установка, обновление и удаление

Процедуры для администратора

4.1. Первичная установка

1. Сделайте резервную копию файлов и базы данных сайта.
2. Скопируйте каталог bussol.regions в /local/modules/ (рекомендуется) либо /bitrix/modules/.
3. В административной панели откройте Marketplace → Установленные решения и установите «Bussol: Мультирегиональность».
4. Перейдите в Bussol → Мультирегиональность → Настройки и выберите сайт.
5. Проверьте созданный инфоблок, включение модуля и статус фонового импорта.
6. Добавьте компонент выбора региона в шаблон сайта (раздел 5).

4.2. Обновление на 1.11.6

1. Зафиксируйте текущие настройки и сделайте резервную копию.
2. Обновите файлы модуля, сохранив его код bussol.regions.
3. Откройте админку: обработчик общего меню Bussol, CSS и иконки восстанавливаются автоматически.
4. Откройте «Настройки» и нажмите «Проверить и восстановить структуру», если необходимо синхронизировать данные и публичные файлы.
5. Очистите актуальные кеши и проверьте регионы, каталог, оформление заказа и домены.

4.3. Удаление

Удаление выполняйте через штатный менеджер модулей. Перед этим экспортируйте региональные контакты, привязки и настройки проекта. Данные и последствия удаления проверьте на тестовой копии; не полагайтесь на сохранение инфоблока без отдельной резервной копии.

5. Быстрый запуск

Минимальная рабочая конфигурация

1. В «Настройках» выберите нужный сайт и убедитесь, что у него создан инфоблок регионов.
2. Оставьте режим ONE_DOMAIN, если региональные поддомены пока не готовы.
3. Убедитесь, что в инфоблоке есть активные элементы и один из них отмечен DEFAULT.
4. Разместите компонент bussol:regions.selector в шапке шаблона.
5. Откройте сайт в приватном окне браузера, переключите город, перезагрузите страницу и проверьте сохранение выбора.

<?php
$APPLICATION->IncludeComponent(
    'bussol:regions.selector',
    '.default',
    [
        'SITE_ID' => SITE_ID,
        'VIEW' => 'DROPDOWN',
        'SHOW_SEARCH' => 'Y',
        'SHOW_CONFIRM' => 'Y',
        'RETURN_URL' => '',
    ],
    false,
    ['HIDE_ICONS' => 'Y']
);

6. Административный центр и права

Боковое меню Bussol

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

Вкладки страницы настроек

7. Инфоблок регионов

Поля и правила заполнения

Модуль использует отдельный инфоблок на каждый сайт. Элементы представляют города/регионы продаж, а разделы задают иерархию для интерфейса COLUMNS. Состав свойств создаётся и восстанавливается установщиком.

1. Откройте Bussol → Мультирегиональность → Регионы и перейдите к инфоблоку нужного сайта.
2. Откройте элемент населённого пункта.
3. Заполните название, активность, местоположения LOCATION_LINK, контакты и при необходимости домен.
4. Для коммерческих ограничений свяжите типы цен и склады, затем сохраните.
5. Проверьте, что элемент доступен в селекторе и корректно определяется при переключении.

8. Справочник и фоновый импорт

Откуда берутся округа, субъекты и города

В дистрибутив включён демонстрационный набор: 8 федеральных округов, 86 субъектов и 1 629 элементов населённых пунктов. Он рассчитан на сопоставление с фактической базой местоположений Битрикс, а не на безусловный перенос чужих числовых ID.

• Импорт запускается агентом и обрабатывает не более 10 элементов за один проход.
• В настройках отображаются состояние, счётчик выполненных элементов и сообщение об ошибке или предупреждении.
• Для одноимённых городов учитывается субъект; альтернативные обозначения населённых пунктов также обрабатываются.
• Если запись sale не найдена, элемент региона может быть создан без LOCATION_LINK и потребует ручной привязки.
• Повторный запуск восстановления структуры позволяет продолжить импорт без создания дублей.

9. Один домен или поддомены

Выбор режима размещения

9.1. Включение SUBDOMAIN

1. Подготовьте DNS и SSL для всех региональных адресов.
2. Добавьте соответствующие домены и алиасы в конфигурацию сайта Битрикс и веб-сервера.
3. Укажите MAIN_DOMAIN у элементов регионов, например kazan.example.ru — без схемы и пути.
4. На вкладке «Основные» выберите режим «Отдельный домен/поддомен».
5. При необходимости задайте COOKIE_DOMAIN и SCHEME на вкладке «Дополнительно».
6. Проверьте переход между городами на HTTPS без циклических редиректов.

10. GeoIP и подтверждение города

Автоматическое определение с возможностью выбора

При включённом GeoIP модуль пытается получить город посетителя через штатные механизмы платформы и сопоставить его с местоположениями sale и привязками LOCATION_LINK в инфоблоке. Точная привязка города имеет приоритет перед более общим совпадением по территории.

• Если автоматический город отличается от региона по умолчанию, посетителю может показываться информер с вопросом о городе.
• «Да, всё верно» подтверждает определённый город и сохраняет региональный выбор.
• «Выбрать другой» открывает основной селектор.
• Закрытие крестиком запоминается для текущего контекста сравниваемых городов.
• Для пользователя с подтверждённым ручным выбором повторная подсказка не должна показываться на каждом запросе.

Настройка информера

1. На вкладке «Основные» включите «Определять регион по GeoIP» и «Показывать подтверждение определённого региона».
2. Настройте четыре цвета: фон и текст кнопки подтверждения; фон и текст кнопки выбора.
3. Проверьте текст вопроса и действия в приватном окне при разных исходных условиях.
4. Для проверки нестандартных IP-путей используйте тестовую среду с известной конфигурацией прокси.

11. Компонент выбора региона

Три варианта интерфейса

В представлениях COLUMNS и SEARCH окно создаётся по нажатию и удаляется при закрытии. В поиске под названием может отображаться путь «Город, субъект, округ», если он задан структурой инфоблока.

<?php
$APPLICATION->IncludeComponent(
    'bussol:regions.selector',
    '.default',
    [
        'SITE_ID' => SITE_ID,
        'VIEW' => 'COLUMNS',
        'SHOW_SEARCH' => 'Y',
        'SHOW_CONFIRM' => 'Y',
        'RETURN_URL' => '/catalog/',
    ]
);

12. Региональная фильтрация контента

Товары и разделы

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

1. Добавьте свойство LINK_REGION в нужные товарные инфоблоки; проверьте формат и значения привязок.
2. При необходимости создайте UF_REGION у разделов.
3. На вкладке «Каталог» включите фильтрацию и проверьте коды полей.
4. Примените фильтр в интеграционном коде шаблона перед вызовом каталожного компонента.
5. Проверьте товары без привязок, товары для одного региона и разделы с несколькими условиями.

<?php
use Bitrix\Main\Loader;
use Bussol\Regions\RegionFilter;

Loader::includeModule('bussol.regions');

$GLOBALS['catalogFilter'] = [
    'IBLOCK_ID' => 7,
    'ACTIVE' => 'Y',
];
RegionFilter::applyToElements($GLOBALS['catalogFilter']);

$sectionFilter = ['IBLOCK_ID' => 7];
RegionFilter::applyToSections($sectionFilter);

13. Цены, остатки и корзина

Сценарии с повышенным влиянием на заказ

Свойства PRICES_LINK и STORES_LINK связывают регион с типами цен и складами. По умолчанию глобальная фильтрация цен и наличие по складам выключены; включение меняет логику витрины и может повлиять на корзину и оформление заказа.

<?php
use Bitrix\Main\Loader;
use Bussol\Regions\RegionFilter;

Loader::includeModule('bussol.regions');
RegionFilter::applyToCatalogParameters($arParams);

$APPLICATION->IncludeComponent(
    'bitrix:catalog',
    '.default',
    $arParams
);

1. Привяжите типы цен и склады у регионов.
2. Проверьте карточку товара и корзину с выбранным регионом.
3. Создайте тестовый заказ в каждом целевом регионе.
4. Проверьте смену региона с товарами в корзине и недоступным складом.
5. Только после этого включайте глобальные ограничения на production.

14. SEO-маркеры и почтовые события

Региональные данные в страницах и коммуникациях

При SEO_REPLACE_ENABLED = Y маркеры заменяются в итоговом HTML. При MAIL_FIELDS_ENABLED = Y соответствующие значения добавляются в поля почтовых событий.

<h1>Доставка в #REGION_NAME#</h1>
<p>Адрес офиса: #REGION_ADDRESS#</p>
<p>Телефон: #REGION_PHONE#</p>

15. PHP API и события

Использование текущего региона в собственном коде

<?php
use Bitrix\Main\Loader;
use Bussol\Regions\RegionManager;

if (Loader::includeModule('bussol.regions')) {
    $manager = RegionManager::getInstance(SITE_ID);
    $region = $manager->getCurrentRegion();
    $location = $manager->getCurrentLocation();
    $regions = $manager->getRegions();
    $url = $manager->getRegionUrl((int)($region['ID'] ?? 0), '/catalog/');
}

Публичный API и обработчики событий рекомендуется подключать через штатный Loader и регистрировать согласно соглашениям Битрикс. Для внедрений проверяйте типы и полноту возвращённых данных: текущий регион может оказаться пустым, если справочник ещё не заполнен.

16. Cookie, прокси, Композит и безопасность

Хранение выбора и доверие к инфраструктуре

Cookie выбора имеют суффикс сайта, чтобы избежать смешивания между многосайтовыми конфигурациями. Для основных cookie используются HttpOnly и SameSite=Lax; на HTTPS устанавливается Secure. Компонент работает с динамическим фреймом Композита, а уточнение GeoIP получает актуальные данные отдельным AJAX-запросом.

Действия AJAX-компонента используют POST и CSRF-защиту. Поля настроек администратора также проверяются штатной сессией. Это не отменяет регулярного обновления платформы и проверки используемой инфраструктуры.

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

Как локализовать причину неисправности

Проверка файловой структуры

node tests/static-check.mjs
node --check install/js/location.js
node --check install/components/bussol/regions.selector/templates/.default/script.js

18. Чек-лист приёмки и ограничения

Финальная проверка перед production

• Модуль установлен; версия 1.11.6 отображается в установленном решении.
• Для каждого сайта выбран корректный инфоблок; импорт завершён или предупреждения обработаны.
• Есть регион по умолчанию, настроены контакты и LOCATION_LINK у критичных городов.
• В селекторе переключаются все нужные города в режимах, используемых на проекте.
• GeoIP и подтверждение проверены в приватном окне и после ручного выбора.
• На всех доменах исправно работают HTTPS, cookie и навигация.
• Проверены региональные контакты и маркеры на реальной странице.
• Каталожные фильтры протестированы на общих и региональных товарах.
• При включённых ограничениях пройдены тестовые заказы, смена региона и складские сценарии.
• Проверены Композит и пользовательские страницы без статической утечки регионального контента.
• Сохранена резервная копия, зафиксированы результаты тестов и назначен ответственный за поддержку.

Известные границы

Модуль не занимается настройкой DNS и SSL, не гарантирует точность внешнего GeoIP-провайдера, не создаёт автоматически уникальные региональные sitemap.xml/robots.txt и не реализует отдельный интерфейс правил скидок/наценок. Расширенные сценарии доставки, оплаты и склада требуют проверки и возможной адаптации под конкретную корзину и шаблон.

19. Приложение: карта настроек и терминов

Краткий справочник

Термины: «регион» — элемент инфоблока; «местоположение» — запись sale, которая может быть связана с регионом; «режим доменов» — способ построения адресов региональных страниц; «региональный контекст» — набор данных, выбранных для пользователя и сайта.