Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
9e1c0c7
feat(analytics): analytics_event tablosu (V4)
Metecode Nov 17, 2026
b45546d
feat(analytics): olay doğrulayıcı ve props şeması
Metecode Nov 17, 2026
14167eb
feat(analytics): kurulum başına ve genel rate limit
Metecode Nov 17, 2026
d418afc
feat(analytics): POST /api/events ve ayrı güvenlik zinciri
Metecode Nov 17, 2026
cb2c7cd
feat(analytics): /api/events için CORS
Metecode Nov 17, 2026
43229d6
feat(analytics): 13 aydan eski olayları silen günlük iş
Metecode Nov 17, 2026
6be8ddb
docs(analytics): analiz sorguları
Metecode Nov 17, 2026
fa1348f
docs: kullanım ölçümü kararları, nginx adımı ve yol haritası
Metecode Nov 17, 2026
29c5dd0
docs(analytics): 04:00 gün sınırının gerekçesi, Faz 2 başlığı
Metecode Nov 17, 2026
f0f2f06
feat(analytics): olay şemaları ve kullanım metrikleri
Metecode Nov 17, 2026
0b0cc10
feat(analytics): olay kuyruğu ve gönderim kararı
Metecode Nov 17, 2026
641a3ab
feat(analytics): ölçüm istemcisi ve platform parçaları
Metecode Nov 17, 2026
77c3534
feat(analytics): app_open, spin, answer_submitted ve self_eval olayları
Metecode Nov 17, 2026
8a6dc5a
feat(analytics): kullanım istatistiği anahtarı ve ilk açılış kartı
Metecode Nov 17, 2026
bf942aa
feat(analytics): hesap silmede ölçüm kimliği ve kuyruğu da silinir
Metecode Nov 17, 2026
cecb7cd
docs(privacy): kullanım istatistikleri bölümü (TR ve EN)
Metecode Nov 17, 2026
2588727
docs: istemci tarafı ölçüm kararları ve yayın engelleri
Metecode Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .env.production
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Derleme zamanı, sır değil. Yalnızca native (Capacitor) derlemesi okur:
# kullanım ölçümü olaylarını bu köke gönderir. Web göreli /api kullanır.
# Tanımsız kalırsa native'de ölçüm sessizce kapalıdır.
VITE_API_BASE_URL=https://slot.meteucar.com
118 changes: 117 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,8 @@ shadcn/ui bileşenleri ihtiyaç oldukça tek tek eklenir, toplu kurulmaz.
- **İki filtre zinciri, iki oturum modeli.** `/oauth2/**` ve `/login/**`
zincirinde session var, çünkü OAuth state/PKCE iki istek arasında
saklanmak zorunda. Başarı anında success handler session'ı kapatır.
Diğer her şey STATELESS.
Diğer her şey STATELESS. Üçüncü zincir `/api/events`'in; JWT hiç
okumuyor (bkz. Kullanım ölçümü).
- **Geliştirmede tek origin.** Vite `/api`, `/oauth2`, `/login` yollarını
8080'e proxy'ler ve `changeOrigin: false` bırakır: Host başlığı
`localhost:5173` kalsın ki Spring GitHub'a gönderdiği `redirect_uri`'yi
Expand Down Expand Up @@ -459,6 +460,121 @@ shadcn/ui bileşenleri ihtiyaç oldukça tek tek eklenir, toplu kurulmaz.
içinde olsaydı sonucu gösteremeden kaybolurdu. Kapanınca odak
"Giriş yap"a taşınır.

## Kullanım ölçümü (`analytics/`)

