Docs/docs/backend/services/connector1C.md

Connector1CService

Назначение

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

Таким образом Connector1CService:

• снимает различия в форматах и структурах данных (1С ↔ микросервисы),
• обеспечивает «единое окно» интеграции для каталогов, остатков, заказов и клиентов,
• играет роль буфера совместимости, позволяя независимо развивать как мастер-систему, так и платформу.

Публичные методы

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

• UpdateDirectoryAsync(pack): ResultPack1C - приём пакета обновлений каталога от 1С.
• GetAllProductsAsync(): ProductExt[] - выгрузка всех товаров в расширенном виде.
• GetAllCategoriesAsync(): CategoryExt[] - выгрузка всех категорий.
• GetFileExtIdsToNeedUploadAsync(take): string[] - список файлов, которые нужно дозагрузить.

Остатки

• UpdateAllRemaindersAsync(pack): ResultPack1C - полная синхронизация остатков.
• UpdateRemaindersAsync(pack): ResultPack1C - частичное обновление остатков.

Заказы

• UpdateOrderProductsAsync(order): OrdersPairExt - обновление состава товаров в заказе.
• UpdateOrdersStatusAsync(orders[]): void - пакетное обновление статусов заказов.
• UpdateOrderStatusToIssuedToCustomerAsync(orderStatus): OrderExt - проставить статус «выдан покупателю».
• GetOrdersUpdatedLPAsync(): OrderExt[] - выборка обновлённых заказов (long-polling).
• GetOrdersUpdatedAsync(): OrderExt[] - выборка обновлённых заказов (обычный вызов).
• GetLastOrderAsync(): OrderExt - получить последний заказ.
• QueryOrdersExternalAsync(orderIds[]): OrderExt[] - запросить заказы по их внешним идентификаторам.

Клиенты

• GetCustomers(userIds[]): OrderCustomer[] - получить сведения о клиентах по идентификаторам.

Особенности

• Форматирование данных: Сервис не меняет бизнес-логику, он лишь «переводит» данные между внутренними моделями (DirectoryService, BusinessService и др.) и структурами 1С.

• Двунаправленный обмен: Поддерживает как входящие запросы от 1С (обновления справочников, остатков, заказов), так и исходящие выборки (товары, категории, клиенты).

• Буфер ошибок: Методы возвращают ResultPack1C либо расширенные модели (OrderExt, ProductExt и т. п.), позволяя фиксировать результаты обмена и возможные ошибки синхронизации.

• Гибкость: Благодаря такому адаптеру можно модифицировать логику работы платформы, не затрагивая 1С, и наоборот - менять 1С без переписывания микросервисов.

Взаимодействие c другими сервисами

Connector1CService взаимодействует со следующими сервисами:

• DirectoryService - (get set) обновленные данных и получение текущих данных.
• BusinessService - (get set) обновленные данных и получение текущих данных.
• FilesDirectoryService - (get set) получение списка файлов на загрузку, загрузка файлов.

Модели Directory

ProductExt

string Id //ИД товара во внешней системе (1С)
string ExtCode //Дополнительный внешний код
string Category //ИД категории
string Article //Артикул
string Name //Наименование
string NameSEO //SEO-наименование (переписывает Name)
string Description //Описание
string DescriptionSEO //SEO-описание (переписывает Description)
string[] BarCodes //Штрих-коды
int UnitCode //Код единицы измерения (ОКЕИ)
string BrandId //ИД бренда
FileRecordExt[] Fotos //Фото-файлы
FileRecordExt[] Files //Другие файлы
decimal Price //Базовая цена
float WeightKg //Вес, кг
Volume SizeM //Размеры (ширина/длина/высота, метры)
float VolumeM //Объём (альтернативное поле)
VATCodeEnum VATCode //Код НДС
TradeAgentSignEnum TradeAgentSign //Признак торгового агента
TradeAgent TradeAgent //Данные торгового агента
bool IsPublished //Признак публикации
bool IsDeleted //Признак удаления

Комментарий: полная витринная модель товара для обмена с 1С; маппится в Product платформы и обратно.

CategoryExt

string Id //ИД категории во внешней системе
string ParentId //ИД родительской категории
int Order //Порядок сортировки на уровне вложенности
string Name //Название категории
bool IsDeleted //Признак удаления

Комментарий: соответствует структуре категорий в 1С; хранит иерархию через ParentId.

BrandExt

string Id //ИД бренда во внешней системе
string Name //Наименование бренда
FileRecordExt Logo //Логотип (файл)
bool IsDeleted //Признак удаления

Комментарий: модель бренда; позволяет передавать и обновлять логотипы.

ProductAttributeExt

string ProductId //ИД товара
string AttributeTypeId //ИД типа атрибута
string Value //Значение атрибута в строковом виде

Комментарий: связь «товар ↔ атрибут» с фактическим значением.

ProductAttributeTypeExt

string Id //ИД типа атрибута
string CategoryId //ИД категории, к которой относится
ProductAttributeTypeEnum TypeEnum //Тип атрибута
string Name //Наименование атрибута
int Order //Порядок отображения
bool IsDeleted //Признак удаления

Комментарий: метаданные атрибута (название, тип, порядок сортировки).

FileRecordExt

string Id //ИД файла (во внешней системе)
string Tag //Тип/назначение файла (например, "изображение", "инструкция")

