Docs/docs/backend/services/business.md

BusinessService

Назначение

Управление остатками и заказами: получение/обновление остатков, создание заказа по счёту (invoice), ожидание подтверждений мастер-системы и статусов оплаты, отмена, выборки заказов пользователя, а также приём внешних обновлений по заказам.

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

Остатки

• GetRemaindersAsync(productsIds[]): decimal[] - получить остатки по товарам.
• FilterInStockAsync(productsIds[]): int[] - оставить только товары «в наличии».
• UpdateAllRemaindersAsync(pack): void - полное обновление остатков.
• UpdateRemaindersAsync(pack): void - частичное обновление остатков.

Создание/управление заказом (жизненный цикл)

• CreateOrderAsync(invoice): Order - создать заказ по счёту (без подтверждения мастер-системы).
• AwaitOrderConfirmMasterSystemLPAsync(orderId): Order - дождаться подтверждения мастер-системы.
• AwaitOrderPaymentPendingLPAsync(orderId): Order - дождаться перехода платежа в ожидание/обработку.
• CancelOrderByCustomerAsync(orderId): Order - отменить заказ пользователем.

Заказы пользователя

• GetMyOrders(skip = 0, take = 20): Order[] - получить мои заказы с пагинацией.

Взаимодействие с внешней системой заказов (обновления)

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

Конфигурация BusinessService

Работа сервиса опирается на конфигурационный файл BusinessServiceConfig. В нём содержатся параметры для интеграции с платёжным шлюзом и настройки доставки. Конфиг хранится в секции config.json и загружается при инициализации сервиса.

Параметры платежей (YooKassa)

• PaymentYooKassa_ShopId - идентификатор магазина в YooKassa.
• PaymentYooKassa_SecretKey - секретный ключ для подписи и проверки запросов.
• PaymentYooKassa_ReturnURL - URL, на который возвращается пользователь после завершения платежа.

Эти параметры обязательны для корректной работы онлайн-оплаты.

Параметры доставки

• DeliveryMasterSystemId - внешний идентификатор доставки в мастер-системе (1С).
• DeliveryName - отображаемое название услуги доставки (по умолчанию «Доставка»).
• DeliveryVAT - ставка НДС, применяемая к услуге доставки (значение из VATCodeEnum, по умолчанию Vat20).

Особенности

• Конфигурация выносится в отдельный JSON и может отличаться между окружениями (Dev/Staging/Prod).
• В боевом окружении рекомендуется хранить ключи (SecretKey) в защищённом хранилище или использовать секреты CI/CD.
• Параметры доставки синхронизируются с мастер-системой и должны совпадать с её справочниками.

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

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

• DirectoryService - (get only) полученине данных о товарах.
• DeliveryService - (get only) проверочный рассчет доставки по заказу.
• ProfilesService - (get only) получение данных пользователя совершающего заказ (User).

Модели

BusinessServiceConfig

string PaymentYooKassa_ShopId //Идентификатор магазина YooKassa
string PaymentYooKassa_SecretKey //Секретный ключ YooKassa
string PaymentYooKassa_ReturnURL //URL возврата после оплаты

string DeliveryMasterSystemId //Внешний идентификатор доставки в мастер-системе
string DeliveryName //Отображаемое название доставки
VATCodeEnum DeliveryVAT //Код НДС, применяемый к доставке

Конфигурационная модель сервиса; содержит настройки платёжного шлюза (YooKassa) и параметры доставки.

Order

long Id //Идентификатор заказа
long ForwardFromId //Ид источника/переноса (если есть)
string ExtId //Внешний идентификатор заказа (мастер-система)
OrderStatusEnum Status //Текущий статус заказа
string[] Discounts //Применённые скидки/промокоды
OrderProduct[] Products //Состав заказа
decimal TotalCost //Итоговая стоимость
DateTimeOffset Created //Когда создан
DateTimeOffset Updated //Когда обновлён (последняя синхронизация)
OrderPayment PaymentInfo //Информация об оплате
OrderDelivery Delivery //Информация о доставке
long CustomerId //Идентификатор покупателя (если авторизован)
OrderCustomer Customer //Данные покупателя
string Comment //Комментарий покупателя/оператора
bool IsPayed //Факт оплаты
OrderPaymentStatusEnum PaymentStatus //Статус платежа
OrderStatusEnum StatusInternal //Внутренний статус (служебный)
bool IsClosed //Заказ закрыт
bool IsNeedUpdateForMasterSystem //Требуется обновление в мастер-системе

