Схема работы торгового каталога и основные объекты

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

Используйте ORM-классы и API модуля catalog, чтобы корзина, заказы, скидки и складской учет получали согласованные данные.

API модуляAPI модуля

В архитектуре каталога используйте ORM-классы, модели и сервисы ядра D7. Классическое API используйте там, где для сценария нет полной D7-замены. Например, через классические методы создают связь инфоблока с каталогом, настраивают связь с торговыми предложениями и проводят складские документы.

Подробнее об API модуля читайте в статье Как выбрать API торгового каталога.

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

Для работы с данными каталога через ORM используйте классы из пространства имен Bitrix\Catalog.

use Bitrix\Catalog\CatalogIblockTable; // Настройки каталога для инфоблока
        use Bitrix\Catalog\ProductTable; // Товарные параметры
        use Bitrix\Catalog\PriceTable; // Цены
        use Bitrix\Catalog\GroupTable; // Типы цен
        use Bitrix\Catalog\VatTable; // Ставки НДС
        use Bitrix\Catalog\MeasureTable; // Единицы измерения
        use Bitrix\Catalog\MeasureRatioTable; // Коэффициенты единиц измерения
        use Bitrix\Catalog\StoreTable; // Склады
        use Bitrix\Catalog\StoreProductTable; // Остатки на складах
        use Bitrix\Catalog\StoreDocumentTable; // Складские документы
        use Bitrix\Catalog\StoreDocumentElementTable; // Строки складских документов
        use Bitrix\Catalog\SubscribeTable; // Подписки на появление товара
        use Bitrix\Catalog\CatalogViewedProductTable; // История просмотров товаров
        

Дополнительные ORM-классыДополнительные ORM-классы

Кроме основных классов, в модуле есть ORM-классы для связанных данных: прав, наценок, округления цен, складского учета и документов. Они не образуют базовую схему товара, но помогают получить или изменить данные, связанные с каталогом.

use Bitrix\Catalog\GroupLangTable; // Названия типов цен по языкам
        use Bitrix\Catalog\GroupAccessTable; // Права групп пользователей на просмотр и покупку по типам цен
        use Bitrix\Catalog\ExtraTable; // Наценки
        use Bitrix\Catalog\RoundingTable; // Правила округления цен
        use Bitrix\Catalog\ProductGroupAccessTable; // Продажа прав доступа к контенту
        use Bitrix\Catalog\ContractorTable; // Контрагенты складских документов
        use Bitrix\Catalog\StoreBarcodeTable; // Штрихкоды товаров на складах
        use Bitrix\Catalog\StoreDocumentBarcodeTable; // Штрихкоды в строках складских документов
        use Bitrix\Catalog\StoreBatchTable; // Партии складского учета
        use Bitrix\Catalog\StoreBatchDocumentElementTable; // Связь партий со строками документов
        use Bitrix\Catalog\StoreDocumentFileTable; // Файлы складских документов
        use Bitrix\Catalog\SubscribeAccessTable; // Данные для аутентификации подписавшихся без регистрации пользователей
        

Карты ORM-классовКарты ORM-классов

Каждый ORM-класс содержит метод getMap(). Он возвращает описание структуры таблицы: поля, типы полей, связи с другими объектами и правила валидации. Система использует карту класса для следующих задач:

• строит SQL-запросы,

• преобразует данные между PHP и базой данных,

• проверяет типы данных при сохранении,

• организует связи между таблицами.

В каталоге карты ORM статические: они описывают фиксированную модель данных модуля. В отличие от инфоблоков, каталог не генерирует отдельные ORM-классы под каждый товарный инфоблок и не добавляет свойства инфоблока в карту ProductTable.

Пример фрагмента результата getMap() для ProductTable:

