ИНЖЕНЕРНЫЙ ПРАКТИКУМP0L4

Сквозной кейс: финансовый журнал и поздняя корректировка

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

4 мин чтения·Проверенный учебный пример

Задача#

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

Все записи ниже синтетические. Стенд реализован на Python и SQLite, работает только с RUB в копейках и намеренно моделирует одно событие двумя строками: дебет и кредит. Это демонстрация контракта и проверок, а не бухгалтерская система или промышленный ETL.

Поток обработки#

JSON пакет
   │ проверка полей, дат, валюты и суммы
   ▼
source_events ── идемпотентность по event_id + SHA-256
   │
   ├── debit (+amount_minor)
   └── credit (−amount_minor)
             ▼
       journal_lines
          │       │
          │       └── сравнение ожидаемых и загруженных ID/payload
          └── обороты по счёту, business_date и observed_at

Контракт и зерно#

Набор	Зерно строки	Ключ и важные поля
`source_events`	Одно неизменяемое входное событие	`event_id`; документ, дебетовый и кредитовый счета, `amount_minor`, валюта, деловая дата, время известности и хеш payload
`journal_lines`	Одна сторона упрощённой двухстрочной записи события	`(event_id, side)`; счёт, сумма в копейках, валюта и временные поля события
Расчёт движения	Счёт за бизнес-период на заданный момент знания	Счёт + валюта + полуинтервал `business_date` + отсечка `observed_at`

business_date отвечает, к какому периоду относится событие. observed_at отвечает, когда система узнала о нём. Это разные оси времени; поздняя запись может относиться к январю и стать известной в феврале.

Синтетический пример#

Событие EVT-200 отражает расход 200,00 RUB 12 января. 3 февраля поступают сторно на 200,00 RUB и исправленная запись на 180,00 RUB. Исходное событие не обновляется и не удаляется.

Срез	Включённые события по расходному счёту	Чистое движение
Известно на 31 января	первоначальное событие `+20 000` копеек	200,00 RUB
Известно на 4 февраля	`+20 000 − 20 000 + 18 000` копеек	180,00 RUB

Это не личные расходы автора. Значения нужны только для воспроизводимой проверки временной логики.

SQL: движение с отсечкой знаний#

Запрос считает знаковое дебетовое движение по одной валюте. Полуинтервал дат включает начало и исключает конец; время сравнивается в каноническом UTC формате с Z.

SELECT account_code,
       currency,
       SUM(CASE WHEN side = 'debit' THEN amount_minor ELSE -amount_minor END) AS net_minor
FROM journal_lines
WHERE business_date >= '2026-01-01'
  AND business_date <  '2026-02-01'
  AND observed_at <= '2026-01-31T23:59:59Z'
GROUP BY account_code, currency
ORDER BY account_code, currency;

Чтобы получить пересчитанный январь, меняется только отсечка observed_at на 2026-02-04T23:59:59Z. В результате позднее сторно и замена попадут в тот же январский бизнес-срез.

Что именно сверяем#

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

reconcile_source_events() возвращает missing_ids, unexpected_ids и conflicting_payload_ids. Функция check_invariants() отдельно проверяет, что для каждого загруженного события есть ожидаемые строки журнала и совпадают счета, сумма и временные атрибуты. Эти проверки отвечают на разные вопросы и не подменяют друг друга.

Ошибки и ожидаемое поведение#

Сценарий	Ожидаемая реакция
Повтор того же события с прежним payload	Нет дубля; повторная загрузка идемпотентна
Тот же ID с изменённой суммой	Конфликт payload; весь пакет откатывается
Событие есть в эталонном пакете, но отсутствует в журнале источника	ID отражается как пропущенный
Загружен ID, которого нет в ожидаемом пакете	ID отражается как лишний
Исправленный payload под уже загруженным ID	ID отражается как конфликт содержимого
Сторно не равно исходной сумме или меняет счета	Контракт отвергается
Замена известна раньше сторно	Контракт отвергается; пакет откатывается
Удалена одна сторона проводки	`check_invariants()` находит нарушение числа строк, даже если другие суммы случайно взаимно компенсируются

Запуск и границы результата#

Из каталога sites/financial-dwh/lab/financial-edwh/ выполните:

python demo.py
python -m unittest discover -s tests -v

Тесты проверяют позднее исправление, идемпотентность, контроль полноты и payload, точность копеек, баланс строк, атомарный откат и негативные сценарии. Они выполняются на SQLite и не подтверждают совместимость или производительность PostgreSQL/Greenplum.

