mufassall

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

Деньги и округление

13 мин · Средний · mufassall.dtwin.uz/ru/l/money-and-rounding/

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

Проблема

Магазин продаёт за сумы и выставляет электронные счета-фактуры с НДС 12%. Пока цены хранятся числами с плавающей точкой, оплата ровно на нужную сумму не проходит проверку на равенство. Суммы становятся целыми числами в минимальных единицах вместе с валютой, и тут начинаются настоящие вопросы: какое правило округления, где округлять (по строке или по документу), как разделить сумму, не потеряв ни тийина, как конвертировать по курсу, который можно доказать и через неделю, и почему форматирование живёт только на самом краю.

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

  • Почему двоичная плавающая точка не может точно хранить 0.1 или 19 990.10 и как это решают целые минимальные единицы с валютой (валюты с 0, 2 и 3 знаками после запятой)
  • Режимы округления: half-up, half-even (банковское) и несимметричный Math.round, и почему правило — бизнес-решение, записанное один раз
  • Округление по строке или по документу: разница НДС в 1 тийин и правило «итоги — это суммы строк в том виде, как они напечатаны»
  • Деление суммы методом наибольшего остатка, конвертация валют с сохранённым курсом и временем и форматирование по локали на краю
Итоговая сцена

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

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

Mermaid: схема

flowchart LR
  n_app(["Checkout"])
  n_api["Сервис заказов"]
  n_db[("База заказов")]
  n_tax>"Система ЭСФ"]
  n_fx>"Источник курсов"]
  n_app -->|"вызов"| n_api
  n_api --> n_db
  n_api -->|"асинхронно"| n_tax
  n_api -->|"вызов"| n_fx

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

sequenceDiagram
  participant n_app as Checkout
  participant n_api as Сервис заказов
  participant n_db as База заказов
  participant n_tax as Система ЭСФ
  participant n_fx as Источник курсов
  Note over n_app,n_api: Заказ с ценами в виде обычных чисел
  n_app->>n_api: POST /v1/orders HTTP/1.1
  n_api-->>n_app: HTTP/1.1 201 Created
  Note over n_app,n_api: Правильная оплата не совпадает с итогом
  n_app->>n_api: #62; 19990.1 * 3
  Note over n_app,n_api: Храни целые числа в минимальных единицах
  n_app->>n_api: POST /v1/orders HTTP/1.1
  n_api-->>n_app: currency exponent 1 unit =
  Note over n_api,n_db: Режимы округления: что происходит ровно на половине
  n_api->>n_db: 1.5% fee on 10 003.00 so'm = 15 004.5 tiyin
  Note over n_api,n_tax: НДС строк не сходится с итогом
  n_api->>n_tax: invoice INV-2026-11-04417 VAT 12%
  n_tax-->>n_api: rejected: total VAT 10 660.71 != sum of line VAT 10 660.72
  Note over n_api,n_tax: Округляй один раз на строку и складывай сохранённое
  n_api->>n_tax: POST /v1/invoices INV-2026-11-04417
  n_tax-->>n_api: accepted INV-2026-11-04417
  Note over n_api,n_db: Три платежа, одного тийина не хватает
  n_api->>n_db: installments: 100 000.00 so'm in 3 months = 10 000 000 tiyin / 3
  Note over n_api,n_db: Раздай остаток, начиная с наибольшего
  n_api->>n_db: allocate a 5 000.00 so'm discount (500 000 tiyin) by line net
  Note over n_api,n_fx: Возврат по сегодняшнему курсу
  n_api->>n_fx: order o_8120 49.99 USD, paid in UZS on 2026-11-09
  Note over n_api,n_db: Храни курс, его источник и время вместе с конвертацией
  n_api->>n_db: INSERT INTO conversions (order o_8120)
  n_db-->>n_api: 4999 x 1268743 / 100 = 63 424 462.57 -#62; 63 424 463 tiyin
  Note over n_app,n_api: Форматируй только на краю, по локали
  n_app->>n_api: stored: minor 63424463, currency UZS

D2

direction: right

n_app: "Checkout" {
  shape: rectangle
}
n_api: "Сервис заказов" {
  shape: rectangle
}
n_db: "База заказов" {
  shape: cylinder
}
n_tax: "Система ЭСФ" {
  shape: cloud
}
n_fx: "Источник курсов" {
  shape: cloud
}

n_app -> n_api: "вызов"
n_api -> n_db
n_api -> n_tax: "асинхронно"
n_api -> n_fx: "вызов"

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