Array
        (
            [ID] => Bitrix\Main\Entity\IntegerField Object
                (
                    [name:protected] => ID
                    [is_primary:protected] => 1
                )
        
            [QUANTITY] => Bitrix\Main\Entity\FloatField Object
                (
                    [name:protected] => QUANTITY
                    [default_value:protected] => 0
                )
        
            [QUANTITY_TRACE] => Bitrix\Main\Entity\EnumField Object
                (
                    [name:protected] => QUANTITY_TRACE
                    [values:protected] => Array
                        (
                            [0] => D
                            [1] => N
                            [2] => Y
                        )
                )
        
            [IBLOCK_ELEMENT] => Bitrix\Main\Entity\ReferenceField Object
                (
                    [name:protected] => IBLOCK_ELEMENT
                    [reference:protected] => Array
                        (
                            [=this.ID] => ref.ID
                        )
                )
        )
        

В разделах ниже описаны поля хранения основных классов. Кроме них, карты ORM содержат служебные поля и связи с другими объектами: например, связи с инфоблоками, товарной записью, типом цены, складом, складским документом, пользователями и элементом инфоблока.

Каталог и инфоблокиКаталог и инфоблоки

Класс Bitrix\Catalog\CatalogIblockTable хранит настройки каталога для инфоблока. Основной ключ записи — IBLOCK_ID, идентификатор инфоблока.

Класс CCatalogSku определяет тип каталога по связи настроек в CatalogIblockTable.

Как устроен каталогКак устроен каталог

Каталог строится вокруг инфоблока. Класс CatalogIblockTable подключает инфоблок к модулю catalog и задает настройки каталога. Если каталог использует торговые предложения, он связывает инфоблок предложений с инфоблоком товаров через поля PRODUCT_IBLOCK_ID и SKU_PROPERTY_ID.

Элемент инфоблока становится товаром, когда для него появляются товарные параметры в ProductTable. Значение ID в ProductTable совпадает с ID элемента инфоблока. Через этот ключ модуль связывает товар с ценами, коэффициентами единиц измерения, остатками на складах, строками складских документов и подписками.

Инфоблок товаров
          ElementTable
                |
                | ID элемента = ID товара
                v
          ProductTable
                |
                +— PriceTable             цены товара
                +— MeasureRatioTable      коэффициенты единицы измерения
                +— StoreProductTable      остатки по складам
                +— SubscribeTable         подписки на появление в продаже
        
        Инфоблок торговых предложений
          ElementTable
                |
                | свойство SKU ссылается на товар
                v
          ProductTable
        

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

Жизненный цикл товараЖизненный цикл товара

Схема подготовки товара к продаже состоит из нескольких шагов:

1. В инфоблоке создается элемент. На этом этапе у элемента есть контентные данные: название, описание, свойства, разделы и изображения.

2. Для элемента создаются товарные параметры в ProductTable. После этого элемент становится товаром для модуля catalog.

3. Для товара добавляют цены через PriceTable, единицу измерения через MeasureTable и коэффициенты продажи через MeasureRatioTable.

4. Если товар учитывается на складах, остатки ведут через StoreProductTable и складские документы.

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

Тип в поле ProductTable::TYPE показывает роль записи в каталоге. ProductTable::TYPE_EMPTY_SKU используется для родительского товара, у которого еще нет предложений. Когда предложения появляются, родительский товар получает ProductTable::TYPE_SKU, а элементы инфоблока предложений получают ProductTable::TYPE_OFFER.

Для обычного товара корзина работает с ID этого товара. Для товара с торговыми предложениями корзина должна получать ID выбранного предложения.

Торговые предложенияТорговые предложения

Чтобы продавать товары с торговыми предложениями, используют два инфоблока. Инфоблок товаров хранит родительские элементы, а инфоблок предложений хранит варианты товара. Связь между ними задает свойство SKU: его идентификатор хранится в SKU_PROPERTY_ID, а инфоблок родительских товаров — в PRODUCT_IBLOCK_ID.

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

В коде каталога тип записи показывает роль элемента.

При добавлении в корзину класс Bitrix\Catalog\Product\Basket проверяет родительские товары TYPE_SKU и TYPE_EMPTY_SKU. Если не включен режим совместимости show_catalog_tab_with_offers, такие товары нельзя добавить в корзину напрямую: покупатель должен выбрать торговое предложение.

