1. Назначение и модель работы

Bussol: Мультикорзина 2.0.12 добавляет интернет-магазину несколько именованных покупательских корзин поверх штатной корзины 1С-Битрикс. Покупатель может хранить несколько вариантов покупки, искать товары сразу по всем корзинам, упорядочивать корзины, добавлять новые товары из каталога прямо из панели, переключать активную корзину, копировать списки, переносить, удалять и редактировать количество позиций. Оформление заказа продолжает выполняться стандартными средствами магазина.

Основные возможности для покупателя

• несколько корзин с собственным названием и цветом;
• создание, переименование, копирование и удаление неактивных корзин;
• drag&drop-сортировка корзин с сохранением порядка; поддерживаются touch и клавиатурные стрелки на маркере сортировки;
• глобальный поиск по всем корзинам по названию товара, ID и свойствам позиции с переходом к найденной корзине;
• добавление нового товара прямо из панели: поиск по каталогу, фильтр по разделам с включением подразделов, выбор количества, добавление в активную или сохранённую корзину;
• переключение активной корзины с сохранением исходного списка;
• перенос выбранных строк в другую сохранённую корзину;
• удаление отдельного товара прямо из панели;
• изменение количества в активной и сохранённой корзине: −/+, ручной ввод и сохранение;
• изображения, свойства строки/SKU и ориентировочные суммы;
• работа для гостей и авторизованных покупателей;
• адаптивная панель для настольных, touch- и мобильных экранов.

Что получает администратор

• раздельные настройки по сайтам (LID);
• автоматическую плавающую кнопку или ручное размещение компонента;
• настройку скругления, цвета фона, цвета текста/иконки, показа количества, суммы и подписи BUSSOL;
• поддержку технологии «Композитный сайт»;
• повторную публикацию интерфейсных файлов и очистку композитного кеша;
• импорт сохранённых корзин версии 1.3.4 при первом открытии панели;
• серверное хранение состояния вместо localStorage.

2. Что изменилось в актуальной версии

Документация пересобрана для модуля bussol.multicorzine2 версии 2.0.12 и включает функции веток 2.0.11 и 2.0.12: поиск по корзинам, добавление товара из каталога, сортировку корзин и фильтр каталога по разделам.

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

Контролируемые лимиты

• лимит создаваемых корзин: от 2 до 30, по умолчанию 10;
• до 500 позиций в операциях копирования, переключения и переноса;
• максимальный размер серверного JSON-состояния владельца/сайта: 8 МБ;
• название корзины: 1–80 символов;
• тело публичного API-запроса: не более 64 КБ;
• catalogSections возвращает не более 1000 разделов за запрос;
• productSearch возвращает не более 20 товаров; текстовый запрос — от 2 до 80 символов, цифровой ID допускается отдельно.

4. Установка

1. Распакуйте каталог bussol.multicorzine2 в /local/modules/. Не создавайте вторую копию этого же модуля в /bitrix/modules/.
2. Откройте «Настройки → Настройки продукта → Модули» и установите «Bussol: Мультикорзина».
3. Перейдите в «Bussol → Мультикорзина → Настройки → нужный сайт».
4. Укажите фактический путь штатной корзины магазина. Значение по умолчанию: /personal/cart/.
5. Настройте лимит корзин, режим показа и оформление кнопки «Мои корзины».
6. Сохраните настройки. После обновления внешнего вида/ресурсов очистите обычный и композитный кеш.
7. Проведите приёмочные сценарии из раздела 18 в конфигурации конкретного магазина.

Что устанавливается

5. Настройки по сайтам

Настройки хранятся отдельно для каждого LID. Для просмотра страницы настроек достаточно права R на модуль, для изменения требуется W. Обновление интерфейсных файлов и подготовка перехода с 1.3.4 доступны только администратору.

Обновление интерфейсных файлов

В блоке «Обновление интерфейса» доступна кнопка «Обновить файлы интерфейса». Она повторно копирует актуальные JS/CSS/иконки, переустанавливает события и очищает композитный кеш. Используйте её после обновления заменой файлов, через Marketplace или если браузер продолжает получать старые widget.js/widget.css.

6. Интерфейс покупателя

Панель реализована как Web Component с Shadow DOM: стили модуля изолированы от CSS шаблона магазина. На широком экране список корзин и выбранная корзина отображаются рядом; на мобильном интерфейс перестраивается. Версия 2.0.12 дополняет панель глобальным поиском, сортировкой корзин и каталоговым picker с фильтром по разделам.

