# 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;
```

[Назад](../../../index.md)