Background Job: PopularityRecomputeJob

Назначение

PopularityRecomputeJob — ночной фоновый расчёт контекста catalog, который пересчитывает сглаженную популярность PopularityScore (decimal(12,4)) карточек CatalogPropertyObjectCard и CatalogProjectCard по завершённым просмотрам за окно 30 дней с экспоненциальным затуханием. PopularityScore — единственный ключ сортировки «по популярности» (индексы ix_property_object_cards_popularity / ix_project_cards_popularity).

Почему нужна собственная таблица срезов

Вход — накопительный счётчик PopularityViews (long, только растёт), который инкрементирует консюмер user-activity-popularity по событию pin.user-activity.property-object-view-ended.v1 (объект недвижимости — по PropertyObjectId; проект — агрегируя по ProjectId). Из одного накопительного счётчика нельзя получить «просмотры за 30 дней» — нужна дневная гранулярность, поэтому job ведёт собственную таблицу дневных срезов накопителя (PopularityDailySnapshot, ниже) и берёт дневные инкременты как разности соседних срезов. Механизм — PostgreSQL-only, без Redis.

Поле	Значение
Owner	PIN Marketplace (Catalog squad)
Статус документа	draft
Область действия	таблицы catalog.property_object_cards / catalog.project_cards / catalog.popularity_daily_views
Assumptions / ограничения	популярность отстаёт от реального времени (лаг закрытия просмотра 10–15 мин + суточный цикл) — приемлемо для сортировки; целевой объём — сотни тысяч объектов недвижимости + тысячи проектных карточек, партиционирования нет
Зависимости	PostgreSQL (catalog: карточки, popularity_daily_views); вход PopularityViews пишет консюмер user-activity-popularity; событий не публикует

Классификация

Поле	Значение
Сервис	catalog
Тип job	Scheduled (ночной, один прогон в сутки)
Trigger	cron 0 3 * * * (UTC, ночной прогон — минимальный трафик витрины); следующий тик не стартует, пока идёт предыдущий прогон
Критичность	low (свежесть сортировки «по популярности» вне денежного пути; деградация лишь задерживает переранжирование)

Расписание и locking

Аспект	Правило
Schedule	раз в сутки, 0 3 * * * UTC; полный детерминированный пересчёт по данным окна (не инкрементальный)
Координация параллелизма	глобального распределённого lock нет (без Redis). Параллельные инстансы координируются построчной блокировкой батча (FOR UPDATE SKIP LOCKED) — каждый батч карточек достаётся одному инстансу. Опциональный строгий single-flight — PostgreSQL advisory-lock Pin:lock:job:scheduled:catalog-popularity-recompute (по построению не обязателен — батчи дизъюнктны)
Batch size	BatchSize карточек/батч (default 1000), keyset по Id; отдельный проход по объектам недвижимости, затем по проектам
Max duration	цель < 10 мин; предохранитель MaxRunDuration (default 30 мин) — при превышении прогон завершается штатно, остаток берёт следующий ночной цикл
Остановка	при остановке воркера текущий батч докоммичивается или откатывается целиком, блокировки освобождаются (graceful stop)

Входная модель PopularityRecomputeInput

Внешнего runtime-входа нет — параметры из конфигурации, проверяются при старте.

Поле	Тип	Обязательность	Источник	Описание
AsOfDate	DateOnly	Да	системное время на старте прогона	Дата прогона D — ключ дневного среза и правая граница окна.
WindowDays	int	Да	config (default 30)	Ширина окна W.
DecayHalfLifeDays	int	Да	config (default 7)	Период полураспада H веса: каждые H суток вклад просмотров падает вдвое.
BatchSize	int	Да	config (default 1000, > 0)	Верхняя граница карточек на батч/транзакцию.
TenantId	—	Нет	не применяется	Платформенная витрина: обработка вне tenant, сквозной скан всех карточек.

Модель хранения дневных срезов PopularityDailySnapshot

