Число «1 234,50» на экране и «1234.5» в CSV может обозначать одно значение. А одинаковая итоговая сумма может скрывать разные строки. Поэтому сравнение начинают с сырого результата: стабильных идентификаторов, чисел до округления и времени снимка. Внешний вид проверяют вторым этапом.

Особенно часто экспорт запускает отдельный endpoint или background job, который заново собирает фильтры. Один забытый статус, другая граница даты или права service account превращают его в другой отчёт, хотя кнопка находится рядом с таблицей.

Fingerprint превращает интерфейс и файл в один запрос

{
  "report": "payments",
  "filters": {"status": ["paid"], "from": "2026-09-01", "to": "2026-10-01"},
  "sort": [["paid_at", "asc"], ["id", "asc"]],
  "timezone": "Europe/Moscow",
  "locale": "ru-RU",
  "columns": ["id", "paid_at", "amount"],
  "policy_version": "reports-v7"
}

request_fingerprint = sha256(canonical_json)

В fingerprint не помещают токен и персональные значения. Он должен меняться, если меняется смысл отчёта: фильтр, сортировка, timezone, набор колонок или версия политики доступа. Экран передаёт этот идентификатор job экспорта, а файл получает его в техническом manifest или журнале.

Матрица симптомов быстро выбирает слой проверки

СимптомВероятный слойЧто сравнить
В файле больше строкФильтры/праваWHERE и policy version
Расходится граница дняTimezoneUTC-интервал для локальных дат
Строки те же, сумма инаяТип/округлениеMinor units и raw decimal
Дубли между страницамиСортировка/snapshotУникальный tie-breaker и ID
CSV «съехал» по колонкамСериализацияКавычки, запятые и переводы строк
В Excel дата или код изменилисьИмпорт приложениемИсходный CSV в текстовом редакторе

Не смешивайте эти проверки. Если набор ID не совпал, настройка разделителя CSV не исправит запрос. Если ID и сырые значения совпали, повторная оптимизация SQL только усложнит расследование — переходите к сериализации и тому, как файл открывает клиентское приложение.

Один снимок защищает многостраничный экспорт от дрейфа

В PostgreSQL READ COMMITTED получает новый snapshot для каждой команды. Пока job выгружает страницы, новые записи могут сдвинуть границу и дать пропуск или дубль. REPEATABLE READ сохраняет один снимок с первой команды, но длинная транзакция имеет операционную цену. Для тяжёлого экспорта часто безопаснее заранее материализовать список ID или immutable report run, а затем читать его частями.

  1. Добавить к бизнес-сортировке уникальный tie-breaker, обычно ID.
  2. Зафиксировать report_run_id, created_at и snapshot/watermark.
  3. Сохранить набор ID либо выполнить чтения в контролируемом согласованном снимке.
  4. Строить следующую страницу по последнему ключу, а не OFFSET.
  5. Сверить row count, first/last key и хеш отсортированных ID.
  6. Ограничить время жизни результата и явно показывать время данных пользователю.

Дата, деньги и проценты сравниваются до локализации

Intl.NumberFormat и Intl.DateTimeFormat форматируют значения с учётом locale и timezone. Это функция представления: она не должна менять сам amount или момент времени. Перед сравнением переведите даты в один UTC instant, деньги — в decimal либо minor units по правилам валюты, проценты — в исходное отношение. Округление применяйте в одном согласованном слое.

  • Локальная дата фильтра переводится в полуоткрытый UTC-интервал [from, to).
  • Timezone пользователя сохраняется рядом с report run.
  • Суммы сверяются до добавления пробелов, валютного знака и десятичной запятой.
  • Пустое значение, ноль и строка «—» не считаются одним состоянием.
  • Формулы процентов используют одинаковые числитель, знаменатель и точность.
  • Заголовок файла указывает locale/timezone, если это важно для чтения.

CSV обязан пережить запятые, кавычки и переносы строк

RFC 4180 описывает распространённый CSV-формат: поле с запятой, кавычкой или переводом строки заключают в двойные кавычки, а кавычку внутри удваивают. Не собирайте строку через join без CSV-библиотеки. Явно договоритесь о кодировке, разделителе, строке заголовков и формате дат.

id,comment,amount

42,"Доставка, второй подъезд",1234.50

43,"Он сказал ""готово""",0.00

44,"Две строки:

проверено",99.90

Проверьте исходный файл в текстовом редакторе и отдельным CSV-parser. Если Excel превращает длинный код в число или распознаёт дату иначе, это ещё не доказывает ошибку экспорта. Для идентификаторов с ведущими нулями и формулоподобного текста нужен заранее выбранный безопасный формат и защита от CSV injection.

Автотест сравнивает инварианты, а не скриншоты

Для одного report_run вычислите на сервере количество строк, сумму amount_minor, число уникальных ID, min/max времени и хеш списка ID в заданной сортировке. Те же инварианты получите из экспортированного файла. Затем выборочно сравните несколько raw rows, включая границу дня, NULL, запятую и многострочный текст.

Исправление считается завершённым, когда экран и экспорт показывают один report fingerprint и время снимка, ID и сырые агрегаты совпадают, CSV проходит parser, а различия locale объяснимы контрактом. Для разбора достаточно обезличенного manifest и синтетических строк — реальные финансовые или персональные данные в тикет прикладывать не нужно.

Проверенные источники