Комментарий: облегчённый дескриптор файла для обмена (только ID и тег).

UpdateDataPackExt

long PackId //Идентификатор пакета синхронизации
BrandExt[] Brands //Справочник брендов
CategoryExt[] Categories //Справочник категорий
ProductAttributeTypeExt[] ProductAttributeTypes //Типы атрибутов
ProductExt[] Products //Товары
ProductAttributeExt[] ProductAttributes //Значения атрибутов

Комментарий: пакет синхронизации от 1С; передаётся в UpdateDirectoryAsync, чтобы массово обновить каталог.

Модели Business

OrderExt

long SiteId //Ид заказа на сайте
long ForwardFromSiteId //Ид исходного заказа на сайте (если пересоздавался)
string Id //Внешний ид заказа (мастер-система)
OrderStatusEnum Status //Статус заказа
string[] Discounts //Идентификаторы применённых скидок/промокодов
OrderProductExt[] Products //Состав заказа
decimal TotalCost //Итоговая стоимость заказа
long CreatedUnixTimestampMS //Момент создания (Unix ms)
long UpdatedUnixTimestampMS //Момент обновления (Unix ms)
OrderDeliveryExt Delivery //Информация о доставке
long CustomerId //Id покупателя
OrderCustomerExt Customer //Снимок данных покупателя на момент заказа
string Comment //Комментарий клиента
OrderPaymentExt PaymentInfo //Платёжные реквизиты (меняется только со стороны ИМ)
OrderPaymentStatusEnum PaymentStatus //Статус оплаты (меняется только со стороны ИМ)
OrderStatusEnum StatusInternal //Внутренний статус (меняется только со стороны ИМ)
bool IsPayed //Флаг «оплачено» (меняется только со стороны ИМ)
bool IsClosed //Флаг «закрыт» (меняется только со стороны ИМ)

Комментарий: основная «передаваемая» форма заказа между 1С и платформой; содержит как витринные, так и служебные поля.

OrderProductExt

string Id //Внешний ид товара (из каталога 1С)
string Name //Наименование
decimal Count //Количество, принятое к исполнению (по нему считается стоимость)
decimal CountInit //Количество, выбранное клиентом
decimal CostPerOne //Цена за единицу
decimal CostWithDiscountPerOne //Цена за единицу с учётом скидки
decimal TotalPrice //Итоговая стоимость позиции

Комментарий: позиция заказа в «внешнем» разрезе; включает и выбранное, и принятое количество.

OrderDeliveryExt

OrderDeliveryTypeEnum Type //Тип доставки
decimal Price //Стоимость доставки
Coordinates Pin //Координаты точки доставки/самовывоза
string Address //Адрес
DeliveryInfo DeliveryInfo //Расчётная информация по доставке

Комментарий: снимок параметров доставки, включая результат тарифного расчёта.

OrderPaymentExt

OrderPaymentTypeEnum Type //Способ оплаты
string PaymentGate //Платёжный шлюз
OrderPaymentDetailsExt Payment //Платёж (сумма/идентификаторы/статус)
OrderPaymentDetailsExt Refund //Возврат (если был)

Комментарий: платёжный блок заказа в форме для обмена.

OrderPaymentDetailsExt

decimal Amount //Сумма
string PaymentInternalId //Внутренний ид платежа
string PaymentId //Ид у платёжного провайдера
string Status //Статус у провайдера

Комментарий: детали конкретного платежа/возврата.

OrderCustomerExt

long Id //Id пользователя (0 - если гость)
string Phone //Телефон
string Email //Email
string Name //Имя
string PhotoFile //Идентификатор фото-файла
DateTimeOffset? BirthDay //Дата рождения (опционально)

Комментарий: «снимок» данных покупателя, прикрепляется к заказу.

OrdersPairExt

OrderExt OrderOld //Старый заказ
OrderExt OrderNew //Новый заказ

Комментарий: пара заказов - используется, когда заказ пересоздаётся с изменёнными параметрами.

OrderUpdateExt

long SiteId //Id заказа на сайте
string Id //Внешний ид заказа (мастер-система)
OrderStatusEnum Status //Статус заказа
string[] Discounts //Применённые скидки
OrderProductExt[] Products //Состав заказа
decimal TotalCost //Итоговая стоимость
long UpdatedUnixTimestampMS //Момент обновления (Unix ms)
OrderDeliveryExt Delivery //Информация о доставке
string Comment //Комментарий клиента

Комментарий: «патч» заказа со стороны мастер-системы (состав, статусы, суммы).

OrderUpdateProductsExt

long SiteId //Id заказа на сайте
OrderProductExt[] Products //Новый состав товаров
decimal TotalCost //Итоговая стоимость

Комментарий: обновление только товарных позиций и суммы заказа.

OrderUpdateStatusExt

long SiteId //Id заказа на сайте
string Id //Внешний ид заказа (мастер-система)
OrderStatusEnum Status //Новый статус заказа

Комментарий: точечное обновление статуса заказа.

RemainderExt

string ProductId //Внешний ид продукта
decimal Value //Остаток

Комментарий: запись об остатке в формате обмена.

UpdateRemaindersPackExt

long PackId //Идентификатор пакета синхронизации остатков
RemainderExt[] Remainders //Массив остатков

Комментарий: пакет для полной/частичной синхронизации остатков.

DB

Базы данных нет. Сервис - адаптер.

Назад