Пересчет торговых предложенийПересчет торговых предложений

Класс Bitrix\Catalog\Product\Sku отвечает за состояние родительского товара с предложениями. Метод getOfferState() определяет одно из состояний:

Метод getDefaultParentSettings() по этому состоянию подбирает тип родительского товара, доступность и правила учета количества. Например, если доступных предложений нет, родительский товар получает статус недоступного. Если есть доступные предложения, родительский товар остается типом TYPE_SKU и получает доступность Y.

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

• enableDeferredCalculation() включает режим, в котором накапливаются задачи для пересчета. После этого методы подготовки не запускают пересчет сразу. Метод используют перед массовым изменением товаров или предложений.

• disableDeferredCalculation() выключает режим, в котором накапливаются задачи для пересчета. Метод не пересчитывает данные. Его используют после массового изменения, перед запуском calculate().

• calculateComplete($id, $iblockId = null, $type = null) добавляет товар или предложение в очередь полного пересчета. Полный пересчет обновляет доступность родительского товара и цены. Если отложенный режим не включен, метод сразу запускает calculate(). Метод используют, когда изменились данные предложения, которые влияют на доступность или состояние родительского товара.

• calculatePrice($id, $iblockId = null, $type = null, array $priceTypes = []) добавляет товар или предложение в очередь пересчета цен родительского товара. Если список $priceTypes пустой, пересчитываются все типы цен. Если отложенный режим не включен, метод сразу запускает calculate(). Метод используют, когда изменились только цены предложений.

• calculate() выполняет накопленные задачи: определяет родительские товары для предложений, пересчитывает их доступность и цены, обновляет связанные данные элемента. Метод используют после завершения массовой операции. Также он запускается автоматически из calculateComplete() и calculatePrice(), если отложенный режим не включен.

Товарные параметрыТоварные параметры

Класс Bitrix\Catalog\ProductTable хранит товарную часть элемента инфоблока: тип, количество, правила учета остатков, доступность, НДС, вес, габариты и единицу измерения.

Тип товараТип товара

Тип товара задает роль записи в каталоге.

Если у товара еще нет предложений, модуль может использовать тип TYPE_EMPTY_SKU. Когда появляются предложения, родительский товар получает тип TYPE_SKU, а элементы инфоблока предложений получают тип TYPE_OFFER.

Доступность и покупкаДоступность и покупка

Значение D в полях QUANTITY_TRACE, CAN_BUY_ZERO, NEGATIVE_AMOUNT_TRACE и SUBSCRIBE означает Использовать настройку модуля. На эти поля влияют настройки модуля Торговый каталог:

• учитывать количество товара при продаже,

• разрешить покупку при отсутствии товара,

• разрешить отрицательное количество товара,

• разрешить подписку на товары, которых нет на складе.

ProductTable подставляет эти значения перед расчетом доступности и правил покупки. Доступность рассчитывается по полям QUANTITY, QUANTITY_TRACE и CAN_BUY_ZERO. Если количество меньше или равно нулю, учет остатков включен и покупка при нуле запрещена, товар получает значение AVAILABLE = 'N'. В остальных случаях товар доступен и получает AVAILABLE = 'Y'.

Поле NEGATIVE_AMOUNT_TRACE управляет разрешением отрицательного остатка, а SUBSCRIBE — подпиской на появление товара. Эти поля не заменяют AVAILABLE, но участвуют в правилах продажи и уведомлений.

Для родительских товаров с предложениями доступность пересчитывает Bitrix\Catalog\Product\Sku. Если среди активных предложений есть доступное, родительский товар может получить AVAILABLE = 'Y'. Если доступных предложений нет, родительский товар становится недоступным для покупки как группа предложений.

Цены и типы ценЦены и типы цен

Класс Bitrix\Catalog\PriceTable хранит цены товаров и торговых предложений. Одна запись цены относится к товару или торговому предложению, типу цены и валюте.

