Все заметки
Финтех

Когда колонка balance врёт: double-entry ledger, дебет = кредит и неизменяемые проводки

Одна колонка balance не скажет, откуда пришли деньги и куда ушли. Счета, проводки и строки, дебет = кредит под охраной триггера PostgreSQL, сторно и снапшоты: собираем честный леджер на Django.

Понедельник, утро, тикет в поддержку: «Вчера в кошельке было 350 000 сумов, сегодня 150 000. Я ничего не покупал». Открываете базу. В таблице wallets одна строка на пользователя, в колонке balance — 150 000. И всё. Это была покупка? Возврат, который потом откатили? Баг в прошлом деплое, который списал дважды? Число есть, а истории за ним нет.

Теперь обратный случай, и он хуже, потому что никто не жалуется: повтор callback'а от платёжки зачисляет мерчанту деньги дважды. Мерчант доволен, пользователь доволен, а система тихо создала 2 миллиона сумов из воздуха. Ничто в ней не знает, что деньги должны откуда-то прийти.

У обеих проблем общий корень: баланс хранится как единственный источник правды. Бухгалтеры решили это столетия назад — двойной записью. В этой статье соберём небольшой, но честный double-entry ledger на PostgreSQL и Django: счета, проводки, строки проводок, инвариант «дебет = кредит», который проверяет сама база, балансы со снапшотами и исправления без редактирования истории.

Почему колонки balance недостаточно

Вот версия, которую многие из нас когда-то писали:

# wallets/services.py — the "simple" version
from django.db import transaction
from django.db.models import F

from .models import Wallet


@transaction.atomic
def transfer(sender_id: int, receiver_id: int, amount: int) -> None:
    Wallet.objects.filter(user_id=sender_id).update(balance=F("balance") - amount)
    Wallet.objects.filter(user_id=receiver_id).update(balance=F("balance") + amount)

Она атомарна, использует F(), так что параллельные обновления не затирают друг друга. И всё равно:

  • Нет истории. После UPDATE прежнее значение исчезло. Если рядом пишется таблица-лог transactions, она живёт рядом с балансом, а не под ним, и рано или поздно они расходятся: кто-то поправил баланс руками, миграция забыла про лог, какой-то путь в коде его пропустил.
  • Нет инварианта. Никто не проверяет, что ушедшее из одного кошелька пришло в другой. Если из-за бага вторая строка зачислит amount + fee, база не возразит.
  • Исправление уничтожает улики. Естественный способ починить неверный баланс — ещё один UPDATE. Теперь не видно ни бага, ни исправления.
  • Деньгам неоткуда взяться. Пополнение с карты просто увеличивает одно число. А откуда деньги? От платёжного провайдера, который теперь нам их должен. Одной колонкой это не выразить.

Баланс — производная величина. Источник правды — список движений, и каждое движение обязано откуда-то деньги взять и куда-то их положить.

Модель: счета, проводки, строки

Двойная запись — это всего три понятия.

Счёт (account) — корзина, в которой лежит ценность: кошелёк пользователя, кошелёк мерчанта, деньги, которые нам должен провайдер, наша комиссионная выручка. У каждого счёта есть тип:

Тип Пример в платёжном кошельке Нормальная сторона
Актив Деньги в банке / долг PSP перед нами Дебет
Обязательство Кошельки пользователей и мерчантов (мы им должны) Кредит
Доход Комиссии Кредит
Расход Кэшбэк, стоимость эквайринга Дебет
Капитал Вложения владельцев Кредит

Неожиданное для разработчиков: кошелёк пользователя — это обязательство платформы. Деньги лежат у нас, но принадлежат ему, значит, это долг.

Проводка (journal entry) — одно бизнес-событие: «пополнение», «оплата заказа #812», «возврат». У неё есть описание, время и ключ идемпотентности.

Строка проводки (posting) — сумма, которая попадает на один счёт в рамках одной проводки. В проводке две строки или больше, и правило такое: в каждой проводке сумма дебета равна сумме кредита.