Стенд не моделирует многолинейные документы, несколько валют, курсовую переоценку, полноценную главную книгу, изоляцию параллельных загрузок или промышленную обработку CDC. PostgreSQL-версия будет отдельным следующим этапом с собственными интеграционными тестами.

Problem#

A package of financial events arrives. Preserve its source values, create journal lines, safely accept the same package again, detect missing records and payload changes, calculate account movements, and show how a late correction changes a closed business period.

All records below are synthetic. The Python and SQLite lab handles RUB in kopecks and deliberately models one event as two lines: debit and credit. This demonstrates a contract and its checks; it is not an accounting system or production ETL.

Processing flow#

JSON package
   │ validate fields, dates, currency, and amount
   ▼
source_events ── idempotency by event_id + SHA-256
   │
   ├── debit (+amount_minor)
   └── credit (−amount_minor)
             ▼
       journal_lines
          │       │
          │       └── compare expected and loaded IDs / payloads
          └── turnover by account, business_date, and observed_at

Contract and grain#

Dataset	Row grain	Key and important fields
`source_events`	One immutable input event	`event_id`; document, debit and credit accounts, `amount_minor`, currency, business date, knowledge time, payload hash
`journal_lines`	One side of a simplified two-line event entry	`(event_id, side)`; account, amount in kopecks, currency, and event times
Movement calculation	Account over a business period at a specified knowledge time	Account + currency + half-open `business_date` interval + `observed_at` cutoff

business_date says which period the event belongs to. observed_at says when the system learned about it. A late event can belong to January and become known in February.

Synthetic example#

Event EVT-200 records an expense of 200.00 RUB on January 12. On February 3, a 200.00 RUB reversal and a corrected entry of 180.00 RUB arrive. The original event is neither updated nor deleted.

Snapshot	Events included for the expense account	Net movement
Known on January 31	Original event `+20,000` kopecks	200.00 RUB
Known on February 4	`+20,000 − 20,000 + 18,000` kopecks	180.00 RUB

These are not the author's personal expenses. The values exist only to make the time logic reproducible.

SQL: movement at a knowledge-time cutoff#

The query calculates signed debit movement for one currency. The date interval includes its start and excludes its end; timestamps use canonical UTC strings ending in Z.

SELECT account_code,
       currency,
       SUM(CASE WHEN side = 'debit' THEN amount_minor ELSE -amount_minor END) AS net_minor
FROM journal_lines
WHERE business_date >= '2026-01-01'
  AND business_date <  '2026-02-01'
  AND observed_at <= '2026-01-31T23:59:59Z'
GROUP BY account_code, currency
ORDER BY account_code, currency;

To restate January, change only the observed_at cutoff to 2026-02-04T23:59:59Z. The late reversal and replacement then enter the same January business snapshot.

What reconciliation checks#

A zero debit-credit sum checks balance among loaded lines, but does not prove that every expected event arrived. The case therefore separately compares the expected package to source_events by ID set and canonical content hash.

reconcile_source_events() returns missing_ids, unexpected_ids, and conflicting_payload_ids. check_invariants() separately verifies that every loaded event has the expected journal lines, accounts, amount, and time attributes. These checks answer different questions and do not replace one another.

Errors and expected behavior#

Scenario	Expected response
Repeat the same event with the same payload	No duplicate; reload is idempotent
Same ID with a changed amount	Payload conflict; roll back the whole package
Event is in the expected package but missing from the source journal	Report its ID as missing
Loaded ID is absent from the expected package	Report its ID as unexpected
Changed payload under an already loaded ID	Report an ID content conflict
Reversal differs from the original amount or changes accounts	Reject the contract
Replacement is known before reversal	Reject the contract and roll back
One journal side is deleted	`check_invariants()` detects the wrong line count, even if other amounts happen to offset

Running the case and limits#

From sites/financial-dwh/lab/financial-edwh/, run:

python demo.py
python -m unittest discover -s tests -v

Tests cover late corrections, idempotency, completeness and payload controls, kopeck precision, line balance, atomic rollback, and negative cases. They run on SQLite and do not establish PostgreSQL/Greenplum compatibility or performance.

The lab does not model multi-line documents, multiple currencies, FX revaluation, a full general ledger, concurrent-load isolation, or production CDC. A PostgreSQL version would be a separate phase with its own integration tests.

Источники и документация

Источники нужны для самостоятельной проверки. Примеры и интерпретации на сайте могут быть учебными упрощениями.