@startuml
participant "Checkout" as n_app
participant "Сервис заказов" as n_api
database "База заказов" as n_db
boundary "Система ЭСФ" as n_tax
boundary "Источник курсов" as n_fx
note over n_app, n_api : Заказ с ценами в виде обычных чисел
n_app -> n_api : POST /v1/orders HTTP/1.1
n_api --> n_app : HTTP/1.1 201 Created
note over n_app, n_api : Правильная оплата не совпадает с итогом
n_app -> n_api : > 19990.1 * 3
note over n_app, n_api : Храни целые числа в минимальных единицах
n_app -> n_api : POST /v1/orders HTTP/1.1
n_api --> n_app : currency exponent 1 unit =
note over n_api, n_db : Режимы округления: что происходит ровно на половине
n_api -> n_db : 1.5% fee on 10 003.00 so'm = 15 004.5 tiyin
note over n_api, n_tax : НДС строк не сходится с итогом
n_api ->> n_tax : invoice INV-2026-11-04417 VAT 12%
n_tax -->> n_api : rejected: total VAT 10 660.71 != sum of line VAT 10 660.72
note over n_api, n_tax : Округляй один раз на строку и складывай сохранённое
n_api ->> n_tax : POST /v1/invoices INV-2026-11-04417
n_tax -->> n_api : accepted INV-2026-11-04417
note over n_api, n_db : Три платежа, одного тийина не хватает
n_api -> n_db : installments: 100 000.00 so'm in 3 months = 10 000 000 tiyin / 3
note over n_api, n_db : Раздай остаток, начиная с наибольшего
n_api -> n_db : allocate a 5 000.00 so'm discount (500 000 tiyin) by line net
note over n_api, n_fx : Возврат по сегодняшнему курсу
n_api -> n_fx : order o_8120 49.99 USD, paid in UZS on 2026-11-09
note over n_api, n_db : Храни курс, его источник и время вместе с конвертацией
n_api -> n_db : INSERT INTO conversions (order o_8120)
n_db --> n_api : 4999 x 1268743 / 100 = 63 424 462.57 -> 63 424 463 tiyin
note over n_app, n_api : Форматируй только на краю, по локали
n_app -> n_api : stored: minor 63424463, currency UZS
@enduml

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

@startuml
left to right direction
agent "Checkout" as n_app
component "Сервис заказов" as n_api
database "База заказов" as n_db
cloud "Система ЭСФ" as n_tax
cloud "Источник курсов" as n_fx
n_app --> n_api : вызов
n_api --> n_db
n_api --> n_tax : асинхронно
n_api --> n_fx : вызов
@enduml

Итог

Семь правил для денег.

1) Никаких float: целые числа в минимальных единицах, всегда с валютой. 2) Число знаков берётся из таблицы валют: 0, 2 или 3. 3) Режим округления выбирай по правилу и используй одну функцию с явным режимом. 4) Округляй в одном определённом месте, храни округлённые суммы, а итоги считай как суммы сохранённого. 5) Дели распределением, чтобы части всегда давали целое. 6) Храни каждую конвертацию с курсом, источником и временем и используй её при возврате. 7) Форматируй по локали только в приложении.

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

ПоказательВ началеВ конце
Расхождение, тийин00
Несходящиеся документы0/день0/день
Недоплата при возврате, тийин00

Шаги

  1. Кейс Заказ с ценами в виде обычных чисел

    Checkout отправляет заказ: три пачки чая по 19 990.10 сума.

  2. Проблема Правильная оплата не совпадает с итогом

    В двоичной плавающей точке 19 990.10 хранится как ближайшая двоичная дробь, а она чуть отличается.

  3. Решение Храни целые числа в минимальных единицах

    Теперь каждая сумма — целое число минимальных единиц плюс валюта: 1 999 010 тийинов UZS.

  4. Решение Режимы округления: что происходит ровно на половине

    Целые числа не отменяют округления: комиссия 1.5% с 10 003.00 сума — это 15 004.5 тийина, а списать можно только целые тийины.

  5. Проблема НДС строк не сходится с итогом

    В счёте-фактуре три строки.

  6. Решение Округляй один раз на строку и складывай сохранённое

    Теперь правило такое: НДС округляется по каждой строке, half-up, в момент создания строки, и сохраняется.

  7. Проблема Три платежа, одного тийина не хватает

    Клиент платит 100 000.00 сумов в рассрочку на 3 месяца.

  8. Решение Раздай остаток, начиная с наибольшего

    Распределение (allocation) делит сумму по весам так, что части всегда дают целое.

  9. Проблема Возврат по сегодняшнему курсу

    Товар стоит 49.99 USD, а клиент платит в сумах.

  10. Решение Храни курс, его источник и время вместе с конвертацией

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

  11. Решение Форматируй только на краю, по локали

    База, API и логи хранят минимальные единицы и валюту.

  12. Итоги Итог

    Семь правил для денег.

Термины

Ошибка плавающей точки
Двоичный double не может точно хранить десятичные дроби вроде 0.1, поэтому 0.1 + 0.2 даёт 0.30000000000000004. Для денег берут целые числа или decimal.
Режим округления
Правило, куда уходит значение ровно на половине: half-up отправляет половину от нуля, half-even (банковское) к чётному соседу. Правило задаёт закон или договор.
Метод наибольшего остатка
Способ делить сумму на части: каждая часть получает долю, округлённую вниз, а оставшиеся тийины по одному уходят частям с наибольшими остатками. Части всегда дают целое.
Сохранённый курс валюты
Курс, записанный вместе с конвертацией, с источником, временем и режимом округления. Возврат и аудит используют эти числа, а не запрашивают курс заново.