Шпаргалка · Бизнес-процессы
Деньги и округление
Проблема
Магазин продаёт за сумы и выставляет электронные счета-фактуры с НДС 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_fxMermaid: последовательность запросов
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 UZSD2
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
@endumlPlantUML: компоненты
@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) Форматируй по локали только в приложении.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Расхождение, тийин | 0 | 0 |
| Несходящиеся документы | 0/день | 0/день |
| Недоплата при возврате, тийин | 0 | 0 |
Шаги
- Кейс Заказ с ценами в виде обычных чисел
Checkout отправляет заказ: три пачки чая по 19 990.10 сума.
- Проблема Правильная оплата не совпадает с итогом
В двоичной плавающей точке 19 990.10 хранится как ближайшая двоичная дробь, а она чуть отличается.
- Решение Храни целые числа в минимальных единицах
Теперь каждая сумма — целое число минимальных единиц плюс валюта: 1 999 010 тийинов UZS.
- Решение Режимы округления: что происходит ровно на половине
Целые числа не отменяют округления: комиссия 1.5% с 10 003.00 сума — это 15 004.5 тийина, а списать можно только целые тийины.
- Проблема НДС строк не сходится с итогом
В счёте-фактуре три строки.
- Решение Округляй один раз на строку и складывай сохранённое
Теперь правило такое: НДС округляется по каждой строке, half-up, в момент создания строки, и сохраняется.
- Проблема Три платежа, одного тийина не хватает
Клиент платит 100 000.00 сумов в рассрочку на 3 месяца.
- Решение Раздай остаток, начиная с наибольшего
Распределение (allocation) делит сумму по весам так, что части всегда дают целое.
- Проблема Возврат по сегодняшнему курсу
Товар стоит 49.99 USD, а клиент платит в сумах.
- Решение Храни курс, его источник и время вместе с конвертацией
Теперь каждая конвертация — запись: исходная сумма, курс точной десятичной дробью, откуда и когда он взят, итоговая сумма и режим округления.
- Решение Форматируй только на краю, по локали
База, API и логи хранят минимальные единицы и валюту.
- Итоги Итог
Семь правил для денег.
Термины
- Ошибка плавающей точки
- Двоичный double не может точно хранить десятичные дроби вроде 0.1, поэтому 0.1 + 0.2 даёт 0.30000000000000004. Для денег берут целые числа или decimal.
- Режим округления
- Правило, куда уходит значение ровно на половине: half-up отправляет половину от нуля, half-even (банковское) к чётному соседу. Правило задаёт закон или договор.
- Метод наибольшего остатка
- Способ делить сумму на части: каждая часть получает долю, округлённую вниз, а оставшиеся тийины по одному уходят частям с наибольшими остатками. Части всегда дают целое.
- Сохранённый курс валюты
- Курс, записанный вместе с конвертацией, с источником, временем и режимом округления. Возврат и аудит используют эти числа, а не запрашивают курс заново.