В коде удобно хранить одно знаковое целое: плюс — дебет, минус — кредит. Тогда правило превращается в «строки проводки в сумме дают ноль», а это проверить тривиально.

Пользователь пополняет кошелёк на 200 000 сумов с карты:

Счёт Тип Сумма
asset:psp-clearing Актив +200 000
wallet:user:42 Обязательство −200 000

PSP должен нам больше (актив растёт по дебету), мы должны пользователю больше (обязательство растёт по кредиту). Потом пользователь платит мерчанту 150 000 сумов с комиссией 1%:

Счёт Тип Сумма
wallet:user:42 Обязательство +150 000
wallet:merchant:7 Обязательство −148 500
revenue:fees Доход −1 500

Дебет 150 000, кредит 148 500 + 1 500. Сумма — ноль. Баланс, который видит пользователь, — сумма его строк с обратным знаком: 200 000 − 150 000 = 50 000. Теперь каждый сум в системе можно проследить до проводки, которая его сдвинула.

Схема PostgreSQL и модели Django

Суммы — целые числа в тийинах (см. прошлую статью про float и Decimal). У счёта есть кэшированный balance, но источник правды по-прежнему строки проводок.

# ledger/models.py
from django.db import models
from django.db.models import Q


class Account(models.Model):
    class Kind(models.TextChoices):
        ASSET = "asset", "Asset"
        LIABILITY = "liability", "Liability"
        EQUITY = "equity", "Equity"
        REVENUE = "revenue", "Revenue"
        EXPENSE = "expense", "Expense"

    code = models.CharField(max_length=64, unique=True)  # "wallet:user:42", "revenue:fees"
    kind = models.CharField(max_length=16, choices=Kind.choices)
    currency = models.CharField(max_length=3, default="UZS")
    allow_negative = models.BooleanField(default=False)
    # Cached sum of all postings, in tiyin, debit-positive.
    balance = models.BigIntegerField(default=0)

    @property
    def is_debit_normal(self) -> bool:
        return self.kind in (self.Kind.ASSET, self.Kind.EXPENSE)

    @property
    def display_balance(self) -> int:
        return self.balance if self.is_debit_normal else -self.balance


class JournalEntry(models.Model):
    description = models.CharField(max_length=255)
    idempotency_key = models.CharField(max_length=64, unique=True)
    reverses = models.OneToOneField(
        "self",
        null=True,
        blank=True,
        on_delete=models.PROTECT,
        related_name="reversed_by",
    )
    created_at = models.DateTimeField(auto_now_add=True)


class Posting(models.Model):
    entry = models.ForeignKey(JournalEntry, on_delete=models.PROTECT, related_name="postings")
    account = models.ForeignKey(Account, on_delete=models.PROTECT, related_name="postings")
    amount = models.BigIntegerField()  # tiyin: + debit, - credit
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        constraints = [
            models.CheckConstraint(condition=~Q(amount=0), name="posting_amount_nonzero"),
        ]
        indexes = [
            models.Index(
                fields=["account", "created_at"],
                include=["amount"],
                name="posting_acc_time_idx",
            ),
        ]

Несколько осознанных решений: on_delete=PROTECT везде, потому что в леджере каскадных удалений не бывает; reverses — это OneToOneField, так что сама база не даст сторнировать одну проводку дважды; индекс (account, created_at) INCLUDE (amount) позволяет PostgreSQL посчитать «баланс на момент X» через index-only scan, если visibility map актуальна. Обратите внимание: начиная с Django 5.1 CheckConstraint принимает condition=, а старый аргумент check= в Django 6.0 удалён.

База сама следит за дебет = кредит

Проверка суммы в Python — хорошо, но гарантия не должна зависеть от того, что каждый путь в коде идёт через ваш сервис. Обычный CHECK не видит других строк, поэтому используем constraint trigger, отложенный до коммита:

