refactor(manager): expose direct filter keys from backend

[Ibochkarev]

Описание

Выносит список прямых ключей фильтров менеджерских гридов на backend и отдаёт его вместе с конфигом грида. Это убирает дублирование между Vue-гридами и PHP-контроллерами: frontend теперь решает, отправлять параметр как key или filter_key, на основе direct_filter_keys из /api/mgr/grid-config/{grid_key}.

Для заказов дополнительно переиспользуется общий обработчик direct-фильтров в списке и статистике, а stats-запрос подключает Address при адресных фильтрах, чтобы filter_customer, filter_email и filter_phone не ломали расчёт.

Тип изменений

• Исправление бага (non-breaking change)
• Новая функциональность (non-breaking change)
• Breaking change (изменение, ломающее обратную совместимость)
• Рефакторинг (без изменения функциональности)
• Документация
• Другое (опишите):

Связанные Issues

Closes #314

Как это было протестировано?

• Ручное тестирование
• Автоматические тесты (PHPStan, ESLint)
• Тестирование на разных версиях PHP/MODX

Конфигурация тестирования:

• MiniShop3: текущая ветка beta
• MODX: не запускался
• PHP: локальный CLI

Проверки:

• php -l core/components/minishop3/src/Controllers/Api/Manager/OrdersController.php
• php -l core/components/minishop3/src/Controllers/Api/Manager/CustomersController.php
• php -l core/components/minishop3/src/Controllers/Api/Manager/GridConfigController.php
• php -l core/components/minishop3/tests/DirectFilterKeysTest.php
• php core/components/minishop3/tests/DirectFilterKeysTest.php
• npx eslint src/components/OrdersGrid.vue src/components/CustomersGrid.vue
• git diff --check

Скриншоты (если применимо)

Не применимо: изменение контракта API и сериализации фильтров без визуальных изменений.

Чеклист

• Код соответствует стилю проекта
• Добавлены/обновлены комментарии в сложных местах
• Изменения не ломают существующую функциональность
• Лексиконы добавлены на двух языках (ru/en)
• PHPStan проходит без новых ошибок
• ESLint проходит без ошибок (для JS/Vue изменений)
• Обновлён CHANGELOG.md (для значимых изменений)

Дополнительные заметки

Новые комментарии и лексиконы не требуются: сложная пользовательская логика и новые UI-строки не добавлялись. CHANGELOG не обновлялся, так как в проектных правилах записи добавляются при подготовке релиза.

PHPStan не запускался; для PHP выполнены синтаксическая проверка и статический regression-тест без MODX-окружения.

[biz87]

Спасибо, что взялся за #314 — подход правильный. PHPStan на 3 контроллерах чист, тест DirectFilterKeysTest проходит. Прошёлся по диффу — есть два момента до мержа и один опциональный.

🟢 Что хорошо

• Single source of truth на backend — ровно та архитектура, что обсуждалась в refactor: consolidate DIRECT_FILTER_KEYS as single source of truth on backend #314. Frontend читает direct-список из /api/mgr/grid-config/{key}, locale-копии больше нет.
• DRY бонус в OrdersController — applyDirectFilters теперь общий для getList() и getOrdersStats(). Раньше там был дублирующийся inline-блок на ~24 строки. Чистый refactor.
• Bug fix мимоходом: address JOIN в getOrdersStats() при наличии filter_customer/email/phone. До этого PR такие фильтры в stats-query валились/возвращали 0.
• Provider-map в GridConfigController — расширяемо. Добавим новый грид с direct-фильтрами → одна строка в DIRECT_FILTER_KEY_PROVIDERS.
• DIRECT_FILTER_FIELD_MAP делает контракт param-key → DB-колонка явным (context_key → context).

🟡 До мержа

1. Inconsistent fallback в addFilterParam между гридами

В OrdersGrid.vue:

if (directFilterKeys.value.size === 0 || directFilterKeys.value.has(key)) {
    params[key] = value
    return
}
params[`filter_${key}`] = value

При пустом списке (старый backend / cached response) — всё как direct, без префикса.

В CustomersGrid.vue:

if (directFilterKeys.value.has(key)) {
    params[key] = value
    return
}
params[`filter_${key}`] = value

При пустом списке — всё как filter_, с префиксом.

Разное поведение в одинаковых сценариях. Предлагаю вариант CustomersGrid (filter-prefix по умолчанию) — безопаснее. Если backend по какой-то причине не прислал список — лучше попасть на пустой фильтр (видно в логах), чем тихо отправить всё как direct и получить непредсказуемый результат.

После мержа PR backend всегда отдаёт список, fallback не должен сработать. Но в момент апгрейда (новый frontend + старый/кэшированный backend) разное поведение даст разную регрессию.

2. Rebase на текущий beta — mergeStateStatus: DIRTY

OrdersController сегодня обновился через #303 (добавлены applyDraftVisibilityFilter, shouldShowDrafts, изменён start getList()). Конфликты в этом файле неизбежны, но концептуально правки не пересекаются — обе расширяют контроллер разными методами. Rebase должен резолвиться take-both.

🟡 Опционально

3. Комментарий рядом с query в DIRECT_FILTER_KEYS

query есть в DIRECT_FILTER_KEYS (чтобы фронт не префиксовал), но не в DIRECT_FILTER_FIELD_MAP — потому что обрабатывается отдельно (поиск по нескольким полям через OR:Address.phone:LIKE etc на строках ~160-177). Это функционально корректно, но создаёт когнитивный шум при чтении. Достаточно одной строки комментария: «query handled separately in getList(), not via applyDirectFilters».

Резюме

После rebase + унификации fallback — мержим без оговорок. Замечание про комментарий — на усмотрение.

[biz87]

Все три замечания закрыты:

• ✅ Rebase на текущий beta — CLEAN status, конфликты с fix(manager): переключатель черновиков и фильтры в списке заказов #303 разрешены.
• ✅ Унифицирован fallback — выделили composable useGridFilterParams.js. И OrdersGrid, и CustomersGrid используют один источник логики. Архитектура лучше моего предложения — я просил выровнять между гридами, автор вынес в общее место. DRY на будущее: новый грид с фильтрами просто useGridFilterParams(). Fallback при пустом списке — filter_ префикс (безопасный).
• ✅ Комментарий для query в DIRECT_FILTER_KEYS — // handled separately in getList(), not via applyDirectFilters.

Проверки:

• ✅ php tests/DirectFilterKeysTest.php — OK.
• ✅ PHPStan чист по 3 PHP-файлам.
• ✅ Лишний local DIRECT_FILTER_KEYS Set из обоих гридов удалён.

Закрывает issue #314 полностью + bonus DRY в OrdersController (общий applyDirectFilters для getList/getOrdersStats) + bug fix address JOIN в stats query.

Мержим.