mufassall

Шпаргалка · Бизнес-процессы

Двойная запись в учёте денег

14 мин · Средний · mufassall.dtwin.uz/ru/l/double-entry-ledger/

← Открыть урок

Проблема

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

Чему вы научитесь

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

Диаграмма как код

Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).

Mermaid: схема

flowchart LR
  n_app(["Приложение"])
  n_api["Wallet API"]
  n_ledger[("Журнал")]
  n_balances[("Кэш балансов")]
  n_payout("Списание холдов")
  n_support(("Поддержка"))
  n_rates>"Курсы валют"]
  n_checker("Оборотка")
  n_pager>"Алерт дежурному"]
  n_app --> n_api
  n_api --> n_ledger
  n_api --> n_balances
  n_payout --> n_ledger
  n_support --> n_api
  n_api --> n_rates
  n_checker --> n_ledger
  n_checker --x n_pager

Mermaid: последовательность запросов

sequenceDiagram
  participant n_api as Wallet API
  participant n_wallets as Таблица кошельков
  participant n_ledger as Журнал
  participant n_balances as Кэш балансов
  participant n_app as Приложение
  participant n_checker as Оборотка
  Note over n_api,n_wallets: Кошелёк — одно число в одной строке
  n_api->>n_wallets: SELECT balance_minor FROM wallets WHERE user_id = 'u_42'#59;
  n_wallets-->>n_api: UPDATE 1
  Note over n_api,n_wallets: Две оплаты разом, одна исчезает
  n_api->>n_wallets: 12:00:01.204 tx A read balance_minor=12000 (order 4500)
  Note over n_api,n_ledger: Каждое движение — проводка, сумма строк равна нулю
  n_api->>n_ledger: BEGIN#59;
  n_ledger-->>n_api: COMMIT
  Note over n_api,n_balances: Баланс — это сумма, закэшированная с версией
  n_api->>n_balances: UPDATE account_balances
  n_balances-->>n_api: UPDATE 1
  Note over n_app,n_api: Повтор проводит одну оплату дважды
  n_app->>n_api: 14:02:10 POST /v1/orders/ord_5133/pay -#62; no answer in 5 s
  Note over n_app,n_api: Один ключ на бизнес-операцию
  n_app->>n_api: POST /v1/orders/ord_5133/pay HTTP/1.1
  n_api-->>n_app: HTTP/1.1 200 OK
  Note over n_app,n_api: Холды: учётный и доступный баланс
  n_app->>n_api: GET /v1/wallets/u_58/balance HTTP/1.1
  n_api-->>n_app: HTTP/1.1 200 OK
  Note over n_api,n_ledger: Возврат — новая проводка, а не правка
  n_api->>n_ledger: INSERT INTO journal_entries (id, kind, ref, reverses)
  n_ledger-->>n_api: INSERT 0 3
  Note over n_api,n_ledger: Одна валюта на сумму, конвертация через счета
  n_api->>n_ledger: INSERT INTO postings (entry_id, account, amount_minor, currency)
  n_ledger-->>n_api: COMMIT
  Note over n_checker,n_ledger: Каждую ночь: всё ли ещё сходится в ноль?
  n_checker->>n_ledger: SELECT currency, SUM(amount_minor) AS total
  n_ledger-->>n_checker: trial balance 2026-11-17

D2

direction: right

n_app: "Приложение" {
  shape: rectangle
}
n_api: "Wallet API" {
  shape: rectangle
}
n_ledger: "Журнал" {
  shape: cylinder
}
n_balances: "Кэш балансов" {
  shape: cylinder
}
n_payout: "Списание холдов" {
  shape: rectangle
  style.multiple: true
}
n_support: "Поддержка" {
  shape: person
}
n_rates: "Курсы валют" {
  shape: cloud
}
n_checker: "Оборотка" {
  shape: rectangle
  style.multiple: true
}
n_pager: "Алерт дежурному" {
  shape: cloud
}

n_app -> n_api
n_api -> n_ledger
n_api -> n_balances
n_payout -> n_ledger
n_support -> n_api
n_api -> n_rates
n_checker -> n_ledger
n_checker -> n_pager {
  target-arrowhead.shape: cross
}

PlantUML: последовательность запросов

