Merge pull request #867 from modx-pro/mfilter

mFilter версия 1.2.0

Author: biz87

docs/components/mfilter/cache.md

@@ -47,6 +47,27 @@ return [
 
 Предзагружается при парсинге URL для минимизации запросов к БД.
 
+### 4. Кэш прогрева (БД)
+
+Хранится в таблице `mfl_cache`. Создаётся системой прогрева (warmup) заранее, до первого посещения пользователем.
+
+Кэшируются три типа данных:
+
+- **baseIds** — список ID товаров категории (результат `ElementRunner::getIds()`)
+- **filter values** — значения для построения формы фильтров
+- **suggestions** — фасетные счётчики (количество товаров для каждого значения)
+
+**Формат ключей:**
+```
+baseids_{resourceId}_{cacheKeyHash}
+filters_{resourceId}_{depth}
+suggestions_forids_{resourceId}_{filterHash}
+```
+
+Конфигурации прогрева хранятся в таблицах `mfl_warmup_configs` и `mfl_warmup_config_resources`.
+
+Подробнее: [Прогрев кэша](interface/warmup)
+
 ## Системные настройки
 
 | Настройка | Описание | По умолчанию |
@@ -105,33 +126,54 @@ $filter->clearCache(0);
 
 ### Ручная инвалидация при изменении товаров
 
-При массовом обновлении товаров рекомендуется очистить кэш:
+При массовом обновлении товаров кэш обновится автоматически рекуррентным таском `mfl_warmup`.
+
+Для немедленного обновления:
 
 ```php
-// После импорта товаров
 $mfilter = $modx->services->get('mfilter');
+
+// Очистить кэш
 $mfilter->clearCache();
+
+// Запустить прогрев (если Scheduler установлен)
+$mfilter->getWarmupManager()->schedule(true);
 ```
 
 ## Scheduler (фоновые задачи)
 
-При установленном Scheduler доступна задача перестройки кэша.
+При установленном Scheduler доступны две задачи:
+
+### mfl_rebuild_cache — перестройка кэша
 
-### Запуск задачи
+Очищает и заново строит кэш роутера и фильтров.
 
 ```php
 $mfilter = $modx->services->get('mfilter');
 $taskId = $mfilter->scheduleCacheRebuild();
 ```
 
-### Параметры задачи
-
 | Параметр | Описание | По умолчанию |
 |----------|----------|--------------|
 | `clear_first` | Очистить кэш перед перестройкой | `true` |
 | `rebuild_router` | Перестроить кэш роутера | `true` |
 | `rebuild_filters` | Перестроить кэш фильтров | `true` |
 
+### mfl_warmup — прогрев кэша
+
+Прогревает baseIds, значения фильтров и фасетные счётчики для всех активных конфигураций. Рекуррентный — запускается каждые 50 минут по умолчанию.
+
+```php
+$warmupManager = $mfilter->getWarmupManager();
+$runId = $warmupManager->schedule(true); // true = с прогревом счётчиков
+```
+
+| Параметр | Описание | По умолчанию |
+|----------|----------|--------------|
+| `warm_suggestions` | Прогревать фасетные счётчики и значения фильтров | `true` |
+
+Подробнее: [Прогрев кэша](interface/warmup)
+
 ## Отключение кэша
 
 ### Глобально
@@ -183,29 +225,29 @@ $files = glob($cachePath . '*');
 
 ### Для больших каталогов (10000+ товаров)
 
-- Используйте Scheduler для фоновой перестройки
-- Настройте cron-задачу на ночное время:
+- Настройте [прогрев кэша](interface/warmup) — создайте конфигурацию и привяжите страницы каталога
+- Рекуррентный таск `mfl_warmup` будет обновлять кэш автоматически
+- Подберите интервал прогрева и TTL под объём каталога и частоту обновлений
 
-```php
-// Задача Scheduler
-$mfilter->scheduleCacheRebuild();
+```
+# Пример для каталога 200k товаров (прогрев ~30 мин)
+mfilter.cache_lifetime = 7200    # TTL 2 часа
+# interval таска = 6000          # прогрев каждые 100 мин
 ```
 
 ### При частых обновлениях товаров
 
-Если товары обновляются часто (цены, наличие), уменьшите TTL:
+Рекуррентный прогрев автоматически обновит кэш. Максимальная задержка = интервал прогрева.
 
-```
-mfilter.cache_lifetime = 1800
-```
+Для немедленного обновления после импорта — запустите `mfl_warmup` вручную из админки.
 
 ### При редких обновлениях
 
-Увеличьте TTL для максимальной производительности:
+Увеличьте TTL и интервал прогрева:
 
 ```
 mfilter.cache_lifetime = 86400
-mfilter.cache_router_lifetime = 604800
+# interval таска = 43200  # прогрев 2 раза в сутки
 ```
 
 ## Структура таблицы mfl_cache

docs/components/mfilter/changelog/1.2.0.md

@@ -0,0 +1,175 @@
+# Версия 1.2.0: прогрев кэша фильтров
+
+Крупное обновление, добавляющее систему прогрева кэша для мгновенной загрузки страниц каталога с первого обращения.
+
+## Проблема
+
+MySQL 8 медленно выполняет запросы для больших каталогов. Первая загрузка страницы с фильтрами занимала от 15 до 60 секунд на каталогах свыше 10 000 товаров. Узкие места:
+
+- Получение списка ID товаров категории (`ElementRunner::getIds()`)
+- Вычисление доступных значений фильтров (`Filter::getFilters()`)
+- Подсчёт фасетных счётчиков (`Filter::getSuggestionsForIds()`)
+
+## Решение
+
+Система прогрева кэша заранее вычисляет и сохраняет все три тяжёлые операции в базу данных. Прогрев запускается в фоне через Scheduler или вручную из админки. После прогрева страницы каталога открываются за доли секунды.
+
+---
+
+## Новые возможности
+
+### Подсистема прогрева (warmup)
+
+Администратор создаёт конфигурацию прогрева в [новой вкладке админки](/components/mfilter/interface/warmup), указывая сниппет и страницы каталога. При прогреве система перебирает все привязанные страницы и кэширует:
+
+1. **baseIds** — список ID товаров категории
+2. **filter values** — значения для формы фильтров
+3. **suggestions** — количество товаров для каждого значения фильтра
+
+### Автосоздание конфигураций
+
+При первом посещении любой страницы каталога конфигурация прогрева создаётся автоматически. Не нужно настраивать каждую страницу вручную — достаточно один раз обойти каталог или дождаться посещения пользователями.
+
+### Парсер вызовов сниппетов
+
+Поле «Вызов сниппета» в редакторе конфигурации принимает код из шаблона и автоматически извлекает параметры. Поддерживаются три формата:
+
+```fenom
+{'!mFilter'|snippet:['element' => 'msProducts', 'parents' => $_modx->resource.id]}
+```
+
+```
+[[!mFilter? &element=`msProducts` &parents=`5`]]
+```
+
+```json
+{"element": "msProducts", "parents": 5}
+```
+
+### Таск Scheduler
+
+Новый таск `mfl_warmup` выполняет прогрев в фоне по крону. По умолчанию рекуррентный — запускается каждые 50 минут, обновляя кэш с запасом до истечения TTL.
+
+Из админки доступна кнопка **«Через Scheduler»** для запуска прогрева в фоне.
+
+### Вкладка «Прогрев кэша» в админке
+
+Новая вкладка в интерфейсе mFilter:
+
+- Таблица конфигураций с информацией о последнем прогреве
+- Редактор с парсингом вызовов, таблицей параметров и деревом ресурсов
+- Кнопки «Прогреть всё», «Через Scheduler», прогрев отдельной конфигурации
+- Чекбокс «+ счётчики» (включён по умолчанию)
+
+[Подробнее об интерфейсе →](/components/mfilter/interface/warmup)
+
+---
+
+## Новые модели БД
+
+| Таблица | Описание |
+|---------|----------|
+| `mfl_warmup_configs` | Конфигурации прогрева (element, params, cache_key_hash, статистика) |
+| `mfl_warmup_config_resources` | Привязка конфигураций к страницам каталога (many-to-many) |
+
+Таблицы создаются автоматически при установке или обновлении пакета.
+
+---
+
+## API
+
+10 новых эндпоинтов для управления конфигурациями:
+
+| Метод | Маршрут | Описание |
+|-------|---------|----------|
+| GET | `/warmup-configs` | Список конфигураций |
+| GET | `/warmup-configs/{id}` | Получить конфигурацию |
+| POST | `/warmup-configs` | Создать |
+| PUT | `/warmup-configs/{id}` | Обновить |
+| DELETE | `/warmup-configs/{id}` | Удалить |
+| POST | `/warmup-configs/{id}/warmup` | Прогреть одну конфигурацию |
+| POST | `/warmup-configs/warmup-all` | Прогреть все |
+| POST | `/warmup-configs/schedule` | Запланировать через Scheduler |
+| POST | `/warmup-configs/parse-snippet` | Распарсить вызов сниппета |
+| GET | `/warmup-configs/resource-tree` | Дерево ресурсов |
+
+---
+
+## Улучшения
+
+### Кэширование getSuggestionsForIds
+
+Метод `Filter::getSuggestionsForIds()` теперь сохраняет результаты в `mfl_cache`. При повторном обращении с теми же параметрами данные берутся из кэша.
+
+### UTC для временных меток кэша
+
+Все временные метки (`expires_at`, `created_at`, `updated_at`) в кэше теперь хранятся в UTC через `gmdate()`. Это устраняет проблему преждевременного протухания кэша на серверах, где cron работает в UTC, а web-процессы — в локальной таймзоне.
+
+### TvIndexer
+
+`TvIndexer::indexResource()` теперь индексирует только TV, используемые в конфигурации фильтров, вместо всех TV ресурса. Снижает нагрузку при индексации.
+
+### Удалён legacy warm_suggestions
+
+Удалён устаревший механизм прогрева suggestions через HTTP-запросы к страницам (`file_get_contents` с отключённой SSL-верификацией). Заменён прямым вызовом через `mfl_warmup`.
+
+---
+
+## Настройка под проект
+
+### Интервал прогрева и TTL
+
+| Размер каталога | TTL | Интервал прогрева | Описание |
+|-----------------|-----|-------------------|----------|
+| До 1 000 товаров | 3600 | 3000 | По умолчанию |
+| 1 000 — 10 000 | 7200 | 6000 | Каждые 100 мин |
+| 10 000 — 100 000 | 14400 | 10800 | Каждые 3 часа |
+| 100 000+ | 86400 | 43200 | 2 раза в сутки |
+
+- **TTL** — системная настройка `mfilter.cache_lifetime`
+- **Интервал** — поле `interval` таска `mfl_warmup` в Scheduler
+
+::: warning
+Интервал должен быть меньше TTL. Учитывайте время выполнения прогрева — для каталога в 200 000 товаров прогрев занимает ~30 минут.
+:::
+
+### При обновлении товарной базы
+
+| Сценарий | Действие |
+|----------|----------|
+| Регулярный импорт цен/остатков | Автоматически — рекуррентный таск обновит кэш |
+| Массовый импорт новых товаров | Запустить прогрев вручную из админки |
+| Изменение структуры фильтров | Очистить кэш + запустить прогрев |
+
+---
+
+## Обновление
+
+### Перед обновлением
+
+1. Сделайте резервную копию базы данных
+
+### После обновления
+
+1. Очистите кэш MODX
+2. Перейдите на вкладку «Прогрев кэша»
+3. Создайте конфигурацию или дождитесь автосоздания при посещении каталога
+4. Запустите прогрев через «Через Scheduler»
+5. Убедитесь, что cron настроен для Scheduler
+
+### Новые таблицы
+
+Таблицы `mfl_warmup_configs` и `mfl_warmup_config_resources` создаются автоматически при установке пакета.
+
+### Новый таск Scheduler
+
+Таск `mfl_warmup` регистрируется автоматически. Если Scheduler не установлен — прогрев доступен только из админки (кнопка «Прогреть всё»).
+
+## Результат
+
+После прогрева на каталоге в 200 000 товаров и 100 категориях:
+
+| Метрика | Без прогрева | С прогревом |
+|---------|-------------|-------------|
+| Первая загрузка страницы | 15–60 сек | < 1 сек |
+| Полный прогрев каталога | — | ~8–30 мин (в фоне) |

docs/components/mfilter/changelog/index.md

@@ -4,9 +4,16 @@
 
 | Версия | Дата | Описание |
 |--------|------|----------|
+| [1.2.0](1.2.0) | 2026 | Прогрев кэша фильтров (warmup) |
 | [1.1.0](1.1.0) | 2024 | Новые сниппеты, SEO улучшения, рефакторинг |
 | 1.0.0-beta1 | 2024 | Первый публичный релиз |
 
+## mFilter 1.2.0
+
+Подсистема прогрева кэша для мгновенной загрузки страниц каталога с первого обращения. Вкладка «Прогрев кэша» в админке, автосоздание конфигураций, рекуррентный таск Scheduler, фикс таймзон UTC.
+
+[Подробнее о версии 1.2.0 →](1.2.0)
+
 ## mFilter 1.1.0
 
 Крупное обновление с новыми возможностями:

docs/components/mfilter/development/models.md

@@ -14,6 +14,8 @@
 | `mfl_word_forms` | MflWordForm | Словоформы |
 | `mfl_page_configs` | MflPageConfig | Конфигурации страниц |
 | `mfl_cache` | MflCache | Кэш результатов |
+| `mfl_warmup_configs` | MflWarmupConfig | Конфигурации прогрева кэша |
+| `mfl_warmup_config_resources` | MflWarmupConfigResource | Привязки конфигураций к страницам |
 
 ## MflFilterSet
 

docs/components/mfilter/development/services.md

@@ -32,6 +32,9 @@ $urlRouter = $mfilter->getUrlRouter();
 | TemplateParser | `Services\Seo\TemplateParser` | Парсинг SEO-шаблонов |
 | WordFormsManager | `Services\Seo\WordFormsManager` | Управление словоформами |
 | ElementRunner | `Services\Element\ElementRunner` | Запуск element/paginator |
+| WarmupManager | `Services\Warmup\WarmupManager` | Управление прогревом кэша |
+| WarmupKeyBuilder | `Services\Warmup\WarmupKeyBuilder` | Построение ключей кэша |
+| SnippetCallParser | `Services\Warmup\SnippetCallParser` | Парсинг вызовов сниппетов |
 | Profiler | `Services\Profiler` | Профилирование запросов |
 
 ## Получение сервисов

docs/components/mfilter/interface/index.md

@@ -11,6 +11,7 @@
 | [Паттерны URL](patterns) | Правила распознавания URL |
 | [SEO шаблоны](seo-templates) | Шаблоны для генерации метаданных |
 | [Словоформы](word-forms) | Склонение слов для SEO-текстов |
+| [Прогрев кэша](warmup) | Управление прогревом кэша фильтров |
 | [Обслуживание](maintenance) | Переиндексация, очистка кэша |
 
 ## Общий вид