Если цифрами документ показывает 1 251,04 ₽, а словами — «одна тысяча двести пятьдесят рублей», не исправляйте окончание вручную в шаблоне. Сначала сохраните исходное decimal-значение, код валюты, локаль, правило округления и уже разобранные major/minor части. Это быстро отделяет арифметическую ошибку от грамматической.
Строка прописью и форматированное число должны строиться из одного неизменяемого snapshot. Если таблица считает сумму заново после скидки, а текстовый блок использует старый total, обе функции могут быть корректны по отдельности и всё равно дать противоречивый документ.
Деньги разбираются как decimal, а не float
| Тест | Ожидаемое разбиение | Что ловит |
|---|---|---|
| 0.00 RUB | 0 major, 00 minor | пустую или пропущенную сумму |
| 1.01 RUB | 1 major, 01 minor | ведущий ноль дробной части |
| 2.05 RUB | 2 major, 05 minor | окончание и формат копеек |
| 11.11 RUB | 11 major, 11 minor | исключение для 11 |
| 21.20 RUB | 21 major, 20 minor | окончание после составного числа |
| -15.40 RUB | sign, 15 major, 40 minor | политику отрицательных документов |
Двоичный float способен представить простую десятичную сумму приближённо. Для денег используйте decimal тип либо целое количество минимальных единиц и выполняйте округление по явной политике. Не определяйте число знаков по длине введённой строки: scale берётся из выбранного каталога валют или конфигурации документа.
Целая и дробная части форматируются раздельно
Сначала нормализуйте сумму, затем получите major и minor без повторного округления. Словами преобразуется major; minor часто остаётся двумя цифрами, но конкретное оформление — правило вашего документа. Не зашивайте «копеек» в общий formatter: для другой валюты единица, грамматический род и scale могут отличаться.
amount_decimal = 1251.04
currency = RUB
locale = ru-RU
scale = currency_metadata.minor_scale
major = 1251
minor = 4
minor_display = 04
snapshot_id = invoice_total/v8Formatter возвращает структурированный результат: sign, major words, major unit form, minor display и minor unit form. Шаблон только размещает эти поля. Так одна и та же функция обслуживает PDF, HTML и печатную форму, а различия в оформлении не меняют арифметику.
Склонение зависит от locale и числа
Unicode CLDR описывает plural categories и правила отображения currency names; набор форм зависит от языка. ICU предоставляет RuleBasedNumberFormat для spellout, но это не отменяет проверку бизнес-терминов и юридического стиля. В русском особенно важны последние две цифры: 11 не следует правилу для 1, а 21 следует.
- Локаль задаётся явно и не наследуется случайно от ОС сервера.
- Код валюты хранится отдельно от символа и переведённого названия.
- Грамматический род числительного проверяется вместе с названием единицы.
- Знак минус оформляется по политике документа, а не теряется.
- Очень большие значения либо поддерживаются тестами, либо отклоняются с понятной ошибкой.
Библиотечный spellout может давать языково корректные слова, но не обязательно утверждённую формулировку конкретной организации. Для документов с правовыми последствиями согласуйте написание, регистр, союз между частями и представление minor units с ответственным специалистом.
Шаблон получает цифры и слова из одного snapshot
Рассчитайте subtotal, скидку, налог, округление и итог один раз. После фиксации snapshot передайте его числовому formatter и модулю spellout. В PDF сохраните технический version ID вне видимой суммы, чтобы можно было доказать, какой алгоритм сформировал документ.
Не вызывайте formatter заново в каждом шаблонном блоке и не передавайте локализованную строку обратно в арифметику. Строка «1 251,04» предназначена для показа, а не для парсинга. Источником истины остаётся typed decimal и currency code.
Граничная матрица ловит ошибки до печати
- Проверить ноль, единицу, 2–4, 5–20, 21–24 и 100+ для каждой локали.
- Добавить значения с 01, 05, 10 и максимальной minor частью.
- Проверить отрицательные корректировки и политику нулевого документа.
- Сравнить HTML, PDF и повторную печать одного snapshot.
- Зафиксировать golden cases, утверждённые владельцем документа.
Исправление принято, когда цифры и слова совпадают на одной версии данных, а тесты защищают валюту, локаль и границы. Для разбора приложите decimal до округления, currency code, locale, formatter version и обезличенный фрагмент результата. Полный договор и реквизиты контрагента обычно не нужны.