- **YAYIN ENGELLERİ.** İstemci tarafı ancak hepsi tamamlanınca yayına çıkar:
- Gizlilik politikası (TR ve EN, `docs/gizlilik-politikasi.md` ve
`privacy/`): güncellendi, 2a bölümü.
- Play veri güvenliği formu: "Uygulama etkinliği → Uygulama
etkileşimleri" ve "Cihaz veya diğer kimlikler" toplanıyor; paylaşılmıyor,
aktarımda şifreli, kullanıcı kapatabiliyor.
- Host nginx'teki `/api/events` bloğu (`access_log off`) uygulanmadan
politika yayına alınmamalı; aksi halde "erişim kaydı tutulmaz" cümlesi
yanlış olur. Politika sayfası frontend imajıyla birlikte kurulduğu için
bu, dalın main'e birleşmesinden ÖNCE yapılır (`docs/deploy.md`).
Metinlerde "anonim" değil, "hesabınla ilişkilendirilmeyen, rastgele
kurulum kimliği" yazılır: kalıcı bir kimlik anonim değildir.
- **Hukuki dayanak: kapatma hakkı + meşru menfaat.** Bilinçli tercih:
varsayılan açık, Ayarlar'dan kapatılır. AB'den anlamlı kullanıcı gelirse
ilk açılış kartı açık rızaya çevrilecek.
- **Hesapla hiçbir bağ yok.** `analytics_event`'te `user_id`, IP ve
user-agent kolonu yok, `app_user`'a yabancı anahtar yok. Girişli web
kullanıcısının olayları da bağlanmaz: `/api/events` kendi güvenlik
zincirinde (`SecurityConfig.eventsFilterChain`) ve orada resource server
yok, Bearer başlığı okunmaz. Controller'a principal parametresi
eklenmez. Host nginx'te bu uçta `access_log off` ve X-Forwarded-For
iletilmez (`docs/deploy.md`); IP backend'e de ulaşmaz.
- **Sözleşme.** Zarfta `installId`, `platform` (web/android/ios),
`appVersion` (X.Y.Z); `events` 1–50 olay, her biri `eventId` (UUID),
`name`, `occurredAt`, `props`. 202 `{accepted, skipped}`; zarf bozuksa
400 `{"error":"invalid_batch"}`; sınır aşılırsa 429 + `Retry-After`,
hiçbir şey yazılmaz.
- **Olaylar ve props tek yerde:** `EventPropsSchema`. Ad listesi V4'teki
CHECK kısıtıyla aynı; olay eklenince yeni migration CHECK'i günceller.
İstemci aynı şemayı kullanıyor. Cevap METNİ hiçbir olayda yok, yalnızca
`answerLength`. `questionId` dar bir karakter kümesiyle sınırlı
(`[A-Za-z0-9._-]{1,128}`): serbest metin bu tabloya girmesin.
- **Bilinmeyen props alanı sessizce atılır,** olay kabul edilir. İlerleme
senkronundaki "denemede bilinmeyen alan → 400" kuralından bilerek farklı:
orada sözleşme ihlali kullanıcı verisini bozabilir, burada yeni sürüm
istemcinin eski sunucuya eklediği alan yüzünden ölçüm kaybolmasın.
Eksik zorunlu alan, yanlış tip (ondalık ya da metin olarak sayı dahil),
aralık dışı değer ise olayı atlatır.
- **Geçersiz olay batch'i düşürmez.** Atlanan olayların sayısı ve sabit
metinli nedenleri `info` ile loglanır; installId, soru kimliği ya da
başka bir istemci değeri loga yazılmaz (`AnalyticsEventEndpointTest`
doğruluyor).
- **Zaman penceresi:** `occurredAt` en fazla 7 gün geçmişte (çevrimdışı
kuyruk), en fazla 5 dakika ileride.
- **Idempotent.** `event_id` UNIQUE, `ON CONFLICT DO NOTHING`. Tekrar gelen
olay `accepted`'a dahildir; istemci için başarılı sayılır.
- **Rate limit bellek içi** (`InstallRateLimiter`): kurulum başına 120,
genel 6000 olay/dakika, sabit dakika penceresi. installId istemciden
geldiği için kimlik döndüren biri kurulum sınırını atlar; IP tutmadığımız
için tek önlem genel tavan. Yeniden başlatmada sıfırlanır; birden fazla
instance olursa yeniden düşünülür.
- **CORS yalnızca bu uçta,** yalnızca `capacitor://localhost` ve
`https://localhost`. Kaynak bean değil, zincire doğrudan veriliyor:
bean olsaydı diğer zincirler ve MVC de bulabilirdi. Diğer uçlarda CORS
izni yok (`AnalyticsCorsTest`). `Retry-After` expose edilir.
- **JPA değil JdbcClient.** IDENTITY id Hibernate'in toplu insert'ini
kapatıyor ve uygulama bu tabloyu okumuyor; batch tek çok satırlı INSERT.
- **13 ay saklama** (`AnalyticsRetentionJob`, her gün 03:30, `occurred_at`).
Politikaya yazılacak süre bununla aynı olmalı.
- **Analiz `docs/analytics/queries.sql`'de.** Gün uygulamadaki gibi 04:00'da
döner (Europe/Istanbul). Leitner tamamlanma: o günkü `wasDue=true`
`self_eval` ÷ günün ilk `app_open.dueCount`'u, tavan 1, `dueCount = 0`
günleri hariç.