Вспомогательная служебная таблица catalog.popularity_daily_views — дом здесь (единственный писатель/читатель — этот job; доменным концептом не является). Хранит снимок накопителя PopularityViews на конец каждого прогона; дневной инкремент = разность соседних снимков.

Поле	Тип	Обязательность	Ограничения	Описание
Id	Guid	Да	PK	Идентификатор строки среза.
CardKind	PopularityCardKind	Да	хранится как text, varchar(16)	PropertyObject / Project — к какой проекции относится срез.
CardId	Guid	Да	логическая ссылка на property_object_cards.id / project_cards.id (без FK — две таблицы)	Карточка.
RunDate	DateOnly	Да	часть unique-ключа	Дата прогона D (ключ «job-дня»).
CumulativeViews	long	Да	>= 0	Снимок PopularityViews карточки на момент прогона.
CreatedAt	DateTimeOffset	Да	—	Момент записи среза.

Индексы: unique ix_popularity_daily_unique (card_kind, card_id, run_date) (один срез на карточку в сутки, идемпотентность прогона); чтение окна — ix_popularity_daily_window (card_kind, card_id, run_date desc). Retention: срезы старше D − (WindowDays + 2) удаляются в конце прогона — ≈ 32 строки/карточку.

Enum PopularityCardKind (хранится как text)

Значение	Описание
PropertyObject	Срез относится к CatalogPropertyObjectCard.
Project	Срез относится к CatalogProjectCard.

Формула сглаживания и затухания

• Период полураспада H = DecayHalfLifeDays → база затухания λ = 2^(−1/H) (при H = 7 → λ ≈ 0.9057).

• «Job-день k» — интервал между срезами прогонов k−1 и k; дневной инкремент Δ_k = max(0, S_k − S_{k−1}), где S_k = CumulativeViews среза (счётчик монотонен — PopularityViews только растёт; max(0, …) — guard от replay/переинициализации).

• Пусть r — текущий прогон (RunDate = D), Δ_r — только что закрытый job-день (вес λ^0 = 1). Тогда

  PopularityScore = round( Σ_{i=0}^{W−1} Δ_{r−i} · λ^i , 4 ) — decimal(12,4).

• Отсутствующий срез дня (карточка создана позже начала окна или пропущенный прогон) → Δ = 0; при пропуске ночи весь накопленный за простой прирост попадает в первый после простоя job-день (документированное упрощение, согласуется с «приемлемым отставанием»).

Пересчёт детерминирован по хранимым срезам → повтор прогона за ту же дату идемпотентен. Мини-пример (H = 7, λ ≈ 0.9057): три свежих job-дня Δ = [10, 0, 25] → 10·1 + 0·λ + 25·λ² = 30.5073.

Алгоритм

Каждый ночной прогон повторяет шаги 3–6 по батчам сначала для объектов недвижимости (property_object_cards), затем для проектов (project_cards).

1. Контекст и доступ. Актор — системный, обработка вне tenant (сквозной скан всех карточек); AsOfDate = системная дата на старте. Идемпотентность обеспечивается детерминированным пересчётом по срезам (см. Формула, шаг 4).
2. Проверка входа. Внешнего ввода нет; конфигурация проверена при старте (WindowDays > 0, DecayHalfLifeDays > 0, BatchSize > 0) — иначе воркер не стартует. Батч-скан сам отбирает карточки Status ∈ {Published, Hidden}; Delisted пропускаются.
3. Что читаем (под блокировкой). Keyset-пагинация по Id: батч карточек Status != Delisted под построчной блокировкой (FOR UPDATE SKIP LOCKED) — проекция (Id, PopularityViews, PopularityScore). Затем окно срезов: срезы этих карточек с RunDate >= AsOfDate − WindowDays (одним запросом, без N+1).
4. Расчёт. Для каждой карточки батча: записать срез дня (S_r = PopularityViews, ключ (CardKind, CardId, RunDate = AsOfDate)); по срезам окна вычислить дневные инкременты Δ_i и новый PopularityScore (Формула). Guard эффективности: если newScore == PopularityScore (типично для давно неактивных — оба 0), карточка не обновляется (не переписываем индекс популярности зря); срез всё равно пишется.
5. Что меняется. В одном согласованном изменении на батч: срезы дня (upsert по ключу (card_kind, card_id, run_date)) и PopularityScore/UpdatedAt изменившихся карточек (точечное обновление — популярность вне инвариантов карточки). Конкурентный доступ — оптимистическая блокировка: конфликт с консюмером-инкрементом ночью крайне маловероятен, при конфликте — повтор с перечиткой батча (шаг 6); построчные блокировки держатся до коммита батча. После двух проходов — удаление устаревших срезов (retention) отдельной транзакцией.
6. Результат. Сводка прогона (PropertyObjectCardsUpdated, ProjectCardsUpdated, SnapshotsWritten, SnapshotsPruned, ItemErrors, DurationMs) — для метрик/логов. Poison-строка исключается, логируется, остальной батч коммитится; инфраструктурный сбой — откат батча целиком, ретрай следующим ночным прогоном (пересчёт детерминирован).