OrderProduct

int Id //Идентификатор товара
string ExtId //Внешний ИД товара
string Name //Наименование
decimal Count //Кол-во, принятое к исполнению (по нему считается стоимость)
decimal CountInit //Кол-во, выбранное клиентом
decimal CostPerOne //Цена за единицу
decimal CostWithDiscountPerOne //Цена со скидкой за единицу
decimal TotalPrice //Итоговая стоимость позиции
VATCodeEnum VAT //Код НДС
TradeAgentSignEnum TradeAgentSign //Признак торгового агента
TradeAgent TradeAgent //Данные торгового агента

OrderCustomer

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

Срез пользовательских данных, фиксируемый в заказе.

OrderDelivery

OrderDeliveryTypeEnum Type //Тип доставки (самовывоз/курьер и т. п.)
decimal Price //Стоимость доставки
Coordinates Pin //Координаты точки доставки/самовывоза
string Address //Адрес доставки/пункта
DeliveryInfo DeliveryInfo //Детали расчёта (зона/тариф/доступность)

Параметры выбранной доставки; есть статическая заготовка SelfPickUp.

OrderPayment

OrderPaymentTypeEnum Type //Тип оплаты (онлайн, офлайн и т. п.)
string PaymentGate //Платёжный провайдер/шлюз
OrderPaymentDetails Payment //Детали платежа
OrderPaymentDetails Refund //Детали возврата (если был)

OrderPaymentDetails

decimal Amount //Сумма платежа/возврата
string PaymentInternalId //Внутренний идентификатор
string PaymentId //Идентификатор у платёжного провайдера
string PaymentURL //Ссылка на оплату (если применяется)
string Status //Статус у провайдера (текстом)

OrderInvoiceItem

int ProductId //Идентификатор товара
decimal Amount //Количество

OrderInvoice

OrderInvoiceItem[] Items //Позиции счёта
string[] Discounts //Скидки/промокоды
decimal CheckCost //Контрольная сумма (ожидаемый итог от клиента)
OrderDelivery Delivery //Параметры доставки
OrderPaymentTypeEnum PaymentType //Способ оплаты
string UserEmail //Email покупателя (если не авторизован)
string UserName //Имя покупателя (если не авторизован)
string Comment //Комментарий покупателя

DB

Содержит таблицы и индексы

-- Migration 1
remainders (
    ProductId INTEGER PRIMARY KEY,
    Value TEXT NOT NULL DEFAULT '0'
)

-- Migration 2
orders (
    Id INTEGER PRIMARY KEY AUTOINCREMENT,
    ExtId TEXT NOT NULL DEFAULT '',
    Status INTEGER NOT NULL,
    Discounts TEXT NOT NULL DEFAULT '[]',
    Products TEXT NOT NULL DEFAULT '[]',
    TotalCost TEXT NOT NULL DEFAULT '0',
    Created INTEGER NOT NULL,
    Updated INTEGER NOT NULL,
    PaymentInfo TEXT NOT NULL DEFAULT '{}',
    Delivery TEXT NOT NULL DEFAULT '{}',
    CustomerId INTEGER NOT NULL,
    Customer TEXT NOT NULL DEFAULT '{}',
    Comment TEXT NOT NULL DEFAULT '',
    InternalComment TEXT NOT NULL DEFAULT '',
    IsPayed BOOLEAN NOT NULL DEFAULT FALSE,
    IsClosed BOOLEAN NOT NULL DEFAULT FALSE,
    IsNeedUpdateForMasterSystem BOOLEAN NOT NULL DEFAULT FALSE
)

CREATE INDEX IF NOT EXISTS idx_orders_customer_id ON orders (CustomerId);

-- Migration 3
ALTER TABLE orders ADD PaymentStatus INTEGER NOT NULL DEFAULT 0;

-- Migration 4
ALTER TABLE orders ADD StatusInternal INTEGER NOT NULL DEFAULT 0;

-- Migration 5
ALTER TABLE orders ADD ForwardFromId INTEGER NOT NULL DEFAULT 0;

Назад