Начните с одного URL, который возвращает неправильный набор, и одной записи, которая попала лишней или пропала. Сохраните параметры, пользователя и timezone, затем выведите не сырой SQL, а нормализованную модель фильтра: поле, оператор, типизированное значение и логическую группу. Она сразу показывает, потерялось условие или изменился смысл.

Самая частая ловушка — считать пустую строку тем же, что отсутствующий параметр. «Исполнитель не выбран» обычно означает не применять условие, а фильтр «без исполнителя» должен явно строить IS NULL. Если оба состояния приходят как assignee=, backend не может угадать намерение.

Одна контрольная запись проходит каждый слой

СлойЧто сверитьТипичная потеря
URL и формаВсе активные controls и их значенияUnchecked checkbox или сброс select
DTO фильтраТипы, enum и отсутствие поляПустая строка превращена в null
Query builderСкобки, операторы и параметрыOR вышел за пределы группы
Data queryWHERE и tenant scopeФильтр применён после пагинации
Count queryТе же условия без LIMITСчётчик строится другим методом
UI resultСортировка и сохранённые параметрыПовторный рендер сбросил фильтр

Логика записывается со скобками до кода

WHERE tenant_id = :tenant
  AND status = :status
  AND created_at >= :from_utc
  AND created_at < :to_utc
  AND (title ILIKE :query OR external_id = :exact_id)
ORDER BY created_at DESC, id DESC
LIMIT :limit

Без скобок OR может вернуть запись другого tenant или статуса. Значения передаются параметрами, а разрешённые имена полей и направлений сортировки выбираются из allowlist: placeholder не предназначен для SQL-идентификатора. В debug показывайте имена параметров и безопасные типы, маскируя поисковый текст, если он содержит персональные данные.

NULL получает отдельный оператор

  • Не применять фильтр: поле условия отсутствует в DTO.
  • Искать незаполненное: column IS NULL, а при необходимости отдельно пустая строка.
  • Искать конкретное значение: column = :value после проверки типа.
  • Исключать значение: учесть, должны ли NULL оставаться в результате.
  • Мультивыбор без элементов: заранее решить, означает он «все» или «ничего».

SQL использует трёхзначную логику: сравнение с NULL не даёт обычного true. Поэтому конструкции column = NULL и column != value не выражают желаемый интерфейс автоматически. Составьте маленькую таблицу строк с value, empty и NULL и зафиксируйте ожидаемый результат каждого режима.

Диапазон даты переводится в полуинтервал

Пользователь выбирает календарные даты в своей зоне, backend превращает начало дня и начало следующего дня в UTC и использует created_at >= from и created_at < to. Условие до 23:59:59 теряет дробные секунды и ломается при другой точности. В интерфейсе покажите timezone, особенно если администраторы работают из разных регионов.

Пагинация требует полного порядка

ORDER BY created_at DESC недостаточен, если несколько строк имеют одинаковое время. Добавьте уникальный id как второй ключ. Документация PostgreSQL предупреждает: LIMIT и OFFSET без предсказуемого порядка могут возвращать разные подмножества. При активно меняющихся данных cursor pagination лучше сохраняет границу, но её тоже строят по полному ключу сортировки.

Count и список используют один predicate

Не копируйте условия вручную в два query builder. Сформируйте predicate один раз, примените его к выборке строк и COUNT, а joins добавляйте осознанно. Если join размножает основную запись, count(distinct id) и список должны следовать одной семантике, иначе интерфейс покажет 120 результатов и 87 уникальных строк.

Тесты строятся вокруг границ

  1. Проверить отсутствие параметра, пустое значение и явный режим IS NULL.
  2. Сочетать поиск OR с tenant и status и не получить чужие строки.
  3. Проверить начало и конец календарного дня в выбранной timezone.
  4. Создать записи с одинаковым created_at и пройти две страницы без дублей.
  5. Сравнить количество уникальных ID списка и count query.
  6. Обновить одну запись между страницами и проверить выбранную стратегию пагинации.

Для разбора нужны URL без чувствительного поиска, нормализованный filter DTO, ожидаемые ID на маленькой выборке, итоговые условия и ключ сортировки. Полная база не требуется: шесть специально подготовленных строк обычно воспроизводят ошибку точнее production-дампа.

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