Перейти к основному содержимому

Transaction Boundaries, Side Effects И Sagas

Назначение​

Документ описывает, как Pin фиксирует границы транзакций и побочные эффекты для операций с деньгами, платежами, KYC, играми, бонусами, партнерами и настройками платформы.

Базовое Правило​

Одна транзакция принадлежит одному сервису и одной operational database. Cross-service distributed transaction запрещена по умолчанию. Межсервисная согласованность достигается через MassTransit Inbox/Outbox, idempotency, saga state, compensating commands и reconciliation.

Стандарт Transaction Boundary​

Каждая mutation операция описывает:

ПунктОписание
НачалоПосле каких проверок открывается транзакция.
CommitПосле каких записей транзакция завершается.
СущностиAggregates, child entities, technical records.
IdempotencyГде хранится ключ и результат повторного запроса.
AuditКакие audit records пишутся в той же транзакции.
OutboxКакие events публикуются через MassTransit outbox до commit.
External CallsДо или после commit, timeout, retry, reconciliation.
RollbackЧто происходит при ошибке до commit.
Partial SuccessЧто происходит при ошибке после external side effect.

Внешние Вызовы​

  • Provider call до commit допускается только если provider требует синхронного создания session/payout до локального ответа.
  • Provider call после commit предпочтителен для долгих операций и выполняется background worker-ом.
  • Каждый external call имеет idempotency key или deterministic external reference.
  • Partial success обязательно закрывается reconciliation job.

Saga​

Saga используется, когда бизнес-flow затрагивает несколько сервисов и не может быть завершен одной локальной транзакцией.

FlowSaga State OwnerПримеры Шагов
DepositAccountingrequest created, provider session created, callback completed, ledger posted
WithdrawalAccountingrequest created, hold placed, admin approved, provider payout sent, ledger captured
Incentive GrantIncentive Storerule matched, incentive created, accounting incentive balance credited
KYC ApprovalProfile/KYCverification approved, profile level updated, accounting limits refreshed

Saga state хранит текущий шаг, correlationId, idempotency keys, external references, retry count, last error и next retry time.

Side Effects​

Side effects не прячутся внутри handler-а. Они перечисляются в постановке:

  • Kafka events через MassTransit outbox;
  • provider/internal HTTP calls;
  • cache invalidation;
  • Elasticsearch/read model updates;
  • notifications;
  • audit records;
  • metrics и traces.

Reconciliation​

Reconciliation job обязателен, если внешний provider может изменить состояние независимо от нашей транзакции.

Job описывает источник правды, ключ сопоставления, периодичность, допустимые статусы для исправления, audit trail и события после исправления.

Обратные ссылки​

Автоссылки: где используется этот документ.