UserBudgetPool: как Sale управляет внутренним счётом покупателя

Контекст: внутренний счёт и таблицы

Внутренний счёт покупателя хранится в b_sale_user_account (CSaleUserAccount). История движений — в b_sale_user_transact (CSaleUserTransact). Платёжная система «С внутреннего счёта» регистрируется через PaySystemInner с ACTION_FILE = INNER_BUDGET и обрабатывается классом Sale\Handlers\PaySystem\InnerHandler.

Прямой вызов CSaleUserAccount::UpdateAccount() из прикладного кода во время сохранения заказа — плохая идея: ядро само накапливает операции и вызывает UpdateAccount централизованно из UserBudgetPool::onUserBudgetSave().

Архитектура UserBudgetPool

Класс Bitrix\Sale\Internals\UserBudgetPool — синглтон на пользователя в рамках одного HTTP-хита. Статический массив $userBudgetPool хранит экземпляры по userId.

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

        InnerHandler::creditNoDemand()
    → UserBudgetPool::addPoolItem()
        → pool->add()  // накопление в $items[]
            → lock()   // GET_LOCK при первом add()
    → Order::save()
        → PaymentCollection::save()
        → UserBudgetPool::onUserBudgetSave()
            → CSaleUserAccount::UpdateAccount() для каждой записи
            → pool->delete() + unlock()

    

Ключевой момент: запись в БД происходит не в момент списания, а в конце Order::save(), сразу после сохранения коллекции платежей.

Структура записи в пуле

Каждый элемент $items[] содержит:

Типы операций

Константы класса UserBudgetPool:

При сбросе пула onUserBudgetSave() передаёт TYPE в CSaleUserAccount::UpdateAccount() как описание транзакции. При ошибке записи возвращается код SALE_PROVIDER_USER_BUDGET_{TYPE}_ERROR.

Блокировка GET_LOCK

Перед первым add() пул вызывает lock():

        // sale/lib/internals/userbudgetpool.php
protected function lock(): void
{
    if ($this->statusLock === self::STATUS_NOT_LOCKED) {
        $connection = Main\Application::getConnection();
        if (!$connection->lock($this->getUniqLockName())) {
            $this->statusLock = self::STATUS_LOCKED_EARLIER;
            return;
        }
        $this->statusLock = self::STATUS_LOCKED_NOW;
    }
}

private function getUniqLockName(): string
{
    return "user_budget_{$this->userId}";
}

    

Connection::lock() оборачивает MySQL GET_LOCK. Имя хешируется: md5(serverUniqId) . md5($name) — ограничение MySQL 5.7+ на 64 символа. Запрос идёт на master (ConnectionPool::useMasterOnly(true)).

Три состояния блокировки

При STATUS_LOCKED_EARLIER текст ошибки: «Внутренний счет заблокирован другой сессией» (SALE_PROVIDER_USER_BUDGET_LOCKED).

Блокировка снимается в __destruct() пула, когда все записи удалены через delete() после успешного UpdateAccount.

Точки входа в ядре

InnerHandler — оплата и возврат

Sale\Handlers\PaySystem\InnerHandler — основной обработчик внутреннего счёта.

Списание (creditNoDemand):

        $userBudget = UserBudgetPool::getUserBudgetByOrder($order);
if ($userBudget >= $paymentSum) {
    UserBudgetPool::addPoolItem($order, ($paymentSum * -1), UserBudgetPool::BUDGET_TYPE_ORDER_PAY, $payment);
} else {
    // ORDER_PSH_INNER_ERROR_INSUFFICIENT_MONEY
}

    

Возврат (refund):

        UserBudgetPool::addPoolItem($order, $refundableSum, UserBudgetPool::BUDGET_TYPE_ORDER_UNPAY, $payment);

    

Перед обеими операциями проверяется isUserBudgetLock() — флаг LOCKED = Y в b_sale_user_account. Это отдельная блокировка от GET_LOCK пула: административная блокировка счёта пользователя.

Order::save() — финальный сброс

        // sale/lib/order.php, конец save()
Internals\UserBudgetPool::onUserBudgetSave($this->getUserId());

    

onUserBudgetSave() итерирует $pool->get() и для каждой записи вызывает:

        \CSaleUserAccount::UpdateAccount(
    $userId,
    $budgetDat['SUM'],
    $budgetDat['CURRENCY'],
    $budgetDat['TYPE'],
    $orderId,
    '',
    $paymentId
);

    

При неуспехе — Result с ошибками; при успехе — delete($key) и unlock().

PaySystemInner — legacy-контур