Кнопка «Мои корзины»

• может быть плавающей или встроенной через компонент;
• по настройкам отображает количество товаров, сумму или оба показателя;
• агрегаты подгружаются отдельным read-only запросом summary и не встраиваются в композитный HTML-кеш;
• после OnBasketChange и возврата на вкладку показатели обновляются.

Левая область: корзины, поиск и порядок

• поиск выполняется по уже загруженным корзинам текущего владельца: название товара, PRODUCT_ID и значения свойств;
• результат поиска открывает соответствующую корзину и позицию;
• маркер сортировки позволяет менять порядок мышью или Pointer Events; стрелки на маркере дают клавиатурную альтернативу;
• сервер принимает только полный набор ID принадлежащих владельцу корзин и отвергает дубликаты/чужие ID.

Карточка товара

• название, изображение, редактируемое количество и ориентировочная цена/сумма;
• свойства строки/SKU сохраняются отдельно;
• для SKU при отсутствии собственной картинки выполняется попытка использовать изображение родительского товара;
• если изображения нет, выводится встроенная заглушка;
• доступны −/+, ручной ввод, «Сохранить» и отдельная кнопка удаления.

7. Пользовательские операции

7.1 Создание корзины

1. Откройте панель и нажмите «Создать корзину».
2. Введите название до 80 символов и выберите цвет.
3. Новая корзина создаётся пустой и не становится активной автоматически.

7.2 Переименование и цвет

Для выбранной корзины откройте редактирование и задайте новое имя/цвет. Цвет проходит серверную проверку формата #RRGGBB.

7.3 Сортировка корзин

Перетащите корзину за маркер drag&drop. На touch-устройствах используются Pointer Events. Для клавиатуры доступны стрелки на маркере сортировки. Новый порядок сохраняется на сервере для текущего владельца и сайта.

7.4 Поиск по всем корзинам

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

7.5 Добавление товара из каталога

1. Выберите корзину, в которую нужно добавить товар, и откройте «Добавить товар».
2. При необходимости выберите раздел каталога. Список разделов формируется сервером из активных разделов товарных инфоблоков, доступных текущему пользователю.
3. Введите название или ID товара. Для текстового поиска требуется минимум 2 символа.
4. Поиск учитывает выбранный раздел и его подразделы. Для торгового предложения (SKU) принадлежность разделу проверяется по родительскому товару.
5. Укажите количество и нажмите «Добавить». Для активной корзины используется штатный D7 Catalog Basket; для сохранённой корзины формируется серверный снимок товара.
6. Цена, provider, USER_ID и FUSER_ID не принимаются от браузера как доверенные данные.

7.6 Копирование

«Создать копию» клонирует сохранённый снимок выбранной корзины. К имени добавляется «— копия». Перед созданием проверяются лимит и поддерживаемая структура строк.

7.7 Переключение активной корзины

При команде «Сделать активной» модуль проверяет снимок и провайдеры, затем заменяет текущую live-корзину через Bitrix Sale, выполняет refresh/save, отправляет bussol:cart-changed и OnBasketChange и перезагружает страницу. Это позволяет штатному шаблону заново получить актуальную корзину.

7.8 Перенос выбранных товаров

Отметьте нужные строки, выберите другую неактивную корзину и выполните перенос. Строки с одинаковым PRODUCT_ID, но разными свойствами/SKU не объединяются только по PRODUCT_ID.

7.9 Удаление отдельного товара

• у каждой обычной позиции есть кнопка «Удалить товар» и подтверждение операции;
• для сохранённой корзины меняется только её серверный снимок;
• для активной корзины строка удаляется из live-корзины Bitrix, затем отправляется OnBasketChange;
• сервер проверяет принадлежность корзины, revision-token и идентификатор конкретной строки;
• позиции комплектов/наборов с TYPE или SET_PARENT_ID по одной строке из панели не удаляются — используйте штатную корзину магазина.

7.10 Изменение количества товара

• кнопки «−» и «+» быстро изменяют количество;
• числовое поле поддерживает ручной ввод и дробные значения до трёх знаков после запятой;
• «Сохранить» отправляет только ID позиции, новое количество и актуальный revision-token;
• в активной корзине выполняются изменение QUANTITY, refresh/save и OnBasketChange; панель остаётся открытой;
• в сохранённой корзине меняется только серверный снимок;
• нулевые, отрицательные, слишком большие значения и неподдерживаемые комплекты отклоняются.