Граница согласованности

Элемент	Правило
Единица изменения	на батч — срезы + обновление карточек в одном согласованном изменении; retention-удаление — отдельной транзакцией в конце
Сохраняемое состояние	popularity_daily_views (upsert срезов), property_object_cards/project_cards (PopularityScore, UpdatedAt изменившихся)
External calls	нет — целиком PostgreSQL; событий/Kafka job не порождает
Частичная ошибка	continue — poison-карточка исключается из батча и логируется, остальной батч коммитится; инфраструктурный сбой — откат батча, ретрай следующим ночным прогоном

Идемпотентность и retry

Сценарий	Правило
Повторный прогон за ту же дату	Срез дня upsert-ится по ключу (CardKind, CardId, RunDate); newScore — чистая функция от хранимых срезов окна → идентичный результат
Job restart	Checkpoint не нужен — пересчёт полный и детерминированный; повтор с любого места безопасен
Параллельные инстансы / партиции	построчная блокировка (FOR UPDATE SKIP LOCKED) разводит батчи по инстансам; одну карточку обновляет ровно один инстанс
Гонка с консюмером user-activity-popularity	Консюмер атомарно инкрементирует PopularityViews; job читает актуальное значение как S_r. Конфликт оптимистической блокировки на сохранении → повтор перечиткой батча (новое S_r лишь уточняет скор)
Пропущенная ночь	Следующий прогон видит разрыв дат в срезах: инкремент за простой атрибутируется первому job-дню после разрыва; окно самокорректируется за WindowDays
Poison item	Исключается из батча, ERROR-лог с CardKind/CardId; при систематике — алерт errors_total, разбор по runbook

Наблюдаемость