Типы ценТипы цен

Класс Bitrix\Catalog\GroupTable хранит типы цен.

Выбор ценыВыбор цены

Для одного товара можно хранить несколько цен. Разные записи отличаются типом цены CATALOG_GROUP_ID, валютой и диапазоном количества QUANTITY_FROM — QUANTITY_TO.

Тип цены задает группу цен, например, базовую, розничную или оптовую. Поле BASE = 'Y' в GroupTable отмечает базовый тип цены. Метод GroupTable::getBasePriceType() возвращает базовый тип цены, если он есть.

Поле PRICE_SCALE хранит цену в базовой валюте. Модуль использует это значение для внутренних расчетов и сортировки. При изменении цены через API каталога система может пересчитать связанные данные для торговых предложений и родительского товара.

Не используйте PRICE_SCALE как исходную цену товара. При добавлении и изменении цены API пересчитывает PRICE_SCALE по PRICE, CURRENCY и текущему курсу валюты, если значение не передано явно. Обработчик Bitrix\Catalog\Product\Price::handlerAfterUpdateCurrencyBaseRate() обновляет PRICE_SCALE при изменении базового курса валюты.

При выборе цены важны три условия:

1. Идентификатор PRODUCT_ID должен указывать на товар или торговое предложение, которое покупатель добавляет в корзину.

2. Идентификатор CATALOG_GROUP_ID должен соответствовать доступному типу цены.

3. Количество в корзине должно попадать в диапазон QUANTITY_FROM — QUANTITY_TO, если для цены задан диапазон.

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

Создавайте цены для товара или торгового предложения через API каталога, чтобы тип цены, валюта и пересчитанная цена PRICE_SCALE оставались согласованными.

Доступность типов ценДоступность типов цен

Тип цены может быть доступен не всем группам пользователей. Класс GroupAccessTable связывает тип цены с группой пользователей и уровнем доступа:

• GroupAccessTable::ACCESS_VIEW — группа может видеть цены этого типа,

• GroupAccessTable::ACCESS_BUY — группа может покупать товары по ценам этого типа.

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

Ставки НДССтавки НДС

Класс Bitrix\Catalog\VatTable работает со ставками НДС. Товар ссылается на ставку через поле VAT_ID, а поле VAT_INCLUDED показывает, включен ли НДС в цену.

Единицы измеренияЕдиницы измерения

Класс Bitrix\Catalog\MeasureTable хранит единицы измерения, а Bitrix\Catalog\MeasureRatioTable хранит коэффициенты. Товар ссылается на единицу измерения через поле MEASURE.

Коэффициенты единиц измеренияКоэффициенты единиц измерения

Класс Bitrix\Catalog\MeasureRatioTable работает с коэффициентами единиц измерения. Коэффициент задает кратность продажи для товара.

Складской учетСкладской учет

Класс Bitrix\Catalog\StoreTable хранит склады. Склад описывает место хранения или выдачи товара.

Остатки товараОстатки товара

Остаток товара на конкретном складе хранит Bitrix\Catalog\StoreProductTable.

В каталоге есть два уровня остатков:

1. ProductTable::QUANTITY хранит общий остаток товара.

2. StoreProductTable::AMOUNT хранит остаток товара на конкретном складе.

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

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

При складском учете меняйте остатки документами, а не прямой правкой данных, с которыми работает StoreProductTable.

ШтрихкодыШтрихкоды

Штрихкоды товаров хранит StoreBarcodeTable. Запись связывает товар или торговое предложение, штрихкод и при необходимости склад.

Штрихкоды идентифицируют товары в документах. Код складских документов читает StoreBarcodeTable: проверяет количество переданных штрихкодов, добавляет или удаляет штрихкоды через действия складского документа.

Если у товара BARCODE_MULTI = 'N', один штрихкод относится к товару как к позиции. Если BARCODE_MULTI = 'Y', штрихкоды ведутся по предложениям товара, а количество штрихкодов в документе должно соответствовать количеству товара в строке.

