ClickHouse analitik deposu ve Kafka ingest

ADR-0026. İkisi de isteğe bağlıdır: ayarlanmadığında sistem Postgres + BullMQ ile eskisi gibi çalışır.

docs/adr/0026-olcek-mimarisi.md. İkisi de isteğe bağlıdır: ayarlanmadığında sistem Postgres + BullMQ ile eskisi gibi çalışır.

ClickHouse'a geçiş

Sunucu: yönetilen ClickHouse (Cloud, Altinity) veya kendi kümeniz; HTTP(S) arayüzü açık olmalı. Yerelde npm run infra:install + npm run infra:up (26.8 LTS, http://127.0.0.1:8123).
Ayarlar (API ve worker): CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD (gizli), CLICKHOUSE_DATABASE.
Şema: npm run ch:migrate (TTL'ler RETENTION_*_DAYS değerlerinden). Geri alma: npm run ch:migrate:down --workspace @pushizo/db.
Outbox'ı aç: npm run ch:outbox:enable. Bu andan itibaren deliveries, delivery_events, events, conversions değişiklikleri analytics_outbox'a yazılır; worker analytics-sync işi (5 sn) ClickHouse'a aktarır.
Geçmiş veri: npm run ch:backfill --workspace @pushizo/db -- --from=2026-07-01 (saklama süresi kadar geriye). Gün gün outbox'a ekler ve aktarır; tekrar çalıştırmak güvenlidir (ReplacingMergeTree sürümü).
Karşılaştırma: ANALYTICS_STORE=dual — raporlar iki depodan okunur, Postgres sonucu döner; fark %0,5'i aşarsa analytics_store_mismatch_total{method,reason} artar ve uyarı loglanır. En az bir hafta sıfır fark beklenir.
Geçiş: org bazında analytics.clickhouse feature flag'i (admin → Feature flag'ler) veya tümü için ANALYTICS_STORE=clickhouse. Geri dönüş: ANALYTICS_STORE=postgres (anında; veri Postgres'te de durur).

Sinyal	Eşik / anlam
`select count(*), min(enqueued_at) from analytics_outbox`	Birikim; en eski satır > 30 sn ise aktarım geride (plan kabulü: p95 < 30 sn)
Worker logu `analytics-sync` hataları	ClickHouse erişimi/parolası; satırlar outbox'ta bekler, kayıp yok
`analytics_store_mismatch_total`	`dual` modunda sıfır olmalı
ClickHouse `system.mutations`	Silme (KVKK, saklama) mutasyonlarının tamamlanması

Kullanıcı/app silme, kuruluş saklama süresi ve olay tanımı saklaması Postgres'te DELETE ile yapılır; tetikleyici satırı outbox'a yazar, aktarım kaynakta bulamadığı satırı ClickHouse'tan da siler (lightweight DELETE).
Genel saklama süresi Postgres'te bölüm düşürülerek uygulanır (tetikleyici çalışmaz): bakım işi aynı kesimi ClickHouse'ta da uygular; tablolar ayrıca aynı değerde TTL taşır. Dönüşümler TTL'sizdir (gelir raporu; kullanıcı bağı anonimleştirilir).

Küme: yönetilen Kafka (MSK, Confluent, Aiven) veya yerelde npm run infra:install -- --kafka + npm run infra:up (Kafka 4.0 KRaft, 127.0.0.1:9092).
Ayarlar: INGEST_BUS=kafka, KAFKA_BROKERS, gerekiyorsa KAFKA_SSL=true, KAFKA_SASL_MECHANISM, KAFKA_USERNAME, KAFKA_PASSWORD (gizli). Konu (KAFKA_EVENTS_TOPIC, varsayılan events.raw) yoksa KAFKA_EVENTS_PARTITIONS bölümle oluşturulur; anahtar app_id (app içi sıra korunur).
Davranış: API olayları konuya yazar ve 202 döner; events kuyruğunu işleyen worker grubu tüketir, Postgres'e on conflict do nothing ile ekler, yeni olaylar için işleme işi ve canlı akış yayını yapar. Ofset Postgres yazımı başarılı olunca işlenir (en az bir kez; tekrar teslim idempotent).
İzleme: ingest_events_total{result=inserted|invalid}, tüketici grubu gecikmesi (kafka-consumer-groups.sh --describe --group pushizo-events).
Geri dönüş: INGEST_BUS=bullmq ile API yeniden Postgres'e doğrudan yazar; konuda kalan mesajlar worker INGEST_BUS=kafka ile bir kez daha başlatılarak tüketilir (idempotent).