Тип	Правило
Logs	run started (runId, AsOfDate, W, H); batch processed (CardKind, rows, updated); run completed (PropertyObjectCardsUpdated, ProjectCardsUpdated, SnapshotsWritten, SnapshotsPruned, DurationMs); item failed (CardKind, CardId, exception)
Metrics	catalog_popularity_recompute_duration_seconds (histogram); catalog_popularity_recompute_cards_total{card_kind} (counter); `catalog_popularity_recompute_snapshots_total{op=written
Traces	correlationId = jobRunId на span прогона; атрибуты card_kind, batch_size, updated_count на span батчей
Dashboard	Grafana catalog-overview (панель Background jobs — длительность, число карточек, ошибки пересчёта)
Alerts	нет успешного прогона > 26 ч; catalog_popularity_recompute_errors_total rate > 0 устойчиво; catalog_popularity_score_staleness_hours > 30

SLO цикла

Показатель	Цель	Обоснование
Свежесть популярности	PopularityScore отражает просмотры не старше ≈ (вчерашний job-день) + лаг закрытия просмотра 10–15 мин	суточный цикл + polling-закрытие property-object-view-ended; отставание приемлемо для сортировки
Длительность прогона	p95 < 10 мин при целевом объёме карточек	нижняя нагрузка ночью; при превышении — MaxRunDuration, добор следующей ночью
Идемпотентность	0 расхождений скора при повторе прогона/рестарте/N инстансах	детерминированная формула по хранимым срезам + FOR UPDATE SKIP LOCKED
Полнота	все Published/Hidden-карточки получают актуальный (в т.ч. затухший до 0) скор за прогон; Delisted исключены осознанно	полный проход обеих таблиц

Кросс-сервисный контракт и деградация источника

Направление	Контракт	Поведение при отсутствии/устаревании
Ожидает (вход)	Накопительный счётчик PopularityViews (монотонный, только растёт), который инкрементирует консюмер user-activity-popularity по pin.user-activity.property-object-view-ended.v1. Job читает снапшот счётчика как S_r под построчной блокировкой	Консюмер лагирует/остановлен → дневные инкременты Δ занижены (часть просмотров ещё не в счётчике); PopularityScore занижен, но валиден. После догона консюмера пропущенный прирост атрибутируется первому job-дню — окно самокорректируется за WindowDays. Job не ждёт и не падает
Предоставляет (выход)	Поле PopularityScore (decimal(12,4)) карточек — единственный ключ сортировки «по популярности» лент (синхронное чтение витрины: get-projects.md, get-property-objects.md); один из ключей дефолта «Рекомендованные» (ranking-rule.md). Интеграционных событий нет — потребление только внутри витрины	Между прогонами скор «застывший» (лаг ≤ суточный цикл + MaxRunDuration); лента отдаёт последний рассчитанный порядок. Пропущенная ночь → скор не обновлён сутки, ранжирование деградирует по свежести, не по корректности

Связанный runbook

Сценарий	Runbook
Прогон не отработал / рост errors_total	../runbooks/popularity-recompute.md (будущий путь по конвенции)
Расхождение скора (ручная сверка)	принудительный пересчёт карточек по id — POST /admin/projections/rebuild (README «Runbooks»)

Тесты

Тест	Ожидание
Empty (нет карточек/просмотров)	no-op success; срезы с нулевым накопителем не меняют скор (newScore == 0, обновление пропущено)
Экспоненциальное затухание	при Δ = [10,0,25], H=7 → PopularityScore = 30.5073 (decimal(12,4))
Затухание без новых просмотров	карточка без новых просмотров N ночей подряд: скор монотонно убывает по λ и достигает 0 за пределами окна
Идемпотентность / повтор прогона	повтор за ту же дату не меняет PopularityScore; срез upsert-ится (Δ=30 из соседних S=100,130 входит с весом λ^0), не дублируется
Партиции / параллельные инстансы	FOR UPDATE SKIP LOCKED — каждая карточка пересчитана один раз
Гонка с консюмером	инкремент PopularityViews во время прогона → либо учтён в S_r, либо конфликт блокировки → повтор без порчи данных
Retention / Delisted	срезы старше WindowDays + 2 удалены (окно прогона не затронуто); Delisted-карточка не пересчитывается
Остановка воркера	остановка в прогоне → текущий батч докоммичен/откачен целиком, блокировки сняты, graceful stop

Обратные ссылки

Автоссылки: где используется этот документ.

• Консюмеры (1): Consumer: User-Activity Popularity (pin-catalog-popularity)
• Фоновые задачи (1): Background Job: DelistedRetentionJob

Связанные документы

• Дом полей PopularityViews/PopularityScore и индексы: ../domain/catalog-property-object-card.md, ../domain/catalog-project-card.md; ленточное ранжирование — ../domain/ranking-rule.md, ../consumers/promotion-boost.md (PromotionBoost).
• Вход счётчика: ../consumers/user-activity-popularity.md; первичные просмотры: ../../user-activity/domain/property-object-view.md, ../../user-activity/domain/property-object-view-stats.md.
• Обзор/эксплуатация: ../README.md («Jobs», «Alerts», «Известные ограничения»); соседний job — delisted-retention.md.
• Решения: ADR-0056 (PostgreSQL-only, FOR UPDATE SKIP LOCKED, без Redis), ADR-0052 (обработка вне tenant), ADR-0057 (просмотры → user-activity).