CREATE FUNCTION ledger_check_entry_balanced() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
    IF EXISTS (
        SELECT 1
        FROM ledger_posting p
        JOIN ledger_account a ON a.id = p.account_id
        WHERE p.entry_id = NEW.entry_id
        GROUP BY a.currency
        HAVING SUM(p.amount) <> 0
    ) THEN
        RAISE EXCEPTION 'journal entry % is not balanced', NEW.entry_id
            USING ERRCODE = 'check_violation';
    END IF;
    RETURN NULL;
END;
$$;

CREATE CONSTRAINT TRIGGER ledger_posting_balanced
    AFTER INSERT ON ledger_posting
    DEFERRABLE INITIALLY DEFERRED
    FOR EACH ROW EXECUTE FUNCTION ledger_check_entry_balanced();

Зачем DEFERRABLE INITIALLY DEFERRED? Строки вставляются по одной (или одним запросом), и после первой строки проводка по определению не сбалансирована. Отложенный constraint trigger срабатывает на COMMIT, когда все строки уже на месте. ERRCODE = 'check_violation' заставляет psycopg бросить CheckViolation, и Django отдаст его как IntegrityError; обычный RAISE EXCEPTION пришёл бы как куда менее говорящий ProgrammingError. Группировка по валюте означает, что проводка должна сходиться в каждой валюте отдельно: «уравновесить» 100 USD сотней UZS не выйдет.

Неизменяемые записи

Строки и проводки только добавляются. Не «по договорённости», а принудительно:

CREATE FUNCTION ledger_forbid_change() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
    RAISE EXCEPTION '% is append-only: % is not allowed', TG_TABLE_NAME, TG_OP;
END;
$$;

CREATE TRIGGER ledger_posting_append_only
    BEFORE UPDATE OR DELETE ON ledger_posting
    FOR EACH ROW EXECUTE FUNCTION ledger_forbid_change();

CREATE TRIGGER ledger_posting_no_truncate
    BEFORE TRUNCATE ON ledger_posting
    FOR EACH STATEMENT EXECUTE FUNCTION ledger_forbid_change();

CREATE TRIGGER ledger_entry_append_only
    BEFORE UPDATE OR DELETE ON ledger_journalentry
    FOR EACH ROW EXECUTE FUNCTION ledger_forbid_change();

Построчные триггеры на TRUNCATE не срабатывают, поэтому для него отдельный триггер уровня оператора. Сверху, если приложение подключается ролью, которая не владеет таблицами, REVOKE UPDATE, DELETE, TRUNCATE ON ledger_posting, ledger_journalentry FROM app_role; закрывает дверь ещё и на уровне прав. SQL поставляется обычной миграцией:

# ledger/migrations/0002_ledger_triggers.py
from django.db import migrations

FORWARD = """
-- paste both SQL blocks from above here:
-- ledger_check_entry_balanced + ledger_posting_balanced,
-- ledger_forbid_change + the three append-only triggers
"""

REVERSE = """
DROP TRIGGER IF EXISTS ledger_posting_balanced ON ledger_posting;
DROP TRIGGER IF EXISTS ledger_posting_append_only ON ledger_posting;
DROP TRIGGER IF EXISTS ledger_posting_no_truncate ON ledger_posting;
DROP TRIGGER IF EXISTS ledger_entry_append_only ON ledger_journalentry;
DROP FUNCTION IF EXISTS ledger_check_entry_balanced();
DROP FUNCTION IF EXISTS ledger_forbid_change();
"""


class Migration(migrations.Migration):
    dependencies = [("ledger", "0001_initial")]
    operations = [migrations.RunSQL(FORWARD, reverse_sql=REVERSE)]

Запись проводки из Django

Сервисная функция — единственное место, которое пишет в леджер. Она валидирует, блокирует затронутые счета, проверяет овердрафт, вставляет строки и обновляет кэшированные балансы — всё в одной транзакции:

# ledger/services.py
from collections import defaultdict
from dataclasses import dataclass

from django.db import transaction
from django.db.models import F

from .models import Account, JournalEntry, Posting


