Проектирование iGaming-кошелька: как объяснить каждый баланс

Кошелёк надёжен, когда команда может точно ответить: почему эта сумма доступна сейчас и какие зафиксированные операции её объясняют? Колонка баланса не даст ответа после потерянного сообщения, пересекающихся ставок или поздней корректировки. Журнал поможет, только если входит в тот же контролируемый процесс записи, который решает, допустимо ли движение денег.

Руководство предназначено для архитекторов, руководителей разработки и специалистов финансовой или операционной проверки. Оно предлагает модель операционного журнала, разбирает записи и определяет подтверждения, необходимые для доверия к нему. Модель счетов и суммы условны. Финансовые специалисты оператора и специалисты по соблюдению требований должны утвердить реальные счета, учёт акций, правила защиты средств и политику корректировок; инженерный проект не решает эти вопросы за них.

Определите полномочия кошелька и факты, которые он должен сохранять

Кошелёк отвечает за денежные проводки и резервы. Платежи предоставляют принятые подтверждения провайдера; игры — сведения о принятых раундах и расчётах; бонусы — правила финансирования и ссылку на акцию. Эти модули запрашивают операции через границу кошелька. Они не ведут каждый свой независимо изменяемый баланс игрока. Более широкий контекст раскрывают услуги по архитектуре iGaming и интеграции платежей и проверки личности.

Различайте операцию и её записи в журнале. Операция хранит намерение, идентификатор и исход; группа проводок содержит дебетовые и кредитовые записи завершённого денежного изменения. Резерв ограничивает доступную для расходования сумму, не обязательно завершая это изменение. Отклонённый запрос может иметь запись операции без финансовых проводок. Сохранение запроса не доказывает его проведение.

• Сбалансированная проводка: у каждой зафиксированной группы дебет равен кредиту в пределах её валюты и границы учёта.
• Контролируемая доступность: расходование и новые резервы не превышают средства, допустимые по утверждённым правилам.
• Стабильный идентификатор: повтор той же принятой операции не создаёт нового финансового результата; изменение её смысла обнаруживается.
• Сохранённая история: корректировки добавляют связанные записи. Пользователи приложения не могут переписывать или удалять зафиксированные проводки.
• Прослеживаемое восстановление: каждая внешняя ссылка, завершение резерва и корректировка связаны с исходной операцией.

Это предлагаемые условия приёмки, а не свойства, возникающие от названия сервиса «журнал». Административные права, импорт и корректировки поддержки должны соблюдать те же условия, что обычные игровые и платёжные запросы.

Выберите типы счетов и точное представление сумм до проектирования баланса

С точки зрения оператора денежные средства игрока — сумма обязательства перед ним. В условной модели оно увеличивается по кредиту и уменьшается по дебету. Поэтому дебет не означает автоматически «деньги уходят из бизнеса»: смысл зависит от типа счёта.

Руководство TigerBeetle по учёту объясняет увеличение активов по дебету, обязательств по кредиту и наличие дебетовых и кредитовых записей в транзакции. Это обосновывает терминологию, но не определяет план счетов оператора или признание выручки.

Для примеров используйте счёт обязательств по денежным средствам игрока, активный счёт расчётов с платёжным провайдером (PSP) для средств у него или сумм к получению и контрольный счёт игровых расчётов. Последний — операционный корреспондирующий счёт, а не автоматически игровая выручка. Последовательность проводок ниже начинается с нулевых остатков, использует EUR и не учитывает комиссии и налоги. В остальных сценариях начальные остатки указаны отдельно. Реальное соответствие счетов требует одобрения финансовых специалистов и отдельного учёта сроков расчётов, комиссий и других обязательств.

Храните валюту и определённую единицу вместе с каждой суммой. Целое число поддерживаемых минимальных единиц или десятичный тип с явной точностью и правилами округления позволяют сохранять точные значения; двоичная плавающая точка не подходит для денежных итогов, на основании которых выполняются операции. Не считайте, что каждая поддерживаемая валюта или актив имеют два знака после запятой. Проверяйте число дробных разрядов входной суммы, границы и преобразование в единицу хранения до принятия операции.

Документация PostgreSQL по числовым типам различает точные десятичные значения и неточную плавающую точку, отмечая возможность округления при заданном числе дробных разрядов. Точное хранение не заменяет явных правил для избыточной входной точности. Это пример базы данных, а не требование использовать PostgreSQL.

Разделяйте денежные средства и ограниченный бонус по счетам и ссылкам на источник финансирования. Общая отображаемая сумма не обязательно доступна для ставки или вывода. В простой денежной модели учтённый остаток равен кредитам минус дебеты; доступный остаток — учтённым средствам минус активные денежные резервы. Формула предполагает отсутствие разрешённого овердрафта и дополнительных денежных ограничений. Реальные правила действия могут уменьшать сумму, пригодную для конкретной игры или вывода. Не объединяйте разные валюты или несвязанные права на акции в этой формуле.

