Налаштування історії операцій кешбеку в особистому кабінеті 1С-Бітрікс

Налаштування історії операцій кешбеку в особистому кабінеті 1С-Бітрікс

Користувач не розуміє, звідки взявся його поточний баланс. Нараховано 250 гривень — за яке замовлення? Списано 100 — коли і при якій покупці? Без прозорої історії операцій програма лояльності викликає недовіру. При цьому «показати таблицю з бази» — недостатньо: потрібна правильна пагінація, фільтрація за типом операції та коректна обробка часових поясів.

Таблиця транзакцій

Історія операцій зберігається в local_cashback_transactions. Структура, достатня для відображення всього необхідного:

CREATE TABLE local_cashback_transactions (
    ID          BIGINT AUTO_INCREMENT PRIMARY KEY,
    USER_ID     INT NOT NULL,
    TYPE        ENUM('accrual','debit','reserve','release','expire','manual') NOT NULL,
    AMOUNT      DECIMAL(10,2) NOT NULL,
    ORDER_ID    INT,
    PAYMENT_ID  INT,
    DESCRIPTION VARCHAR(500),
    CREATED_AT  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    EXPIRES_AT  DATETIME,
    INDEX idx_user_date (USER_ID, CREATED_AT DESC)
);

Індекс по (USER_ID, CREATED_AT DESC) — обов'язковий. Без нього вибірка історії за останні 6 місяців у активного користувача з тисячами транзакцій буде повним скануванням таблиці.

Компонент історії

Створюємо компонент /local/components/local/cashback.history/. Структура:

class.php        — логіка вибірки
templates/.default/template.php  — шаблон
lang/ru/         — мовні файли

class.php — успадковуємо від CBitrixComponent:

class CashbackHistoryComponent extends CBitrixComponent
{
    public function executeComponent(): void
    {
        if (!$this->getUser()->isAuthorized()) {
            ShowError('Доступ заборонено');
            return;
        }

        $userId    = (int)$this->getUser()->GetID();
        $pageNum   = max(1, (int)($_GET['page'] ?? 1));
        $pageSize  = (int)($this->arParams['PAGE_SIZE'] ?? 20);
        $typeFilter = $_GET['type'] ?? '';

        $filter = ['USER_ID' => $userId];
        if (in_array($typeFilter, ['accrual', 'debit', 'expire'])) {
            $filter['TYPE'] = $typeFilter;
        }

        $totalCount = CashbackTransactionTable::getCount($filter);

        $transactions = CashbackTransactionTable::getList([
            'filter' => $filter,
            'order'  => ['CREATED_AT' => 'DESC'],
            'limit'  => $pageSize,
            'offset' => ($pageNum - 1) * $pageSize,
            'select' => ['ID', 'TYPE', 'AMOUNT', 'ORDER_ID', 'DESCRIPTION', 'CREATED_AT', 'EXPIRES_AT'],
        ])->fetchAll();

        // Завантажуємо номери замовлень одним запитом
        $orderIds = array_filter(array_column($transactions, 'ORDER_ID'));
        $orderNumbers = [];
        if ($orderIds) {
            $res = \Bitrix\Sale\Internals\OrderTable::getList([
                'filter' => ['ID' => $orderIds],
                'select' => ['ID', 'ACCOUNT_NUMBER'],
            ]);
            while ($row = $res->fetch()) {
                $orderNumbers[$row['ID']] = $row['ACCOUNT_NUMBER'];
            }
        }

        $this->arResult = [
            'BALANCE'       => CashbackBalanceTable::getBalance($userId),
            'TRANSACTIONS'  => $transactions,
            'ORDER_NUMBERS' => $orderNumbers,
            'TOTAL_COUNT'   => $totalCount,
            'PAGE_NUM'      => $pageNum,
            'PAGE_SIZE'     => $pageSize,
            'TYPE_FILTER'   => $typeFilter,
        ];

        $this->includeComponentTemplate();
    }
}

Відображення та пагінація

Ключовий момент із пагінацією: стандартний CDBResult із NavStart/NavNext підходить для старих компонентів. Для D7-компонента — власний розрахунок $totalPages і генерація URL.

// template.php
$totalPages = (int)ceil($arResult['TOTAL_COUNT'] / $arResult['PAGE_SIZE']);

$typeLabels = [
    'accrual' => 'Нарахування',
    'debit'   => 'Списання',
    'reserve' => 'Резерв',
    'release' => 'Повернення резерву',
    'expire'  => 'Згоряння',
    'manual'  => 'Ручне коригування',
];

$amountSign = [
    'accrual' => '+',
    'debit'   => '−',
    'reserve' => '−',
    'release' => '+',
    'expire'  => '−',
    'manual'  => '',
];

Часовий пояс: дати з бази — UTC. Конвертація в часовий пояс користувача:

$userTz = new \DateTimeZone(\CTimeZone::GetOffset() ? 'UTC' : date_default_timezone_get());
$dt = new \DateTime($transaction['CREATED_AT'], new \DateTimeZone('UTC'));
$dt->setTimezone($userTz);
echo $dt->format('d.m.Y H:i');

Або через стандартний \Bitrix\Main\Type\DateTime::createFromTimestamp() — він враховує налаштування часового поясу сайту.

Зв'язок із замовленнями

Транзакції типу accrual і debit мають давати посилання на замовлення. Посилання будуємо через ACCOUNT_NUMBER, а не через ID — це публічний номер замовлення в особистому кабінеті:

/personal/order/detail/{ACCOUNT_NUMBER}/

Якщо замовлення видалено — посилання не показуємо, лише номер з позначкою «(замовлення видалено)».

Термін дії кешбеку

Якщо бізнес-логіка передбачає згоряння кешбеку (наприклад, через 12 місяців неактивності), поле EXPIRES_AT відображається для транзакцій типу accrual. Cron щодня знаходить кешбек із вичерпаним терміном і створює транзакцію типу expire:

// Cron: місцівська північ
$expired = CashbackTransactionTable::getList([
    'filter' => [
        'TYPE'       => 'accrual',
        '<EXPIRES_AT' => new \Bitrix\Main\Type\DateTime(),
        'EXPIRED'    => false,
    ],
]);

Склад робіт

• Таблиця транзакцій з індексами
• Компонент /local/components/local/cashback.history/ із пагінацією та фільтрацією
• Конвертація часових поясів, зв'язок із замовленнями
• Механізм згоряння кешбеку (якщо потрібен)
• Розміщення компонента в шаблоні особистого кабінету

Терміни: 1–1.5 тижні для компонента і шаблону. 2–3 тижні з урахуванням механізму згоряння та адміністративного інтерфейсу ручних коригувань.