class LedgerError(Exception):
    pass


class UnbalancedEntry(LedgerError):
    pass


class InsufficientFunds(LedgerError):
    pass


@dataclass(frozen=True)
class Line:
    account_id: int
    amount: int  # tiyin: + debit, - credit


@transaction.atomic
def post_entry(
    *,
    description: str,
    idempotency_key: str,
    lines: list[Line],
    reverses: JournalEntry | None = None,
) -> JournalEntry:
    if any(line.amount == 0 for line in lines):
        raise UnbalancedEntry("zero-amount line")

    existing = JournalEntry.objects.filter(idempotency_key=idempotency_key).first()
    if existing is not None:
        return existing

    deltas: dict[int, int] = defaultdict(int)
    for line in lines:
        deltas[line.account_id] += line.amount

    # Stable lock order: A->B and B->A transfers cannot deadlock each other.
    accounts = {
        acc.id: acc
        for acc in Account.objects.select_for_update()
        .filter(id__in=list(deltas))
        .order_by("id")
    }
    if len(accounts) != len(deltas):
        raise LedgerError("unknown account")

    per_currency: dict[str, int] = defaultdict(int)
    for acc_id, delta in deltas.items():
        per_currency[accounts[acc_id].currency] += delta
    if any(total != 0 for total in per_currency.values()):
        raise UnbalancedEntry(f"debits != credits: {dict(per_currency)}")

    for acc_id, delta in deltas.items():
        acc = accounts[acc_id]
        new_balance = acc.balance + delta
        shown = new_balance if acc.is_debit_normal else -new_balance
        if shown < 0 and not acc.allow_negative:
            raise InsufficientFunds(acc.code)

    entry = JournalEntry.objects.create(
        description=description,
        idempotency_key=idempotency_key,
        reverses=reverses,
    )
    Posting.objects.bulk_create(
        [Posting(entry=entry, account_id=line.account_id, amount=line.amount) for line in lines]
    )
    for acc_id, delta in deltas.items():
        Account.objects.filter(id=acc_id).update(balance=F("balance") + delta)
    return entry

Что происходит по шагам:

  1. Идемпотентность. Если проводка с таким ключом уже есть, возвращаем её вместо повторной записи. Два параллельных запроса с одним ключом оба пройдут проверку, но unique пропустит только один коммит; второй получит IntegrityError и может перечитать победителя (подробно — в статье про ключи идемпотентности).
  2. Блокировка в стабильном порядке. select_for_update() с order_by("id") блокирует строки счетов по возрастанию id. Два встречных перевода блокируют в одном порядке и ждут друг друга, а не уходят в deadlock.
  3. Баланс по каждой валюте. Проверка в Python даёт понятную ошибку заранее; триггер — страховочная сетка.
  4. Овердрафт. Пока строки заблокированы, кэшированный баланс актуален, и потратить одни и те же деньги параллельно никто не сможет.
  5. Запись. Одна проводка, её строки через bulk_create и обновление баланса каждого счёта.

Оплата мерчанту из примера выше:

# payments/services.py
from ledger.models import Account, JournalEntry
from ledger.services import Line, post_entry


def pay_merchant(
    payer: Account, merchant: Account, fees: Account, amount: int, order_id: int
) -> JournalEntry:
    fee = amount // 100  # 1%, rounded down to a whole tiyin
    lines = [
        Line(payer.id, amount),              # debit: we owe the payer less
        Line(merchant.id, -(amount - fee)),  # credit: we owe the merchant more
        Line(fees.id, -fee),                 # credit: our revenue
    ]
    return post_entry(
        description=f"order #{order_id}",
        idempotency_key=f"order:{order_id}:pay",
        lines=[line for line in lines if line.amount != 0],
    )

Обратите внимание на округление комиссии: мерчант получает amount - fee, а не отдельно округлённое amount * 0.99. Посчитайте одну сторону и выведите из неё другую — тогда строки всегда в сумме дают ровно ноль.