Проследите депозиты, резервы и расчёты через соответствующие записи

Используйте этот предлагаемый список операций, чтобы связать каждое действие с его записями. Он предусматривает полное завершение резерва; частичный расчёт требует отдельно определённых правил распределения.

1. Депозит EUR 100. Когда согласованное подтверждение разрешает зачисление, дебетуйте счёт расчётов с PSP на EUR 100 и кредитуйте денежный счёт игрока на EUR 100 в одной группе проводок. Денежный остаток — EUR 100. Укажите принятый платёж и внешнюю транзакцию; возврат браузера не разрешает эту проводку.
2. Резерв под ставку EUR 30. Создайте резерв денежных средств игрока и сохраните его назначение. В этой модели резерв не создаёт проведённого дебета или кредита: остаток сохраняется EUR 100, в резерве EUR 30, доступно EUR 70. Объяснимыми должны быть и журнал, и история резервирования.
3. Освобождение резерва, если ставка окончательно не принята. Добавьте запись освобождения со ссылкой на резерв. Остаток сохраняется EUR 100, доступная сумма возвращается к EUR 100. Освобождение — не новый депозит EUR 30.
4. Альтернативная ветвь: проведение принятой ставки. Дебетуйте денежный счёт игрока на EUR 30 и кредитуйте контрольный счёт игровых расчётов на EUR 30, одновременно завершая резерв в той же атомарной операции кошелька. Учтённая и доступная суммы становятся EUR 70; EUR 30 не должны дополнительно оставаться активным резервом.
5. Расчёт с общей выплатой EUR 45. Дебетуйте контрольный счёт игровых расчётов на EUR 45 и кредитуйте денежный счёт игрока на EUR 45 со ссылкой на первоначальный принятый раунд. Остаток становится EUR 115. Выплата в примере включает ставку; дополнительный возврат ставки дал бы избыточное зачисление.
6. Запрос вывода EUR 40. Зарезервируйте EUR 40 по утверждённым правилам вывода. Учтённый остаток сохраняется EUR 115, в резерве EUR 40, доступно EUR 75. Подтверждённая завершённая выплата дебетует денежный счёт игрока на EUR 40 и кредитует счёт расчётов с PSP на EUR 40, одновременно списывая резерв. Остаток теперь EUR 75, активного резерва нет.
7. Сторнирование выплаты EUR 45, если этого требует проверенная корректировка. Добавьте новую группу: дебет денежного счёта игрока EUR 45, кредит контрольного счёта игровых расчётов EUR 45. Если после завершённого вывода других расходов не было, остаток становится EUR 30. Сохраните первоначальную выплату и свяжите с ней корректировку; заменяющий расчёт оформляйте отдельной явной операцией.

Освобождение и проведение ставки — альтернативные ветви. При отклонённом или отменённом выводе резерв освобождается лишь тогда, когда правила взаимодействия устанавливают, что выплата не произошла и не произойдёт. Неизвестный результат провайдера нельзя считать отказом только из-за истечения локального таймера.

Документация TigerBeetle по двухэтапным переводам описывает конкретную модель: резервирование, затем проведение или отмена новой неизменяемой записью перевода, с поддержкой настроенного истечения срока. Локальный механизм не устанавливает завершение внешней выплаты. Правила истечения срока должны учитывать реальные условия внешнего принятия и восстановления.

Фиксируйте решение о расходовании, операцию и проводки вместе

Допустим, доступно EUR 60 и одновременно поступают два разных запроса на EUR 40. Оба могут пройти предварительное чтение баланса. Не дать им расходовать одну и ту же сумму может только окончательное атомарное решение о принятии: после успешного создания одного резерва доступно EUR 20, а второй запрос должен быть отклонён или ожидать реального изменения баланса.

Для реляционной реализации используйте транзакцию, которая вместе проверяет область операции и параметры, защищает затронутые баланс и резервы, проверяет доступность, записывает все проводки или изменения резервов и сохраняет исход. Выберите явную блокировку строк с одинаковым порядком захвата, условные обновления с проверкой версии и инварианта или подходящий вариант сериализуемого исполнения. Блокировка несвязанной строки запроса не защищает общие средства игрока. Очередь на счёт должна также учитывать конкурирующих отправителей и восстановление обработчиков; автоматически общей блокировкой она не становится.

Документация PostgreSQL по изоляции объясняет: зафиксированные конкурентные транзакции при сериализуемом исполнении эквивалентны последовательному порядку, а приложение должно обрабатывать ошибки сериализации. Защита ограничена транзакцией этой базы; она не сериализует удалённый вызов провайдера вместе с кошельком.