7.11 После оформления заказа

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

8. Мобильный режим

На экранах до 740 px и на устройствах с coarse pointer панель использует собственный viewport-fixed режим и не полагается на нативное поведение <dialog>. Ключевые действия остаются доступны при touch-управлении.

• position: fixed; окно занимает доступную ширину и высоту viewport;
• учитываются env(safe-area-inset-*) для iPhone;
• прокрутка страницы под панелью блокируется, состав прокручивается внутри панели;
• до 560 px карточка товара перестраивается в мобильную сетку;
• кнопки удаления, редактирования количества и основные действия имеют touch-размер не менее 44 px;
• drag&drop порядка корзин работает через Pointer Events;
• для браузеров без showModal() действует fixed-fallback.

9. Композитный режим

Модуль поддерживает технологию «Композитный сайт». Ручной компонент явно голосует за композит. Автоматическая вставка не выполняется в фоновом composite-AJAX ответе, чтобы не создавать дубли. Персональные корзины, USER_ID/FUSER_ID и CSRF-токен не включаются в статическую оболочку страницы.

• summary загружает агрегаты кнопки отдельным read-only запросом;
• list и остальные персональные данные загружаются после инициализации панели;
• после обновления JS/CSS используйте «Обновить файлы интерфейса» и очистите композитный кеш;
• на приёмке проверьте первый полный hit, повторный hit из static HTML cache и фоновый composite-AJAX.

10. Ручное размещение компонента

Если автоматическая плавающая кнопка не нужна, отключите её для сайта и вставьте компонент в подходящее место шаблона/страницы:

<?php
$APPLICATION->IncludeComponent(
    'bussol:multicorzine.multicorzine',
    '',
    [],
    false
);

Компонент выводит кнопку в потоке страницы и открывает ту же независимую панель. Он не заменяет bitrix:sale.basket.basket и не требует правок шаблона штатной корзины. Персональный состав загружается отдельным запросом.

11. Публичный API

Endpoint после установки: /bitrix/tools/bussol.multicorzine2/api.php. Используется POST с X-Requested-With: XMLHttpRequest и подписанным идентификатором сайта. CORS не включён. Все действия, кроме summary и bootstrap, требуют действующий sessid.

Коды ответа

12. Архитектура и хранение данных

BasketAdapter работает с текущей неоформленной корзиной Bitrix\Sale\Basket::loadItemsForFUser. Заказы модулем не изменяются.

Состояние владельца

• таблица b_bussol_mc_state_v2 содержит один JSON-документ для владельца и сайта;
• ключ — SHA-256 от идентичности владельца и LID;
• в JSON хранятся active, revision, carts, legacyImported и серверные снимки неактивных корзин;
• идентификатор сохранённой корзины — случайные 96 бит;
• данные хранятся в БД магазина, а не в localStorage.

Синхронизация с live-корзиной

На list модуль перечитывает текущую live-корзину sale и подменяет содержимое active актуальными строками. Неактивные снимки не затрагиваются. После заказа это предотвращает возврат оформленных товаров из старого снимка.

Каталог и разделы

catalogSections строит дерево из активных доступных разделов товарных инфоблоков. productSearch сначала проверяет права, активность и доступность товаров, затем при выбранном sectionId проверяет принадлежность разделу с INCLUDE_SUBSECTIONS=Y. Для SKU предложение сопоставляется с родительским товаром через CCatalogSku::getProductList.

Мутации и конкурентность

Изменения выполняются внутри транзакционной логики Storage с блокировкой состояния и live-корзины. revision-token защищает от устаревших действий. При ошибке провайдера переключение/изменение не должно оставлять исходную корзину в частично изменённом состоянии.

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