### İstemci (`src/analytics/`)

- **Şema tek yerde, backend'le birebir:** `domain/usageEvents.ts` (Zod).
Backend'deki `EventPropsSchema` değişirse burası da değişir;
`usageEvents.test.ts` backend testleriyle aynı sınır değerlerini dener.
- **Alanların kaynağı saf fonksiyonlar** (`domain/usageMetrics.ts`):
- `dueCount`: çekilişin `isDue`'su ile; yalnızca içerikte bulunan ve seçili
kategorideki sorular. Kapalı kategorinin kartı çekilişe girmiyor,
sayılsaydı tamamlanma oranı yapay düşerdi.
- `wasDue`: değerlendirmeden ÖNCEKİ kayıtla `isDue`; ilk kez görülen soru
false (tekrar değil, tanıtım).
- `box`: `nextBox` ile, reducer'ın RATE'iyle aynı (test karşılaştırıyor).
- `aliasResult`: kullanıcının sonuç ekranında gördüğü seviye
(`domain/conceptMatch.ts`, ScoreCard'ın alt yazısıyla ortak). Pas ya da
boş cevap `skipped`. Metrik kullanıcının gördüğüyle kendi kararını
karşılaştırıyor; iki yer ayrı hesaplarsa anlamını kaybeder.
- **Track çağrıları App'te:** `spin` spinKey efektinde (reducer çekilişi
reddederse gitmez), `answer_submitted` `handleSubmit`'te, `self_eval`
`handleRate`'te reducer'dan ÖNCE (önceki kutu ancak o an elde).
`app_open` ve gönderim `useAnalytics`'te: açılışta bir kez (modül
seviyesinde güvence, StrictMode), 30 dk'dan uzun arka plandan dönüşte;
gönderim açılış, 60 sn aralık ve arka plana geçişte (`keepalive`).
- **Yerel kayıt ayrı namespace'te** (`slot-analytics`: `consent`, `install`,
`queue`). Store bozulup kurtarma ayarları varsayılana döndürse kapatma
tercihi kaybolurdu. Kayıt yoksa açık; kayıt var ama okunamıyorsa KAPALI.
Hesap silmede "bu cihazdaki verileri de sil" kimliği ve kuyruğu siler,
tercihi bırakır.
- **Kuyruğun tek kaynağı depo.** Her adım kilit içinde oku-değiştir-yaz
(`platform/locks.ts`, Web Locks): web'de sekmeler aynı kuyruğu paylaşıyor,
kilitsiz art arda olaylar birbirini eziyordu (test bunu yakaladı). Ağ
isteği kilidin dışında. Kuyruktan yalnızca 202 ya da 400/413'te silinir;
ağ hatasında aynı `eventId`'ler yeniden gider, backend ayıklar.
- **Kenar durumlar.** 7 günden eski olaylar gönderilmeden atılır (backend
reddediyor, 1 saat pay). Gönderim başına en fazla 2 batch (backend sınırı
dakikada 120). Cihaz saati 5 dk'dan fazla ileriyse backend olayları
sessizce atlar; istemci bunu göremez, bilinen sınır.
- **Kapatma** kuyruğu ve kimliği siler, `generation` sayacıyla kapatmadan
önce başlamış bir yazma da kuyruğu yeniden oluşturmaz. Yeniden açınca
bir sonraki olayda yeni kimlik üretilir.
- **Hedef.** Web her zaman göreli `/api/events` (aynı origin, CORS yok).
Native `VITE_API_BASE_URL`'den (`.env.production`). Native release
build'inde olayların sunucuya ulaştığı elle doğrulanmalı. Değişken
tanımsızsa analitik sessizce kapalıdır: anahtar ve kart da çizilmez.
- **Kimlik `platform/randomId.ts`'ten.** iOS'ta `capacitor://` güvenli bağlam
sayılmayabilir ve `crypto.randomUUID` yalnızca orada var; yedek
`getRandomValues` ile v4. Cihaz/reklam/hesap kimliği kullanılmaz.
- **Ölçüm uygulamayı bozmaz.** `track` senkron döner, hiçbir şey beklemez;
dışa açık her fonksiyon hatayı yutar, geliştirmede yalnızca `console.warn`.