Внешние вызовы должны выполняться вне короткой транзакции защиты средств. Сохраняйте намерение внешней работы и восстанавливайте её со стабильным идентификатором операции после локальной фиксации. Если транзакцию базы нужно перезапустить после взаимной блокировки или конфликта сериализации, повторяйте всё её локальное решение с тем же идентификатором операции; не повторяйте платёж провайдеру как случайный побочный эффект перезапуска.

Ограничьте защиту от повторов доверенным вызывающим участником или интеграцией, типом операции и стабильным идентификатором запроса. Свяжите его с игроком, счётом, валютой, суммой, распределением финансирования и соответствующей первоначальной ссылкой. Повтор идентификатора события и повтор бизнес-операции — разные случаи: два сообщения могут относиться к одному расчёту. Финансовый идентификатор определяется на границе, отвечающей за запись.

Amazon Builders’ Library описывает идентификаторы от вызывающей стороны, атомарное сохранение с изменениями и отклонение изменённых параметров под тем же идентификатором. Если токен кошелька сохраняется до проводок или проводки до токена, возникает разрыв при сбое — кроме случая их совместной фиксации.

Одновременные повторы должны сходиться к сохранённой операции благодаря обязательной уникальности и транзакции проводок. После потери ответа разрешённый поиск или безопасный повтор должны определять первоначальный исход, а не просто сообщать «уже существует». Сохраняйте достаточные финансовые ссылки дольше краткого кеша ответов API; поздний повтор не должен становиться новой проводкой. Намеренно новая корректировка получает собственный идентификатор и ссылку на исходную операцию.

Исправляйте историю, не скрывая недостачу

Журнал, допускающий только добавление, сохраняет зафиксированные записи; он не делает все меняющиеся операционные поля неизменяемыми. Статус процесса или производный баланс могут изменяться по контролируемым переходам. Первоначальную группу проводок, сумму, счета и ссылки нельзя редактировать, чтобы история выглядела как новейший результат. Ограничения записи приложения, контроль привилегированного доступа и подтверждения восстановления должны обеспечивать это правило.

Корректировка — финансовое решение с полномочиями, причиной и ссылкой. Проверьте источник провайдера или разрешённое действие сотрудника, определите сторнируемый результат и ограничьте повторные или избыточные сторнирования. При частичном сторнировании ранее отменённая сумма плюс новая не должны превышать допустимую первоначальную сумму. Проверяйте условие атомарно относительно других корректировок; метка администратора не освобождает операцию от проверки.

Рассмотрим вариант примера: после достижения EUR 75 игрок тратит ещё EUR 50, оставляя EUR 25, а затем сторнируется выплата EUR 45. Простое вычитание даёт отрицательный остаток EUR 20, нарушая запрет овердрафта в этой модели. Ни отбрасывание корректировки, ни незаметное обнуление не объясняют недостающую сумму.

Если утверждённые правила разрешают финансовое урегулирование с использованием оставшихся EUR 25, условная группа может дебетовать денежный счёт игрока на EUR 25, дебетовать одобренный финансовыми специалистами счёт убытка или дебиторской задолженности на EUR 20 и кредитовать контрольный счёт игровых расчётов на EUR 45, указав дело разбора. Остаток становится нулевым, а недостача остаётся учтённой. Дебиторская задолженность должна означать обоснованное утверждённое требование, а не инженерную выдумку. Если правила не разрешают такое урегулирование, сохраните корректировку как нерешённую работу и передайте её ответственным; не объявляйте её проведённой. Ограничения аккаунта, уведомления и последующее урегулирование определяйте с ответственными специалистами оператора.

Денежные, бонусные и смешанные операции добавляют ещё одно условие: корректировка следует первоначальному распределению финансирования и правилам акции. Сторнирование ставки из ограниченного бонуса не должно незаметно превращаться в выводимые деньги. Инструменты сотрудников должны предлагать поддерживаемые операции корректировки с причинами и необходимым рассмотрением, а не прямой редактор баланса.

Сверяйте записи на одинаковых границах учёта

Сверка проверяет, согласуются ли независимо сохранённые факты на одной границе учёта. Начните с внутренних проверок: сбалансированные группы, отсутствие проводок без соответствующей группы, завершения резервов со ссылками на реальные резервы, соответствие исходов операций проводкам и сохранённых представлений баланса журналу и активным резервам. Сравнивайте согласованный снимок или явно совпадающие позиции; сравнение текущего журнала со старым представлением создаёт ложные расхождения.