Исправления: сторно, а не редактирование

Неверная сумма? Не тот мерчант? Старую проводку не трогаем. Записываем сторнирующую проводку с теми же строками и обратными знаками, а затем, если нужно, новую правильную:

# ledger/services.py (continued)
def reverse_entry(entry: JournalEntry, *, reason: str) -> JournalEntry:
    return post_entry(
        description=f"reversal of #{entry.pk}: {reason}",
        idempotency_key=f"reversal:{entry.pk}",
        lines=[Line(p.account_id, -p.amount) for p in entry.postings.all()],
        reverses=entry,
    )

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

Балансы и снапшоты

На вопрос «какой баланс» есть три ответа, и реальная система использует все три:

  1. Кэшированный balance на счёте, обновляемый в той же транзакции, что и строки. Его показываем в приложении и по нему проверяем овердрафт.
  2. Сумма строк — истина. На момент времени:
# ledger/queries.py
from datetime import datetime

from django.db.models import Sum

from .models import Account, Posting


def balance_at(account: Account, moment: datetime) -> int:
    """Debit-positive balance from all postings created before `moment`."""
    return Posting.objects.filter(account=account, created_at__lt=moment).aggregate(
        total=Sum("amount", default=0)
    )["total"]
  1. Снапшоты. Суммировать миллионы строк ради выписки медленно, поэтому закрываем каждый день в отдельную таблицу и суммируем только строки после последнего снапшота:
CREATE TABLE ledger_daily_balance (
    account_id bigint NOT NULL REFERENCES ledger_account (id),
    day        date   NOT NULL,
    balance    bigint NOT NULL,  -- closing balance, debit-positive
    PRIMARY KEY (account_id, day)
);

-- Closing balance of 2026-11-10 (Tashkent time) = previous day + that day's postings.
INSERT INTO ledger_daily_balance (account_id, day, balance)
SELECT a.id,
       DATE '2026-11-10',
       COALESCE(prev.balance, 0) + COALESCE(SUM(p.amount), 0)
FROM ledger_account a
LEFT JOIN ledger_daily_balance prev
       ON prev.account_id = a.id AND prev.day = DATE '2026-11-09'
LEFT JOIN ledger_posting p
       ON p.account_id = a.id
      AND p.created_at >= TIMESTAMPTZ '2026-11-10 00:00:00+05'
      AND p.created_at <  TIMESTAMPTZ '2026-11-11 00:00:00+05'
GROUP BY a.id, prev.balance
ON CONFLICT (account_id, day) DO UPDATE SET balance = EXCLUDED.balance;

Баланс на любой момент — это остаток на конец предыдущего дня плюс строки с полуночи. Прежде чем на это полагаться, измерьте: прогоните EXPLAIN (ANALYZE, BUFFERS) на запросе «баланс на момент» для самого нагруженного счёта со снапшотами и без них.

И наконец сверка. Запускайте регулярно (ночной Celery-задачи достаточно) и поднимайте алерт, если запрос вернул хоть одну строку:

-- 1. Every account: cached balance must equal the sum of its postings.
SELECT a.id, a.code, a.balance, COALESCE(SUM(p.amount), 0) AS computed
FROM ledger_account a
LEFT JOIN ledger_posting p ON p.account_id = a.id
GROUP BY a.id
HAVING a.balance <> COALESCE(SUM(p.amount), 0);

-- 2. The whole ledger, per currency, must sum to zero.
SELECT a.currency, SUM(p.amount) AS total
FROM ledger_posting p
JOIN ledger_account a ON a.id = p.account_id
GROUP BY a.currency
HAVING SUM(p.amount) <> 0;

Подводные камни в продакшене

  • Отложенные триггеры и тесты. TestCase в Django оборачивает каждый тест в транзакцию, которая никогда не коммитится, поэтому отложенная проверка не срабатывает там, где вы её ждёте. Форсируйте её через SET CONSTRAINTS ALL IMMEDIATE — он проверяет накопленные события задним числом:
