Если запись есть по прямой ссылке, но поиск возвращает пусто, начните с точного ID без пробелов и снимите один диагностический trace: значение в поле, query string, нормализованный backend-параметр, активные фильтры, SQL и число строк до пагинации. Такой маршрут сразу отделяет ошибку интерфейса от ограничения доступа и собственно алгоритма поиска.
Не отключайте tenant или role filter ради проверки в production. Создайте тестовую запись или воспроизведите запрос под разрешённой ролью. Пустой результат часто оказывается корректным: пользователь ищет архивный заказ при включённом status=active либо запись принадлежит другой организации.
Пять слоёв могут превратить запись в ноль строк
| Слой | Контрольный признак | Типичная ошибка |
|---|---|---|
| UI | request содержит введённый текст | debounce отправил старое значение |
| нормализация | видны raw и normalized length | неразрывный пробел или Unicode form |
| scope доступа | tenant/role записаны отдельно | лишний фильтр или неверный actor |
| SQL | параметр и план соответствуют режиму | LIKE без wildcard или другое поле |
| пагинация | total и page считаются после фильтра | осталась страница 8 после нового query |
В лог пишут не персональное значение целиком, а request ID, режим поиска, длину, безопасный hash или маскированный фрагмент, применённые scopes и количество результатов. SQL с параметрами проверяют в тестовом окружении. Это даёт воспроизводимость без копирования телефонов, email и ФИО в общий debug-лог.
Точный идентификатор и имя — разные режимы
if query matches ORDER-ID format:
where order_id = :exact_id
else:
normalized = NFC(trim(query))
where tenant_id = :tenant
and unaccent(lower(customer_name)) ILIKE unaccent(lower(:pattern))
reset page to 1 whenever query or filters changeПсевдокод показывает разделение путей, а не готовую схему авторизации. Exact ID не должен обходить tenant scope. Пользовательские строки передают параметрами, не склеивают в SQL. Символы % и _ имеют специальное значение для LIKE, поэтому режим буквального поиска должен экранировать их согласно драйверу и запросу.
Unicode и пробелы проверяются до нестрогого поиска
- Сравнить количество code points до и после trim, не выводя чувствительный текст в лог.
- Привести вход и индексируемое значение к одной выбранной Unicode normalization form.
- Решить отдельно, нужно ли игнорировать регистр, диакритику, дефисы и раскладку клавиатуры.
- Не применять NFKC вслепую к полям, где типографические различия имеют смысл.
- Хранить исходное значение и отдельное нормализованное представление, если это требуется продуктом.
Unicode определяет NFC, NFD, NFKC и NFKD как разные формы с разными свойствами; compatibility-нормализация способна стирать значимые различия. В PostgreSQL доступны normalize/is normalized и nondeterministic collations, а расширение unaccent убирает диакритические знаки. Выбор фиксируют тестами на языках, которыми реально пользуется админка.
Индекс выбирают после определения поведения
B-tree подходит для точного значения и многих prefix-сценариев, но поиск %строка% требует другого плана. PostgreSQL pg_trgm даёт GiST/GIN operator classes для similarity и поддерживает индексный поиск для LIKE/ILIKE; короткий шаблон без извлекаемых триграмм может быть неэффективен. Проверьте EXPLAIN на реальном объёме и ограничьте длину и частоту запросов.
Fuzzy search не должен маскировать неверный scope. Сначала докажите, что точный ID и нормализованное имя возвращают ожидаемые строки, затем добавляйте опечатки и ranking. Иначе похожая запись из другого tenant станет утечкой, а не улучшением UX.
Регрессионная матрица закрывает крайние случаи
- Проверить точный ID, начало имени, фрагмент в середине и заведомо отсутствующее значение.
- Повторить тест с пробелами, разным регистром и канонически эквивалентными Unicode-строками.
- Сравнить владельца, соседний tenant, архивную запись и роль с ограниченными правами.
- Сбросить пагинацию и фильтры при изменении query и проверить total.
- Зафиксировать время ответа и план на выборке, близкой к production.
Для разбора подготовьте request ID, обезличенные raw/normalized признаки, активные фильтры, параметризованный SQL, EXPLAIN без чувствительных значений и ожидаемый scope роли. Этого достаточно, чтобы определить слой сбоя; полный дамп пользователей и production-токены к задаче прикладывать нельзя.