• только POST; требуется X-Requested-With: XMLHttpRequest;
• запрос cross-site по Sec-Fetch-Site отклоняется;
• идентификатор сайта подписан Bitrix Signer и валидируется по SiteTable;
• тело запроса ограничено 64 КБ;
• для персональных и мутирующих действий проверяется sessid;
• каждая корзина и строка проверяются на принадлежность текущему владельцу/сайту;
• revision-token блокирует устаревшие изменения;
• цвета принимаются только в формате #RRGGBB, имена ограничены по длине и управляющим символам;
• catalogSections/productSearch учитывают права текущего пользователя на инфоблоки/разделы;
• sectionId валидируется сервером; фильтр раздела нельзя подменить только клиентской логикой;
• addProduct принимает только productId и quantity; цена, provider, USER_ID и FUSER_ID вычисляются/берутся сервером;
• публичные 500-ошибки нейтральны; подробности пишутся в серверный журнал.

Гостевая cookie

Гостевой токен подписывается сервером и привязывается к текущему FUSER. Под HTTPS используется __Host-BUSSOL_MC_V2 с HttpOnly, Secure и SameSite=Lax. Неподписанное старое значение может использоваться только как одноразовый указатель для безопасной миграции при совпадении LID и сохранённого FUSER_ID.

14. Гости, авторизация и миграция идентичности

Для гостя мультикорзины привязаны к подписанной cookie и текущему FUSER. После входа Bitrix объединяет активную гостевую live-корзину, а модуль при первом list присоединяет неактивные гостевые корзины к USER_ID. Повторный list не должен создавать дубли.

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

Импорт 1.3.4

При первом открытии панели для владельца/сайта импортируются старые таблицы корзин. Импорт ограничен текущим FUSER, сайтом и проверкой USER_ID владельца FUSER. Названия, цвета, свойства и неактивные корзины сохраняются; активная корзина всегда перечитывается из sale. Старые таблицы не удаляются автоматически.

15. Обновление и откат

Обновление 1.3.4 → 2.0.12

1. Сделайте полный дамп БД и резервную копию модуля, компонента, шаблона корзины и административного прокси.
2. Закройте магазин на обслуживание и завершите активные операции. Не запускайте деинсталлятор 1.3.4, если необходимо сохранить старые таблицы.
3. Верните штатный/собственный шаблон bitrix:sale.basket.basket, отключите старые скрипты и модификаторы мультикорзины.
4. Замените каталог модуля целиком новым bussol.multicorzine2 в том же месте. Не держите две копии с одинаковым ID.
5. Скопируйте новый admin-прокси, затем администратором откройте страницу модуля и выполните «Подготовить версию 2.0».
6. Проверьте настройки каждого сайта и URL штатной корзины.
7. Обновите публичные JS/CSS, очистите обычный и композитный кеш, при необходимости сбросьте OPcache.
8. Проведите приёмку гостя, login/logout, поиска, добавления товара, разделов, сортировки, переключения, checkout и composite flow.

Обновление 2.0.10/2.0.11 → 2.0.12

Замените файлы модуля актуальной сборкой, выполните штатное обновление/повторную публикацию интерфейсных ресурсов, очистите обычный и композитный кеш. После обновления проверьте catalogSections, productSearch с sectionId, добавление простого товара и SKU, а также права групп пользователей.

Откат

До открытия магазина можно вернуть согласованную резервную копию файлов и БД. После появления новых заказов нельзя без плана отката восстанавливать старый полный дамп рабочей БД. Автоматического обратного переноса снимков 2.0 в таблицы 1.3.4 пакет не содержит.

16. Ограничения и совместимость

• Модуль рассчитан на магазины, использующие штатные sale/FUSER/checkout Bitrix. Для headless-витрины или полностью собственной корзины нужен адаптер.
• Комплекты/наборы с TYPE или SET_PARENT_ID не активируются, не переносятся, не удаляются и не редактируются по одной строке из панели; используйте штатную корзину.
• Сохранённые суммы ориентировочные. Финальные скидки, купоны, доставка и оплата определяются штатным оформлением.
• Купоны не являются отдельным состоянием каждой сохранённой корзины.
• Нестандартные провайдеры, обработчики, особые цены, резервирование и параллельное оформление требуют проверки на конкретном магазине.
• Поиск товаров возвращает только активные доступные товары/предложения, которые проходят права пользователя; состав и цена могут измениться к моменту оформления.
• Срок хранения серверных снимков автоматически не ограничивается; политику очистки определяет владелец магазина.
• При строгой CSP необходимо разрешить собственные JS/CSS/изображения модуля; пользовательские цветовые метки используют style-атрибут.

17. Выполненные проверки 2.0.12