@startuml
participant "Wallet API" as n_api
database "Таблица кошельков" as n_wallets
database "Журнал" as n_ledger
database "Кэш балансов" as n_balances
participant "Приложение" as n_app
participant "Оборотка" as n_checker
note over n_api, n_wallets : Кошелёк — одно число в одной строке
n_api -> n_wallets : SELECT balance_minor FROM wallets WHERE user_id = 'u_42';
n_wallets --> n_api : UPDATE 1
note over n_api, n_wallets : Две оплаты разом, одна исчезает
n_api -> n_wallets : [дубль] 12:00:01.204 tx A read balance_minor=12000 (order 4500)
note over n_api, n_ledger : Каждое движение — проводка, сумма строк равна нулю
n_api -> n_ledger : BEGIN;
n_ledger --> n_api : COMMIT
note over n_api, n_balances : Баланс — это сумма, закэшированная с версией
n_api -> n_balances : UPDATE account_balances
n_balances --> n_api : UPDATE 1
note over n_app, n_api : Повтор проводит одну оплату дважды
n_app -> n_api : [дубль] 14:02:10 POST /v1/orders/ord_5133/pay -> no answer in 5 s
note over n_app, n_api : Один ключ на бизнес-операцию
n_app -> n_api : POST /v1/orders/ord_5133/pay HTTP/1.1
n_api --> n_app : HTTP/1.1 200 OK
note over n_app, n_api : Холды: учётный и доступный баланс
n_app -> n_api : GET /v1/wallets/u_58/balance HTTP/1.1
n_api --> n_app : HTTP/1.1 200 OK
note over n_api, n_ledger : Возврат — новая проводка, а не правка
n_api -> n_ledger : INSERT INTO journal_entries (id, kind, ref, reverses)
n_ledger --> n_api : INSERT 0 3
note over n_api, n_ledger : Одна валюта на сумму, конвертация через счета
n_api -> n_ledger : INSERT INTO postings (entry_id, account, amount_minor, currency)
n_ledger --> n_api : COMMIT
note over n_checker, n_ledger : Каждую ночь: всё ли ещё сходится в ноль?
n_checker -> n_ledger : SELECT currency, SUM(amount_minor) AS total
n_ledger --> n_checker : trial balance 2026-11-17
@enduml

PlantUML: компоненты

@startuml
left to right direction
agent "Приложение" as n_app
component "Wallet API" as n_api
database "Журнал" as n_ledger
database "Кэш балансов" as n_balances
collections "Списание холдов" as n_payout
actor "Поддержка" as n_support
cloud "Курсы валют" as n_rates
collections "Оборотка" as n_checker
cloud "Алерт дежурному" as n_pager
n_app --> n_api
n_api --> n_ledger
n_api --> n_balances
n_payout --> n_ledger
n_support --> n_api
n_api --> n_rates
n_checker --> n_ledger
n_checker -[#c62828]-> n_pager
@enduml

Итог

Шесть правил для денег в продукте.

1) Никогда не храните деньги числом, которое перезаписывается на месте. 2) Каждое движение — проводка с нулевой суммой строк, вставленная в одной транзакции. 3) Баланс — сумма строк; кэш допустим, если у него есть версия и его можно перестроить. 4) Один ключ идемпотентности на бизнес-операцию; холд уменьшает доступный баланс до списания или истечения. 5) Отмена — сторнирующей проводкой, никогда не UPDATE и не DELETE; одна валюта на сумму, конвертация через счета. 6) Каждый день считайте оборотку и будите человека, если она не ноль.

Показатели: в начале и в конце

ПоказательВ началеВ конце
Необъяснённые деньги0 $0 $
Потерянные обновления0/день0/день
Двойные списания0/день0/день
Чтение баланса2 мс3 мс

Шаги

  1. Кейс Кошелёк — одно число в одной строке

    Покупатель платит $45.00 за заказ.

  2. Проблема Две оплаты разом, одна исчезает

    Покупатель в одну секунду оплачивает один заказ в телефоне, другой в браузере.

  3. Решение Каждое движение — проводка, сумма строк равна нулю

    Кошелёк становится счётом, как и продавец, и комиссионный доход платформы.

  4. Решение Баланс — это сумма, закэшированная с версией

    Настоящий баланс — SUM(amount_minor) по строкам счёта.

  5. Проблема Повтор проводит одну оплату дважды

    На медленной сети запрос оплаты уходит в таймаут.

  6. Решение Один ключ на бизнес-операцию

    Приложение создаёт ключ один раз на оплату, pay-ord_5133, и шлёт его в каждом повторе.

  7. Решение Холды: учётный и доступный баланс

    Покупатель заказывает товар за $129.00, который отправят через неделю.

  8. Решение Возврат — новая проводка, а не правка

    Поддержка оформляет возврат по ord_5120.

  9. Решение Одна валюта на сумму, конвертация через счета

    Покупатель платит 100.00 EUR в долларовый кошелёк.

  10. Решение Каждую ночь: всё ли ещё сходится в ноль?

    Ночной джоб считает оборотный баланс (trial balance): сумма всех строк по каждой валюте обязана быть ровно нулём.

  11. Итоги Итог

    Шесть правил для денег в продукте.

Термины

Двойная запись
Каждое движение денег — проводка, сумма строк которой равна нулю: дебет равен кредиту.
Оборотный баланс
Регулярная проверка, что сумма всех строк по каждой валюте ровно ноль.
Сторнирующая проводка
Новая проводка с обратными строками, отменяющая прежнюю без её правки.