Состояние складского учета проверяет Bitrix\Catalog\Config\State::isUsedInventoryManagement(). Если складской учет выключен, система отключает складские ограничения и часть складских полей в интерфейсе.

ДокументыДокументы

Складской учет работает с документами. Документ фиксирует операцию складского учета: приход, оприходование, перемещение, возврат, списание или отмену резерва.

1. Документ создается в StoreDocumentTable и получает тип операции в поле DOC_TYPE.

2. Товары документа добавляются строками через StoreDocumentElementTable.

3. В строке указывают товар, количество, склад-источник STORE_FROM и склад-получатель STORE_TO, если они нужны для типа операции.

4. После проведения документа модуль меняет складские остатки и фиксирует статус документа.

Пока документ не проведен, он хранит планируемую операцию. Поле STATUS показывает, проведен ли документ, а WAS_CANCELLED — был ли он отменен. Для фильтрации и отображения состояния модуль использует константы:

• StoreDocumentTable::STATUS_CONDUCTED — документ проведен,

• StoreDocumentTable::STATUS_DRAFT — черновик, документ еще не проведен,

• StoreDocumentTable::STATUS_CANCELLED — документ отменен.

Складские документы хранит класс Bitrix\Catalog\StoreDocumentTable.

Строки документа хранит Bitrix\Catalog\StoreDocumentElementTable.

Типы складских документовТипы складских документов

Основные типы складских документов:

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

Класс Bitrix\Catalog\SubscribeTable хранит подписки на появление товара. Подписка связывает товар, контакт пользователя и сайт.

Когда доступность товара меняется с N на Y, модуль может пометить активные подписки флагом NEED_SENDING = 'Y' и запустить агент отправки уведомлений. Подписка работает, если для товара разрешено поле SUBSCRIBE или это разрешение берется из настройки модуля.

История просмотров товаровИстория просмотров товаров

Класс Bitrix\Catalog\CatalogViewedProductTable хранит историю просмотров товаров. Модуль использует эти данные для блоков просмотренных товаров и сценариев рекомендаций.

Для товара с торговыми предложениями история просмотров может хранить два идентификатора: выбранное предложение и родительский товар. Метод CatalogViewedProductTable::getProductsMap() помогает получить такую связь. Он возвращает массив, где ключ — идентификатор переданного товара или предложения, а значение — идентификатор родительского товара. Если переданный товар не является предложением, значение совпадает с ключом.

Интеграция с модулем Интернет-магазинИнтеграция с модулем Интернет-магазин

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

Для обычного товара корзина работает с ID товара. Для товара с торговыми предложениями корзина должна получать ID выбранного предложения. Родительский товар типа TYPE_SKU группирует предложения, но обычно не является самостоятельной продаваемой позицией.

В корзину можно добавить:

• обычный товар ProductTable::TYPE_PRODUCT,

• комплект ProductTable::TYPE_SET, если для него найден состав комплекта,

• торговое предложение ProductTable::TYPE_OFFER, если найден активный родительский товар,

• услуга ProductTable::TYPE_SERVICE.

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

При оформлении заказа данные каталога участвуют в проверках:

• товар должен существовать как элемент инфоблока и товарная запись каталога,

• товар должен быть доступен для покупки,

• цена должна соответствовать типу цены, валюте и количеству,

• остаток должен позволять продажу с учетом настроек QUANTITY_TRACE и CAN_BUY_ZERO,

• при складском учете отгрузка должна учитывать складские остатки и резервы.

Не дублируйте цены, остатки и правила покупки в свойствах инфоблока. Такие свойства не заменяют данные модуля catalog для корзины и заказа в модуле sale.

Что не нужно хранить в свойствах инфоблокаЧто не нужно хранить в свойствах инфоблока

Свойства инфоблока подходят для описания товара: цвет, бренд, материал, страна, технические характеристики, файлы и другие данные карточки. Данные продажи храните через объекты каталога.

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