## Yapay zekâ değerlendirmesi — denendi, kaldırıldı

- **Ne denendi.** Sunucu tarafında sağlayıcıdan bağımsız bir
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
package com.meteucar.mulakatslot.analytics;

import com.meteucar.mulakatslot.analytics.AnalyticsIngestService.Accepted;
import com.meteucar.mulakatslot.analytics.AnalyticsIngestService.BatchRejected;
import com.meteucar.mulakatslot.analytics.AnalyticsIngestService.RateLimited;
import java.util.Map;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

/**
* Kullanım ölçümü. Kimlik doğrulama yok ve olaylar hesaba bağlanmaz: uç
* kendi güvenlik zincirinde (SecurityConfig.eventsFilterChain), orada JWT
* hiç okunmuyor. Burada da principal parametresi yok; eklenmemeli.
*/
@RestController
public class AnalyticsEventController {

private final AnalyticsIngestService ingestService;

public AnalyticsEventController(AnalyticsIngestService ingestService) {
this.ingestService = ingestService;
}

@PostMapping("/api/events")
public ResponseEntity<Map<String, Object>> ingest(@RequestBody EventBatchRequest batch) {
return switch (ingestService.ingest(batch)) {
case Accepted(int accepted, int skipped) -> ResponseEntity.status(HttpStatus.ACCEPTED)
.body(Map.of("accepted", accepted, "skipped", skipped));
case BatchRejected() -> invalidBatch();
case RateLimited(long retryAfterSeconds) -> ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
.header(HttpHeaders.RETRY_AFTER, Long.toString(retryAfterSeconds))
.body(Map.of("error", "rate_limited"));
};
}

/** Bozuk JSON da aynı sözleşmeyle dönsün; Spring'in varsayılan gövdesi değil. */
@ExceptionHandler(HttpMessageNotReadableException.class)
public ResponseEntity<Map<String, Object>> handleUnreadable(HttpMessageNotReadableException e) {
return invalidBatch();
}

private static ResponseEntity<Map<String, Object>> invalidBatch() {
return ResponseEntity.badRequest().body(Map.of("error", "invalid_batch"));
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
package com.meteucar.mulakatslot.analytics;

import com.meteucar.mulakatslot.analytics.EventValidator.AcceptedEvent;
import com.meteucar.mulakatslot.analytics.EventValidator.BatchHeader;
import java.time.Instant;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.util.List;
import java.util.StringJoiner;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.stereotype.Component;
import tools.jackson.databind.json.JsonMapper;

/**
* Olayları tek bir çok satırlı INSERT ile yazar.
*
* <p>JPA değil JdbcClient: id IDENTITY olduğu için Hibernate toplu insert'i
* kapatıp satır başına bir sorgu atardı, ve bu tabloyu uygulama hiç okumuyor;
* entity'nin bir karşılığı yok.
*
* <p>Tekrar gelen eventId ON CONFLICT DO NOTHING ile sessizce geçilir: ağ
* hatasından sonra istemci aynı batch'i yeniden gönderebilir.
*/
@Component
class AnalyticsEventWriter {

private final JdbcClient jdbcClient;
private final JsonMapper jsonMapper;

AnalyticsEventWriter(JdbcClient jdbcClient, JsonMapper jsonMapper) {
this.jdbcClient = jdbcClient;
this.jsonMapper = jsonMapper;
}

/** @return gerçekten eklenen satır sayısı (tekrarlar hariç) */
int insert(BatchHeader header, List<AcceptedEvent> events, Instant receivedAt) {
if (events.isEmpty()) {
return 0;
}

// Olay sayısı en fazla 50 (EventValidator.MAX_EVENTS_PER_BATCH);
// parametre sayısı Postgres'in sınırının çok altında.
StringJoiner rows = new StringJoiner(", ");
for (int i = 0; i < events.size(); i++) {
rows.add("(:eventId" + i + ", :installId, :name" + i + ", :platform, :appVersion, :occurredAt" + i
+ ", :receivedAt, CAST(:props" + i + " AS jsonb))");
}
String sql = "INSERT INTO analytics_event "
+ "(event_id, install_id, event_name, platform, app_version, occurred_at, received_at, props) "
+ "VALUES " + rows
+ " ON CONFLICT (event_id) DO NOTHING";

JdbcClient.StatementSpec statement = jdbcClient.sql(sql)
.param("installId", header.installId())
.param("platform", header.platform())
.param("appVersion", header.appVersion())
.param("receivedAt", OffsetDateTime.ofInstant(receivedAt, ZoneOffset.UTC));
for (int i = 0; i < events.size(); i++) {
AcceptedEvent event = events.get(i);
statement = statement
.param("eventId" + i, event.eventId())
.param("name" + i, event.name())
.param("occurredAt" + i, OffsetDateTime.ofInstant(event.occurredAt(), ZoneOffset.UTC))
.param("props" + i, jsonMapper.writeValueAsString(event.props()));
}
return statement.update();
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
package com.meteucar.mulakatslot.analytics;

import com.meteucar.mulakatslot.analytics.EventValidator.AcceptedEvent;
import com.meteucar.mulakatslot.analytics.EventValidator.BatchHeader;
import com.meteucar.mulakatslot.analytics.EventValidator.InvalidBatch;
import com.meteucar.mulakatslot.analytics.EventValidator.Rejected;
import com.meteucar.mulakatslot.analytics.EventValidator.Valid;
import com.meteucar.mulakatslot.analytics.EventValidator.ValidBatch;
import java.time.Clock;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

/**
* Batch'i doğrular, sınırı uygular ve geçerli olayları yazar.
*
* <p>Log yalnızca sayı ve sabit metinli nedenler içerir: installId, soru
* kimliği ya da başka bir istemci değeri yazılmaz.
*/
@Service
public class AnalyticsIngestService {

private static final Logger log = LoggerFactory.getLogger(AnalyticsIngestService.class);

private final InstallRateLimiter rateLimiter;
private final AnalyticsEventWriter writer;
private final Clock clock;

public AnalyticsIngestService(InstallRateLimiter rateLimiter, AnalyticsEventWriter writer, Clock clock) {
this.rateLimiter = rateLimiter;
this.writer = writer;
this.clock = clock;
}

sealed interface Outcome permits Accepted, BatchRejected, RateLimited {
}

/**
* @param accepted geçerli olay sayısı; daha önce yazılmış (tekrar gelen)
* olaylar dahil, istemci için onlar da başarılı
*/
record Accepted(int accepted, int skipped) implements Outcome {
}

record BatchRejected() implements Outcome {
}

record RateLimited(long retryAfterSeconds) implements Outcome {
}

Outcome ingest(EventBatchRequest batch) {
BatchHeader header;
switch (EventValidator.validateBatch(batch)) {
case InvalidBatch(String reason) -> {
// 400 zaten istemciye dönüyor; bozuk istemci sürümünü
// aramak gerekirse debug açılır.
log.debug("Analitik: batch reddedildi ({})", reason);
return new BatchRejected();
}
case ValidBatch(BatchHeader validHeader) -> header = validHeader;
}

var decision = rateLimiter.tryAcquire(header.installId(), batch.events().size());
if (!decision.allowed()) {
return new RateLimited(decision.retryAfterSeconds());
}

Instant now = clock.instant();
List<AcceptedEvent> valid = new ArrayList<>();
Map<String, Integer> skippedByReason = new TreeMap<>();
for (EventRequest event : batch.events()) {
switch (EventValidator.validateEvent(event, now)) {
case Valid(AcceptedEvent accepted) -> valid.add(accepted);
case Rejected(String reason) -> skippedByReason.merge(reason, 1, Integer::sum);
}
}

int inserted = writer.insert(header, valid, now);
int skipped = batch.events().size() - valid.size();
if (skipped > 0) {
log.info("Analitik: {} olaydan {} tanesi atlandı {}", batch.events().size(), skipped, skippedByReason);
}
if (inserted < valid.size()) {
log.debug("Analitik: {} olay daha önce yazılmıştı", valid.size() - inserted);
}
return new Accepted(valid.size(), skipped);
}
}
Loading
Loading