ADR-0007: ClickHouse Для Analytics

Статус

Accepted

Контекст

Админка и партнерский кабинет должны показывать статистику по игрокам, депозитам, выводам, ставкам, выигрышам, странам, устройствам, играм и партнерам за произвольные периоды. PostgreSQL не должен обслуживать тяжелые OLAP запросы.

Решение

Analytics Service потребляет события из Kafka и пишет raw/event facts в ClickHouse. Часто используемые метрики строятся через materialized views и агрегирующие таблицы. API динамически выбирает bucket size по длительности периода, чтобы не возвращать сотни тысяч точек на фронт.

ClickHouse используется только для OLAP: dashboards, user/partner statistics, anti-fraud analytics, funnels, cohorts, retention, агрегаты платежей, ставок, выигрышей, бонусов и турниров. Operational decisions не читают ClickHouse как source of truth; для денег, KYC, бонусной выдачи, блокировок и платежей source of truth остается в owning PostgreSQL service.

Каждая ClickHouse таблица документируется как typed model с колонками, типами ClickHouse, source event mapping, partition/order keys, TTL, retention, PII classification и rebuild strategy. Сырые Kafka факты пишутся batch consumers, а online API использует materialized views или агрегирующие таблицы.

Последствия

• Analytics consumers должны быть идемпотентны по eventId и уметь replay без дублей в витринах.
• События producer services должны содержать достаточные typed snapshots, чтобы analytics не делала синхронные запросы к owning services.
• Anti-fraud может использовать аналитические признаки из ClickHouse как вспомогательный сигнал, но blocking decisions должны иметь fallback на operational data или fail-closed policy.
• Миграции ClickHouse tables/materialized views выполняются через migrator и описываются рядом с analytics service docs.