PaySystemInner::createOperation() дублирует логику для операций OPERATION_DEBIT, OPERATION_CREDIT, OPERATION_RETURN. Для возврата использует getUserBudgetTransForOrder() чтобы учесть незакоммиченные транзакции пула.

Чтение «живого» баланса

getUserBudget() — только БД

        UserBudgetPool::getUserBudget($userId, $currency);

    

Читает CURRENT_BUDGET из CSaleUserAccount::GetByUserId(). Игнорирует заблокированные счета (LOCKED = Y → null). Не учитывает пул.

getUserBudgetByOrder() — БД + пул

        UserBudgetPool::getUserBudgetByOrder($order);

    

Суммирует getUserBudget() и все SUM из незаписанных $items пула. Именно этот метод использует InnerHandler перед списанием — чтобы видеть баланс с учётом операций текущего хита.

getUserBudgetTransForOrder() — транзакции + пул

        UserBudgetPool::getUserBudgetTransForOrder($order);

    

Суммирует AMOUNT из CSaleUserTransact по ORDER_ID (с учётом DEBIT) и добавляет суммы из пула, кроме типа BUDGET_TYPE_ORDER_PAY. Нужен при расчёте возвратов, когда часть операций ещё не попала в b_sale_user_transact.

Практика: диагностика и отладка

Шаг 1. Проверить состояние счёта в БД

        SELECT USER_ID, CURRENT_BUDGET, CURRENCY, LOCKED
FROM b_sale_user_account
WHERE USER_ID = :userId;

    

Если LOCKED = Y — InnerHandler откажет до обращения к пулу (ORDER_PSH_INNER_ERROR_USER_BUDGET_LOCK).

Шаг 2. Посмотреть транзакции по заказу

        SELECT TRANSACT_DATE, AMOUNT, CURRENCY, DEBIT, DESCRIPTION, ORDER_ID, PAYMENT_ID
FROM b_sale_user_transact
WHERE ORDER_ID = :orderId
ORDER BY TRANSACT_DATE DESC;

    

Шаг 3. Проверить пул в runtime

        <?php
declare(strict_types=1);

use Bitrix\Main\Loader;
use Bitrix\Sale\Internals\UserBudgetPool;
use Bitrix\Sale\Order;

Loader::includeModule('sale');

$order = Order::load($orderId);
$userId = $order->getUserId();

// Эффективный баланс (БД + незаписанный пул)
$effectiveBudget = UserBudgetPool::getUserBudgetByOrder($order);

// Только БД
$dbBudget = UserBudgetPool::getUserBudget($userId, $order->getCurrency());

// Незаписанные операции текущего хита
$pool = UserBudgetPool::getUserBudgetPool($userId);
$pending = $pool->get() ?: [];

// Сумма транзакций + пул (для возвратов)
$transSum = UserBudgetPool::getUserBudgetTransForOrder($order);

    

Шаг 4. Отловить SALE_PROVIDER_USER_BUDGET_LOCKED

Что делать:

1. Проверить логи на дублирующиеся callback-и платёжных систем.
2. Убедиться, что повторная обработка идемпотентна (проверка Payment::isPaid() до списания).
3. Не вызывать onUserBudgetSave() вручную вне Order::save() — это нарушит порядок операций.

Шаг 5. Проверить GET_LOCK в MySQL

        SELECT IS_USED_LOCK(MD5(:serverUniqId) + MD5('user_budget_123')) AS lock_status;

    

Или через обёртку ядра:

        $connection = \Bitrix\Main\Application::getConnection();
$acquired = $connection->lock('user_budget_123', 0); // 0 = не ждать
if ($acquired) {
    $connection->unlock('user_budget_123');
}

    

Антипаттерны

Прямой UpdateAccount во время save()

        // ❌ Не делайте так внутри обработчиков оплаты
\CSaleUserAccount::UpdateAccount($userId, -500, 'RUB', 'MANUAL', $orderId);
$order->save(); // onUserBudgetSave() может перезаписать или конфликтовать

    

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

Чтение баланса через getUserBudget() при проверке оплаты

        // ❌ Устаревший баланс, если в этом хите уже было списание
$budget = UserBudgetPool::getUserBudget($userId, 'RUB');

// ✅ С учётом пула
$budget = UserBudgetPool::getUserBudgetByOrder($order);

    

Игнорирование Result после Order::save()

        $result = $order->save();
if (!$result->isSuccess()) {
    // Обязательно логируйте — сюда попадает SALE_PROVIDER_USER_BUDGET_LOCKED
}

    

Ручной addPoolItem без последующего save()

Операция останется в памяти пула и сбросится только при Order::save() или потеряется при завершении хита без save.