Затем сравнивайте принятые платёжные записи, операции кошелька и отчёты провайдера или расчётов. Сопоставляйте сначала стабильные ссылки, затем валюту, сумму, статус и период. Отчёт о платежах провайдера и отчёт о его банковских расчётах могут описывать разные границы; комиссии, возвратные списания и сроки расчётов требуют явных категорий. Один итог не выявит отсутствующее зачисление EUR 100, компенсированное несвязанным лишним зачислением EUR 100.

• Провайдер принял, проводки кошелька нет: установите достоверный исход платежа, найдите исходную операцию кошелька и завершайте её только по правилам зачисления.
• Проводка есть, ответа нет: восстановите видимый результат операции; не добавляйте проводку ради исправления статуса.
• Исход вывода неизвестен, резерв активен: выясняйте первоначальную отправку провайдеру и сохраняйте резерв, пока правила восстановления не разрешат завершение.
• Внутренние записи сбалансированы, внешние итоги расходятся: проверьте отсутствующие, повторные или неправильно классифицированные операции, комиссии и момент отсечения данных. Сбалансированный учёт может отражать неверные бизнес-факты.

Для каждого расхождения нужны ответственный, сумма под риском, время ожидания, подтверждающие ссылки и разрешённое решение. Выполняйте корректировку лишь после установления причины и полномочий. Считайте необъяснимое отклонение инцидентом по согласованным порогам; анонимная «корректировка сверки» уравнивает число, уничтожая объяснение.

Проверьте восстановление и переход без появления второго кошелька

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

Для восстановления установите, до какой зафиксированной точки возвращается база или журнал, затем сопоставьте её с внешними операциями, которые могли завершиться после этой точки. Восстановленная локальная база не отменяет выплату провайдера. Сохраните и сверьте подтверждения промежутка до разрешения новых расходов; повторная обработка должна различать отсутствующие локальные результаты и уже завершённые. Определяйте допустимую потерю данных и время восстановления по реальным обязательствам и проверяйте их, а не обещайте ноль по умолчанию.

Миграция требует той же дисциплины. Восстановите начальные остатки и активные резервы, сохраните их происхождение и внешние ссылки, классифицируйте нерешённые операции. Сверьте импортированную начальную позицию со старой системой и независимыми подтверждениями на документированный момент отсечения. При передаче для каждого счёта должен быть один компонент с правом записи; простое дублирование запросов в два журнала может повторить реальные действия или дать расхождения при сбое. До разрешения возврата к старому источнику проверьте восстановление новых записей.

Проверка производительности должна измерять финансовый путь: одновременные действия на часто используемых счетах, ожидания блокировок или конфликты, скорость фиксации проводок, время ожидания незавершённых операций и восстановление при накопленной очереди. При необходимости вынесите отчётность с большим числом чтений в контролируемые представления, но не разрешайте расходование по устаревшей читающей реплике. Журнал, сбалансированный в отдельной демонстрации успешного пути, ещё не прошёл приведённые ниже проверки конкурентности и восстановления.

Дополните проверку материалами о проектировании исходов платежей и сверки, финансировании ставок и расчётах букмекерской платформы и границах безопасности и привилегированных правах.

Ограничения аккаунта, акции и координация модулей влияют на запросы к журналу. Держите их правила взаимодействия видимыми через архитектуру аккаунтов игроков, проектирование бонусного движка и полный путь игрока и денег. Кошелёк остаётся ответственным за соблюдение финансовых инвариантов, когда эти модули запрашивают изменение.

• Потерянный ответ и изменённые параметры. Зафиксируйте депозит, потеряйте ответ и отправьте одновременные повторы с исходным идентификатором. Докажите наличие одной сбалансированной группы проводок и разрешённое получение её результата. Повторите с другой суммой, валютой или игроком: принятая операция не должна измениться или создаться заново.
• Конкурирующие расходы и завершение резерва. При доступных EUR 60 отправьте два разных запроса на EUR 40. Докажите, что оба не могут расходовать одни средства. Затем одновременно освободите и спишите успешно созданный резерв: допускается ровно одно действительное завершение без оставшегося дублирующего резерва или двойного возврата.
• Поздняя и избыточная корректировка. Сторнируйте выплату EUR 45, когда осталось лишь EUR 25, при запрете овердрафта из примера. Покажите утверждённое урегулирование недостачи или явно нерешённое дело. Также одновременно запросите частичные сторнирования, вместе превышающие первоначальную сумму: инвариант должен сохраниться.
• Восстановление при уже завершённой внешней работе. Вернитесь к локальной точке до сохранения исхода выплаты, когда провайдер уже заплатил. Сверьте первоначальную ссылку до возобновления расходов. Перестройте представления баланса и сравните их на совпадающих позициях; восстановление или повторная обработка не должны отправить ещё одну выплату.