Начните с одного URL, который возвращает неправильный набор, и одной записи, которая попала лишней или пропала. Сохраните параметры, пользователя и timezone, затем выведите не сырой SQL, а нормализованную модель фильтра: поле, оператор, типизированное значение и логическую группу. Она сразу показывает, потерялось условие или изменился смысл.
Самая частая ловушка — считать пустую строку тем же, что отсутствующий параметр. «Исполнитель не выбран» обычно означает не применять условие, а фильтр «без исполнителя» должен явно строить IS NULL. Если оба состояния приходят как assignee=, backend не может угадать намерение.
Одна контрольная запись проходит каждый слой
| Слой | Что сверить | Типичная потеря |
|---|---|---|
| URL и форма | Все активные controls и их значения | Unchecked checkbox или сброс select |
| DTO фильтра | Типы, enum и отсутствие поля | Пустая строка превращена в null |
| Query builder | Скобки, операторы и параметры | OR вышел за пределы группы |
| Data query | WHERE и 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 уникальных строк.
Тесты строятся вокруг границ
- Проверить отсутствие параметра, пустое значение и явный режим IS NULL.
- Сочетать поиск OR с tenant и status и не получить чужие строки.
- Проверить начало и конец календарного дня в выбранной timezone.
- Создать записи с одинаковым created_at и пройти две страницы без дублей.
- Сравнить количество уникальных ID списка и count query.
- Обновить одну запись между страницами и проверить выбранную стратегию пагинации.
Для разбора нужны URL без чувствительного поиска, нормализованный filter DTO, ожидаемые ID на маленькой выборке, итоговые условия и ключ сортировки. Полная база не требуется: шесть специально подготовленных строк обычно воспроизводят ошибку точнее production-дампа.