SHA-256 архива 2.0.12: ceea6c0651f4e73645c0d8a26b39e5e1205e73e94094716e2a8d459d0fd062a8

Что покрывают автоматические проверки

• принадлежность ID, revision-token, имена/цвета, лимиты, свойства SKU, дробные количества, запрет неподдерживаемых комплектов;
• создание, перенос, удаление, изменение количества, переключение, откат при ошибке, добавление товара, reorder, guest/login/logout;
• подписанную FUSER-связанную гостевую идентичность;
• композитную оболочку без персональных данных;
• глобальный поиск, catalog picker, фильтр разделов, sectionId, touch drag-handle и актуальные assets.

18. Приёмка на копии магазина

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

• ☐ Чистая установка/обновление: PHP 8.2+, main 26+, sale/catalog/currency, права R/W и настройки по сайтам.
• ☐ Гость: несколько корзин, разные SKU, перезапуск браузера, подписанная cookie и привязка к FUSER.
• ☐ Вход/выход: присоединение неактивных гостевых корзин без дублей и отсутствие доступа к спискам другого аккаунта.
• ☐ Поиск по корзинам: название, ID, свойства позиции, переход к правильной корзине.
• ☐ Добавление из каталога: простой товар и SKU, активная и сохранённая корзина, права пользователя, цена/provider только с сервера.
• ☐ Фильтр разделов: корневые/вложенные разделы, INCLUDE_SUBSECTIONS, соседний раздел не попадает в результат, SKU проверяется по родителю.
• ☐ Сортировка: mouse/touch/keyboard, сохранение порядка после перезагрузки, отказ от неполного/чужого набора ID.
• ☐ Переключение A → B → A: количество, свойства, delayed, дробные значения, пользовательская цена/provider.
• ☐ Количество и удаление: активная/сохранённая корзина, поддельный/устаревший ID, комплекты отклоняются.
• ☐ Цены/наличие/скидки: изменение между сохранением и активацией; provider error не оставляет live-корзину пустой.
• ☐ Checkout: оформленные товары не возвращаются; другие корзины не меняются.
• ☐ Безопасность: GET, POST без AJAX/CSRF, чужая подпись/ID, HTML в имени, попытка передать цену/provider/FUSER/USER.
• ☐ Параллельность: две вкладки/устройства, двойной клик, стандартное добавление + switch, checkout + switch.
• ☐ UI/composite/mobile: автоматическая/ручная кнопка, static cache, composite-AJAX, 360/390/768/1440, safe-area, клавиатура и touch.

19. Диагностика

Команды разработчика

php tests/domain.php
php tests/service.php
php tests/security_identity.php
php tests/composite.php
php tests/ui_static.php
find . -name '*.php' -exec php -l {} \;
node --check install/assets/widget.js
node --check docs/preview-data.js
node --check tests/widget.cjs

20. Структура файлов

21. Чек-лист запуска

• ☐ Есть свежая резервная копия файлов и БД.
• ☐ PHP/main/sale/catalog/currency/mbstring/MySQL-MariaDB соответствуют требованиям.
• ☐ Каталог модуля и ID — bussol.multicorzine2, версия — 2.0.12.
• ☐ Для каждого LID указан правильный URL штатной корзины.
• ☐ Проверены автоматическая и/или встроенная кнопка; оформление и подпись BUSSOL настроены.
• ☐ После обновления выполнено «Обновить файлы интерфейса» и очищен композитный кеш.
• ☐ Проверены глобальный поиск, drag&drop/touch/keyboard сортировка.
• ☐ Проверены catalogSections, productSearch, разделы/подразделы и SKU через родительский товар.
• ☐ Проверено добавление товара в активную и сохранённую корзину без клиентской цены/provider.
• ☐ Проверены изображения/заглушки, изменение количества, удаление и перенос товара.
• ☐ Проверены guest/login/logout, переключение и работа с SKU/свойствами.
• ☐ Проверены реальные цены, наличие, скидки, provider-ошибки и заказ.
• ☐ Проверены CSRF/чужой ID/устаревший token/параллельные запросы.
• ☐ Проверены desktop/mobile, safe-area, поворот, клавиатура и touch.
• ☐ Проверены обычный и композитный режимы без утечки персональных данных в кеш.
• ☐ Для миграции 1.3.4 проверен реальный дамп и согласован план отката.
• ☐ Назначена политика хранения/очистки сохранённых снимков.