ADR-0057: Статистика просмотров для застройщиков — контекст dev-stats на ClickHouse (3 года)

Статус

Accepted

Дата

2026-07-13

Контекст

Застройщику нужны метрики внимания к его недвижимости: кто, сколько, как долго и как часто смотрит его проекты / здания / планировки / группы планировок / объекты — с графиками и фильтрацией: обязательно по дате и застройщику (самому себе), как минимум по проекту; опционально по зданию, планировке, группе планировок, конкретному объекту. Глубина хранения — 3 года.

PostgreSQL-модель user-activity (ADR-0054/0056) — операционная (открытые сессии/просмотры, закрытие polling-ом); для 3-летнего массива фактов просмотров с произвольными агрегациями она не подходит. ClickHouse уже легитимен в системе (история цен, ТЗ.md:203–208) и поддержан SDK (Talent.Common.Infrastructure.DataBase.ClickHouse, linq2db + мигратор).

Решение

1. Новый контекст dev-stats (аналитика застройщика): consumer событий user-activity → ClickHouse facts → API метрик/графиков для ЛК застройщика.
2. Поток данных: pin.user-activity.lot-view-ended.v1 (+session-ended для сессионных метрик) → консюмер dev-stats обогащает просмотр измерениями из chessboard (DeveloperId, ProjectId, BuildingId, LayoutGroupId, LayoutId, LotId — реплика-справочник измерений) и типом зрителя (гость/инвестор/агент/менеджер) → вставка facts батчами (append-only, идемпотентность по ViewId/SourceEventId).
3. Fact-таблица lot_view_facts (ReplacingMergeTree по dedup-ключу):
   • PARTITION BY toYYYYMM(ViewedAt);
   • ORDER BY (DeveloperId, ProjectId, BuildingId, LayoutGroupId, LayoutId, LotId, ViewedAt) — ключ сортировки повторяет иерархию фильтров (подсказка по индексам): обязательные фильтры (застройщик → проект) — префикс ключа, опциональные (здание → группа планировок → планировка → объект) — продолжение префикса; диапазон дат режется партициями + ViewedAt в конце ключа;
   • TTL ViewedAt + INTERVAL 3 YEAR (авто-очистка, требование «отслеживать 3 года»);
   • меры: DurationSeconds, ViewerUserId/AnonymousId, ViewerKind, SessionId, ViewedAt.
4. Агрегирующие materialized views (дневные rollup-ы по той же иерархии): views_count, unique_viewers (uniqCombined), total/avg duration, repeat_views — чтобы графики за месяцы/годы не сканировали сырые facts. FINAL в online-запросах запрещён (правило SDK).
5. API dev-stats (Query-методы, area developers): временные ряды и сводки с группировкой день/неделя/месяц; фильтры: DateRange (обяз.), DeveloperId = из scope застройщика (обяз., только свои данные), ProjectId (мин. уровень), опционально BuildingId/LayoutGroupId/LayoutId/LotId; метрики: количество просмотров, уникальные зрители, суммарная/средняя длительность, частота повторных просмотров, разбивка по типу зрителя.
6. Security: tenant-scope застройщика обязателен в каждом запросе (видит только себя); агрегаты не раскрывают персональные данные зрителей (ФИО/телефон недоступны — только типы/уникальные счётчики); доступ платформы (Менеджер ПИН/админ) — отдельные permissions.

Последствия

• user-activity остаётся простым PostgreSQL-контекстом (ADR-0056); аналитическая нагрузка уходит в dev-stats/ClickHouse — уточнение ADR-0056: ClickHouse = история цен (invest-analytics) и view-статистика застройщиков (dev-stats); других применений без ADR не добавлять.
• Нужна реплика измерений из chessboard (консюмер справочников) для обогащения facts.
• ТЗ контекста пишется в Батче 4 (после user-activity, события которого потребляет); UC-префикс STA.

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

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

• Домен (CQRS) (3): Классификация зрителя и источника (ViewerKind / ViewSource), Модели ответа dev-stats (типизированные ряды / точки / сводки), DevStatsFilterModel (общий вход метрик dev-stats)
• API (11): GET /api/developer/crm/statistics — Статистика ЛК застройщика, GET /api/internal/user-activity/users/{userId}/property-object-activity — Активность инвестора по объектам недвижимости (карточка лида CRM), GET /api/internal/user-activity/users/{userId}/property-objects/view-stats — Батч просмотров инвестора по объектам недвижимости (обогащение карточек CRM), GET /api/v1/dev-stats/activity-heatmap — Хитмап активности (час × день недели), GET /api/v1/dev-stats/bounce-signal — Сигнал отказа (короткие просмотры по объекту), GET /api/v1/dev-stats/duration/histogram — Гистограмма длительностей просмотра, GET /api/v1/dev-stats/repeat-frequency — Повторные просмотры и частота возврата на объект, GET /api/v1/dev-stats/session-depth — Глубина сессии (объектов за сессию), GET /api/v1/dev-stats/time-to-first-view — Время до первого просмотра (TTFV), GET /api/v1/dev-stats/viewers/unique — Уникальные зрители (гость/агент/инвестор), GET /api/v1/dev-stats/views/summary — Сводка просмотров (кто/сколько/как долго/как часто)
• Use Cases (5): UC-STA-001. Застройщик смотрит статистику проекта (период + проект), UC-STA-002. Детализация просмотров до здания / группы планировок / планировки, UC-STA-003. Сравнение периодов и тренд просмотров, UC-STA-004. Воронка конверсии «просмотр → сделка», UC-STA-005. Экспорт отчёта статистики (Excel / PDF) с аудитом
• События (1): События dev-stats
• Фоновые задачи (3): Background Job: DimensionBackfillJob, Background Job: FactsBackfillJob, Background Job: PopularityRecomputeJob
• Отчёты (1): Отчет/Export: dev-stats-export (выгрузка аналитики застройщика)
• Дашборды (3): Панель Метрик Застройщика: dev-stats-overview (аналитика внимания), Панель Наблюдаемости: support-overview (эксплуатация), Ops-борд: dev-stats-ingest-overview (здоровье ingestion)
• index.md (4): DevStats Service (Pin.DevStats), News Service (Pin.News), Support Service, user-activity Service

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

• docs/06-services/dev-stats/ (детальное ТЗ), ADR-0054/0056, docs/99-templates/clickhouse-fact-template.md, SDK: Talent.Common.Infrastructure.DataBase.ClickHouse (+Migrator).