# ledger/tests.py
from django.db import IntegrityError, connection, transaction
from django.test import TestCase

from ledger.models import Account, JournalEntry, Posting


class LedgerInvariantTests(TestCase):
    def test_unbalanced_entry_is_rejected_by_db(self):
        a = Account.objects.create(code="asset:psp", kind="asset")
        b = Account.objects.create(code="wallet:user:1", kind="liability")
        with self.assertRaises(IntegrityError):
            with transaction.atomic():
                entry = JournalEntry.objects.create(description="bad", idempotency_key="t1")
                Posting.objects.create(entry=entry, account=a, amount=100)
                Posting.objects.create(entry=entry, account=b, amount=-90)
                # TestCase never commits, so force the deferred check right here.
                with connection.cursor() as cur:
                    cur.execute("SET CONSTRAINTS ALL IMMEDIATE")
  • Внешние транзакции. Если post_entry вызывается внутри большого блока atomic(), триггер сработает на внешнем коммите, и IntegrityError вылезет там, далеко от причины. Держите записи в леджер в коротких транзакциях.
  • Триггер на TRUNCATE и очистка тестовой базы. TransactionTestCase и manage.py flush очищают таблицы через TRUNCATE, поэтому триггер падает с «ledger_posting is append-only». Либо держите тесты леджера на TestCase, либо уберите именно этот триггер и полагайтесь на REVOKE TRUNCATE для продакшен-роли.
  • Горячие счета. Каждый платёж кредитует revenue:fees. Если блокировать его через select_for_update(), все платежи выстроятся в очередь на одну строку. Счетам, которые могут уходить в минус или не требуют проверки овердрафта (доходы, PSP clearing), не нужны ни блокировка, ни кэшированный баланс: вставляйте строки, а баланс считайте по строкам и снапшотам.
  • Время — не порядок коммитов. created_at выставляется до коммита (в Python через auto_now_add, а now() в PostgreSQL — это время начала транзакции). Транзакция, начавшаяся в 23:59:59 и закоммиченная в 00:00:01, попадёт во «вчера», когда вчерашний снапшот, возможно, уже посчитан. Запускайте снапшот с запасом по времени и держите транзакции короткими. По той же причине никогда не используйте «id последней строки» как водяной знак снапшота: значения sequence выдаются при вставке, а не при коммите.
  • Сторно может уйти в овердрафт. Сторно пополнения после того, как пользователь потратил деньги, упадёт с InsufficientFunds. Это правильное поведение, но нужен бизнес-ответ: счёт дебиторки для долга пользователя или ручной процесс.
  • Админка. Стандартный ModelAdmin для Posting предлагает кнопки редактирования и удаления. Регистрируйте его только для чтения (has_change_permission и has_delete_permission возвращают False), даже если триггер всё равно откажет.
  • Один счёт — одна валюта. Конвертация — это две проводки через FX-счёт, а не одна проводка со смешанными валютами.

Чеклист

  • Деньги — целые числа в минимальных единицах (BigIntegerField, тийины), никогда не float.
  • Каждое движение — проводка с ≥ 2 строками, сумма которых по каждой валюте равна нулю.
  • Отложенный constraint trigger проверяет сумму на коммите.
  • Строки и проводки только добавляются: триггеры плюс отозванные права.
  • Ошибки исправляются сторно, никогда не UPDATE.
  • Счета блокируются select_for_update() по возрастанию id.
  • У каждой проводки уникальный ключ идемпотентности.
  • Кэшированные балансы регулярно сверяются со строками; при расхождении — алерт.
  • Снапшоты только для закрытых периодов и с запасом по времени.

Итог

Колонка balance говорит вам число; double-entry ledger говорит, почему число именно такое. Дизайн небольшой: счета, проводки, строки и один инвариант — каждая проводка в сумме даёт ноль, и следит за этим PostgreSQL, а не добрые намерения. Добавьте неизменяемость и сторно — и у каждого сума в системе появится прослеживаемое происхождение.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