From 9e1c0c705fcdbac3e8fe0167852e0baa995c80c7 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:00:58 +0300 Subject: [PATCH 01/17] feat(analytics): analytics_event tablosu (V4) Co-Authored-By: Claude Opus 5.5 --- .../db/migration/V4__analytics_event.sql | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 backend/src/main/resources/db/migration/V4__analytics_event.sql diff --git a/backend/src/main/resources/db/migration/V4__analytics_event.sql b/backend/src/main/resources/db/migration/V4__analytics_event.sql new file mode 100644 index 0000000..6393f65 --- /dev/null +++ b/backend/src/main/resources/db/migration/V4__analytics_event.sql @@ -0,0 +1,22 @@ +-- Kullanım ölçümü. Hesapla HİÇBİR bağ yok: user_id, IP ve user-agent +-- kolonu yok, app_user'a yabancı anahtar yok. install_id istemcinin +-- kurulumda ürettiği rastgele kimlik; giriş yapmış kullanıcıda da aynı. +-- Satırlar 13 ay sonra AnalyticsRetentionJob ile silinir. +CREATE TABLE analytics_event ( + id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, + -- İstemcinin ürettiği olay kimliği: ağ hatasından sonraki tekrar + -- gönderim ON CONFLICT DO NOTHING ile çift kayıt üretmez. + event_id UUID NOT NULL UNIQUE, + install_id UUID NOT NULL, + event_name TEXT NOT NULL + CHECK (event_name IN ('app_open', 'spin', 'answer_submitted', 'self_eval')), + platform TEXT NOT NULL CHECK (platform IN ('web', 'android', 'ios')), + app_version TEXT NOT NULL, + -- İstemci saati; doğrulama 7 gün geriye, 5 dakika ileriye izin veriyor. + occurred_at TIMESTAMPTZ NOT NULL, + received_at TIMESTAMPTZ NOT NULL DEFAULT now(), + props JSONB NOT NULL DEFAULT '{}' +); + +CREATE INDEX idx_analytics_event_install_occurred ON analytics_event (install_id, occurred_at); +CREATE INDEX idx_analytics_event_name_occurred ON analytics_event (event_name, occurred_at); From b45546d2b1ffcc5fb2424e266115bd29643306e7 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:04:35 +0300 Subject: [PATCH 02/17] =?UTF-8?q?feat(analytics):=20olay=20do=C4=9Frulay?= =?UTF-8?q?=C4=B1c=C4=B1=20ve=20props=20=C5=9Femas=C4=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Zarf bozuksa batch reddedilir, olay bozuksa yalnızca o olay atlanır. props'ta şemada olmayan alanlar sessizce atılır. Co-Authored-By: Claude Opus 5.5 --- .../analytics/EventBatchRequest.java | 17 ++ .../analytics/EventPropsSchema.java | 109 +++++++ .../mulakatslot/analytics/EventRequest.java | 15 + .../mulakatslot/analytics/EventValidator.java | 159 ++++++++++ .../analytics/EventValidatorTest.java | 280 ++++++++++++++++++ 5 files changed, 580 insertions(+) create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/EventBatchRequest.java create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/EventPropsSchema.java create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/EventRequest.java create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/EventValidator.java create mode 100644 backend/src/test/java/com/meteucar/mulakatslot/analytics/EventValidatorTest.java diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventBatchRequest.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventBatchRequest.java new file mode 100644 index 0000000..e7cb325 --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventBatchRequest.java @@ -0,0 +1,17 @@ +package com.meteucar.mulakatslot.analytics; + +import java.util.List; + +/** + * POST /api/events gövdesi. Kurulum, platform ve sürüm zarfta bir kez gelir: + * bir batch tek kurulumundur, rate limit de buna dayanıyor. + * + *

Alanlar String: Jackson ayrıştırsaydı bozuk bir UUID tüm isteği + * Spring'in varsayılan 400'üne çevirirdi. Doğrulama {@link EventValidator}'da. + */ +public record EventBatchRequest( + String installId, + String platform, + String appVersion, + List events) { +} diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventPropsSchema.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventPropsSchema.java new file mode 100644 index 0000000..c38d8fe --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventPropsSchema.java @@ -0,0 +1,109 @@ +package com.meteucar.mulakatslot.analytics; + +import java.util.Map; +import java.util.Set; +import java.util.regex.Pattern; + +/** + * Olay adları ve her olayın izin verilen props alanları. İstemci de aynı + * şemayı kullanıyor; bir alan eklenirse iki tarafta birlikte değişir. + * + *

Listedeki her alan zorunlu. Listede olmayan alanlar atılır, olayı + * geçersiz kılmaz: yeni sürüm istemci eski sunucuya yeni bir alan + * gönderdiğinde olay kaybolmasın. + * + *

Ad listesi V4 migration'ındaki CHECK kısıtıyla aynı olmalı. + */ +final class EventPropsSchema { + + /** Bir props alanının kabul ettiği değer. */ + sealed interface FieldRule permits IntRange, BooleanField, IdField, OneOf { + boolean accepts(Object value); + } + + /** + * Tam sayı, sınırlar dahil. Ondalık (3.0 dahil) ve metin olarak sayı + * kabul edilmez: istemcinin bir hatasını sessizce düzeltmek, sorgularda + * görünmeyen bir tutarsızlık bırakırdı. + */ + record IntRange(long min, long max) implements FieldRule { + @Override + public boolean accepts(Object value) { + if (value instanceof Integer || value instanceof Long + || value instanceof Short || value instanceof Byte) { + long number = ((Number) value).longValue(); + return number >= min && number <= max; + } + // Long'a sığmayan bir sayı zaten aralık dışında. + return false; + } + } + + record BooleanField() implements FieldRule { + @Override + public boolean accepts(Object value) { + return value instanceof Boolean; + } + } + + /** + * Soru kimliği. Karakter kümesi dar tutuldu: NUL ve eşi olmayan + * surrogate JSONB yazmasını düşürürdü, serbest metin de bu tabloya + * hiç girmesin. + */ + record IdField() implements FieldRule { + private static final Pattern ID = Pattern.compile("^[A-Za-z0-9._-]{1,128}$"); + + @Override + public boolean accepts(Object value) { + return value instanceof String text && ID.matcher(text).matches(); + } + } + + record OneOf(Set allowed) implements FieldRule { + @Override + public boolean accepts(Object value) { + return value instanceof String text && allowed.contains(text); + } + } + + /** Kutu aralığı: question_progress.box CHECK'iyle aynı. */ + private static final IntRange BOX = new IntRange(1, 5); + + /** Cevap uzunluğu: ProgressValidator.MAX_ANSWER_LENGTH ile aynı sınır. */ + private static final IntRange ANSWER_LENGTH = new IntRange(0, 5000); + + private static final Map> SCHEMAS = Map.of( + // dueCount: açılış anında vadesi gelmiş kart sayısı. + "app_open", Map.of( + "dueCount", new IntRange(0, 10_000)), + "spin", Map.of( + "categoryCount", new IntRange(1, 100)), + // Cevap METNİ değil, yalnızca uzunluğu. + "answer_submitted", Map.of( + "questionId", new IdField(), + "answerLength", ANSWER_LENGTH), + // box: öz-değerlendirmeden SONRAKİ kutu. + "self_eval", Map.of( + "questionId", new IdField(), + "aliasResult", new OneOf(Set.of("match", "partial", "none", "skipped")), + "result", new OneOf(Set.of("knew", "partial", "didnt")), + "box", BOX, + "wasDue", new BooleanField())); + + private EventPropsSchema() { + } + + static boolean isKnownEvent(String name) { + return name != null && SCHEMAS.containsKey(name); + } + + /** Bilinen bir olayın alanları; {@link #isKnownEvent} ile kontrol edildikten sonra çağrılır. */ + static Map fieldsOf(String name) { + return SCHEMAS.get(name); + } + + static Set eventNames() { + return SCHEMAS.keySet(); + } +} diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventRequest.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventRequest.java new file mode 100644 index 0000000..b6463e3 --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventRequest.java @@ -0,0 +1,15 @@ +package com.meteucar.mulakatslot.analytics; + +/** + * Batch'teki tek olay, API sınırındaki şekliyle. + * + *

Alanlar ayrıştırılmamış gelir: bozuk tarih ya da UUID, ya da nesne + * olmayan props yalnızca bu olayı atlatır, tüm batch'i değil. + * props'ta tanınmayan alanlar {@link EventValidator}'da sessizce atılır. + */ +public record EventRequest( + String eventId, + String name, + String occurredAt, + Object props) { +} diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventValidator.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventValidator.java new file mode 100644 index 0000000..17350a4 --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/EventValidator.java @@ -0,0 +1,159 @@ +package com.meteucar.mulakatslot.analytics; + +import com.meteucar.mulakatslot.analytics.EventPropsSchema.FieldRule; +import java.time.Duration; +import java.time.Instant; +import java.time.OffsetDateTime; +import java.time.format.DateTimeParseException; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.UUID; +import java.util.regex.Pattern; + +/** + * Gelen batch'i ve olayları eler. Saf: Spring, veritabanı ve log bilmez. + * + *

İki seviye var. Zarf (kurulum, platform, sürüm, olay sayısı) bozuksa + * batch'in hiçbir olayına güvenilemez, tamamı 400 alır. Olay bozuksa yalnızca + * o olay atlanır: tek hatalı olay yüzünden diğerleri kaybolmasın. + * + *

Ret nedenleri sabit metin; istemciden gelen hiçbir değer loga ulaşmasın. + */ +final class EventValidator { + + static final int MAX_EVENTS_PER_BATCH = 50; + + /** Çevrimdışı kalan istemcinin kuyruğu bu kadar geriye gidebilir. */ + static final Duration MAX_PAST = Duration.ofDays(7); + + /** İstemci saatinin ileri kayması için pay. */ + static final Duration MAX_FUTURE = Duration.ofMinutes(5); + + static final Set PLATFORMS = Set.of("web", "android", "ios"); + + /** package.json sürümü; Android'in versionCode şeması da X.Y.Z istiyor. */ + private static final Pattern APP_VERSION = Pattern.compile("^\\d{1,4}\\.\\d{1,4}\\.\\d{1,4}$"); + + /** + * Kanonik UUID biçimi. UUID.fromString tek başına gevşek: "1-1-1-1-1"i + * de kabul ediyor. + */ + private static final Pattern UUID_TEXT = Pattern.compile( + "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"); + + private EventValidator() { + } + + /** Batch'in tüm olaylarında ortak olan, doğrulanmış zarf. */ + record BatchHeader(UUID installId, String platform, String appVersion) { + } + + /** Saklanmaya hazır olay; props yalnızca şemadaki alanları taşır. */ + record AcceptedEvent(UUID eventId, String name, Instant occurredAt, Map props) { + } + + sealed interface BatchResult permits ValidBatch, InvalidBatch { + } + + record ValidBatch(BatchHeader header) implements BatchResult { + } + + record InvalidBatch(String reason) implements BatchResult { + } + + sealed interface EventResult permits Valid, Rejected { + } + + record Valid(AcceptedEvent event) implements EventResult { + } + + /** @param reason sabit metin; loga olduğu gibi yazılır */ + record Rejected(String reason) implements EventResult { + } + + static BatchResult validateBatch(EventBatchRequest batch) { + if (batch == null) { + return new InvalidBatch("gövde yok"); + } + UUID installId = parseUuid(batch.installId()); + if (installId == null) { + return new InvalidBatch("installId geçerli UUID değil"); + } + if (batch.platform() == null || !PLATFORMS.contains(batch.platform())) { + return new InvalidBatch("platform tanınmıyor"); + } + if (batch.appVersion() == null || !APP_VERSION.matcher(batch.appVersion()).matches()) { + return new InvalidBatch("appVersion X.Y.Z biçiminde değil"); + } + List events = batch.events(); + if (events == null || events.isEmpty()) { + return new InvalidBatch("events boş"); + } + if (events.size() > MAX_EVENTS_PER_BATCH) { + return new InvalidBatch("events " + MAX_EVENTS_PER_BATCH + " olaydan uzun"); + } + return new ValidBatch(new BatchHeader(installId, batch.platform(), batch.appVersion())); + } + + static EventResult validateEvent(EventRequest event, Instant now) { + if (event == null) { + return new Rejected("olay boş"); + } + UUID eventId = parseUuid(event.eventId()); + if (eventId == null) { + return new Rejected("eventId geçerli UUID değil"); + } + if (!EventPropsSchema.isKnownEvent(event.name())) { + return new Rejected("olay adı listede yok"); + } + + Instant occurredAt = parseInstant(event.occurredAt()); + if (occurredAt == null) { + return new Rejected("occurredAt geçerli ISO tarih değil"); + } + if (occurredAt.isBefore(now.minus(MAX_PAST))) { + return new Rejected("occurredAt 7 günden eski"); + } + if (occurredAt.isAfter(now.plus(MAX_FUTURE))) { + return new Rejected("occurredAt 5 dakikadan fazla ileride"); + } + + if (!(event.props() instanceof Map rawProps)) { + return new Rejected("props nesne değil"); + } + Map props = new LinkedHashMap<>(); + for (Map.Entry field : EventPropsSchema.fieldsOf(event.name()).entrySet()) { + Object value = rawProps.get(field.getKey()); + // Eksik alan ve null aynı şey: zorunlu alan yok. + if (value == null) { + return new Rejected("props alanı eksik"); + } + if (!field.getValue().accepts(value)) { + return new Rejected("props alanı tipi ya da aralığı geçersiz"); + } + props.put(field.getKey(), value); + } + // Şemada olmayan alanlar buraya hiç kopyalanmadı: sessizce atıldı. + return new Valid(new AcceptedEvent(eventId, event.name(), occurredAt, props)); + } + + private static UUID parseUuid(String value) { + if (value == null || !UUID_TEXT.matcher(value).matches()) { + return null; + } + return UUID.fromString(value); + } + + private static Instant parseInstant(String value) { + if (value == null) { + return null; + } + try { + return OffsetDateTime.parse(value).toInstant(); + } catch (DateTimeParseException e) { + return null; + } + } +} diff --git a/backend/src/test/java/com/meteucar/mulakatslot/analytics/EventValidatorTest.java b/backend/src/test/java/com/meteucar/mulakatslot/analytics/EventValidatorTest.java new file mode 100644 index 0000000..bf15191 --- /dev/null +++ b/backend/src/test/java/com/meteucar/mulakatslot/analytics/EventValidatorTest.java @@ -0,0 +1,280 @@ +package com.meteucar.mulakatslot.analytics; + +import static org.assertj.core.api.Assertions.assertThat; + +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.Duration; +import java.time.Instant; +import java.util.Collections; +import java.util.HashMap; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.UUID; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +/** Saf doğrulama kuralları; veritabanı ve Spring gerekmez. */ +class EventValidatorTest { + + private static final Instant NOW = Instant.parse("2026-11-17T12:00:00Z"); + private static final String INSTALL = "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b"; + private static final String EVENT_ID = "0b1c2d3e-4f50-4617-8293-a4b5c6d7e8f9"; + + private static Map selfEvalProps() { + Map props = new LinkedHashMap<>(); + props.put("questionId", "java-equals-hashcode"); + props.put("aliasResult", "partial"); + props.put("result", "knew"); + props.put("box", 3); + props.put("wasDue", true); + return props; + } + + private static EventRequest event(String name, Object props) { + return new EventRequest(EVENT_ID, name, NOW.toString(), props); + } + + private static EventRequest eventAt(Instant occurredAt) { + return new EventRequest(EVENT_ID, "app_open", occurredAt.toString(), Map.of("dueCount", 4)); + } + + private static EventValidator.EventResult validate(EventRequest event) { + return EventValidator.validateEvent(event, NOW); + } + + + private EventBatchRequest batch(String installId, String platform, String version, int eventCount) { + List events = Collections.nCopies(eventCount, eventAt(NOW)); + return new EventBatchRequest(installId, platform, version, events); + } + + @Test + void acceptsValidEnvelope() { + var result = EventValidator.validateBatch(batch(INSTALL, "android", "1.2.0", 50)); + + assertThat(result).isInstanceOfSatisfying(ValidBatch.class, valid -> { + assertThat(valid.header().installId()).isEqualTo(UUID.fromString(INSTALL)); + assertThat(valid.header().platform()).isEqualTo("android"); + assertThat(valid.header().appVersion()).isEqualTo("1.2.0"); + }); + } + + @Test + void rejectsMoreThanFiftyEvents() { + assertThat(EventValidator.validateBatch(batch(INSTALL, "web", "1.0.0", 51))) + .isInstanceOf(InvalidBatch.class); + } + + @Test + void rejectsEmptyAndMissingEvents() { + assertThat(EventValidator.validateBatch(batch(INSTALL, "web", "1.0.0", 0))) + .isInstanceOf(InvalidBatch.class); + assertThat(EventValidator.validateBatch(new EventBatchRequest(INSTALL, "web", "1.0.0", null))) + .isInstanceOf(InvalidBatch.class); + } + + @ParameterizedTest + @ValueSource(strings = {"", "nope", "1-1-1-1-1", "6f1c2a3b4d5e4f608a7b9c0d1e2f3a4b"}) + void rejectsNonCanonicalInstallId(String installId) { + assertThat(EventValidator.validateBatch(batch(installId, "web", "1.0.0", 1))) + .isInstanceOf(InvalidBatch.class); + } + + @ParameterizedTest + @ValueSource(strings = {"", "desktop", "Web"}) + void rejectsUnknownPlatform(String platform) { + assertThat(EventValidator.validateBatch(batch(INSTALL, platform, "1.0.0", 1))) + .isInstanceOf(InvalidBatch.class); + } + + @ParameterizedTest + @ValueSource(strings = {"", "1.0", "1.0.0-beta", "v1.0.0", "12345.0.0"}) + void rejectsMalformedAppVersion(String version) { + assertThat(EventValidator.validateBatch(batch(INSTALL, "ios", version, 1))) + .isInstanceOf(InvalidBatch.class); + } + + @Test + void rejectsMissingFields() { + assertThat(EventValidator.validateBatch(null)).isInstanceOf(InvalidBatch.class); + assertThat(EventValidator.validateBatch(batch(null, "web", "1.0.0", 1))).isInstanceOf(InvalidBatch.class); + assertThat(EventValidator.validateBatch(batch(INSTALL, null, "1.0.0", 1))).isInstanceOf(InvalidBatch.class); + assertThat(EventValidator.validateBatch(batch(INSTALL, "web", null, 1))).isInstanceOf(InvalidBatch.class); + } + + + @Test + void whitelistHasExactlyFourEvents() { + // V4 migration'ındaki CHECK kısıtıyla aynı liste. + assertThat(EventPropsSchema.eventNames()) + .containsExactlyInAnyOrder("app_open", "spin", "answer_submitted", "self_eval"); + } + + @ParameterizedTest + @ValueSource(strings = {"leitner_review_done", "APP_OPEN", "page_view", ""}) + void rejectsUnknownName(String name) { + assertThat(validate(event(name, Map.of()))).isInstanceOf(Rejected.class); + } + + @Test + void rejectsMissingName() { + assertThat(validate(event(null, Map.of()))).isInstanceOf(Rejected.class); + } + + @Test + void acceptsEveryKnownEventWithValidProps() { + assertThat(validate(event("app_open", Map.of("dueCount", 0)))).isInstanceOf(Valid.class); + assertThat(validate(event("spin", Map.of("categoryCount", 1)))).isInstanceOf(Valid.class); + assertThat(validate(event("answer_submitted", + Map.of("questionId", "sql-index", "answerLength", 0)))).isInstanceOf(Valid.class); + assertThat(validate(event("self_eval", selfEvalProps()))).isInstanceOf(Valid.class); + } + + + @Test + void acceptsBoundaries() { + assertThat(validate(eventAt(NOW.minus(Duration.ofDays(7))))).isInstanceOf(Valid.class); + assertThat(validate(eventAt(NOW.plus(Duration.ofMinutes(5))))).isInstanceOf(Valid.class); + } + + @Test + void rejectsJustOutsideBoundaries() { + assertThat(validate(eventAt(NOW.minus(Duration.ofDays(7)).minusSeconds(1)))).isInstanceOf(Rejected.class); + assertThat(validate(eventAt(NOW.plus(Duration.ofMinutes(5)).plusSeconds(1)))).isInstanceOf(Rejected.class); + } + + @Test + void acceptsOffsetAndKeepsInstant() { + var event = new EventRequest(EVENT_ID, "app_open", "2026-11-17T15:00:00+03:00", Map.of("dueCount", 1)); + + assertThat(validate(event)).isInstanceOfSatisfying(Valid.class, + valid -> assertThat(valid.event().occurredAt()).isEqualTo(NOW)); + } + + @ParameterizedTest + @ValueSource(strings = {"", "dün", "2026-11-17", "2026-11-17T12:00:00"}) + void rejectsUnparseableTimestamp(String occurredAt) { + var event = new EventRequest(EVENT_ID, "app_open", occurredAt, Map.of("dueCount", 1)); + assertThat(validate(event)).isInstanceOf(Rejected.class); + } + + + @ParameterizedTest + @ValueSource(strings = {"", "abc", "1-1-1-1-1"}) + void rejectsInvalidEventId(String eventId) { + var event = new EventRequest(eventId, "app_open", NOW.toString(), Map.of("dueCount", 1)); + assertThat(validate(event)).isInstanceOf(Rejected.class); + } + + @Test + void rejectsNullEvent() { + assertThat(validate(null)).isInstanceOf(Rejected.class); + } + + + @Test + void dropsUnknownFieldsAndKeepsEvent() { + Map props = selfEvalProps(); + props.put("answer", "cevap metni buraya girmemeli"); + props.put("extra", 1); + + assertThat(validate(event("self_eval", props))).isInstanceOfSatisfying(Valid.class, + valid -> assertThat(valid.event().props()) + .containsOnlyKeys("questionId", "aliasResult", "result", "box", "wasDue")); + } + + @Test + void rejectsMissingRequiredField() { + Map props = selfEvalProps(); + props.remove("wasDue"); + assertThat(validate(event("self_eval", props))).isInstanceOf(Rejected.class); + assertThat(validate(event("app_open", Map.of()))).isInstanceOf(Rejected.class); + } + + @Test + void rejectsNullValue() { + Map props = new HashMap<>(selfEvalProps()); + props.put("box", null); + assertThat(validate(event("self_eval", props))).isInstanceOf(Rejected.class); + } + + @Test + void rejectsNonObjectProps() { + assertThat(validate(event("spin", List.of(1)))).isInstanceOf(Rejected.class); + assertThat(validate(event("spin", "categoryCount=3"))).isInstanceOf(Rejected.class); + assertThat(validate(event("spin", null))).isInstanceOf(Rejected.class); + } + + @Test + void rejectsWrongIntegerTypes() { + assertThat(validate(event("spin", Map.of("categoryCount", 3.0)))).isInstanceOf(Rejected.class); + assertThat(validate(event("spin", Map.of("categoryCount", "3")))).isInstanceOf(Rejected.class); + assertThat(validate(event("spin", Map.of("categoryCount", true)))).isInstanceOf(Rejected.class); + assertThat(validate(event("spin", Map.of("categoryCount", 3L)))).isInstanceOf(Valid.class); + } + + @Test + void enforcesIntegerRanges() { + assertThat(validate(event("spin", Map.of("categoryCount", 0)))).isInstanceOf(Rejected.class); + assertThat(validate(event("spin", Map.of("categoryCount", 100)))).isInstanceOf(Valid.class); + assertThat(validate(event("spin", Map.of("categoryCount", 101)))).isInstanceOf(Rejected.class); + assertThat(validate(event("app_open", Map.of("dueCount", -1)))).isInstanceOf(Rejected.class); + assertThat(validate(event("app_open", Map.of("dueCount", 10_000)))).isInstanceOf(Valid.class); + assertThat(validate(event("app_open", Map.of("dueCount", 10_001)))).isInstanceOf(Rejected.class); + assertThat(validate(event("answer_submitted", + Map.of("questionId", "q", "answerLength", 5001)))).isInstanceOf(Rejected.class); + } + + @ParameterizedTest + @ValueSource(ints = {0, 6}) + void rejectsBoxOutsideOneToFive(int box) { + Map props = selfEvalProps(); + props.put("box", box); + assertThat(validate(event("self_eval", props))).isInstanceOf(Rejected.class); + } + + @Test + void rejectsNonBooleanWasDue() { + Map props = selfEvalProps(); + props.put("wasDue", "true"); + assertThat(validate(event("self_eval", props))).isInstanceOf(Rejected.class); + } + + @ParameterizedTest + @ValueSource(strings = {"MATCH", "maybe", ""}) + void rejectsUnknownAliasResult(String aliasResult) { + Map props = selfEvalProps(); + props.put("aliasResult", aliasResult); + assertThat(validate(event("self_eval", props))).isInstanceOf(Rejected.class); + } + + @Test + void acceptsEveryAliasResultAndResult() { + for (String aliasResult : List.of("match", "partial", "none", "skipped")) { + for (String result : List.of("knew", "partial", "didnt")) { + Map props = selfEvalProps(); + props.put("aliasResult", aliasResult); + props.put("result", result); + assertThat(validate(event("self_eval", props))).isInstanceOf(Valid.class); + } + } + } + + @ParameterizedTest + @ValueSource(strings = {"", "bir cevap", "a\u0000b", "q\uD800", "ğ-soru"}) + void rejectsQuestionIdOutsideCharset(String questionId) { + var props = Map.of("questionId", questionId, "answerLength", 10); + assertThat(validate(event("answer_submitted", props))).isInstanceOf(Rejected.class); + } + + @Test + void rejectsQuestionIdLongerThan128() { + var props = Map.of("questionId", "q".repeat(129), "answerLength", 10); + assertThat(validate(event("answer_submitted", props))).isInstanceOf(Rejected.class); + } +} From 14167eb18b608a66ff0c909ea180858f66377849 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:05:36 +0300 Subject: [PATCH 03/17] =?UTF-8?q?feat(analytics):=20kurulum=20ba=C5=9F?= =?UTF-8?q?=C4=B1na=20ve=20genel=20rate=20limit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bellek içi sabit dakika penceresi: kurulum başına 120, genel 6000 olay/dk. MutableClock analytics testleri de kullanabilsin diye public. Co-Authored-By: Claude Opus 5.5 --- .../analytics/InstallRateLimiter.java | 91 ++++++++++++++++++ .../analytics/InstallRateLimiterTest.java | 96 +++++++++++++++++++ .../mulakatslot/auth/MutableClock.java | 6 +- 3 files changed, 190 insertions(+), 3 deletions(-) create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/InstallRateLimiter.java create mode 100644 backend/src/test/java/com/meteucar/mulakatslot/analytics/InstallRateLimiterTest.java diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/InstallRateLimiter.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/InstallRateLimiter.java new file mode 100644 index 0000000..13987c8 --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/InstallRateLimiter.java @@ -0,0 +1,91 @@ +package com.meteucar.mulakatslot.analytics; + +import java.time.Clock; +import java.time.Instant; +import java.util.HashMap; +import java.util.Map; +import java.util.UUID; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.stereotype.Component; + +/** + * /api/events için bellek içi, sabit dakika pencereli sınır. + * + *

İki sınır var. Kurulum başına sınır sıradan bir istemcinin hatalı + * döngüsünü durdurur. Ama installId istemciden geliyor: her istekte yeni + * kimlik üreten biri onu atlar. IP tutmadığımız için buna karşı tek önlem + * genel tavan; aşılırsa herkes kısa süre 429 alır, istemciler kuyruğu tutup + * sonra tekrar dener. + * + *

Dakika değişince bütün sayaçlar sıfırlanır: bellekte yalnızca o dakika + * istek atmış kurulumlar durur, ayrı bir temizlik gerekmez. Sayaçlar yeniden + * başlatmada sıfırlanır; tek instance için yeterli. + * + *

Sayılan, batch'teki olay sayısıdır (geçersizler dahil): sınır sunucunun + * işlediği yükü korur. + */ +@Component +public class InstallRateLimiter { + + static final int DEFAULT_PER_INSTALL_PER_MINUTE = 120; + static final int DEFAULT_GLOBAL_PER_MINUTE = 6000; + + private final Clock clock; + private final int perInstallLimit; + private final int globalLimit; + + private final Map usedByInstall = new HashMap<>(); + private long currentMinute = Long.MIN_VALUE; + private int usedGlobally; + + /** @param retryAfterSeconds izin verildiyse 0 */ + record Decision(boolean allowed, long retryAfterSeconds) { + } + + @Autowired + public InstallRateLimiter(Clock clock) { + this(clock, DEFAULT_PER_INSTALL_PER_MINUTE, DEFAULT_GLOBAL_PER_MINUTE); + } + + InstallRateLimiter(Clock clock, int perInstallLimit, int globalLimit) { + this.clock = clock; + this.perInstallLimit = perInstallLimit; + this.globalLimit = globalLimit; + } + + /** + * Hepsi ya da hiçbiri: batch sığıyorsa olay sayısı iki sayaçtan da düşülür, + * sığmıyorsa hiçbir şey düşülmez. + * + *

synchronized yeterli: kritik bölge birkaç map işlemi, ve iki sayacın + * birlikte kontrol edilip düşülmesi gerekiyor. + */ + synchronized Decision tryAcquire(UUID installId, int eventCount) { + Instant now = clock.instant(); + long minute = now.getEpochSecond() / 60; + if (minute != currentMinute) { + currentMinute = minute; + usedByInstall.clear(); + usedGlobally = 0; + } + + int usedByThisInstall = usedByInstall.getOrDefault(installId, 0); + if (usedByThisInstall + eventCount > perInstallLimit || usedGlobally + eventCount > globalLimit) { + return new Decision(false, secondsUntilNextMinute(now)); + } + usedByInstall.put(installId, usedByThisInstall + eventCount); + usedGlobally += eventCount; + return new Decision(true, 0); + } + + /** Retry-After en az 1 sn: 0, istemcide hemen tekrar dene diye okunur. */ + private static long secondsUntilNextMinute(Instant now) { + long remaining = 60 - (now.getEpochSecond() % 60); + return Math.max(1, remaining); + } + + /** Test için: bu dakika bellekte tutulan kurulum sayısı. */ + synchronized int trackedInstallCount() { + return usedByInstall.size(); + } +} diff --git a/backend/src/test/java/com/meteucar/mulakatslot/analytics/InstallRateLimiterTest.java b/backend/src/test/java/com/meteucar/mulakatslot/analytics/InstallRateLimiterTest.java new file mode 100644 index 0000000..914060d --- /dev/null +++ b/backend/src/test/java/com/meteucar/mulakatslot/analytics/InstallRateLimiterTest.java @@ -0,0 +1,96 @@ +package com.meteucar.mulakatslot.analytics; + +import static org.assertj.core.api.Assertions.assertThat; + +import com.meteucar.mulakatslot.auth.MutableClock; +import java.time.Duration; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.UUID; +import org.junit.jupiter.api.Test; + +class InstallRateLimiterTest { + + /** Bir dakikanın 15. saniyesi: pencere sonuna 45 sn var. */ + private final MutableClock clock = new MutableClock(Instant.parse("2026-11-17T12:00:15Z"), ZoneOffset.UTC); + + private final UUID installA = UUID.randomUUID(); + private final UUID installB = UUID.randomUUID(); + + @Test + void allowsUpToPerInstallLimitWithinAMinute() { + var limiter = new InstallRateLimiter(clock, 120, 6000); + + assertThat(limiter.tryAcquire(installA, 50).allowed()).isTrue(); + assertThat(limiter.tryAcquire(installA, 50).allowed()).isTrue(); + assertThat(limiter.tryAcquire(installA, 20).allowed()).isTrue(); + + var denied = limiter.tryAcquire(installA, 1); + assertThat(denied.allowed()).isFalse(); + assertThat(denied.retryAfterSeconds()).isEqualTo(45); + } + + @Test + void deniedBatchConsumesNothing() { + var limiter = new InstallRateLimiter(clock, 120, 6000); + limiter.tryAcquire(installA, 100); + + // 30 sığmıyor ama 20 sığıyor: reddedilen batch sayaçtan düşülmedi. + assertThat(limiter.tryAcquire(installA, 30).allowed()).isFalse(); + assertThat(limiter.tryAcquire(installA, 20).allowed()).isTrue(); + } + + @Test + void installsAreCountedSeparately() { + var limiter = new InstallRateLimiter(clock, 120, 6000); + limiter.tryAcquire(installA, 120); + + assertThat(limiter.tryAcquire(installA, 1).allowed()).isFalse(); + assertThat(limiter.tryAcquire(installB, 50).allowed()).isTrue(); + } + + @Test + void windowResetsAtNextMinute() { + var limiter = new InstallRateLimiter(clock, 120, 6000); + limiter.tryAcquire(installA, 120); + + clock.advance(Duration.ofSeconds(44)); + assertThat(limiter.tryAcquire(installA, 1).allowed()).isFalse(); + + clock.advance(Duration.ofSeconds(1)); + assertThat(limiter.tryAcquire(installA, 120).allowed()).isTrue(); + } + + @Test + void globalCeilingStopsRotatingInstallIds() { + var limiter = new InstallRateLimiter(clock, 120, 200); + + assertThat(limiter.tryAcquire(UUID.randomUUID(), 100).allowed()).isTrue(); + assertThat(limiter.tryAcquire(UUID.randomUUID(), 100).allowed()).isTrue(); + // Yepyeni bir kimlik de genel tavana takılır. + assertThat(limiter.tryAcquire(UUID.randomUUID(), 1).allowed()).isFalse(); + } + + @Test + void forgetsInstallsOfPreviousMinute() { + var limiter = new InstallRateLimiter(clock, 120, 6000); + for (int i = 0; i < 10; i++) { + limiter.tryAcquire(UUID.randomUUID(), 1); + } + assertThat(limiter.trackedInstallCount()).isEqualTo(10); + + clock.advance(Duration.ofMinutes(1)); + limiter.tryAcquire(installA, 1); + + assertThat(limiter.trackedInstallCount()).isEqualTo(1); + } + + @Test + void retryAfterIsAtLeastOneSecond() { + var lastSecond = new MutableClock(Instant.parse("2026-11-17T12:00:59.900Z"), ZoneOffset.UTC); + var limiter = new InstallRateLimiter(lastSecond, 1, 6000); + limiter.tryAcquire(installA, 1); + + assertThat(limiter.tryAcquire(installA, 1).retryAfterSeconds()).isEqualTo(1); + } +} diff --git a/backend/src/test/java/com/meteucar/mulakatslot/auth/MutableClock.java b/backend/src/test/java/com/meteucar/mulakatslot/auth/MutableClock.java index 31dc2aa..fcf0734 100644 --- a/backend/src/test/java/com/meteucar/mulakatslot/auth/MutableClock.java +++ b/backend/src/test/java/com/meteucar/mulakatslot/auth/MutableClock.java @@ -11,17 +11,17 @@ * *

instant volatile: eşzamanlılık testinde iki iş parçacığı aynı saati okuyor. */ -class MutableClock extends Clock { +public class MutableClock extends Clock { private final ZoneId zone; private volatile Instant instant; - MutableClock(Instant instant, ZoneId zone) { + public MutableClock(Instant instant, ZoneId zone) { this.instant = instant; this.zone = zone; } - void advance(Duration amount) { + public void advance(Duration amount) { this.instant = this.instant.plus(amount); } From d418afced174957ccb83621e89b429252417fcd1 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:10:03 +0300 Subject: [PATCH 04/17] =?UTF-8?q?feat(analytics):=20POST=20/api/events=20v?= =?UTF-8?q?e=20ayr=C4=B1=20g=C3=BCvenlik=20zinciri?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Zincirde resource server yok: Bearer başlığı okunmaz, olay hesaba bağlanmaz. Tekrar gelen eventId ON CONFLICT ile atlanır, accepted'a dahildir. Sınır aşılırsa 429 + Retry-After, hiçbir şey yazılmaz. Co-Authored-By: Claude Opus 5.5 --- .../analytics/AnalyticsEventController.java | 51 ++++ .../analytics/AnalyticsEventWriter.java | 68 +++++ .../analytics/AnalyticsIngestService.java | 93 ++++++ .../mulakatslot/config/SecurityConfig.java | 27 +- .../analytics/AnalyticsEventEndpointTest.java | 282 ++++++++++++++++++ .../analytics/AnalyticsTestClock.java | 25 ++ 6 files changed, 544 insertions(+), 2 deletions(-) create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsEventController.java create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsEventWriter.java create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsIngestService.java create mode 100644 backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsEventEndpointTest.java create mode 100644 backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsTestClock.java diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsEventController.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsEventController.java new file mode 100644 index 0000000..9e0174f --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsEventController.java @@ -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> 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> handleUnreadable(HttpMessageNotReadableException e) { + return invalidBatch(); + } + + private static ResponseEntity> invalidBatch() { + return ResponseEntity.badRequest().body(Map.of("error", "invalid_batch")); + } +} diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsEventWriter.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsEventWriter.java new file mode 100644 index 0000000..b0ff6a2 --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsEventWriter.java @@ -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. + * + *

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. + * + *

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 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(); + } +} diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsIngestService.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsIngestService.java new file mode 100644 index 0000000..10dd552 --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsIngestService.java @@ -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. + * + *

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 valid = new ArrayList<>(); + Map 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); + } +} diff --git a/backend/src/main/java/com/meteucar/mulakatslot/config/SecurityConfig.java b/backend/src/main/java/com/meteucar/mulakatslot/config/SecurityConfig.java index be66c5c..505f68c 100644 --- a/backend/src/main/java/com/meteucar/mulakatslot/config/SecurityConfig.java +++ b/backend/src/main/java/com/meteucar/mulakatslot/config/SecurityConfig.java @@ -8,11 +8,13 @@ import org.springframework.security.config.Customizer; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; +import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer; import org.springframework.security.config.http.SessionCreationPolicy; import org.springframework.security.web.SecurityFilterChain; /** - * İki ayrı filtre zinciri var, çünkü iki farklı oturum modeli gerekiyor. + * Üç filtre zinciri var: iki farklı oturum modeli (OAuth el sıkışması ve + * API) ve hiç kimlik okumayan kullanım ölçümü ucu. */ @Configuration @EnableWebSecurity @@ -37,12 +39,33 @@ SecurityFilterChain oauthFilterChain(HttpSecurity http, .build(); } + /** + * Kullanım ölçümü. Olaylar hesaba bağlanmamalı; bu yüzden bu zincirde + * resource server YOK: Authorization başlığı gelse bile JWT okunmaz, + * principal oluşmaz. Yan faydası: süresi dolmuş Bearer başlığı taşıyan + * girişli bir web istemcisinin olayları API zincirindeki gibi 401 almaz. + * + *

Kimlik doğrulama olmadığı için CSRF'in koruyacağı bir şey yok. + */ + @Bean + @Order(2) + SecurityFilterChain eventsFilterChain(HttpSecurity http) throws Exception { + return http + .securityMatcher("/api/events") + // Yalnızca POST eşlenmiş; diğer metotlara Spring MVC 405 döner. + .authorizeHttpRequests(auth -> auth.anyRequest().permitAll()) + .csrf(AbstractHttpConfigurer::disable) + .sessionManagement(session -> session + .sessionCreationPolicy(SessionCreationPolicy.STATELESS)) + .build(); + } + /** * API. Kimlik yalnızca Authorization başlığındaki Bearer JWT ile * doğrulanır, sunucuda oturum tutulmaz. */ @Bean - @Order(2) + @Order(3) SecurityFilterChain apiFilterChain(HttpSecurity http, JsonAuthenticationEntryPoint entryPoint) throws Exception { return http .authorizeHttpRequests(auth -> auth diff --git a/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsEventEndpointTest.java b/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsEventEndpointTest.java new file mode 100644 index 0000000..57b330e --- /dev/null +++ b/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsEventEndpointTest.java @@ -0,0 +1,282 @@ +package com.meteucar.mulakatslot.analytics; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; + +import com.meteucar.mulakatslot.TestcontainersConfiguration; +import com.meteucar.mulakatslot.auth.AccessTokenService; +import com.meteucar.mulakatslot.auth.MutableClock; +import com.meteucar.mulakatslot.user.AppUser; +import com.meteucar.mulakatslot.user.AppUserRepository; +import java.time.Duration; +import java.time.OffsetDateTime; +import java.time.ZoneOffset; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.UUID; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.test.system.CapturedOutput; +import org.springframework.boot.test.system.OutputCaptureExtension; +import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc; +import org.springframework.context.annotation.Import; +import org.springframework.http.HttpHeaders; +import org.springframework.http.MediaType; +import org.springframework.jdbc.core.simple.JdbcClient; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.test.web.servlet.ResultActions; +import tools.jackson.databind.json.JsonMapper; + +/** + * POST /api/events uçtan uca: güvenlik zinciri, batch davranışı, JSONB + * yazımı, tekrar gönderim ve sınır. Kuralların ayrıntısı EventValidatorTest + * ve InstallRateLimiterTest'te. + */ +@Import({TestcontainersConfiguration.class, AnalyticsTestClock.class}) +@SpringBootTest +@AutoConfigureMockMvc +@ExtendWith(OutputCaptureExtension.class) +class AnalyticsEventEndpointTest { + + /** Loga ulaşmaması gereken soru kimliği. */ + private static final String SECRET_QUESTION = "gizli-soru-kimligi"; + + @Autowired + private MockMvc mockMvc; + + @Autowired + private JsonMapper jsonMapper; + + @Autowired + private JdbcClient jdbcClient; + + @Autowired + private MutableClock clock; + + @Autowired + private AccessTokenService accessTokenService; + + @Autowired + private AppUserRepository appUserRepository; + + private String installId; + + @BeforeEach + void setUp() { + jdbcClient.sql("DELETE FROM analytics_event").update(); + // Yeni dakika: rate limit penceresi temiz başlar. + clock.advance(Duration.ofMinutes(1)); + installId = UUID.randomUUID().toString(); + } + + @Test + void acceptsBatchWithoutAuthenticationAndStoresEveryColumn() throws Exception { + Map props = selfEvalProps(SECRET_QUESTION); + props.put("extra", "atılmalı"); + var event = event("self_eval", props); + + send(batch(List.of(event))) + .andExpect(status().isAccepted()) + .andExpect(jsonPath("$.accepted").value(1)) + .andExpect(jsonPath("$.skipped").value(0)); + + Map row = jdbcClient.sql(""" + SELECT event_id::text, install_id::text, event_name, platform, app_version, + occurred_at = :now AS occurred_ok, received_at = :now AS received_ok, props::text + FROM analytics_event""") + .param("now", OffsetDateTime.ofInstant(clock.instant(), ZoneOffset.UTC)) + .query().singleRow(); + assertThat(row).containsEntry("event_id", event.get("eventId")) + .containsEntry("install_id", installId) + .containsEntry("event_name", "self_eval") + .containsEntry("platform", "android") + .containsEntry("app_version", "1.2.0") + .containsEntry("occurred_ok", true) + .containsEntry("received_ok", true); + Map storedProps = jsonMapper.readValue((String) row.get("props"), Map.class); + assertThat(storedProps).isEqualTo(Map.of( + "questionId", SECRET_QUESTION, "aliasResult", "partial", "result", "knew", + "box", 3, "wasDue", true)); + } + + /** + * Girişli web istemcisi Bearer başlığı gönderse bile olay hesaba + * bağlanmaz: zincir JWT okumuyor, geçersiz başlık da 401'e dönmüyor. + */ + @Test + void ignoresAuthorizationHeader() throws Exception { + AppUser user = appUserRepository.save(new AppUser("gh-analytics-" + UUID.randomUUID(), "metecode")); + String body = batch(List.of(event("app_open", Map.of("dueCount", 2)))); + + mockMvc.perform(post("/api/events").contentType(MediaType.APPLICATION_JSON).content(body) + .header(HttpHeaders.AUTHORIZATION, "Bearer " + accessTokenService.issue(user.getId()))) + .andExpect(status().isAccepted()); + String second = batch(List.of(event("app_open", Map.of("dueCount", 2)))); + mockMvc.perform(post("/api/events").contentType(MediaType.APPLICATION_JSON).content(second) + .header(HttpHeaders.AUTHORIZATION, "Bearer bu-bir-jwt-degil")) + .andExpect(status().isAccepted()); + + assertThat(count()).isEqualTo(2); + } + + @Test + void tableHasNoColumnThatCouldIdentifyAnAccount() { + List columns = jdbcClient.sql(""" + SELECT column_name FROM information_schema.columns + WHERE table_name = 'analytics_event'""").query(String.class).list(); + + assertThat(columns).containsExactlyInAnyOrder("id", "event_id", "install_id", "event_name", + "platform", "app_version", "occurred_at", "received_at", "props"); + } + + @Test + void skipsInvalidEventsAndLogsOnlyCounts(CapturedOutput output) throws Exception { + var events = List.of( + event("app_open", Map.of("dueCount", 5)), + event("leitner_review_done", Map.of("box", 2)), + event("spin", Map.of("categoryCount", "3")), + event("answer_submitted", Map.of("questionId", SECRET_QUESTION, "answerLength", 9999))); + + send(batch(events)) + .andExpect(status().isAccepted()) + .andExpect(jsonPath("$.accepted").value(1)) + .andExpect(jsonPath("$.skipped").value(3)); + + assertThat(count()).isEqualTo(1); + assertThat(output).contains("4 olaydan 3 tanesi atlandı") + .doesNotContain(installId) + .doesNotContain(SECRET_QUESTION); + } + + @Test + void duplicateEventIdIsAcceptedButStoredOnce() throws Exception { + String body = batch(List.of(event("app_open", Map.of("dueCount", 1)))); + + send(body).andExpect(status().isAccepted()).andExpect(jsonPath("$.accepted").value(1)); + send(body).andExpect(status().isAccepted()).andExpect(jsonPath("$.accepted").value(1)); + + assertThat(count()).isEqualTo(1); + } + + @Test + void duplicateWithinOneBatchIsStoredOnce() throws Exception { + var event = event("app_open", Map.of("dueCount", 1)); + + send(batch(List.of(event, event))).andExpect(status().isAccepted()) + .andExpect(jsonPath("$.accepted").value(2)); + + assertThat(count()).isEqualTo(1); + } + + @Test + void rejectsBatchOfFiftyOneWithoutWriting() throws Exception { + send(batch(spins(51))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.error").value("invalid_batch")); + + assertThat(count()).isZero(); + } + + @Test + void acceptsBatchOfFifty() throws Exception { + send(batch(spins(50))).andExpect(status().isAccepted()).andExpect(jsonPath("$.accepted").value(50)); + + assertThat(count()).isEqualTo(50); + } + + @Test + void rejectsBadEnvelope() throws Exception { + Map body = envelope(spins(1)); + body.put("platform", "desktop"); + + send(jsonMapper.writeValueAsString(body)) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.error").value("invalid_batch")); + assertThat(count()).isZero(); + } + + @Test + void rejectsMalformedJson() throws Exception { + send("{\"installId\": ") + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.error").value("invalid_batch")); + } + + @Test + void rateLimitRejectsWholeBatchWithRetryAfter() throws Exception { + send(batch(spins(50))).andExpect(status().isAccepted()); + send(batch(spins(50))).andExpect(status().isAccepted()); + send(batch(spins(20))).andExpect(status().isAccepted()); + + send(batch(spins(1))) + .andExpect(status().isTooManyRequests()) + .andExpect(header().exists(HttpHeaders.RETRY_AFTER)) + .andExpect(jsonPath("$.error").value("rate_limited")); + assertThat(count()).isEqualTo(120); + + clock.advance(Duration.ofMinutes(1)); + send(batch(spins(1))).andExpect(status().isAccepted()); + } + + @Test + void getIsNotAllowed() throws Exception { + mockMvc.perform(get("/api/events")).andExpect(status().isMethodNotAllowed()); + } + + private ResultActions send(String body) throws Exception { + return mockMvc.perform(post("/api/events").contentType(MediaType.APPLICATION_JSON).content(body)); + } + + private long count() { + return jdbcClient.sql("SELECT count(*) FROM analytics_event").query(Long.class).single(); + } + + private List> spins(int n) { + List> events = new ArrayList<>(); + for (int i = 0; i < n; i++) { + events.add(event("spin", Map.of("categoryCount", 3))); + } + return events; + } + + private Map event(String name, Map props) { + Map event = new LinkedHashMap<>(); + event.put("eventId", UUID.randomUUID().toString()); + event.put("name", name); + event.put("occurredAt", clock.instant().toString()); + event.put("props", props); + return event; + } + + private static Map selfEvalProps(String questionId) { + Map props = new LinkedHashMap<>(); + props.put("questionId", questionId); + props.put("aliasResult", "partial"); + props.put("result", "knew"); + props.put("box", 3); + props.put("wasDue", true); + return props; + } + + private Map envelope(List> events) { + Map body = new LinkedHashMap<>(); + body.put("installId", installId); + body.put("platform", "android"); + body.put("appVersion", "1.2.0"); + body.put("events", events); + return body; + } + + private String batch(List> events) { + return jsonMapper.writeValueAsString(envelope(events)); + } +} diff --git a/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsTestClock.java b/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsTestClock.java new file mode 100644 index 0000000..ffe2538 --- /dev/null +++ b/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsTestClock.java @@ -0,0 +1,25 @@ +package com.meteucar.mulakatslot.analytics; + +import com.meteucar.mulakatslot.auth.MutableClock; +import java.time.Instant; +import java.time.ZoneOffset; +import org.springframework.boot.test.context.TestConfiguration; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Primary; + +/** + * Analitik entegrasyon testlerinin ortak saati. Testler aynı yapılandırmayı + * kullandığı için Spring context'i (ve Postgres konteynerini) paylaşıyorlar. + * + *

Rate limit dakika penceresiyle çalışıyor; testler her başta saati bir + * dakika ilerletip temiz bir pencereyle başlar. + */ +@TestConfiguration(proxyBeanMethods = false) +class AnalyticsTestClock { + + @Bean + @Primary + MutableClock analyticsClock() { + return new MutableClock(Instant.parse("2026-11-17T12:00:00Z"), ZoneOffset.UTC); + } +} From cb2c7cd61039f22521d482038318d66726ed324e Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:12:14 +0300 Subject: [PATCH 05/17] =?UTF-8?q?feat(analytics):=20/api/events=20i=C3=A7i?= =?UTF-8?q?n=20CORS?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Yalnızca olay zincirinde, yalnızca capacitor://localhost ve https://localhost. Kaynak bean değil; diğer uçların CORS davranışı değişmedi (testle doğrulandı). Retry-After expose edildi. Co-Authored-By: Claude Opus 5.5 --- .../mulakatslot/config/SecurityConfig.java | 36 +++++++- .../analytics/AnalyticsCorsTest.java | 88 +++++++++++++++++++ 2 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsCorsTest.java diff --git a/backend/src/main/java/com/meteucar/mulakatslot/config/SecurityConfig.java b/backend/src/main/java/com/meteucar/mulakatslot/config/SecurityConfig.java index 505f68c..17a7bd5 100644 --- a/backend/src/main/java/com/meteucar/mulakatslot/config/SecurityConfig.java +++ b/backend/src/main/java/com/meteucar/mulakatslot/config/SecurityConfig.java @@ -1,6 +1,8 @@ package com.meteucar.mulakatslot.config; import com.meteucar.mulakatslot.auth.GithubAuthenticationSuccessHandler; +import java.time.Duration; +import java.util.List; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.Order; @@ -11,6 +13,9 @@ import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer; import org.springframework.security.config.http.SessionCreationPolicy; import org.springframework.security.web.SecurityFilterChain; +import org.springframework.web.cors.CorsConfiguration; +import org.springframework.web.cors.CorsConfigurationSource; +import org.springframework.web.cors.UrlBasedCorsConfigurationSource; /** * Üç filtre zinciri var: iki farklı oturum modeli (OAuth el sıkışması ve @@ -20,6 +25,8 @@ @EnableWebSecurity public class SecurityConfig { + private static final String EVENTS_PATH = "/api/events"; + /** * GitHub el sıkışması. Yetkilendirme isteğinin durumu (state parametresi, * PKCE doğrulayıcısı) iki HTTP isteği arasında saklanmak zorunda, bu yüzden @@ -51,15 +58,42 @@ SecurityFilterChain oauthFilterChain(HttpSecurity http, @Order(2) SecurityFilterChain eventsFilterChain(HttpSecurity http) throws Exception { return http - .securityMatcher("/api/events") + .securityMatcher(EVENTS_PATH) // Yalnızca POST eşlenmiş; diğer metotlara Spring MVC 405 döner. .authorizeHttpRequests(auth -> auth.anyRequest().permitAll()) + .cors(cors -> cors.configurationSource(eventsCorsSource())) .csrf(AbstractHttpConfigurer::disable) .sessionManagement(session -> session .sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .build(); } + /** + * Mobil uygulamanın WebView origin'leri: iOS'ta capacitor://localhost, + * Android'de https://localhost. Web aynı origin'den geliyor, CORS'a + * ihtiyacı yok. + * + *

Bilerek bean değil: CorsConfigurationSource bean'i diğer zincirler + * ve Spring MVC tarafından da bulunup kullanılabilirdi. Diğer uçların + * CORS davranışı (hiç izin yok) değişmesin. + * + *

Cookie ve kimlik taşınmadığı için credentials kapalı. Retry-After + * açıkça izinli: cross-origin yanıtta istemci onu başka türlü okuyamaz. + */ + private static CorsConfigurationSource eventsCorsSource() { + CorsConfiguration config = new CorsConfiguration(); + config.setAllowedOrigins(List.of("capacitor://localhost", "https://localhost")); + config.setAllowedMethods(List.of("POST")); + config.setAllowedHeaders(List.of("Content-Type")); + config.setExposedHeaders(List.of("Retry-After")); + config.setAllowCredentials(false); + config.setMaxAge(Duration.ofDays(1)); + + UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); + source.registerCorsConfiguration(EVENTS_PATH, config); + return source; + } + /** * API. Kimlik yalnızca Authorization başlığındaki Bearer JWT ile * doğrulanır, sunucuda oturum tutulmaz. diff --git a/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsCorsTest.java b/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsCorsTest.java new file mode 100644 index 0000000..62c5b4f --- /dev/null +++ b/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsCorsTest.java @@ -0,0 +1,88 @@ +package com.meteucar.mulakatslot.analytics; + +import static org.hamcrest.Matchers.containsString; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.options; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; + +import com.meteucar.mulakatslot.TestcontainersConfiguration; +import com.meteucar.mulakatslot.auth.MutableClock; +import java.time.Duration; +import java.util.UUID; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc; +import org.springframework.context.annotation.Import; +import org.springframework.http.HttpHeaders; +import org.springframework.http.MediaType; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder; + +/** + * CORS yalnızca /api/events için ve yalnızca mobil WebView origin'lerine + * açık; diğer uçlarda hiçbir origin'e izin yok. + */ +@Import({TestcontainersConfiguration.class, AnalyticsTestClock.class}) +@SpringBootTest +@AutoConfigureMockMvc +class AnalyticsCorsTest { + + @Autowired + private MockMvc mockMvc; + + @Autowired + private MutableClock clock; + + @ParameterizedTest + @ValueSource(strings = {"capacitor://localhost", "https://localhost"}) + void preflightToEventsIsAllowedForMobileOrigins(String origin) throws Exception { + mockMvc.perform(preflight("/api/events", origin)) + .andExpect(status().isOk()) + .andExpect(header().string(HttpHeaders.ACCESS_CONTROL_ALLOW_ORIGIN, origin)) + .andExpect(header().string(HttpHeaders.ACCESS_CONTROL_ALLOW_METHODS, containsString("POST"))) + .andExpect(header().doesNotExist(HttpHeaders.ACCESS_CONTROL_ALLOW_CREDENTIALS)); + } + + @Test + void actualPostExposesRetryAfter() throws Exception { + clock.advance(Duration.ofMinutes(1)); + String body = """ + {"installId":"%s","platform":"ios","appVersion":"1.0.0", + "events":[{"eventId":"%s","name":"spin","occurredAt":"%s","props":{"categoryCount":2}}]}""" + .formatted(UUID.randomUUID(), UUID.randomUUID(), clock.instant()); + + mockMvc.perform(post("/api/events").header(HttpHeaders.ORIGIN, "capacitor://localhost") + .contentType(MediaType.APPLICATION_JSON).content(body)) + .andExpect(status().isAccepted()) + .andExpect(header().string(HttpHeaders.ACCESS_CONTROL_ALLOW_ORIGIN, "capacitor://localhost")) + .andExpect(header().string(HttpHeaders.ACCESS_CONTROL_EXPOSE_HEADERS, containsString("Retry-After"))); + } + + @ParameterizedTest + // http://localhost değil: MockMvc'nin kendi origin'i, CORS isteği sayılmaz. + @ValueSource(strings = {"https://evil.example", "http://localhost:5173", "capacitor://evil"}) + void preflightToEventsIsRejectedForOtherOrigins(String origin) throws Exception { + mockMvc.perform(preflight("/api/events", origin)) + .andExpect(status().isForbidden()) + .andExpect(header().doesNotExist(HttpHeaders.ACCESS_CONTROL_ALLOW_ORIGIN)); + } + + /** Mobil origin'leri yalnızca olay ucu için eklendi; senkron uçları değişmedi. */ + @ParameterizedTest + @ValueSource(strings = {"/api/progress", "/api/questions", "/api/auth/refresh", "/api/me"}) + void otherEndpointsGetNoCorsHeaders(String path) throws Exception { + mockMvc.perform(preflight(path, "capacitor://localhost")) + .andExpect(header().doesNotExist(HttpHeaders.ACCESS_CONTROL_ALLOW_ORIGIN)); + } + + private static MockHttpServletRequestBuilder preflight(String path, String origin) { + return options(path) + .header(HttpHeaders.ORIGIN, origin) + .header(HttpHeaders.ACCESS_CONTROL_REQUEST_METHOD, "POST") + .header(HttpHeaders.ACCESS_CONTROL_REQUEST_HEADERS, "content-type"); + } +} From 43229d60fa2f86cd0206f1bc9acc165cd310db96 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:13:19 +0300 Subject: [PATCH 06/17] =?UTF-8?q?feat(analytics):=2013=20aydan=20eski=20ol?= =?UTF-8?q?aylar=C4=B1=20silen=20g=C3=BCnl=C3=BCk=20i=C5=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- .../analytics/AnalyticsRetentionJob.java | 49 +++++++++++++ .../mulakatslot/config/SchedulingConfig.java | 5 +- .../analytics/AnalyticsRetentionJobTest.java | 72 +++++++++++++++++++ 3 files changed, 124 insertions(+), 2 deletions(-) create mode 100644 backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsRetentionJob.java create mode 100644 backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsRetentionJobTest.java diff --git a/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsRetentionJob.java b/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsRetentionJob.java new file mode 100644 index 0000000..77a272e --- /dev/null +++ b/backend/src/main/java/com/meteucar/mulakatslot/analytics/AnalyticsRetentionJob.java @@ -0,0 +1,49 @@ +package com.meteucar.mulakatslot.analytics; + +import java.time.Clock; +import java.time.OffsetDateTime; +import java.time.ZoneOffset; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.jdbc.core.simple.JdbcClient; +import org.springframework.scheduling.annotation.Scheduled; +import org.springframework.stereotype.Component; + +/** + * 13 aydan eski kullanım olaylarını siler. + * + *

13 ay: yıllık karşılaştırma (bu ay ile geçen yılın aynı ayı) için + * gereken en kısa süre. Gizlilik politikasındaki süre bununla aynı olmalı. + * + *

occurred_at'e göre: doğrulama onu en fazla 7 gün geriye kabul ettiği + * için received_at'ten sapması küçük. Silme günlük bir tam tarama; bu hacimde + * sorun değil, büyürse aylık partition'a geçilir (yol haritası, Faz 2). + */ +@Component +public class AnalyticsRetentionJob { + + static final int RETENTION_MONTHS = 13; + + private static final Logger log = LoggerFactory.getLogger(AnalyticsRetentionJob.class); + + private final JdbcClient jdbcClient; + private final Clock clock; + + public AnalyticsRetentionJob(JdbcClient jdbcClient, Clock clock) { + this.jdbcClient = jdbcClient; + this.clock = clock; + } + + /** Günde bir; refresh token temizliğinden (03:00) yarım saat sonra. */ + @Scheduled(cron = "0 30 3 * * *") + public int deleteExpiredEvents() { + OffsetDateTime cutoff = OffsetDateTime.now(clock.withZone(ZoneOffset.UTC)).minusMonths(RETENTION_MONTHS); + int deleted = jdbcClient.sql("DELETE FROM analytics_event WHERE occurred_at < :cutoff") + .param("cutoff", cutoff) + .update(); + if (deleted > 0) { + log.info("Saklama: {} tarihinden eski {} kullanım olayı silindi", cutoff, deleted); + } + return deleted; + } +} diff --git a/backend/src/main/java/com/meteucar/mulakatslot/config/SchedulingConfig.java b/backend/src/main/java/com/meteucar/mulakatslot/config/SchedulingConfig.java index 1582641..ac42133 100644 --- a/backend/src/main/java/com/meteucar/mulakatslot/config/SchedulingConfig.java +++ b/backend/src/main/java/com/meteucar/mulakatslot/config/SchedulingConfig.java @@ -4,8 +4,9 @@ import org.springframework.scheduling.annotation.EnableScheduling; /** - * Zamanlanmış işleri açar. Şimdilik tek iş var: süresi dolmuş refresh - * token'larının temizliği (RefreshTokenCleanupJob). + * Zamanlanmış işleri açar: süresi dolmuş refresh token'larının temizliği + * (RefreshTokenCleanupJob) ve 13 aydan eski kullanım olaylarının silinmesi + * (AnalyticsRetentionJob). */ @Configuration @EnableScheduling diff --git a/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsRetentionJobTest.java b/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsRetentionJobTest.java new file mode 100644 index 0000000..b6ebd49 --- /dev/null +++ b/backend/src/test/java/com/meteucar/mulakatslot/analytics/AnalyticsRetentionJobTest.java @@ -0,0 +1,72 @@ +package com.meteucar.mulakatslot.analytics; + +import static org.assertj.core.api.Assertions.assertThat; + +import com.meteucar.mulakatslot.TestcontainersConfiguration; +import com.meteucar.mulakatslot.auth.MutableClock; +import java.time.OffsetDateTime; +import java.time.ZoneOffset; +import java.util.List; +import java.util.UUID; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.context.annotation.Import; +import org.springframework.jdbc.core.simple.JdbcClient; + +@Import({TestcontainersConfiguration.class, AnalyticsTestClock.class}) +@SpringBootTest +class AnalyticsRetentionJobTest { + + @Autowired + private AnalyticsRetentionJob retentionJob; + + @Autowired + private JdbcClient jdbcClient; + + @Autowired + private MutableClock clock; + + private OffsetDateTime now; + + @BeforeEach + void setUp() { + jdbcClient.sql("DELETE FROM analytics_event").update(); + now = OffsetDateTime.ofInstant(clock.instant(), ZoneOffset.UTC); + } + + @Test + void deletesEventsOlderThanThirteenMonthsAndKeepsTheRest() { + insert("cok-eski", now.minusMonths(13).minusDays(1)); + insert("sinirda", now.minusMonths(13).plusSeconds(1)); + insert("yeni", now.minusDays(2)); + + assertThat(retentionJob.deleteExpiredEvents()).isEqualTo(1); + + List remaining = jdbcClient.sql("SELECT props->>'label' FROM analytics_event") + .query(String.class).list(); + assertThat(remaining).containsExactlyInAnyOrder("sinirda", "yeni"); + } + + @Test + void deletesNothingWhenEverythingIsRecent() { + insert("yeni", now.minusMonths(12)); + + assertThat(retentionJob.deleteExpiredEvents()).isZero(); + } + + /** Doğrulamayı atlayıp doğrudan yazıyoruz: burada önemli olan yalnızca occurred_at. */ + private void insert(String label, OffsetDateTime occurredAt) { + jdbcClient.sql(""" + INSERT INTO analytics_event + (event_id, install_id, event_name, platform, app_version, occurred_at, props) + VALUES (:eventId, :installId, 'app_open', 'web', '1.0.0', :occurredAt, + jsonb_build_object('label', CAST(:label AS text)))""") + .param("eventId", UUID.randomUUID()) + .param("installId", UUID.randomUUID()) + .param("occurredAt", occurredAt) + .param("label", label) + .update(); + } +} From 6be8ddb2a89158e232f8538b112227d4c41245bb Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:15:02 +0300 Subject: [PATCH 07/17] =?UTF-8?q?docs(analytics):=20analiz=20sorgular?= =?UTF-8?q?=C4=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DAU/WAU, D1/D7/D30 geri dönüş, Leitner tamamlanma oranı ve alias × öz-değerlendirme matrisi (uyuşma oranı ve Cohen's kappa). Gün uygulamadaki gibi 04:00'da döner (Europe/Istanbul). Co-Authored-By: Claude Opus 5.5 --- docs/analytics/queries.sql | 283 +++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 docs/analytics/queries.sql diff --git a/docs/analytics/queries.sql b/docs/analytics/queries.sql new file mode 100644 index 0000000..368ea47 --- /dev/null +++ b/docs/analytics/queries.sql @@ -0,0 +1,283 @@ +-- Kullanım ölçümü analiz sorguları (analytics_event, V4 migration). +-- +-- Her sorgu kendi başına çalışır; psql ya da herhangi bir istemcide tek tek +-- çalıştırılır. Tablo hesapla ilişkilendirilmeyen, rastgele kurulum kimliği +-- (install_id) taşır; buradaki "kullanıcı" her yerde "kurulum" demek: aynı +-- kişi iki cihazda iki kurulum sayılır, uygulamayı silip kuran yeni kurulumdur. +-- +-- GÜN TANIMI. Uygulamadaki gibi gün 04:00'da döner (src/domain/studyDay.ts): +-- 23:50'deki oturum önceki güne sayılır, app_open.dueCount da bu güne göre +-- hesaplanıyor. Saat dilimi Europe/Istanbul: istemcinin dilimi gönderilmiyor, +-- kullanıcıların büyük kısmı Türkiye'de. Her sorgunun başındaki `e` CTE'si +-- study_day'i bu kuralla üretir; bir sorguda değiştirilirse hepsinde +-- değiştirilmeli. +-- +-- SINIRLAR. +-- * Satırlar 13 ay saklanır (AnalyticsRetentionJob): ondan eski kohortlar +-- eksik görünür. +-- * Bir kurulumun ilk olayı en fazla 7 gün geç gelebilir (çevrimdışı kuyruk): +-- son 7 günün sayıları sonradan artabilir. +-- * Opt-out eden kurulumlar hiç görünmez; oranlar ölçüme izin verenler içindir. + + +-- --------------------------------------------------------------------------- +-- 1a. Günlük aktif kurulum (DAU) — herhangi bir olay gönderen kurulumlar. +-- --------------------------------------------------------------------------- +WITH e AS ( + SELECT *, ((occurred_at AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date AS study_day + FROM analytics_event +) +SELECT study_day, + count(DISTINCT install_id) AS active_installs +FROM e +WHERE study_day >= current_date - 90 +GROUP BY study_day +ORDER BY study_day; + + +-- --------------------------------------------------------------------------- +-- 1b. DAU platforma göre. +-- --------------------------------------------------------------------------- +WITH e AS ( + SELECT *, ((occurred_at AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date AS study_day + FROM analytics_event +) +SELECT study_day, + count(DISTINCT install_id) FILTER (WHERE platform = 'web') AS web, + count(DISTINCT install_id) FILTER (WHERE platform = 'android') AS android, + count(DISTINCT install_id) FILTER (WHERE platform = 'ios') AS ios +FROM e +WHERE study_day >= current_date - 90 +GROUP BY study_day +ORDER BY study_day; + + +-- --------------------------------------------------------------------------- +-- 1c. Haftalık aktif kurulum (WAU) — takvim haftası, pazartesi başlar. +-- Son satır içinde bulunulan, henüz bitmemiş hafta. +-- --------------------------------------------------------------------------- +WITH e AS ( + SELECT *, ((occurred_at AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date AS study_day + FROM analytics_event +) +SELECT date_trunc('week', study_day)::date AS week_start, + count(DISTINCT install_id) AS active_installs +FROM e +WHERE study_day >= current_date - 7 * 26 +GROUP BY week_start +ORDER BY week_start; + + +-- --------------------------------------------------------------------------- +-- 2a. D1 / D7 / D30 geri dönüş, ilk app_open gününe göre kohort. +-- +-- DN: kohort gününden tam N gün sonra en az bir app_open olan kurulumların +-- kohorta oranı (tam gün tanımı, "N gün içinde" değil). Kohort günü + N +-- henüz tamamlanmadıysa oran NULL: eksik gün sıfır gibi görünmesin. +-- --------------------------------------------------------------------------- +WITH e AS ( + SELECT *, ((occurred_at AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date AS study_day + FROM analytics_event +), +opens AS ( + SELECT DISTINCT install_id, study_day FROM e WHERE event_name = 'app_open' +), +cohort AS ( + SELECT install_id, min(study_day) AS cohort_day FROM opens GROUP BY install_id +), +-- Bitmiş son gün: bugünün çalışma günü henüz sürüyor. +last_complete AS ( + SELECT ((now() AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date - 1 AS day +) +SELECT c.cohort_day, + count(*) AS cohort_size, + CASE WHEN c.cohort_day + 1 <= l.day THEN + round(100.0 * count(*) FILTER (WHERE EXISTS (SELECT 1 FROM opens o + WHERE o.install_id = c.install_id AND o.study_day = c.cohort_day + 1)) / count(*), 1) + END AS d1_pct, + CASE WHEN c.cohort_day + 7 <= l.day THEN + round(100.0 * count(*) FILTER (WHERE EXISTS (SELECT 1 FROM opens o + WHERE o.install_id = c.install_id AND o.study_day = c.cohort_day + 7)) / count(*), 1) + END AS d7_pct, + CASE WHEN c.cohort_day + 30 <= l.day THEN + round(100.0 * count(*) FILTER (WHERE EXISTS (SELECT 1 FROM opens o + WHERE o.install_id = c.install_id AND o.study_day = c.cohort_day + 30)) / count(*), 1) + END AS d30_pct +FROM cohort c CROSS JOIN last_complete l +GROUP BY c.cohort_day, l.day +ORDER BY c.cohort_day; + + +-- --------------------------------------------------------------------------- +-- 2b. Aynı geri dönüş, tüm kohortların toplamı. Her DN yalnızca ölçülebilir +-- (kohort günü + N tamamlanmış) kurulumlar üzerinden hesaplanır. +-- --------------------------------------------------------------------------- +WITH e AS ( + SELECT *, ((occurred_at AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date AS study_day + FROM analytics_event +), +opens AS ( + SELECT DISTINCT install_id, study_day FROM e WHERE event_name = 'app_open' +), +cohort AS ( + SELECT install_id, min(study_day) AS cohort_day FROM opens GROUP BY install_id +), +last_complete AS ( + SELECT ((now() AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date - 1 AS day +), +flags AS ( + SELECT c.install_id, c.cohort_day, + EXISTS (SELECT 1 FROM opens o WHERE o.install_id = c.install_id AND o.study_day = c.cohort_day + 1) AS back_d1, + EXISTS (SELECT 1 FROM opens o WHERE o.install_id = c.install_id AND o.study_day = c.cohort_day + 7) AS back_d7, + EXISTS (SELECT 1 FROM opens o WHERE o.install_id = c.install_id AND o.study_day = c.cohort_day + 30) AS back_d30 + FROM cohort c +) +SELECT count(*) FILTER (WHERE f.cohort_day + 1 <= l.day) AS d1_measurable, + round(100.0 * count(*) FILTER (WHERE f.cohort_day + 1 <= l.day AND back_d1) + / NULLIF(count(*) FILTER (WHERE f.cohort_day + 1 <= l.day), 0), 1) AS d1_pct, + count(*) FILTER (WHERE f.cohort_day + 7 <= l.day) AS d7_measurable, + round(100.0 * count(*) FILTER (WHERE f.cohort_day + 7 <= l.day AND back_d7) + / NULLIF(count(*) FILTER (WHERE f.cohort_day + 7 <= l.day), 0), 1) AS d7_pct, + count(*) FILTER (WHERE f.cohort_day + 30 <= l.day) AS d30_measurable, + round(100.0 * count(*) FILTER (WHERE f.cohort_day + 30 <= l.day AND back_d30) + / NULLIF(count(*) FILTER (WHERE f.cohort_day + 30 <= l.day), 0), 1) AS d30_pct +FROM flags f CROSS JOIN last_complete l; + + +-- --------------------------------------------------------------------------- +-- 3a. Leitner tekrar tamamlanma oranı, kurulum ve gün bazında. +-- +-- completion = o gün wasDue=true olan self_eval sayısı +-- ÷ o günün İLK app_open'ındaki dueCount, en fazla 1. +-- dueCount = 0 olan günler hariç (yapılacak tekrar yok, oran tanımsız). +-- Gün içinde yeni vadesi gelen kart olursa pay paydayı aşabilir; tavan bu +-- yüzden 1. +-- --------------------------------------------------------------------------- +WITH e AS ( + SELECT *, ((occurred_at AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date AS study_day + FROM analytics_event +), +first_open AS ( + SELECT DISTINCT ON (install_id, study_day) + install_id, study_day, (props ->> 'dueCount')::int AS due_count + FROM e + WHERE event_name = 'app_open' + ORDER BY install_id, study_day, occurred_at, id +), +due_reviews AS ( + SELECT install_id, study_day, count(*) AS due_reviewed + FROM e + WHERE event_name = 'self_eval' AND (props ->> 'wasDue')::boolean + GROUP BY install_id, study_day +) +SELECT f.install_id, + f.study_day, + f.due_count, + coalesce(r.due_reviewed, 0) AS due_reviewed, + round(LEAST(1.0, coalesce(r.due_reviewed, 0)::numeric / f.due_count), 3) AS completion +FROM first_open f +LEFT JOIN due_reviews r USING (install_id, study_day) +WHERE f.due_count > 0 +ORDER BY f.study_day DESC, f.install_id; + + +-- --------------------------------------------------------------------------- +-- 3b. Günlük özet: ortalama tamamlanma ve vadesi gelenlerin TAMAMINI bitiren +-- kurulumların oranı. Yalnızca o gün dueCount > 0 ile açılan kurulumlar. +-- --------------------------------------------------------------------------- +WITH e AS ( + SELECT *, ((occurred_at AT TIME ZONE 'Europe/Istanbul') - INTERVAL '4 hours')::date AS study_day + FROM analytics_event +), +first_open AS ( + SELECT DISTINCT ON (install_id, study_day) + install_id, study_day, (props ->> 'dueCount')::int AS due_count + FROM e + WHERE event_name = 'app_open' + ORDER BY install_id, study_day, occurred_at, id +), +due_reviews AS ( + SELECT install_id, study_day, count(*) AS due_reviewed + FROM e + WHERE event_name = 'self_eval' AND (props ->> 'wasDue')::boolean + GROUP BY install_id, study_day +), +per_install_day AS ( + SELECT f.study_day, + LEAST(1.0, coalesce(r.due_reviewed, 0)::numeric / f.due_count) AS completion + FROM first_open f + LEFT JOIN due_reviews r USING (install_id, study_day) + WHERE f.due_count > 0 +) +SELECT study_day, + count(*) AS installs_with_due, + round(avg(completion), 3) AS avg_completion, + round(100.0 * count(*) FILTER (WHERE completion >= 1) / count(*), 1) AS finished_all_pct +FROM per_install_day +GROUP BY study_day +ORDER BY study_day; + + +-- --------------------------------------------------------------------------- +-- 4a. Alias eşleşmesi × öz-değerlendirme matrisi (self_eval, adet). +-- Satır: uygulamanın kelime eşleşmesi (aliasResult), sütun: kullanıcının +-- kendi kararı (result). skipped: kullanıcı cevap yazmadan pas geçti. +-- --------------------------------------------------------------------------- +SELECT props ->> 'aliasResult' AS alias_result, + count(*) FILTER (WHERE props ->> 'result' = 'knew') AS knew, + count(*) FILTER (WHERE props ->> 'result' = 'partial') AS partial, + count(*) FILTER (WHERE props ->> 'result' = 'didnt') AS didnt, + count(*) AS total +FROM analytics_event +WHERE event_name = 'self_eval' +GROUP BY alias_result +ORDER BY array_position(ARRAY['match', 'partial', 'none', 'skipped'], props ->> 'aliasResult'); + + +-- --------------------------------------------------------------------------- +-- 4b. Aynı matris satır yüzdesiyle: "eşleşme X dediğinde kullanıcı ne dedi?" +-- --------------------------------------------------------------------------- +SELECT props ->> 'aliasResult' AS alias_result, + round(100.0 * count(*) FILTER (WHERE props ->> 'result' = 'knew') / count(*), 1) AS knew_pct, + round(100.0 * count(*) FILTER (WHERE props ->> 'result' = 'partial') / count(*), 1) AS partial_pct, + round(100.0 * count(*) FILTER (WHERE props ->> 'result' = 'didnt') / count(*), 1) AS didnt_pct, + count(*) AS total +FROM analytics_event +WHERE event_name = 'self_eval' +GROUP BY alias_result +ORDER BY array_position(ARRAY['match', 'partial', 'none', 'skipped'], props ->> 'aliasResult'); + + +-- --------------------------------------------------------------------------- +-- 4c. Uyuşma oranı ve Cohen's kappa (skipped hariç). +-- +-- Köşegen: match↔knew, partial↔partial, none↔didnt. +-- agreement_pct ham uyuşma. Kategoriler dengesizse (ör. çoğu cevap "knew") +-- ham oran şans eseri de yüksek çıkar; kappa bu şans payını düşer: +-- 0 civarı şanstan farksız, 0.6 üstü iyi uyuşma. +-- --------------------------------------------------------------------------- +WITH pairs AS ( + SELECT CASE props ->> 'aliasResult' + WHEN 'match' THEN 'knew' + WHEN 'partial' THEN 'partial' + WHEN 'none' THEN 'didnt' + END AS alias_as_result, + props ->> 'result' AS result + FROM analytics_event + WHERE event_name = 'self_eval' AND props ->> 'aliasResult' <> 'skipped' +), +totals AS ( + SELECT count(*)::numeric AS n, + count(*) FILTER (WHERE alias_as_result = result)::numeric AS agreed + FROM pairs +), +expected AS ( + -- Şans eseri uyuşma: her kategori için iki tarafın marjinal oranlarının çarpımı. + SELECT sum(a.cnt * r.cnt) / nullif(power((SELECT n FROM totals), 2), 0) AS p_e + FROM (SELECT alias_as_result AS k, count(*)::numeric AS cnt FROM pairs GROUP BY 1) a + JOIN (SELECT result AS k, count(*)::numeric AS cnt FROM pairs GROUP BY 1) r USING (k) +) +SELECT t.n::int AS evaluated, + round(100 * t.agreed / nullif(t.n, 0), 1) AS agreement_pct, + round((t.agreed / nullif(t.n, 0) - x.p_e) / nullif(1 - x.p_e, 0), 3) AS cohens_kappa +FROM totals t CROSS JOIN expected x; From fa1348f4b62c70abf52c8a8132279f22c26049b1 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:16:25 +0300 Subject: [PATCH 08/17] =?UTF-8?q?docs:=20kullan=C4=B1m=20=C3=B6l=C3=A7?= =?UTF-8?q?=C3=BCm=C3=BC=20kararlar=C4=B1,=20nginx=20ad=C4=B1m=C4=B1=20ve?= =?UTF-8?q?=20yol=20haritas=C4=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md'ye analitik bölümü ve yayın engeli; deploy.md'ye host nginx'te /api/events için access_log off; yol haritasında Faz 0 tetiğinin bilerek atlandığı ve Faz 2 durumu. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 59 ++++++++++++++++++++++++++++++++++++++++- docs/deploy.md | 37 ++++++++++++++++++++++++++ docs/roadmap-backend.md | 29 +++++++++++++------- 3 files changed, 115 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 13e86e7..2b12671 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 @@ -459,6 +460,62 @@ 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 ENGELİ.** Gizlilik politikası (TR ve EN, `docs/gizlilik-politikasi.md` + ve `privacy/`) ile Play veri güvenliği formu güncellenmeden istemci + tarafı yayına çıkmaz. Politika bugün "analitik kullanmıyoruz" diyor. + Metinlerde "anonim" değil, "hesabınla ilişkilendirilmeyen, rastgele + kurulum kimliği" yazılır: kalıcı bir kimlik anonim değildir. +- **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ç. + ## Yapay zekâ değerlendirmesi — denendi, kaldırıldı - **Ne denendi.** Sunucu tarafında sağlayıcıdan bağımsız bir diff --git a/docs/deploy.md b/docs/deploy.md index 1a086f3..60e6b05 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -129,6 +129,43 @@ kullanıcısı, `/opt/mulakat`. Kalan adımlar: 8081/8082'ye erişilemediğini de kontrol et: `curl -m 5 http://:8082/api/health` zaman aşımına uğramalı. +## Kullanım ölçümü ucu (`/api/events`) + +Olaylar hesapla ilişkilendirilmeyen, rastgele kurulum kimliğiyle gelir; IP +hiçbir yerde tutulmamalı. Uygulama IP saklamıyor (Tomcat erişim günlüğü +kapalı, tabloda IP kolonu yok), ama host nginx'in erişim günlüğü her isteğin +IP'sini yazar ve olay isteği o IP'yi kurulum kimliğinin gönderildiği anla +eşleştirmeye yeter. Bu uç için host nginx'e ayrı bir blok eklenir; `= ` +tam eşleşmesi `/api/` önek bloğundan önce gelir: + +```nginx +location = /api/events { + # IP + zaman + kurulum kimliği eşleşmesi olmasın. + access_log off; + # 50 olaylık batch ~15 KB; varsayılan 1 MB'ın gereği yok. + client_max_body_size 64k; + + proxy_pass http://127.0.0.1:8082; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + # X-Forwarded-For bilerek iletilmiyor: IP backend'e de ulaşmasın. +} +``` + +Sonra `sudo nginx -t && sudo systemctl reload nginx`. Doğrulama: + +```sh +curl -i -X POST https://slot.meteucar.com/api/events \ + -H 'Content-Type: application/json' -d '{}' +# 400 {"error":"invalid_batch"} beklenir; erişim günlüğünde satır olmamalı: +sudo tail -n 5 /var/log/nginx/access.log +``` + +`error_log` açık kalır ve bir hata olursa (ör. backend düşükken 502) istemci +IP'sini yazabilir; bu yalnızca hata anında ve sunucu kayıtlarının genel +saklama süresine tabi. + ## Geri alma Her `up -d` sonrası SHA `deploy-history.txt`'nin sonuna eklenir. Son satır diff --git a/docs/roadmap-backend.md b/docs/roadmap-backend.md index 358a347..a2a1e89 100644 --- a/docs/roadmap-backend.md +++ b/docs/roadmap-backend.md @@ -55,13 +55,18 @@ restic → R2 yedek imajı, supercronic ile günlük yedek, canlı compose'daki `docs/backup.md`. Geri yükleme provası, Actuator, izleme, alarmlar ve JSON log başlamadı. Faza dönülünce branch güncel main'e rebase edilir. +**Faz 2 tetiği bilerek atlandı (2026-11-17).** Faz 2 analitiği, Faz 0 +tamamlanmadan başlatıldı. Gerekçe: analitik verisi kritik değil, kullanıcı +ilerlemesi günlük pg_dump ile korunuyor. Faz 0 (sunucu dışı yedek, geri +yükleme testi, izleme), kullanıcı sayısı anlamlı hale geldiğinde yapılacak. + **Tetik listesi** — ilki gerçekleşince Faz 0'a dönülür: 1. Mobil v1.1'de giriş ve senkron yayına hazırlanırken (mobil kullanıcı verisi sunucuya gelmeden). 2. Giriş yapmış (sunucuda verisi olan) kullanıcı sayısı 50'yi geçtiğinde. 3. Faz 2 (kullanıcı metrikleri) ya da Faz 4 (topluluk soruları) başlamadan - önce. + önce. Faz 2 için bilerek atlandı (yukarıda); Faz 4 için geçerli. 4. Canlıda veri kaybı, disk sorunu ya da fark edilmeyen/uzun bir kesinti yaşandığında. 5. Sunucu taşınırken ya da Postgres ana sürümü yükseltilirken. @@ -102,17 +107,23 @@ Sonraki fazlarda güvenle değişiklik yapabilmek için güvenlik ağı. Takım ## Faz 2 — Anonim metrik ve olay toplama -Kurulun ilk koşulu: aktif kullanıcı, 7/30 gün geri dönüş ve Leitner tamamlanma oranını ölçmek. Hesapsız mobil kullanıcılar dahil, kişisel veri tutmadan. +Kurulun ilk koşulu: aktif kullanıcı, 7/30 gün geri dönüş ve Leitner tamamlanma oranını ölçmek. Hesapsız mobil kullanıcılar dahil, hesapla ilişkilendirilmeyen, rastgele kurulum kimliğiyle; ad, e-posta, IP, user-agent tutulmadan. + +**Durum (2026-11-17):** backend `feat/analytics` dalında (V4, `POST /api/events`, saklama işi, `docs/analytics/queries.sql`). İstemci ayrı adımda. + +**Yayın engeli:** gizlilik politikası (TR ve EN) ve Play veri güvenliği formu güncellenmeden istemci tarafı yayına çıkmaz. Politika bugün "analitik kullanmıyoruz" diyor. Metinlerde "anonim" değil "hesabınla ilişkilendirilmeyen, rastgele kurulum kimliği" ifadesi kullanılır. **Kapsam** -- [ ] Olay şeması: `app_open`, `spin`, `answer_submitted`, `self_assessed`, `review_completed`; her olayda istemcide üretilen rastgele cihaz kimliği (ad/e-posta yok). -- [ ] `POST /events` toplu uç: istemci olayları biriktirip toplu gönderir; çevrimdışıyken kuyrukta bekler. -- [ ] Idempotency: olay başına `eventId`, tekrar gönderimde çift kayıt yok. -- [ ] Yazma yolu: tek tabloya toplu insert, zaman bazlı partitioning (aylık) ve saklama süresi. -- [ ] Rollup: gecelik job ile günlük aktif cihaz ve cohort tabloları; dashboard bunları okur. -- [ ] Cevap kontrolü ölçümü: alias eşleşmesi ile kullanıcının öz-değerlendirmesi ne sıklıkla uyuşuyor. -- [ ] Uygulamada açık "anonim kullanım istatistiği" ayarı ve gizlilik politikasına ekleme. +- [x] Olay şeması: `app_open {dueCount}`, `spin {categoryCount}`, `answer_submitted {questionId, answerLength}`, `self_eval {questionId, aliasResult, result, box, wasDue}`; kurulum kimliği, platform ve sürüm batch zarfında. Cevap metni gönderilmez. (İlk taslaktaki `self_assessed`/`review_completed` adları kullanılmadı; `leitner_review_done` da çıkarıldı, tamamlanma `self_eval.wasDue` ve `app_open.dueCount`'tan hesaplanıyor.) +- [x] `POST /api/events` toplu uç: en fazla 50 olay, geçersiz olay batch'i düşürmez, kurulum başına ve genel rate limit, mobil WebView origin'leri için CORS. +- [ ] İstemci: olayları biriktirip toplu gönderir, çevrimdışıyken kuyrukta bekler (istemci adımı). +- [x] Idempotency: olay başına `eventId`, tekrar gönderimde çift kayıt yok. +- [x] Yazma yolu: tek tabloya toplu insert, 13 ay saklama. Aylık partitioning henüz yok; hacim gerektirince. +- [ ] Rollup: gecelik job ile günlük aktif cihaz ve cohort tabloları; dashboard bunları okur. Şimdilik `docs/analytics/queries.sql` elle çalıştırılıyor. +- [x] Cevap kontrolü ölçümü: alias eşleşmesi × öz-değerlendirme matrisi, uyuşma oranı ve Cohen's kappa (`queries.sql`). +- [ ] Uygulamada açık kullanım ölçümü ayarı ve gizlilik politikasına ekleme — **yayın engeli** (yukarıda). +- [ ] Host nginx'te `/api/events` için `access_log off` (`docs/deploy.md`, "Kullanım ölçümü ucu"). **Bitti tanımı:** Grafana'da DAU, 7/30 gün retention ve Leitner tamamlanma oranı panelleri canlı veriyle çalışıyor. From 29c5dd05ee88b5a4ee1b0eb58c4893ed307ddb53 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 17:58:40 +0300 Subject: [PATCH 09/17] =?UTF-8?q?docs(analytics):=2004:00=20g=C3=BCn=20s?= =?UTF-8?q?=C4=B1n=C4=B1r=C4=B1n=C4=B1n=20gerek=C3=A7esi,=20Faz=202=20ba?= =?UTF-8?q?=C5=9Fl=C4=B1=C4=9F=C4=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Gün sınırı bilinçli olarak 04:00 (Europe/Istanbul): dueCount uygulamanın çalışma gününe göre hesaplanıyor, gece yarısı gece oturumlarını ikiye bölüp DAU ve D1'i şişirirdi. Önceki açıklamadaki 23:50 örneği yanlıştı. Co-Authored-By: Claude Opus 5.5 --- docs/analytics/queries.sql | 25 +++++++++++++++++++------ docs/roadmap-backend.md | 2 +- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/analytics/queries.sql b/docs/analytics/queries.sql index 368ea47..ce07425 100644 --- a/docs/analytics/queries.sql +++ b/docs/analytics/queries.sql @@ -5,12 +5,25 @@ -- (install_id) taşır; buradaki "kullanıcı" her yerde "kurulum" demek: aynı -- kişi iki cihazda iki kurulum sayılır, uygulamayı silip kuran yeni kurulumdur. -- --- GÜN TANIMI. Uygulamadaki gibi gün 04:00'da döner (src/domain/studyDay.ts): --- 23:50'deki oturum önceki güne sayılır, app_open.dueCount da bu güne göre --- hesaplanıyor. Saat dilimi Europe/Istanbul: istemcinin dilimi gönderilmiyor, --- kullanıcıların büyük kısmı Türkiye'de. Her sorgunun başındaki `e` CTE'si --- study_day'i bu kuralla üretir; bir sorguda değiştirilirse hepsinde --- değiştirilmeli. +-- GÜN TANIMI: Europe/Istanbul saatiyle 04:00 — gece yarısı DEĞİL, bilinçli. +-- 00:00–03:59 arasındaki olaylar önceki güne sayılır. +-- +-- Gerekçe: +-- 1. Uygulamanın kendi günü 04:00'da dönüyor (src/domain/studyDay.ts, +-- CLAUDE.md "Gün 04:00'da döner"). app_open.dueCount o güne göre +-- hesaplanıyor; analiz günü farklı olsaydı Leitner oranında pay +-- (wasDue self_eval) ile payda (dueCount) farklı günleri sayardı. +-- 2. Gece yarısını aşan tek bir oturum (23:30–00:30) gece yarısı sınırında +-- iki güne bölünür: DAU şişer, kurulum ertesi gün "geri dönmüş" sayılır ve +-- D1 yapay olarak yükselir. +-- +-- Saat dilimi Europe/Istanbul, çünkü istemci kendi dilimini göndermiyor ve +-- kullanıcıların büyük kısmı Türkiye'de. Uygulama cihazın yerel saatini +-- kullanıyor; yurt dışındaki bir kullanıcının günü burada birkaç saat +-- kayabilir. +-- +-- Her sorgunun başındaki `e` CTE'si study_day'i bu kuralla üretir. Kural bir +-- sorguda değişirse hepsinde değişmeli. -- -- SINIRLAR. -- * Satırlar 13 ay saklanır (AnalyticsRetentionJob): ondan eski kohortlar diff --git a/docs/roadmap-backend.md b/docs/roadmap-backend.md index a2a1e89..579c587 100644 --- a/docs/roadmap-backend.md +++ b/docs/roadmap-backend.md @@ -105,7 +105,7 @@ Sonraki fazlarda güvenle değişiklik yapabilmek için güvenlik ağı. Takım **Mülakat konusu:** Neden H2 değil Testcontainers; migration geri alma stratejisi; token yenilemenin test edilmesi. -## Faz 2 — Anonim metrik ve olay toplama +## Faz 2 — Kullanım ölçümü ve olay toplama Kurulun ilk koşulu: aktif kullanıcı, 7/30 gün geri dönüş ve Leitner tamamlanma oranını ölçmek. Hesapsız mobil kullanıcılar dahil, hesapla ilişkilendirilmeyen, rastgele kurulum kimliğiyle; ad, e-posta, IP, user-agent tutulmadan. From f0f2f0620fd9b72be8d0236e8169f9d00cabae11 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 18:16:47 +0300 Subject: [PATCH 10/17] =?UTF-8?q?feat(analytics):=20olay=20=C5=9Femalar?= =?UTF-8?q?=C4=B1=20ve=20kullan=C4=B1m=20metrikleri?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Zod şemaları backend EventPropsSchema ile birebir. dueCount, wasDue ve self_eval alanları saf fonksiyonlarda; box reducer'ın RATE sonucuyla aynı olduğu testle doğrulanıyor. Kavram eşleşme seviyesi ScoreCard ile ortak (conceptMatch): aliasResult kullanıcının gördüğü sonuçtan gelir. Co-Authored-By: Claude Opus 5.5 --- src/components/result/ScoreCard.tsx | 7 +- src/domain/conceptMatch.test.ts | 22 ++++ src/domain/conceptMatch.ts | 24 ++++ src/domain/usageEvents.test.ts | 113 +++++++++++++++++ src/domain/usageEvents.ts | 91 ++++++++++++++ src/domain/usageMetrics.test.ts | 181 ++++++++++++++++++++++++++++ src/domain/usageMetrics.ts | 105 ++++++++++++++++ 7 files changed, 541 insertions(+), 2 deletions(-) create mode 100644 src/domain/conceptMatch.test.ts create mode 100644 src/domain/conceptMatch.ts create mode 100644 src/domain/usageEvents.test.ts create mode 100644 src/domain/usageEvents.ts create mode 100644 src/domain/usageMetrics.test.ts create mode 100644 src/domain/usageMetrics.ts diff --git a/src/components/result/ScoreCard.tsx b/src/components/result/ScoreCard.tsx index bf19b93..d4d6fe4 100644 --- a/src/components/result/ScoreCard.tsx +++ b/src/components/result/ScoreCard.tsx @@ -2,6 +2,7 @@ import { useId } from "react"; import type { CSSProperties, ReactNode } from "react"; import { useCountUp } from "../../hooks/useCountUp"; +import { conceptMatchLevel } from "../../domain/conceptMatch"; import type { Evaluation, Question } from "../../domain/question"; import { CheckIcon, DashIcon } from "./icons"; import styles from "./ScoreCard.module.css"; @@ -41,8 +42,10 @@ function scoreCaption( total: number, answerEmpty: boolean, ): string { - if (hitCount === total) return "Tüm kavramlar cevabında geçiyor."; - if (hitCount > 0) { + // Seviye kullanım ölçümüyle ortak (aliasResult): bkz. domain/conceptMatch.ts. + const level = conceptMatchLevel(hitCount, total); + if (level === "all") return "Tüm kavramlar cevabında geçiyor."; + if (level === "some") { return `${total} kavramdan ${hitCount}'${possessiveSuffix(hitCount)} cevabında geçiyor.`; } if (answerEmpty) return `${total} kavramdan hiçbiri cevabında geçmedi.`; diff --git a/src/domain/conceptMatch.test.ts b/src/domain/conceptMatch.test.ts new file mode 100644 index 0000000..b928cad --- /dev/null +++ b/src/domain/conceptMatch.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it } from "vitest"; + +import { conceptMatchLevel } from "./conceptMatch"; + +describe("conceptMatchLevel", () => { + it("tüm kavramlar geçiyorsa all", () => { + expect(conceptMatchLevel(3, 3)).toBe("all"); + }); + + it("en az biri geçiyorsa some", () => { + expect(conceptMatchLevel(1, 3)).toBe("some"); + expect(conceptMatchLevel(2, 3)).toBe("some"); + }); + + it("hiçbiri geçmiyorsa none", () => { + expect(conceptMatchLevel(0, 3)).toBe("none"); + }); + + it("kavramı olmayan soru all: eksik kavram yok", () => { + expect(conceptMatchLevel(0, 0)).toBe("all"); + }); +}); diff --git a/src/domain/conceptMatch.ts b/src/domain/conceptMatch.ts new file mode 100644 index 0000000..2864805 --- /dev/null +++ b/src/domain/conceptMatch.ts @@ -0,0 +1,24 @@ +/* ------------------------------------------------------------------ */ +/* Kavram eşleşmesinin seviyesi — kullanıcının gördüğü sonuç */ +/* ------------------------------------------------------------------ */ + +/* + Sonuç ekranı (ScoreCard) alt yazıyı bu seviyeye göre seçiyor; kullanım + ölçümündeki self_eval.aliasResult da buradan geliyor. Metrik kullanıcının + gördüğü sonucu onun kendi değerlendirmesiyle karşılaştırıyor, iki yer bu + yüzden aynı fonksiyonu kullanır, ayrı ayrı hesaplamaz. +*/ + +/** + * all — tüm kavramlar geçiyor ("Tüm kavramlar cevabında geçiyor.") + * some — en az biri ("3 kavramdan 2'si cevabında geçiyor.") + * none — hiçbiri + */ +export type ConceptMatchLevel = "all" | "some" | "none"; + +/** Kavramı olmayan soru (total 0) "all" sayılır: eksik kavram yok. */ +export function conceptMatchLevel(hitCount: number, total: number): ConceptMatchLevel { + if (hitCount >= total) return "all"; + if (hitCount > 0) return "some"; + return "none"; +} diff --git a/src/domain/usageEvents.test.ts b/src/domain/usageEvents.test.ts new file mode 100644 index 0000000..2000858 --- /dev/null +++ b/src/domain/usageEvents.test.ts @@ -0,0 +1,113 @@ +import { describe, expect, it } from "vitest"; + +import { eventBatchSchema, usageEventSchema } from "./usageEvents"; + +/* + Sınır değerleri backend'deki EventValidatorTest ile aynı. Burada geçen + bir olay orada da geçmeli; aksi halde sunucu onu sessizce atlar. +*/ + +function accepts(event: unknown): boolean { + return usageEventSchema.safeParse(event).success; +} + +const selfEval = { + questionId: "java-equals-hashcode", + aliasResult: "partial", + result: "knew", + box: 3, + wasDue: true, +}; + +describe("usageEventSchema", () => { + it("dört olayı da kabul eder", () => { + expect(accepts({ name: "app_open", props: { dueCount: 0 } })).toBe(true); + expect(accepts({ name: "spin", props: { categoryCount: 1 } })).toBe(true); + expect(accepts({ name: "answer_submitted", props: { questionId: "sql-index", answerLength: 0 } })).toBe(true); + expect(accepts({ name: "self_eval", props: selfEval })).toBe(true); + }); + + it("listede olmayan adı reddeder", () => { + expect(accepts({ name: "leitner_review_done", props: { box: 2 } })).toBe(false); + expect(accepts({ name: "APP_OPEN", props: { dueCount: 0 } })).toBe(false); + }); + + it("aralıkların iki ucu backend'le aynı", () => { + expect(accepts({ name: "app_open", props: { dueCount: -1 } })).toBe(false); + expect(accepts({ name: "app_open", props: { dueCount: 10_000 } })).toBe(true); + expect(accepts({ name: "app_open", props: { dueCount: 10_001 } })).toBe(false); + expect(accepts({ name: "spin", props: { categoryCount: 0 } })).toBe(false); + expect(accepts({ name: "spin", props: { categoryCount: 100 } })).toBe(true); + expect(accepts({ name: "spin", props: { categoryCount: 101 } })).toBe(false); + expect(accepts({ name: "answer_submitted", props: { questionId: "q", answerLength: 5000 } })).toBe(true); + expect(accepts({ name: "answer_submitted", props: { questionId: "q", answerLength: 5001 } })).toBe(false); + expect(accepts({ name: "self_eval", props: { ...selfEval, box: 0 } })).toBe(false); + expect(accepts({ name: "self_eval", props: { ...selfEval, box: 5 } })).toBe(true); + expect(accepts({ name: "self_eval", props: { ...selfEval, box: 6 } })).toBe(false); + }); + + it("ondalık, metin olarak sayı ve eksik alanı reddeder", () => { + expect(accepts({ name: "spin", props: { categoryCount: 3.5 } })).toBe(false); + expect(accepts({ name: "spin", props: { categoryCount: "3" } })).toBe(false); + expect(accepts({ name: "app_open", props: {} })).toBe(false); + const withoutWasDue: Partial = { ...selfEval }; + delete withoutWasDue.wasDue; + expect(accepts({ name: "self_eval", props: withoutWasDue })).toBe(false); + expect(accepts({ name: "self_eval", props: { ...selfEval, wasDue: "true" } })).toBe(false); + }); + + it("enum değerleri backend'le aynı", () => { + for (const aliasResult of ["match", "partial", "none", "skipped"]) { + for (const result of ["knew", "partial", "didnt"]) { + expect(accepts({ name: "self_eval", props: { ...selfEval, aliasResult, result } })).toBe(true); + } + } + expect(accepts({ name: "self_eval", props: { ...selfEval, aliasResult: "MATCH" } })).toBe(false); + }); + + it("soru kimliği dar karakter kümesinde", () => { + const submit = (questionId: string) => accepts({ name: "answer_submitted", props: { questionId, answerLength: 1 } }); + expect(submit("a".repeat(128))).toBe(true); + expect(submit("a".repeat(129))).toBe(false); + expect(submit("")).toBe(false); + expect(submit("bir cevap")).toBe(false); + expect(submit("ğ-soru")).toBe(false); + }); + + it("props'taki şema dışı alanı atar", () => { + const parsed = usageEventSchema.parse({ name: "spin", props: { categoryCount: 2, answer: "metin" } }); + expect(parsed.props).toEqual({ categoryCount: 2 }); + }); +}); + +describe("eventBatchSchema", () => { + const event = { + eventId: "0b1c2d3e-4f50-4617-8293-a4b5c6d7e8f9", + name: "app_open", + occurredAt: "2026-11-17T12:00:00.000Z", + props: { dueCount: 1 }, + }; + const batch = (overrides: object) => ({ + installId: "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b", + platform: "android", + appVersion: "1.2.0", + events: [event], + ...overrides, + }); + + it("geçerli zarfı kabul eder", () => { + expect(eventBatchSchema.safeParse(batch({})).success).toBe(true); + }); + + it("1–50 olay", () => { + expect(eventBatchSchema.safeParse(batch({ events: [] })).success).toBe(false); + expect(eventBatchSchema.safeParse(batch({ events: Array(50).fill(event) })).success).toBe(true); + expect(eventBatchSchema.safeParse(batch({ events: Array(51).fill(event) })).success).toBe(false); + }); + + it("platform ve sürüm biçimi backend'le aynı", () => { + expect(eventBatchSchema.safeParse(batch({ platform: "desktop" })).success).toBe(false); + expect(eventBatchSchema.safeParse(batch({ appVersion: "1.0" })).success).toBe(false); + expect(eventBatchSchema.safeParse(batch({ appVersion: "1.0.0-beta" })).success).toBe(false); + }); +}); diff --git a/src/domain/usageEvents.ts b/src/domain/usageEvents.ts new file mode 100644 index 0000000..6e05bbd --- /dev/null +++ b/src/domain/usageEvents.ts @@ -0,0 +1,91 @@ +import { z } from "zod"; + +import { MAX_ANSWER_LENGTH } from "./progress"; + +/* ------------------------------------------------------------------ */ +/* Kullanım ölçümü — olay sözleşmesi */ +/* ------------------------------------------------------------------ */ + +/* + Backend'deki EventPropsSchema (backend/.../analytics/EventPropsSchema.java) + ve EventValidator ile BİREBİR aynı: ad listesi, alanlar, tipler, aralıklar. + Biri değişirse öteki de değişir; backend şemada olmayan alanı atar, aralık + dışını ise olayı atlatarak sessizce kaybeder. + + Cevap METNİ hiçbir olayda yok; yalnızca uzunluğu. +*/ + +const intBetween = (min: number, max: number) => z.number().int().min(min).max(max); + +/** Backend IdField ile aynı: serbest metin bu tabloya girmesin. */ +export const QUESTION_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/; +const questionId = z.string().regex(QUESTION_ID_PATTERN); + +export const ALIAS_RESULTS = ["match", "partial", "none", "skipped"] as const; +export const SELF_EVAL_RESULTS = ["knew", "partial", "didnt"] as const; + +export const appOpenPropsSchema = z.object({ + /** Açılış anında vadesi gelmiş kart sayısı (bkz. usageMetrics.dueCountOf). */ + dueCount: intBetween(0, 10_000), +}); + +export const spinPropsSchema = z.object({ + categoryCount: intBetween(1, 100), +}); + +export const answerSubmittedPropsSchema = z.object({ + questionId, + answerLength: intBetween(0, MAX_ANSWER_LENGTH), +}); + +export const selfEvalPropsSchema = z.object({ + questionId, + aliasResult: z.enum(ALIAS_RESULTS), + result: z.enum(SELF_EVAL_RESULTS), + /** Öz-değerlendirmeden SONRAKİ kutu. */ + box: intBetween(1, 5), + wasDue: z.boolean(), +}); + +/** track()'e verilen olay: ad ve ona ait props. */ +export const usageEventSchema = z.discriminatedUnion("name", [ + z.object({ name: z.literal("app_open"), props: appOpenPropsSchema }), + z.object({ name: z.literal("spin"), props: spinPropsSchema }), + z.object({ name: z.literal("answer_submitted"), props: answerSubmittedPropsSchema }), + z.object({ name: z.literal("self_eval"), props: selfEvalPropsSchema }), +]); +export type UsageEvent = z.infer; +export type UsageEventName = UsageEvent["name"]; +export type SelfEvalProps = z.infer; + +export const USAGE_EVENT_NAMES = ["app_open", "spin", "answer_submitted", "self_eval"] as const; + +/** + * Kuyruktaki olay: kimliği ve zamanı track() anında verilir, tekrar + * denemelerde değişmez (backend tekrarları eventId ile ayıklıyor). + * props burada yeniden doğrulanmaz; track() zaten doğruladı, depodan + * okurken şekil kontrolü yeter. + */ +export const queuedEventSchema = z.object({ + eventId: z.uuid(), + name: z.enum(USAGE_EVENT_NAMES), + occurredAt: z.iso.datetime(), + props: z.record(z.string(), z.unknown()), +}); +export type QueuedEvent = z.infer; + +/** Backend EventValidator.MAX_EVENTS_PER_BATCH. */ +export const MAX_EVENTS_PER_BATCH = 50; + +export const USAGE_PLATFORMS = ["web", "android", "ios"] as const; +export type UsagePlatform = (typeof USAGE_PLATFORMS)[number]; + +/** POST /api/events gövdesi. */ +export const eventBatchSchema = z.object({ + installId: z.uuid(), + platform: z.enum(USAGE_PLATFORMS), + /** package.json sürümü; backend X.Y.Z istiyor. */ + appVersion: z.string().regex(/^\d{1,4}\.\d{1,4}\.\d{1,4}$/), + events: z.array(queuedEventSchema).min(1).max(MAX_EVENTS_PER_BATCH), +}); +export type EventBatch = z.infer; diff --git a/src/domain/usageMetrics.test.ts b/src/domain/usageMetrics.test.ts new file mode 100644 index 0000000..165809f --- /dev/null +++ b/src/domain/usageMetrics.test.ts @@ -0,0 +1,181 @@ +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; + +import type { Box, QuestionProgress, SelfRating } from "./progress"; +import type { Category, Evaluation, Question } from "./question"; +import { initialSessionState, sessionReducer } from "./session"; +import { categoryCountOf, dueCountOf, selfEvalPropsOf } from "./usageMetrics"; + +/* Tekrar günü yerel takvime bağlı (studyDay.ts, 04:00). */ +beforeAll(() => { + vi.stubEnv("TZ", "Europe/Istanbul"); +}); +afterAll(() => { + vi.unstubAllEnvs(); +}); + +/** Yerel saat; ay 1'den başlar. */ +function local(year: number, month: number, day: number, hour = 0, minute = 0): Date { + return new Date(year, month - 1, day, hour, minute); +} + +function makeQuestion(id: string, category: Category = "sql", conceptCount = 3): Question { + return { + id, + category, + kind: "definition", + topic: "Index", + difficulty: 1, + prompt: `${id} için soru metni`, + modelAnswer: "Yeterince uzun bir örnek cevap metni.", + keyConcepts: Array.from({ length: conceptCount }, (_, i) => ({ + id: `kavram-${i + 1}`, + label: `Kavram ${i + 1}`, + aliases: [`kavram${i + 1}`], + anchors: ["Kavramı anlatan yeterince uzun bir çapa cümlesi."], + })), + }; +} + +function seen(questionId: string, box: Box, at: Date): QuestionProgress { + return { questionId, box, lastSeenAt: at.toISOString(), attempts: [] }; +} + +function evaluation(hitCount: number): Evaluation { + const hits = Array.from({ length: hitCount }, (_, i) => `kavram-${i + 1}`); + return { source: "lexical", hits, missing: [] }; +} + +describe("dueCountOf", () => { + const sqlA = makeQuestion("sql-a", "sql"); + const sqlB = makeQuestion("sql-b", "sql"); + const javaA = makeQuestion("java-a", "java"); + const questions = [sqlA, sqlB, javaA]; + + it("yalnızca zamanı gelmiş, seçili kategorideki soruları sayar", () => { + const now = local(2026, 11, 17, 10); + const progress = { + // Kutu 1, dün görüldü: bugün 04:00'dan beri zamanı gelmiş. + "sql-a": seen("sql-a", 1, local(2026, 11, 16, 20)), + // Kutu 2, dün görüldü: yarın gelir. + "sql-b": seen("sql-b", 2, local(2026, 11, 16, 20)), + // Zamanı gelmiş ama kategori kapalı. + "java-a": seen("java-a", 1, local(2026, 11, 10, 20)), + }; + + expect(dueCountOf(progress, questions, ["sql"], now)).toBe(1); + expect(dueCountOf(progress, questions, ["sql", "java"], now)).toBe(2); + }); + + it("gün 04:00'da döner", () => { + const progress = { "sql-a": seen("sql-a", 1, local(2026, 11, 16, 20)) }; + + expect(dueCountOf(progress, questions, ["sql"], local(2026, 11, 17, 3, 59))).toBe(0); + expect(dueCountOf(progress, questions, ["sql"], local(2026, 11, 17, 4, 0))).toBe(1); + }); + + it("içerikten kalkmış sorunun kaydını saymaz", () => { + const progress = { "silinmis-soru": seen("silinmis-soru", 1, local(2026, 11, 1)) }; + + expect(dueCountOf(progress, questions, ["sql"], local(2026, 11, 17, 10))).toBe(0); + }); + + it("ileri tarihli ya da bozuk kayıt zamanı gelmiş sayılır (çekilişle aynı)", () => { + const now = local(2026, 11, 17, 10); + const progress = { + "sql-a": seen("sql-a", 3, local(2026, 12, 1)), + "sql-b": { ...seen("sql-b", 1, now), lastSeenAt: "bozuk" }, + }; + + expect(dueCountOf(progress, questions, ["sql"], now)).toBe(2); + }); + + it("hiç görülmemiş soru zamanı gelmiş değildir", () => { + expect(dueCountOf({}, questions, ["sql", "java"], local(2026, 11, 17))).toBe(0); + }); +}); + +describe("categoryCountOf", () => { + it("içeriği olmayan seçili kategoriyi saymaz", () => { + expect(categoryCountOf(["sql", "java", "docker"], ["sql", "java"])).toBe(2); + }); +}); + +describe("selfEvalPropsOf", () => { + const question = makeQuestion("sql-a", "sql", 3); + const now = local(2026, 11, 17, 10); + + const base = { + question, + previous: undefined, + evaluation: evaluation(3), + passed: false, + answer: "cevap metni", + rating: 2 as SelfRating, + now, + }; + + it("aliasResult kullanıcının gördüğü seviyeden gelir", () => { + expect(selfEvalPropsOf({ ...base, evaluation: evaluation(3) }).aliasResult).toBe("match"); + expect(selfEvalPropsOf({ ...base, evaluation: evaluation(1) }).aliasResult).toBe("partial"); + expect(selfEvalPropsOf({ ...base, evaluation: evaluation(0) }).aliasResult).toBe("none"); + }); + + it("pas geçilen ya da boş gönderilen cevap skipped", () => { + expect(selfEvalPropsOf({ ...base, passed: true, evaluation: null, answer: "" }).aliasResult).toBe("skipped"); + expect(selfEvalPropsOf({ ...base, answer: " ", evaluation: evaluation(0) }).aliasResult).toBe("skipped"); + }); + + it("puanı result'a çevirir; pas geçildiyse didnt", () => { + expect(selfEvalPropsOf({ ...base, rating: 0 }).result).toBe("didnt"); + expect(selfEvalPropsOf({ ...base, rating: 1 }).result).toBe("partial"); + expect(selfEvalPropsOf({ ...base, rating: 2 }).result).toBe("knew"); + expect(selfEvalPropsOf({ ...base, rating: 2, passed: true, evaluation: null }).result).toBe("didnt"); + }); + + it("wasDue: ilk kez görülen soru false, zamanı gelmiş kayıt true", () => { + expect(selfEvalPropsOf({ ...base, previous: undefined }).wasDue).toBe(false); + expect(selfEvalPropsOf({ ...base, previous: seen("sql-a", 1, local(2026, 11, 16, 20)) }).wasDue).toBe(true); + expect(selfEvalPropsOf({ ...base, previous: seen("sql-a", 3, local(2026, 11, 16, 20)) }).wasDue).toBe(false); + }); + + /* + box olayda "değerlendirmeden sonraki kutu". Ayrı bir hesap değil, + reducer'ın gerçekte yazdığı kutu olmalı: aynı girdilerle RATE'in + sonucuyla karşılaştırılır. + */ + it.each([ + { box: 1 as Box, rating: 2 as SelfRating, passed: false }, + { box: 3 as Box, rating: 1 as SelfRating, passed: false }, + { box: 4 as Box, rating: 0 as SelfRating, passed: false }, + { box: 5 as Box, rating: 2 as SelfRating, passed: false }, + { box: 4 as Box, rating: 2 as SelfRating, passed: true }, + ])("box reducer'ın RATE sonucuyla aynı ($box, $rating, pas: $passed)", ({ box, rating, passed }) => { + const previous = seen("sql-a", box, local(2026, 11, 1)); + const state = { + ...initialSessionState(), + phase: "evaluated" as const, + current: question, + evaluation: passed ? null : evaluation(2), + passed, + progress: { "sql-a": previous }, + }; + + const after = sessionReducer(state, { type: "RATE", rating, answer: "cevap", now }); + const props = selfEvalPropsOf({ ...base, previous, rating, passed, evaluation: state.evaluation }); + + expect(props.box).toBe(after.progress["sql-a"].box); + }); + + it("ilk kez görülen soruda kutu 1'den hesaplanır", () => { + const state = { + ...initialSessionState(), + phase: "evaluated" as const, + current: question, + evaluation: evaluation(3), + passed: false, + }; + const after = sessionReducer(state, { type: "RATE", rating: 2, answer: "cevap", now }); + + expect(selfEvalPropsOf({ ...base, previous: undefined, rating: 2 }).box).toBe(after.progress["sql-a"].box); + }); +}); diff --git a/src/domain/usageMetrics.ts b/src/domain/usageMetrics.ts new file mode 100644 index 0000000..b575b0b --- /dev/null +++ b/src/domain/usageMetrics.ts @@ -0,0 +1,105 @@ +import { conceptMatchLevel } from "./conceptMatch"; +import { isDue } from "./drawTiers"; +import { nextBox } from "./leitner"; +import type { QuestionProgress, SelfRating } from "./progress"; +import type { Category, Evaluation, Question } from "./question"; +import type { SelfEvalProps } from "./usageEvents"; + +/* ------------------------------------------------------------------ */ +/* Kullanım ölçümü — olay alanlarının türetilmesi */ +/* ------------------------------------------------------------------ */ + +/* + Leitner tamamlanma oranı (docs/analytics/queries.sql) iki sayıdan çıkıyor: + günün ilk app_open'ındaki dueCount ve o gün wasDue=true gelen self_eval + sayısı. İkisi de çekilişin "zamanı gelmiş" tanımını (drawTiers.isDue) + kullanır; ayrı bir tanım yazılırsa oran anlamını kaybeder. +*/ + +type ProgressMap = Readonly>; + +/** + * Şu an vadesi gelmiş kart sayısı: içerikte bulunan, seçili kategoride + * olan ve zamanı gelmiş sorular. Kapatılmış kategorinin kartları + * çekilişe girmiyor; sayılsalardı tamamlanma oranı yapay olarak düşerdi. + * İçerikten kalkmış sorunun kaydı da sayılmaz. + */ +export function dueCountOf( + progress: ProgressMap, + questions: readonly Question[], + activeCategories: readonly Category[], + now: Date, +): number { + const active = new Set(activeCategories); + let count = 0; + for (const question of questions) { + if (!active.has(question.category)) continue; + const entry = progress[question.id]; + if (entry !== undefined && isDue(entry, now)) count++; + } + return count; +} + +/** Seçili kategorilerden içeriği olanların sayısı. */ +export function categoryCountOf( + activeCategories: readonly Category[], + availableCategories: readonly Category[], +): number { + const available = new Set(availableCategories); + return activeCategories.filter((category) => available.has(category)).length; +} + +const RESULT_BY_RATING = ["didnt", "partial", "knew"] as const; + +export type SelfEvalInput = { + question: Question; + /** Değerlendirmeden ÖNCEKİ kayıt; soru ilk kez görülüyorsa undefined. */ + previous: QuestionProgress | undefined; + /** Pas geçildiyse null. */ + evaluation: Evaluation | null; + passed: boolean; + answer: string; + rating: SelfRating; + now: Date; +}; + +/** + * self_eval olayının alanları. + * + * - aliasResult: kullanıcının sonuç ekranında gördüğü seviye + * (conceptMatchLevel). Pas geçildiyse ya da cevap boşsa "skipped": + * kullanıcı yazmadan değerlendirdi. + * - result ve box reducer'ın RATE'iyle aynı kuralla: pas geçildiyse + * puan "bilmiyordum" sayılır, kutu nextBox'tan gelir. + * - wasDue: değerlendirme anında soru zamanı gelmiş miydi. İlk kez + * görülen soru zamanı gelmiş sayılmaz: tekrar değil, tanıtım. + */ +export function selfEvalPropsOf(input: SelfEvalInput): SelfEvalProps { + const { question, previous, evaluation, passed, answer, rating, now } = input; + const effectiveRating: SelfRating = passed ? 0 : rating; + + return { + questionId: question.id, + aliasResult: aliasResultOf(question, evaluation, passed, answer), + result: RESULT_BY_RATING[effectiveRating], + box: nextBox(previous?.box ?? 1, effectiveRating, passed), + wasDue: previous !== undefined && isDue(previous, now), + }; +} + +function aliasResultOf( + question: Question, + evaluation: Evaluation | null, + passed: boolean, + answer: string, +): SelfEvalProps["aliasResult"] { + if (passed || evaluation === null || answer.trim() === "") return "skipped"; + switch (conceptMatchLevel(evaluation.hits.length, question.keyConcepts.length)) { + case "all": + return "match"; + case "some": + return "partial"; + case "none": + return "none"; + } +} From 0b0cc10a5a3482a1078a6219a422fe54f426c9a6 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 18:24:21 +0300 Subject: [PATCH 11/17] =?UTF-8?q?feat(analytics):=20olay=20kuyru=C4=9Fu=20?= =?UTF-8?q?ve=20g=C3=B6nderim=20karar=C4=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Kuyruk en fazla 500 olay, taşarsa en eskiler atılır; backend'in reddedeceği 7 günden eski olaylar gönderilmeden ayıklanır. Yanıta göre: 202 sil, 400/413 at, 429 Retry-After, diğerleri artan bekleme. Co-Authored-By: Claude Opus 5.5 --- src/analytics/delivery.test.ts | 56 ++++++++++++++++++++++++++ src/analytics/delivery.ts | 63 +++++++++++++++++++++++++++++ src/analytics/queue.test.ts | 72 ++++++++++++++++++++++++++++++++++ src/analytics/queue.ts | 50 +++++++++++++++++++++++ 4 files changed, 241 insertions(+) create mode 100644 src/analytics/delivery.test.ts create mode 100644 src/analytics/delivery.ts create mode 100644 src/analytics/queue.test.ts create mode 100644 src/analytics/queue.ts diff --git a/src/analytics/delivery.test.ts b/src/analytics/delivery.test.ts new file mode 100644 index 0000000..85dbf7b --- /dev/null +++ b/src/analytics/delivery.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, it } from "vitest"; + +import { backoffDelayMs, deliveryOutcome } from "./delivery"; + +const now = new Date("2026-11-17T12:00:00.000Z"); + +describe("deliveryOutcome", () => { + it("202 gönderildi", () => { + expect(deliveryOutcome(202, null, now)).toEqual({ kind: "sent" }); + }); + + it("400 ve 413 atılır: tekrar denemenin anlamı yok", () => { + expect(deliveryOutcome(400, null, now)).toEqual({ kind: "rejected" }); + expect(deliveryOutcome(413, null, now)).toEqual({ kind: "rejected" }); + }); + + it("429 Retry-After saniyesine uyar", () => { + expect(deliveryOutcome(429, "45", now)).toEqual({ kind: "retryAfter", delayMs: 45_000 }); + }); + + it("429 HTTP tarihli Retry-After'ı da okur", () => { + const at = new Date(now.getTime() + 30_000).toUTCString(); + expect(deliveryOutcome(429, at, now)).toEqual({ kind: "retryAfter", delayMs: 30_000 }); + }); + + it("429 başlıksız ya da bozuksa bir dakika, aralık 1 sn–1 saat", () => { + expect(deliveryOutcome(429, null, now)).toEqual({ kind: "retryAfter", delayMs: 60_000 }); + expect(deliveryOutcome(429, "yarın", now)).toEqual({ kind: "retryAfter", delayMs: 60_000 }); + expect(deliveryOutcome(429, "0", now)).toEqual({ kind: "retryAfter", delayMs: 1000 }); + expect(deliveryOutcome(429, "999999", now)).toEqual({ kind: "retryAfter", delayMs: 3_600_000 }); + }); + + it("ağ hatası, 5xx ve beklenmeyen kodlar artan beklemeye düşer", () => { + expect(deliveryOutcome(null, null, now)).toEqual({ kind: "backoff" }); + expect(deliveryOutcome(500, null, now)).toEqual({ kind: "backoff" }); + expect(deliveryOutcome(503, null, now)).toEqual({ kind: "backoff" }); + expect(deliveryOutcome(404, null, now)).toEqual({ kind: "backoff" }); + }); +}); + +describe("backoffDelayMs", () => { + it("her başarısızlıkta iki katına çıkar", () => { + expect(backoffDelayMs(1, 1 - Number.EPSILON)).toBeCloseTo(5_000, -1); + expect(backoffDelayMs(2, 1 - Number.EPSILON)).toBeCloseTo(10_000, -1); + expect(backoffDelayMs(3, 1 - Number.EPSILON)).toBeCloseTo(20_000, -1); + }); + + it("30 dakikayı aşmaz", () => { + expect(backoffDelayMs(50, 1 - Number.EPSILON)).toBeLessThanOrEqual(30 * 60_000); + }); + + it("jitter tavanın yarısı ile tamamı arasında", () => { + expect(backoffDelayMs(3, 0)).toBe(10_000); + expect(backoffDelayMs(3, 0.5)).toBe(15_000); + }); +}); diff --git a/src/analytics/delivery.ts b/src/analytics/delivery.ts new file mode 100644 index 0000000..9308c95 --- /dev/null +++ b/src/analytics/delivery.ts @@ -0,0 +1,63 @@ +/* ------------------------------------------------------------------ */ +/* Gönderim sonucu — yanıta göre ne yapılacağı */ +/* ------------------------------------------------------------------ */ + +/* + POST /api/events sözleşmesi (CLAUDE.md, Kullanım ölçümü): + - 202: geçerliler yazıldı, geçersizler atlandı; batch kuyruktan çıkar. + - 400: zarf bozuk; aynı batch tekrar gönderilse yine reddedilir, atılır. + - 429: Retry-After kadar beklenir; batch kuyrukta kalır. + - Ağ hatası, 5xx ve beklenmeyen her kod: artan bekleme, batch kalır. +*/ + +export type DeliveryOutcome = + | { kind: "sent" } + | { kind: "rejected" } + | { kind: "retryAfter"; delayMs: number } + | { kind: "backoff" }; + +/** Retry-After okunamazsa bir dakika: backend'in sınır penceresi. */ +const DEFAULT_RETRY_AFTER_MS = 60_000; +const MAX_RETRY_AFTER_MS = 60 * 60_000; + +/** @param status ağ hatasında null */ +export function deliveryOutcome(status: number | null, retryAfter: string | null, now: Date): DeliveryOutcome { + if (status === null) return { kind: "backoff" }; + if (status >= 200 && status < 300) return { kind: "sent" }; + // 413: gövde nginx'in sınırını aştı; aynı batch yine aşar. + if (status === 400 || status === 413) return { kind: "rejected" }; + if (status === 429) return { kind: "retryAfter", delayMs: retryAfterMs(retryAfter, now) }; + return { kind: "backoff" }; +} + +/** Saniye ya da HTTP tarihi; ikisi de olmazsa varsayılan. 1 sn ile 1 saat arasında tutulur. */ +function retryAfterMs(header: string | null, now: Date): number { + let delay = DEFAULT_RETRY_AFTER_MS; + if (header !== null && header.trim() !== "") { + const seconds = Number(header); + if (Number.isFinite(seconds)) { + delay = seconds * 1000; + } else { + const date = Date.parse(header); + if (Number.isFinite(date)) delay = date - now.getTime(); + } + } + return Math.min(Math.max(delay, 1000), MAX_RETRY_AFTER_MS); +} + +const BACKOFF_BASE_MS = 5_000; +const BACKOFF_MAX_MS = 30 * 60_000; + +/** + * Art arda başarısızlık sayısına göre bekleme: 5 sn, 10 sn, 20 sn… en + * fazla 30 dk. Jitter (0.5–1 katı): sunucu dönünce bütün istemciler aynı + * anda saldırmasın. + * + * @param failures en az 1 + * @param random [0, 1) + */ +export function backoffDelayMs(failures: number, random: number): number { + const exponent = Math.min(Math.max(failures, 1) - 1, 20); + const ceiling = Math.min(BACKOFF_BASE_MS * 2 ** exponent, BACKOFF_MAX_MS); + return Math.round(ceiling * (0.5 + random / 2)); +} diff --git a/src/analytics/queue.test.ts b/src/analytics/queue.test.ts new file mode 100644 index 0000000..4df7f61 --- /dev/null +++ b/src/analytics/queue.test.ts @@ -0,0 +1,72 @@ +import { describe, expect, it } from "vitest"; + +import type { QueuedEvent } from "../domain/usageEvents"; +import { MAX_EVENT_AGE_MS, MAX_QUEUE_LENGTH, appendEvent, dropStale, nextBatch, removeEvents } from "./queue"; + +function event(n: number, occurredAt = "2026-11-17T12:00:00.000Z"): QueuedEvent { + const hex = n.toString(16).padStart(12, "0"); + return { eventId: `00000000-0000-4000-8000-${hex}`, name: "spin", occurredAt, props: { categoryCount: 1 } }; +} + +function events(count: number, from = 0): QueuedEvent[] { + return Array.from({ length: count }, (_, i) => event(from + i)); +} + +describe("appendEvent", () => { + it("sona ekler", () => { + expect(appendEvent(events(2), event(9)).map((e) => e.eventId)).toEqual([event(0), event(1), event(9)].map((e) => e.eventId)); + }); + + it("500'ü aşınca en eskiyi atar", () => { + const full = events(MAX_QUEUE_LENGTH); + const next = appendEvent(full, event(1000)); + + expect(next).toHaveLength(MAX_QUEUE_LENGTH); + expect(next[0].eventId).toBe(event(1).eventId); + expect(next.at(-1)?.eventId).toBe(event(1000).eventId); + }); +}); + +describe("dropStale", () => { + const now = new Date("2026-11-17T12:00:00.000Z"); + + it("backend'in reddedeceği eski olayları atar, sınırdakini tutar", () => { + const edge = new Date(now.getTime() - MAX_EVENT_AGE_MS).toISOString(); + const tooOld = new Date(now.getTime() - MAX_EVENT_AGE_MS - 1).toISOString(); + const queue = [event(1, tooOld), event(2, edge), event(3, now.toISOString())]; + + expect(dropStale(queue, now).map((e) => e.eventId)).toEqual([event(2).eventId, event(3).eventId]); + }); + + it("pay backend'in 7 gününden önce keser", () => { + expect(MAX_EVENT_AGE_MS).toBeLessThan(7 * 24 * 60 * 60 * 1000); + }); + + it("okunamayan zamanı atar", () => { + expect(dropStale([event(1, "bozuk")], now)).toEqual([]); + }); +}); + +describe("nextBatch", () => { + it("en eski 50 olay", () => { + const batch = nextBatch(events(120)); + + expect(batch).toHaveLength(50); + expect(batch[0].eventId).toBe(event(0).eventId); + expect(batch[49].eventId).toBe(event(49).eventId); + }); + + it("kuyruk kısaysa hepsi", () => { + expect(nextBatch(events(3))).toHaveLength(3); + }); +}); + +describe("removeEvents", () => { + it("gönderilenleri id ile çıkarır, sonradan eklenenleri tutar", () => { + const sent = events(2); + // Gönderim sürerken başa değil sona yeni olay eklendi, bir olay da başka sekmece silindi. + const current = [event(1), event(5), event(6)]; + + expect(removeEvents(current, sent).map((e) => e.eventId)).toEqual([event(5).eventId, event(6).eventId]); + }); +}); diff --git a/src/analytics/queue.ts b/src/analytics/queue.ts new file mode 100644 index 0000000..5f1e26d --- /dev/null +++ b/src/analytics/queue.ts @@ -0,0 +1,50 @@ +import { MAX_EVENTS_PER_BATCH } from "../domain/usageEvents"; +import type { QueuedEvent } from "../domain/usageEvents"; + +/* ------------------------------------------------------------------ */ +/* Olay kuyruğu — saf işlemler */ +/* ------------------------------------------------------------------ */ + +/* + Olaylar önce yerel kuyruğa yazılır, gönderim sonra: uygulama tam + çevrimdışı çalışır, kuyruk bir sonraki fırsatta boşalır. Kuyruktan + yalnızca sunucu kabul ettiğinde (202) ya da batch'i reddettiğinde (400) + silinir; ağ hatasında aynı olaylar aynı eventId'lerle yeniden gider. +*/ + +/** Kuyruk tavanı. Taşarsa en eskiler atılır: yeni davranış daha değerli. */ +export const MAX_QUEUE_LENGTH = 500; + +/** + * Backend 7 günden eski olayı reddediyor (EventValidator.MAX_PAST). + * Bir saat pay: cihaz saati biraz geride olsa da sınırdaki olay boşuna + * gönderilip "skipped" sayılmasın. + */ +export const MAX_EVENT_AGE_MS = 7 * 24 * 60 * 60 * 1000 - 60 * 60 * 1000; + +export function appendEvent(queue: readonly QueuedEvent[], event: QueuedEvent): QueuedEvent[] { + return [...queue, event].slice(-MAX_QUEUE_LENGTH); +} + +/** Sunucunun zaten reddedeceği eski olayları ve okunamayan zamanları atar. */ +export function dropStale(queue: readonly QueuedEvent[], now: Date): QueuedEvent[] { + const oldest = now.getTime() - MAX_EVENT_AGE_MS; + return queue.filter((event) => { + const at = Date.parse(event.occurredAt); + return Number.isFinite(at) && at >= oldest; + }); +} + +/** Sıradaki batch: en eski olaylar önce gider. */ +export function nextBatch(queue: readonly QueuedEvent[]): QueuedEvent[] { + return queue.slice(0, MAX_EVENTS_PER_BATCH); +} + +/** + * Gönderilen batch'i kuyruktan çıkarır. id ile, konumla değil: gönderim + * sürerken yeni olay eklenmiş ya da başka sekme kuyruğu değiştirmiş olabilir. + */ +export function removeEvents(queue: readonly QueuedEvent[], sent: readonly QueuedEvent[]): QueuedEvent[] { + const ids = new Set(sent.map((event) => event.eventId)); + return queue.filter((event) => !ids.has(event.eventId)); +} From 641a3abb4d73952007d5a16066bdc5de659d628b Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 18:27:55 +0300 Subject: [PATCH 12/17] =?UTF-8?q?feat(analytics):=20=C3=B6l=C3=A7=C3=BCm?= =?UTF-8?q?=20istemcisi=20ve=20platform=20par=C3=A7alar=C4=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tercih, kurulum kimliği ve kuyruk ayrı namespace'te (slot-analytics). Kuyruğun tek kaynağı depo; oku-değiştir-yaz Web Locks ile sekmeler arasında sıraya girer. Kapatınca kuyruk ve kimlik silinir. Web göreli /api/events'e, native VITE_API_BASE_URL'e gider; tanımsızsa kapalı. iOS'ta randomUUID yoksa getRandomValues yedeği. Co-Authored-By: Claude Opus 5.5 --- .env.production | 4 + src/analytics/analytics.ts | 51 +++++ src/analytics/analyticsClient.test.ts | 310 ++++++++++++++++++++++++++ src/analytics/analyticsClient.ts | 203 +++++++++++++++++ src/analytics/analyticsStorage.ts | 77 +++++++ src/platform/index.ts | 23 ++ src/platform/locks.test.ts | 26 +++ src/platform/locks.ts | 26 +++ src/platform/randomId.test.ts | 17 ++ src/platform/randomId.ts | 25 +++ src/storage/storeKeys.ts | 11 + src/vite-env.d.ts | 6 + 12 files changed, 779 insertions(+) create mode 100644 .env.production create mode 100644 src/analytics/analytics.ts create mode 100644 src/analytics/analyticsClient.test.ts create mode 100644 src/analytics/analyticsClient.ts create mode 100644 src/analytics/analyticsStorage.ts create mode 100644 src/platform/locks.test.ts create mode 100644 src/platform/locks.ts create mode 100644 src/platform/randomId.test.ts create mode 100644 src/platform/randomId.ts diff --git a/.env.production b/.env.production new file mode 100644 index 0000000..010e4ff --- /dev/null +++ b/.env.production @@ -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 diff --git a/src/analytics/analytics.ts b/src/analytics/analytics.ts new file mode 100644 index 0000000..0fe11c8 --- /dev/null +++ b/src/analytics/analytics.ts @@ -0,0 +1,51 @@ +import { analyticsTarget, storage } from "../platform"; +import { withLock } from "../platform/locks"; +import { randomUuid } from "../platform/randomId"; +import { createAnalyticsClient } from "./analyticsClient"; +import type { SendResult } from "./analyticsClient"; +import { createAnalyticsStorage } from "./analyticsStorage"; + +/* ------------------------------------------------------------------ */ +/* Uygulamanın tek ölçüm istemcisi */ +/* ------------------------------------------------------------------ */ + +/* + Modül seviyesinde tek örnek: StrictMode efektleri iki kez çalıştırsa da + durum (tercih, bekleme süresi) tek yerde kalır (progressSync ile aynı + gerekçe). Kurulum kodu burada, kararlar analyticsClient.ts'te. +*/ + +/** + * credentials: "omit" — çerez gönderilmez; olay hiçbir oturuma bağlanmasın. + * keepalive: arka plana geçişte sayfa/WebView isteği öldürse bile gitsin. + * Gitmezse olaylar kuyrukta kalır, aynı eventId'lerle yeniden gönderilir. + */ +async function send(url: string, body: string, keepalive: boolean): Promise { + try { + const response = await fetch(url, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body, + keepalive, + credentials: "omit", + }); + return { status: response.status, retryAfter: response.headers.get("Retry-After") }; + } catch { + return null; + } +} + +export const analytics = createAnalyticsClient({ + storage: createAnalyticsStorage(storage), + send, + withLock: (fn) => withLock("slot-analytics-queue", fn), + now: () => new Date(), + random: Math.random, + randomUuid, + endpoint: analyticsTarget.endpoint, + platform: analyticsTarget.platform, + appVersion: __APP_VERSION__, + warn: (message) => { + if (import.meta.env.DEV) console.warn(message); + }, +}); diff --git a/src/analytics/analyticsClient.test.ts b/src/analytics/analyticsClient.test.ts new file mode 100644 index 0000000..64af659 --- /dev/null +++ b/src/analytics/analyticsClient.test.ts @@ -0,0 +1,310 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { z } from "zod"; + +import type { QueuedEvent } from "../domain/usageEvents"; +import { withLock } from "../platform/locks"; +import { createMemoryAdapter } from "../platform/storage/memoryAdapter"; +import type { StorageAdapter } from "../platform/storage/StorageAdapter"; +import { ANALYTICS_CONSENT_KEY, ANALYTICS_INSTALL_KEY, ANALYTICS_NS, ANALYTICS_QUEUE_KEY } from "../storage/storeKeys"; +import { createAnalyticsClient } from "./analyticsClient"; +import type { AnalyticsDeps, SendResult } from "./analyticsClient"; +import { createAnalyticsStorage } from "./analyticsStorage"; + +const START = new Date("2026-11-17T12:00:00.000Z").getTime(); + +/** Arkada süren yazmaların bitmesi: kilit zinciri ve bellek deposu mikro görevlerle ilerliyor. */ +const settle = () => new Promise((resolve) => setTimeout(resolve, 0)); + +type Sent = { url: string; body: { installId: string; platform: string; appVersion: string; events: QueuedEvent[] }; keepalive: boolean }; + +function setup(overrides: Partial = {}, store: StorageAdapter = createMemoryAdapter()) { + let now = START; + let uuidCounter = 0; + const sent: Sent[] = []; + const responses: SendResult[] = []; + const warn = vi.fn(); + // Uygulamadaki gibi tek ad: her çağrıda farklı ad hiçbir şeyi sıraya sokmaz + // ve art arda olaylar birbirinin yazdığını ezer. + const lockName = `test-${Math.random()}`; + + const client = createAnalyticsClient({ + storage: createAnalyticsStorage(store), + send: async (url, body, keepalive) => { + sent.push({ url, body: JSON.parse(body) as Sent["body"], keepalive }); + return responses.length > 0 ? (responses.shift() ?? null) : { status: 202, retryAfter: null }; + }, + withLock: (fn) => withLock(lockName, fn), + now: () => new Date(now), + random: () => 0.999, + randomUuid: () => `00000000-0000-4000-8000-${(++uuidCounter).toString(16).padStart(12, "0")}`, + endpoint: "/api/events", + platform: "android", + appVersion: "1.2.0", + warn, + ...overrides, + }); + + return { + client, + store, + sent, + warn, + respond: (...results: SendResult[]) => responses.push(...results), + advance: (ms: number) => { + now += ms; + }, + queue: async () => (await store.get(ANALYTICS_NS, ANALYTICS_QUEUE_KEY)) ?? [], + installId: () => store.get(ANALYTICS_NS, ANALYTICS_INSTALL_KEY), + }; +} + +async function enabledSetup(overrides: Partial = {}) { + const ctx = setup(overrides); + await ctx.client.load(); + return ctx; +} + +function spins(client: ReturnType["client"], count: number) { + for (let i = 0; i < count; i++) client.track({ name: "spin", props: { categoryCount: 2 } }); +} + +describe("tercih", () => { + it("kayıt yoksa varsayılan açık, bilgilendirme gösterilmemiş", async () => { + const { client } = setup(); + expect(await client.load()).toEqual({ enabled: true, noticeShown: false }); + }); + + it("okunmadan önce kapalı: hiçbir şey yazılmaz", async () => { + const ctx = setup(); + spins(ctx.client, 1); + await settle(); + expect(await ctx.queue()).toEqual([]); + }); + + it("kayıtlı kapatma tercihine uyar", async () => { + const store = createMemoryAdapter(); + await store.set(ANALYTICS_NS, ANALYTICS_CONSENT_KEY, { enabled: false, noticeShown: true }); + const ctx = setup({}, store); + + expect((await ctx.client.load()).enabled).toBe(false); + spins(ctx.client, 1); + await settle(); + expect(await ctx.queue()).toEqual([]); + }); + + it("bozuk tercih kaydı kapalı sayılır", async () => { + const store = createMemoryAdapter(); + await store.set(ANALYTICS_NS, ANALYTICS_CONSENT_KEY, "bozuk"); + expect(await setup({}, store).client.load()).toEqual({ enabled: false, noticeShown: true }); + }); + + it("bilgilendirme gösterildi olarak kaydedilir", async () => { + const ctx = await enabledSetup(); + await ctx.client.markNoticeShown(); + expect(await ctx.store.get(ANALYTICS_NS, ANALYTICS_CONSENT_KEY)).toEqual({ enabled: true, noticeShown: true }); + }); +}); + +describe("track", () => { + it("olayı kimlik ve zamanla kuyruğa yazar, kurulum kimliğini üretir", async () => { + const ctx = await enabledSetup(); + ctx.client.track({ name: "app_open", props: { dueCount: 3 } }); + await settle(); + + const [event] = await ctx.queue(); + expect(z.uuid().safeParse(event.eventId).success).toBe(true); + expect(event).toMatchObject({ name: "app_open", occurredAt: new Date(START).toISOString(), props: { dueCount: 3 } }); + expect(z.uuid().safeParse(await ctx.installId()).success).toBe(true); + }); + + it("geçersiz olayı atlar, hata fırlatmaz", async () => { + const ctx = await enabledSetup(); + expect(() => ctx.client.track({ name: "spin", props: { categoryCount: 0 } })).not.toThrow(); + await settle(); + expect(await ctx.queue()).toEqual([]); + expect(ctx.warn).toHaveBeenCalled(); + }); + + it("hedef yoksa (native'de adres tanımsız) hiçbir şey yazmaz", async () => { + const ctx = await enabledSetup({ endpoint: null }); + spins(ctx.client, 1); + await ctx.client.flush(); + await settle(); + expect(await ctx.queue()).toEqual([]); + expect(ctx.sent).toEqual([]); + }); + + it("depo hata verirse uygulamaya sızdırmaz", async () => { + const broken = createMemoryAdapter(); + broken.set = () => Promise.reject(new Error("disk dolu")); + broken.get = () => Promise.reject(new Error("okunamadı")); + const ctx = setup({}, broken); + + await expect(ctx.client.load()).resolves.toBeDefined(); + await ctx.client.setEnabled(true); + expect(() => spins(ctx.client, 1)).not.toThrow(); + await expect(ctx.client.flush()).resolves.toBeUndefined(); + await settle(); + }); +}); + +describe("flush", () => { + it("202'de batch kuyruktan silinir; zarf sözleşmeye uyar", async () => { + const ctx = await enabledSetup(); + spins(ctx.client, 3); + await settle(); + await ctx.client.flush(); + + expect(ctx.sent).toHaveLength(1); + expect(ctx.sent[0].url).toBe("/api/events"); + expect(ctx.sent[0].body).toMatchObject({ installId: await ctx.installId(), platform: "android", appVersion: "1.2.0" }); + expect(ctx.sent[0].body.events).toHaveLength(3); + expect(await ctx.queue()).toEqual([]); + }); + + it("gönderim başına en fazla 2 batch (100 olay)", async () => { + const ctx = await enabledSetup(); + spins(ctx.client, 120); + await settle(); + await ctx.client.flush(); + + expect(ctx.sent.map((s) => s.body.events.length)).toEqual([50, 50]); + expect(await ctx.queue()).toHaveLength(20); + }); + + it("400'de batch atılır ve uyarı verilir", async () => { + const ctx = await enabledSetup(); + spins(ctx.client, 2); + await settle(); + ctx.respond({ status: 400, retryAfter: null }); + await ctx.client.flush(); + + expect(await ctx.queue()).toEqual([]); + expect(ctx.warn).toHaveBeenCalledWith(expect.stringContaining("reddedildi")); + }); + + it("429'da Retry-After dolana kadar gönderilmez, olaylar kalır", async () => { + const ctx = await enabledSetup(); + spins(ctx.client, 2); + await settle(); + ctx.respond({ status: 429, retryAfter: "30" }); + await ctx.client.flush(); + expect(await ctx.queue()).toHaveLength(2); + + ctx.advance(29_000); + await ctx.client.flush(); + expect(ctx.sent).toHaveLength(1); + + ctx.advance(1_000); + await ctx.client.flush(); + expect(ctx.sent).toHaveLength(2); + expect(await ctx.queue()).toEqual([]); + }); + + it("ağ hatasında tekrar denemede aynı eventId'ler gider", async () => { + const ctx = await enabledSetup(); + spins(ctx.client, 2); + await settle(); + ctx.respond(null); + await ctx.client.flush(); + expect(await ctx.queue()).toHaveLength(2); + + ctx.advance(10_000); + await ctx.client.flush(); + + const ids = (n: number) => ctx.sent[n].body.events.map((e) => e.eventId); + expect(ctx.sent).toHaveLength(2); + expect(ids(1)).toEqual(ids(0)); + }); + + it("5xx'te bekleme her başarısızlıkta uzar, başarıdan sonra sıfırlanır", async () => { + const ctx = await enabledSetup(); + spins(ctx.client, 1); + await settle(); + + ctx.respond({ status: 503, retryAfter: null }); + await ctx.client.flush(); + ctx.advance(5_000); + ctx.respond({ status: 503, retryAfter: null }); + await ctx.client.flush(); + expect(ctx.sent).toHaveLength(2); + + // İkinci başarısızlıktan sonra bekleme ~10 sn: 5 sn yetmez. + ctx.advance(5_000); + await ctx.client.flush(); + expect(ctx.sent).toHaveLength(2); + + ctx.advance(5_000); + await ctx.client.flush(); + expect(ctx.sent).toHaveLength(3); + expect(await ctx.queue()).toEqual([]); + }); + + it("backend'in reddedeceği eski olaylar gönderilmeden atılır", async () => { + const ctx = await enabledSetup(); + spins(ctx.client, 1); + await settle(); + ctx.advance(7 * 24 * 60 * 60 * 1000); + await ctx.client.flush(); + + expect(ctx.sent).toEqual([]); + expect(await ctx.queue()).toEqual([]); + }); + + it("keepalive seçeneği gönderime geçer", async () => { + const ctx = await enabledSetup(); + spins(ctx.client, 1); + await settle(); + await ctx.client.flush({ keepalive: true }); + expect(ctx.sent[0].keepalive).toBe(true); + }); +}); + +describe("kapatma", () => { + let ctx: Awaited>; + + beforeEach(async () => { + ctx = await enabledSetup(); + spins(ctx.client, 3); + await settle(); + }); + + it("kuyruk ve kurulum kimliği silinir, tercih kapalı yazılır", async () => { + await ctx.client.setEnabled(false); + + expect(await ctx.queue()).toEqual([]); + expect(await ctx.installId()).toBeUndefined(); + expect(await ctx.store.get(ANALYTICS_NS, ANALYTICS_CONSENT_KEY)).toEqual({ enabled: false, noticeShown: false }); + }); + + it("kapalıyken olay yazılmaz, gönderim yapılmaz", async () => { + await ctx.client.setEnabled(false); + spins(ctx.client, 2); + await settle(); + await ctx.client.flush(); + + expect(await ctx.queue()).toEqual([]); + expect(ctx.sent).toEqual([]); + }); + + it("kapatmadan hemen önce başlayan yazma kuyruğu yeniden oluşturmaz", async () => { + spins(ctx.client, 1); + await ctx.client.setEnabled(false); + await settle(); + + expect(await ctx.queue()).toEqual([]); + expect(await ctx.installId()).toBeUndefined(); + }); + + it("yeniden açılınca yeni kurulum kimliği üretilir", async () => { + const before = await ctx.installId(); + await ctx.client.setEnabled(false); + await ctx.client.setEnabled(true); + spins(ctx.client, 1); + await settle(); + + const after = await ctx.installId(); + expect(after).toBeDefined(); + expect(after).not.toBe(before); + }); +}); diff --git a/src/analytics/analyticsClient.ts b/src/analytics/analyticsClient.ts new file mode 100644 index 0000000..abbc968 --- /dev/null +++ b/src/analytics/analyticsClient.ts @@ -0,0 +1,203 @@ +import { eventBatchSchema, usageEventSchema } from "../domain/usageEvents"; +import type { QueuedEvent, UsageEvent, UsagePlatform } from "../domain/usageEvents"; +import type { AnalyticsStorage, Consent } from "./analyticsStorage"; +import { DEFAULT_CONSENT } from "./analyticsStorage"; +import { backoffDelayMs, deliveryOutcome } from "./delivery"; +import { appendEvent, dropStale, nextBatch, removeEvents } from "./queue"; + +/* ------------------------------------------------------------------ */ +/* Kullanım ölçümü istemcisi — React bilmez */ +/* ------------------------------------------------------------------ */ + +/* + Kural: ölçüm uygulamayı ASLA bozmaz. Dışa açık her fonksiyon hatayı + yutar; track senkron döner ve hiçbir şey beklemez. + + Kuyruğun tek kaynağı depo, bellekte kopya yok: her adım kilit içinde + okur, değiştirir, yazar (web'de birden fazla sekme aynı kuyruğu + paylaşıyor). Ağ isteği kilidin dışında; kilit yalnızca depo adımlarını + sıraya sokar. + + Bağımlılıklar dışarıdan gelir: testte bellek deposu, sahte fetch ve saat. +*/ + +/** Backend'in sınırı dakikada 120 olay; tek gönderimde en fazla 100. */ +export const MAX_BATCHES_PER_FLUSH = 2; + +export type SendResult = { status: number; retryAfter: string | null } | null; + +export type AnalyticsDeps = { + storage: AnalyticsStorage; + /** Ağ hatasında null döner, fırlatmaz. */ + send: (url: string, body: string, keepalive: boolean) => Promise; + withLock: (fn: () => Promise) => Promise; + now: () => Date; + random: () => number; + randomUuid: () => string; + /** null: hedef yok (native'de VITE_API_BASE_URL tanımsız), ölçüm kapalı. */ + endpoint: string | null; + platform: UsagePlatform; + appVersion: string; + /** Yalnızca geliştirmede uyarı; üretimde sessiz. */ + warn: (message: string) => void; +}; + +export function createAnalyticsClient(deps: AnalyticsDeps) { + const { storage } = deps; + + // Tercih okunana kadar kapalı: kapatmış bir kullanıcının ilk olayı yazılmasın. + let consent: Consent = { ...DEFAULT_CONSENT, enabled: false }; + // Kapatma anında artar: kapatmadan önce başlamış bir track sonradan yazmasın. + let generation = 0; + let flushing = false; + let failures = 0; + let nextAttemptAt = 0; + + const active = () => consent.enabled && deps.endpoint !== null; + + async function safely(label: string, work: () => Promise): Promise { + try { + await work(); + } catch (error) { + deps.warn(`Kullanım ölçümü: ${label} başarısız (${String(error)})`); + } + } + + async function ensureInstallId(): Promise { + const existing = await storage.readInstallId(); + if (existing) return existing; + const created = deps.randomUuid(); + await storage.writeInstallId(created); + return created; + } + + /** Tercihi depodan okur; okunamazsa kapalı kalır. */ + async function load(): Promise { + await safely("tercih okuma", async () => { + consent = await storage.readConsent(); + }); + return consent; + } + + /** + * Kapatınca kuyruk ve kurulum kimliği silinir; açınca bir sonraki olayda + * yeni kimlik üretilir. + */ + async function setEnabled(enabled: boolean): Promise { + if (!enabled) generation++; + consent = { ...consent, enabled }; + const next = consent; + await safely("tercih yazma", () => + deps.withLock(async () => { + await storage.writeConsent(next); + if (!enabled) await storage.clearCollected(); + }), + ); + } + + async function markNoticeShown(): Promise { + consent = { ...consent, noticeShown: true }; + const next = consent; + await safely("bilgilendirme kaydı", () => deps.withLock(() => storage.writeConsent(next))); + } + + /** Senkron döner; yazma arkada sürer. Geçersiz olay sessizce düşer. */ + function track(event: UsageEvent): void { + try { + if (!active()) return; + const parsed = usageEventSchema.safeParse(event); + if (!parsed.success) { + deps.warn(`Kullanım ölçümü: geçersiz olay atlandı (${event.name})`); + return; + } + // Kimlik ve zaman şimdi: tekrar denemelerde aynı eventId gider. + const queued: QueuedEvent = { + eventId: deps.randomUuid(), + name: parsed.data.name, + occurredAt: deps.now().toISOString(), + props: parsed.data.props, + }; + const startedIn = generation; + void safely("olay yazma", () => + deps.withLock(async () => { + if (!active() || generation !== startedIn) return; + await ensureInstallId(); + await storage.writeQueue(appendEvent(await storage.readQueue(), queued)); + }), + ); + } catch (error) { + deps.warn(`Kullanım ölçümü: olay atlandı (${String(error)})`); + } + } + + /** Kuyruktan en fazla MAX_BATCHES_PER_FLUSH batch gönderir. */ + async function flush(options: { keepalive?: boolean } = {}): Promise { + if (!active() || flushing || deps.now().getTime() < nextAttemptAt) return; + flushing = true; + await safely("gönderim", async () => { + for (let i = 0; i < MAX_BATCHES_PER_FLUSH; i++) { + if (!(await sendNextBatch(options.keepalive ?? false))) break; + } + }); + flushing = false; + } + + /** Bir batch gönderir; devam edilebilirse true. */ + async function sendNextBatch(keepalive: boolean): Promise { + const prepared = await deps.withLock(async () => { + const queue = await storage.readQueue(); + const fresh = dropStale(queue, deps.now()); + if (fresh.length !== queue.length) await storage.writeQueue(fresh); + const installId = await storage.readInstallId(); + return installId ? { installId, events: nextBatch(fresh) } : null; + }); + if (!prepared || prepared.events.length === 0 || deps.endpoint === null) return false; + + const batch = eventBatchSchema.safeParse({ + installId: prepared.installId, + platform: deps.platform, + appVersion: deps.appVersion, + events: prepared.events, + }); + const outcome = batch.success + ? await sendBatch(deps.endpoint, JSON.stringify(batch.data), keepalive) + : ({ kind: "rejected" } as const); + + switch (outcome.kind) { + case "sent": + case "rejected": + if (outcome.kind === "rejected") { + // Tekrar denemenin anlamı yok; bir istemci hatası, geliştirmede görünsün. + deps.warn(`Kullanım ölçümü: ${prepared.events.length} olaylık batch reddedildi, atıldı`); + } + failures = 0; + await deps.withLock(async () => + storage.writeQueue(removeEvents(await storage.readQueue(), prepared.events)), + ); + return outcome.kind === "sent"; + case "retryAfter": + nextAttemptAt = deps.now().getTime() + outcome.delayMs; + return false; + case "backoff": + failures++; + nextAttemptAt = deps.now().getTime() + backoffDelayMs(failures, deps.random()); + return false; + } + } + + async function sendBatch(url: string, body: string, keepalive: boolean) { + const result = await deps.send(url, body, keepalive); + return deliveryOutcome(result?.status ?? null, result?.retryAfter ?? null, deps.now()); + } + + return { + load, + setEnabled, + markNoticeShown, + track, + flush, + consent: (): Consent => consent, + }; +} + +export type AnalyticsClient = ReturnType; diff --git a/src/analytics/analyticsStorage.ts b/src/analytics/analyticsStorage.ts new file mode 100644 index 0000000..977454f --- /dev/null +++ b/src/analytics/analyticsStorage.ts @@ -0,0 +1,77 @@ +import { z } from "zod"; + +import { queuedEventSchema } from "../domain/usageEvents"; +import type { QueuedEvent } from "../domain/usageEvents"; +import type { StorageAdapter } from "../platform/storage/StorageAdapter"; +import { + ANALYTICS_CONSENT_KEY, + ANALYTICS_INSTALL_KEY, + ANALYTICS_NS, + ANALYTICS_QUEUE_KEY, +} from "../storage/storeKeys"; + +/* ------------------------------------------------------------------ */ +/* Kullanım ölçümünün yerel kaydı: tercih, kurulum kimliği, kuyruk */ +/* ------------------------------------------------------------------ */ + +export const consentSchema = z.object({ + /** "Kullanım istatistiklerini paylaş". */ + enabled: z.boolean(), + /** İlk açılış bilgilendirmesi gösterildi mi. */ + noticeShown: z.boolean(), +}); +export type Consent = z.infer; + +/** Hiç kayıt yoksa: varsayılan açık, bilgilendirme henüz gösterilmedi. */ +export const DEFAULT_CONSENT: Consent = { enabled: true, noticeShown: false }; + +/** + * Kayıt var ama okunamıyorsa kapalı: bozuk bir kayıt kullanıcının kapatma + * tercihi olabilir, sessizce açık sayılmamalı. Bilgilendirme de tekrar çıkmaz. + */ +const UNREADABLE_CONSENT: Consent = { enabled: false, noticeShown: true }; + +const queueSchema = z.array(queuedEventSchema); + +export function createAnalyticsStorage(storage: StorageAdapter) { + return { + async readConsent(): Promise { + const raw = await storage.get(ANALYTICS_NS, ANALYTICS_CONSENT_KEY); + if (raw === undefined) return DEFAULT_CONSENT; + const parsed = consentSchema.safeParse(raw); + return parsed.success ? parsed.data : UNREADABLE_CONSENT; + }, + + writeConsent(consent: Consent): Promise { + return storage.set(ANALYTICS_NS, ANALYTICS_CONSENT_KEY, consent); + }, + + async readInstallId(): Promise { + const raw = await storage.get(ANALYTICS_NS, ANALYTICS_INSTALL_KEY); + return z.uuid().safeParse(raw).success ? (raw as string) : undefined; + }, + + writeInstallId(installId: string): Promise { + return storage.set(ANALYTICS_NS, ANALYTICS_INSTALL_KEY, installId); + }, + + /** Okunamayan kuyruk boş sayılır: ölçüm verisi için kurtarma gerekmez. */ + async readQueue(): Promise { + const raw = await storage.get(ANALYTICS_NS, ANALYTICS_QUEUE_KEY); + const parsed = queueSchema.safeParse(raw); + return parsed.success ? parsed.data : []; + }, + + writeQueue(queue: readonly QueuedEvent[]): Promise { + return storage.set(ANALYTICS_NS, ANALYTICS_QUEUE_KEY, queue); + }, + + /** Kimlik ve kuyruk; tercih kalır. */ + async clearCollected(): Promise { + await storage.delete(ANALYTICS_NS, ANALYTICS_QUEUE_KEY); + await storage.delete(ANALYTICS_NS, ANALYTICS_INSTALL_KEY); + }, + }; +} + +export type AnalyticsStorage = ReturnType; diff --git a/src/platform/index.ts b/src/platform/index.ts index de69622..b560c99 100644 --- a/src/platform/index.ts +++ b/src/platform/index.ts @@ -59,6 +59,29 @@ export const platformFeatures = { sameOriginPages: !native, } as const; +/** + * Kullanım ölçümünün hedefi. + * + * Web her zaman göreli /api/events'e gider: aynı origin, CORS gerekmez, + * geliştirmede Vite proxy'si backend'e iletir. VITE_API_BASE_URL'i bilerek + * okumaz; başka bir origin'e gitseydi backend'in CORS'u (yalnızca mobil + * origin'ler) isteği reddederdi. + * + * Native'de göreli yol paketlenmiş varlıklara düşer (bkz. auth bayrağı); + * adres VITE_API_BASE_URL'den gelir (.env.production). Tanımsızsa endpoint + * null ve ölçüm native'de tamamen kapalıdır: hiçbir şey kuyruğa yazılmaz. + */ +function analyticsEndpoint(): string | null { + if (!native) return "/api/events"; + const base = import.meta.env.VITE_API_BASE_URL?.trim().replace(/\/+$/, ""); + return base ? `${base}/api/events` : null; +} + +export const analyticsTarget = { + platform: native ? (android ? "android" : "ios") : "web", + endpoint: analyticsEndpoint(), +} as const satisfies { platform: "web" | "android" | "ios"; endpoint: string | null }; + /* ------------------------------------------------------------------ */ /* Platform seçimi — tek karar noktası */ /* ------------------------------------------------------------------ */ diff --git a/src/platform/locks.test.ts b/src/platform/locks.test.ts new file mode 100644 index 0000000..c6b9e28 --- /dev/null +++ b/src/platform/locks.test.ts @@ -0,0 +1,26 @@ +import { describe, expect, it } from "vitest"; + +import { withLock } from "./locks"; + +const tick = () => new Promise((resolve) => setTimeout(resolve, 0)); + +describe("withLock", () => { + it("aynı addaki oku-değiştir-yaz adımlarını sıraya sokar", async () => { + let stored = 0; + const increment = () => + withLock("sayac", async () => { + const read = stored; + await tick(); + stored = read + 1; + }); + + await Promise.all([increment(), increment(), increment()]); + + expect(stored).toBe(3); + }); + + it("hata çağırana döner, zincir sonraki çağrı için açık kalır", async () => { + await expect(withLock("hata", () => Promise.reject(new Error("bozuk")))).rejects.toThrow("bozuk"); + await expect(withLock("hata", async () => "devam")).resolves.toBe("devam"); + }); +}); diff --git a/src/platform/locks.ts b/src/platform/locks.ts new file mode 100644 index 0000000..4dfb169 --- /dev/null +++ b/src/platform/locks.ts @@ -0,0 +1,26 @@ +/* ------------------------------------------------------------------ */ +/* Adlandırılmış kilit — oku-değiştir-yaz adımlarını sıraya sokar */ +/* ------------------------------------------------------------------ */ + +/* + StorageAdapter'da oku-değiştir-yaz için transaction yok. Web'de iki + sekme aynı kuyruğu okuyup birbirinin yazdığını ezebiliyor; Web Locks API + sekmeler arasında sıraya sokar. Native'de tek WebView var, API olmasa da + aynı sayfadaki çağrılar aşağıdaki zincirle sıraya girer. +*/ + +const chains = new Map>(); + +/** fn'in hatası çağırana döner; zincir bir sonraki çağrı için açık kalır. */ +export function withLock(name: string, fn: () => Promise): Promise { + const locks = typeof navigator === "undefined" ? undefined : navigator.locks; + const run = locks ? () => locks.request(name, fn) : fn; + + const previous = chains.get(name) ?? Promise.resolve(); + const result = previous.then(run, run); + chains.set( + name, + result.catch(() => undefined), + ); + return result; +} diff --git a/src/platform/randomId.test.ts b/src/platform/randomId.test.ts new file mode 100644 index 0000000..7105b9d --- /dev/null +++ b/src/platform/randomId.test.ts @@ -0,0 +1,17 @@ +import { describe, expect, it } from "vitest"; +import { z } from "zod"; + +import { randomUuid, uuidFromBytes } from "./randomId"; + +describe("randomUuid", () => { + it("geçerli v4 UUID üretir", () => { + expect(z.uuidv4().safeParse(randomUuid()).success).toBe(true); + }); + + it("randomUUID olmayan bağlamdaki yedek de geçerli v4 üretir", () => { + for (const fill of [0x00, 0xff, 0x5a]) { + const id = uuidFromBytes(new Uint8Array(16).fill(fill)); + expect(z.uuidv4().safeParse(id).success).toBe(true); + } + }); +}); diff --git a/src/platform/randomId.ts b/src/platform/randomId.ts new file mode 100644 index 0000000..741e63f --- /dev/null +++ b/src/platform/randomId.ts @@ -0,0 +1,25 @@ +/* ------------------------------------------------------------------ */ +/* Rastgele UUID (v4) */ +/* ------------------------------------------------------------------ */ + +/* + crypto.randomUUID yalnızca güvenli bağlamda var. iOS'ta origin + capacitor://localhost ve WKWebView'in onu güvenli bağlam saydığı + belgelenmemiş (bkz. platform/index.ts, copyToClipboard). getRandomValues + güvenli bağlam istemiyor; yoksa aynı v4 biçimi ondan kurulur. +*/ + +export function randomUuid(): string { + const cryptoApi = globalThis.crypto; + if (typeof cryptoApi.randomUUID === "function") return cryptoApi.randomUUID(); + return uuidFromBytes(cryptoApi.getRandomValues(new Uint8Array(16))); +} + +/** RFC 9562 v4: sürüm ve varyant bitleri sabit, gerisi rastgele. */ +export function uuidFromBytes(bytes: Uint8Array): string { + const b = Uint8Array.from(bytes); + b[6] = (b[6] & 0x0f) | 0x40; + b[8] = (b[8] & 0x3f) | 0x80; + const hex = Array.from(b, (byte) => byte.toString(16).padStart(2, "0")).join(""); + return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`; +} diff --git a/src/storage/storeKeys.ts b/src/storage/storeKeys.ts index 8cc355e..04b7a8d 100644 --- a/src/storage/storeKeys.ts +++ b/src/storage/storeKeys.ts @@ -14,3 +14,14 @@ export const STORE_KEY = "store"; * sırasında zaman sırası olduğu için en eskiyi bulmak düz sıralama. */ export const CORRUPT_BACKUP_PREFIX = `${STORE_KEY}.corrupt-`; + +/* + Kullanım ölçümü ayrı namespace'te: store bozulup kurtarma akışı ayarları + varsayılana döndürdüğünde kullanıcının kapatma tercihi kaybolmasın. + Hesap silmede "bu cihazdaki verileri de sil" yalnızca kimliği ve kuyruğu + siler; tercih (consent) kalır. +*/ +export const ANALYTICS_NS = "slot-analytics"; +export const ANALYTICS_CONSENT_KEY = "consent"; +export const ANALYTICS_INSTALL_KEY = "install"; +export const ANALYTICS_QUEUE_KEY = "queue"; diff --git a/src/vite-env.d.ts b/src/vite-env.d.ts index 873d59a..e22d5d2 100644 --- a/src/vite-env.d.ts +++ b/src/vite-env.d.ts @@ -12,4 +12,10 @@ interface ImportMetaEnv { * bildirim her kurulumda N saniye sonraya kurulur (bkz. useReviewReminder). */ readonly VITE_REMINDER_TEST_SECONDS?: string; + /** + * Native'in API kökü (ör. https://slot.meteucar.com). Web okumaz, göreli + * yol kullanır. Tanımsızsa native'de kullanım ölçümü kapalıdır + * (bkz. platform/index.ts analyticsTarget). + */ + readonly VITE_API_BASE_URL?: string; } From 77c3534b68a2b5f6c745a08f4dba500be75337a7 Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 18:29:45 +0300 Subject: [PATCH 13/17] =?UTF-8?q?feat(analytics):=20app=5Fopen,=20spin,=20?= =?UTF-8?q?answer=5Fsubmitted=20ve=20self=5Feval=20olaylar=C4=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit app_open açılışta bir kez (modül seviyesinde güvence) ve 30 dk'dan uzun arka plandan dönüşte. Gönderim açılışta, 60 sn'de bir ve arka plana geçişte (keepalive). spin yalnızca gerçekten başlayan dönüşte; self_eval değerlendirme reducer'a gitmeden önce, önceki kutu elde varken. Co-Authored-By: Claude Opus 5.5 --- src/App.tsx | 30 +++++++++- src/analytics/trackers.ts | 40 +++++++++++++ src/analytics/useAnalytics.ts | 105 ++++++++++++++++++++++++++++++++++ 3 files changed, 173 insertions(+), 2 deletions(-) create mode 100644 src/analytics/trackers.ts create mode 100644 src/analytics/useAnalytics.ts diff --git a/src/App.tsx b/src/App.tsx index e3ea683..0658f6a 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -1,6 +1,8 @@ import { useEffect, useRef, useState } from "react"; import styles from "./App.module.css"; +import { trackAnswerSubmitted, trackSelfEval, trackSpin } from "./analytics/trackers"; +import { useAnalytics } from "./analytics/useAnalytics"; import { useAuth } from "./auth/useAuth"; import { CategoryPicker } from "./components/CategoryPicker"; import { Footer } from "./components/Footer"; @@ -54,7 +56,7 @@ type SessionProps = { /* Oturum, ayarlar ve hatırlatıcı kendi hook'larında; burası onları birbirine bağlıyor. Efektli hook'ların çağrı sırası bilinçli: diske - yazma → senkron → hatırlatıcı → spinKey. Bölmeden önceki sıra buydu; + yazma → senkron → hatırlatıcı → kullanım ölçümü → spinKey. Bölmeden önceki sıra buydu; üstteki üç hook (useSession, useSettings, useReminderSettings) pasif efekt içermediği için öne alınmaları bu sırayı değiştirmiyor. */ @@ -97,18 +99,42 @@ function Session({ store, warning, save }: SessionProps) { onPermissionLost: reminder.permissionLost, }); + // Kullanım ölçümü: app_open, periyodik ve arka plana geçişte gönderim. + // Sıra: hatırlatıcıdan sonra, spinKey'den önce; diske yazmayla ilişkisi yok, + // kendi namespace'ine yazıyor. + useAnalytics({ progress, questions: QUESTIONS, activeCategories }); + // spinKey yalnızca gerçek bir dönüş başladığında artar — çekiliş havuzu // boşsa reducer state'i değiştirmez, Machine'e anlamsız bir dönüş gitmez. + // spin olayı da burada: reducer çekilişi reddederse olay da gitmez. useEffect(() => { if (state.phase === "spinning" && prevPhaseRef.current !== "spinning") { setSpinKey((key) => key + 1); + trackSpin(state.activeCategories); } prevPhaseRef.current = state.phase; }, [state]); + function handleSubmit(answer: string) { + if (state.current) trackAnswerSubmitted(state.current, answer); + session.submit(answer); + } + function handleRate(rating: SelfRating) { // Soru id'si dispatch'ten önce alınır: RATE turu kapatınca current null olur. if (state.current) pushQuestion(state.current.id); + // Ölçüm de önce: değerlendirmeden önceki kutu ve kayıt yalnızca şimdi elde. + if (state.phase === "evaluated" && state.current) { + trackSelfEval({ + question: state.current, + previous: progress[state.current.id], + evaluation: state.evaluation, + passed: state.passed, + answer: session.lastAnswer, + rating, + now: new Date(), + }); + } session.rate(rating); // Bu değerlendirme henüz state'e yansımadı. reminder.offerAfterRating(countRatings(progress) + 1); @@ -175,7 +201,7 @@ function Session({ store, warning, save }: SessionProps) { {/* Soru kartı ve sonuç ekranı burada; geçişi Stage yönetiyor. */} >; + questions: readonly Question[]; + activeCategories: readonly Category[]; +}; + +function trackAppOpen({ progress, questions, activeCategories }: DueSource): void { + try { + const dueCount = Math.min(dueCountOf(progress, questions, activeCategories, new Date()), 10_000); + analytics.track({ name: "app_open", props: { dueCount } }); + } catch { + // Ölçüm uygulamayı bozmaz. + } +} + +export type AnalyticsSettings = { + /** Tercih okunana kadar null. */ + consent: Consent | null; + setEnabled: (enabled: boolean) => void; + markNoticeShown: () => void; +}; + +export function useAnalytics(source: DueSource): AnalyticsSettings { + const [consent, setConsent] = useState(null); + // Arka plandan dönüşte o anki ilerleme ve seçim gerekiyor; efekt yeniden kurulmasın. + const sourceRef = useRef(source); + useEffect(() => { + sourceRef.current = source; + }); + + useEffect(() => { + let cancelled = false; + void analytics.load().then((loaded) => { + if (!cancelled) setConsent(loaded); + if (launchStarted) return; + launchStarted = true; + trackAppOpen(sourceRef.current); + void analytics.flush(); + }); + + const interval = window.setInterval(() => void analytics.flush(), FLUSH_INTERVAL_MS); + + function handleVisibilityChange() { + if (document.visibilityState === "hidden") { + hiddenAt = Date.now(); + void analytics.flush({ keepalive: true }); + return; + } + if (hiddenAt !== null && Date.now() - hiddenAt >= RESUME_AFTER_MS) { + trackAppOpen(sourceRef.current); + } + hiddenAt = null; + void analytics.flush(); + } + document.addEventListener("visibilitychange", handleVisibilityChange); + + return () => { + cancelled = true; + window.clearInterval(interval); + document.removeEventListener("visibilitychange", handleVisibilityChange); + }; + }, []); + + const setEnabled = useCallback((enabled: boolean) => { + void analytics.setEnabled(enabled); + setConsent(analytics.consent()); + }, []); + + const markNoticeShown = useCallback(() => { + void analytics.markNoticeShown(); + setConsent(analytics.consent()); + }, []); + + return { consent, setEnabled, markNoticeShown }; +} From 8a6dc5a642f681056481e7ef1decf9bf034b5c3d Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 18:33:51 +0300 Subject: [PATCH 14/17] =?UTF-8?q?feat(analytics):=20kullan=C4=B1m=20istati?= =?UTF-8?q?sti=C4=9Fi=20anahtar=C4=B1=20ve=20ilk=20a=C3=A7=C4=B1l=C4=B1?= =?UTF-8?q?=C5=9F=20kart=C4=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ayarlar'da 'Kullanım istatistiklerini paylaş' (varsayılan açık), altında tek satır açıklama ve politika bağlantısı. İlk açılışta engellemeyen kart; gösterildiği an kaydedilir, 'Ayarlar' paneli açıp odağı anahtara taşır. Gizlilik bağlantısı Footer ile ortak bileşende. Co-Authored-By: Claude Opus 5.5 --- src/App.tsx | 18 +++++++- src/analytics/analyticsClient.ts | 23 +++++++--- src/analytics/usageNotice.test.ts | 25 +++++++++++ src/analytics/usageNotice.ts | 14 ++++++ src/analytics/useAnalytics.ts | 34 +++++++++++---- src/components/Footer.tsx | 17 +------- src/components/PrivacyLink.tsx | 25 +++++++++++ src/components/SettingsPanel.tsx | 27 ++++++++++++ src/components/UsageNotice.tsx | 40 ++++++++++++++++++ src/components/UsageStatsSetting.module.css | 23 ++++++++++ src/components/UsageStatsSetting.tsx | 47 +++++++++++++++++++++ 11 files changed, 262 insertions(+), 31 deletions(-) create mode 100644 src/analytics/usageNotice.test.ts create mode 100644 src/analytics/usageNotice.ts create mode 100644 src/components/PrivacyLink.tsx create mode 100644 src/components/UsageNotice.tsx create mode 100644 src/components/UsageStatsSetting.module.css create mode 100644 src/components/UsageStatsSetting.tsx diff --git a/src/App.tsx b/src/App.tsx index 0658f6a..650072a 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -13,6 +13,7 @@ import { SettingsPanel } from "./components/SettingsPanel"; import { Stage } from "./components/Stage"; import { StepIndicator } from "./components/StepIndicator"; import { TopBar } from "./components/TopBar"; +import { UsageNotice } from "./components/UsageNotice"; import { useReminderSettings } from "./hooks/useReminderSettings"; import { useReviewReminder } from "./hooks/useReviewReminder"; import { useSession } from "./hooks/useSession"; @@ -102,7 +103,8 @@ function Session({ store, warning, save }: SessionProps) { // Kullanım ölçümü: app_open, periyodik ve arka plana geçişte gönderim. // Sıra: hatırlatıcıdan sonra, spinKey'den önce; diske yazmayla ilişkisi yok, // kendi namespace'ine yazıyor. - useAnalytics({ progress, questions: QUESTIONS, activeCategories }); + const usage = useAnalytics({ progress, questions: QUESTIONS, activeCategories }); + const [settingsOpenRequest, setSettingsOpenRequest] = useState(0); // spinKey yalnızca gerçek bir dönüş başladığında artar — çekiliş havuzu // boşsa reducer state'i değiştirmez, Machine'e anlamsız bir dönüş gitmez. @@ -183,6 +185,16 @@ function Session({ store, warning, save }: SessionProps) { )} + {usage.noticeOpen && ( + { + usage.closeNotice(); + setSettingsOpenRequest((n) => n + 1); + }} + onClose={usage.closeNotice} + /> + )} + diff --git a/src/analytics/analyticsClient.ts b/src/analytics/analyticsClient.ts index abbc968..d0911ce 100644 --- a/src/analytics/analyticsClient.ts +++ b/src/analytics/analyticsClient.ts @@ -71,12 +71,21 @@ export function createAnalyticsClient(deps: AnalyticsDeps) { return created; } - /** Tercihi depodan okur; okunamazsa kapalı kalır. */ - async function load(): Promise { - await safely("tercih okuma", async () => { - consent = await storage.readConsent(); - }); - return consent; + let loading: Promise | null = null; + + /** + * Tercihi depodan bir kez okur; okunamazsa kapalı kalır. Tekrar çağrı aynı + * sonucu döner: StrictMode'un ikinci efekti, ilkinin sonradan yaptığı + * değişikliği (bilgilendirme gösterildi) depodaki eski değerle ezmesin. + */ + function load(): Promise { + loading ??= (async () => { + await safely("tercih okuma", async () => { + consent = await storage.readConsent(); + }); + return consent; + })(); + return loading; } /** @@ -197,6 +206,8 @@ export function createAnalyticsClient(deps: AnalyticsDeps) { track, flush, consent: (): Consent => consent, + /** Bu derlemede ölçüm mümkün mü (native'de adres tanımlı mı). */ + available: deps.endpoint !== null, }; } diff --git a/src/analytics/usageNotice.test.ts b/src/analytics/usageNotice.test.ts new file mode 100644 index 0000000..f7c1715 --- /dev/null +++ b/src/analytics/usageNotice.test.ts @@ -0,0 +1,25 @@ +import { describe, expect, it } from "vitest"; + +import { shouldShowUsageNotice } from "./usageNotice"; + +describe("shouldShowUsageNotice", () => { + it("ilk açılışta gösterilir", () => { + expect(shouldShowUsageNotice({ enabled: true, noticeShown: false }, true)).toBe(true); + }); + + it("bir kez gösterildiyse bir daha gösterilmez", () => { + expect(shouldShowUsageNotice({ enabled: true, noticeShown: true }, true)).toBe(false); + }); + + it("tercih okunmadan gösterilmez", () => { + expect(shouldShowUsageNotice(null, true)).toBe(false); + }); + + it("ölçüm bu derlemede kapalıysa gösterilmez", () => { + expect(shouldShowUsageNotice({ enabled: true, noticeShown: false }, false)).toBe(false); + }); + + it("kullanıcı zaten kapattıysa gösterilmez", () => { + expect(shouldShowUsageNotice({ enabled: false, noticeShown: false }, true)).toBe(false); + }); +}); diff --git a/src/analytics/usageNotice.ts b/src/analytics/usageNotice.ts new file mode 100644 index 0000000..c08da62 --- /dev/null +++ b/src/analytics/usageNotice.ts @@ -0,0 +1,14 @@ +import type { Consent } from "./analyticsStorage"; + +/* ------------------------------------------------------------------ */ +/* İlk açılış bilgilendirmesi — ne zaman gösterilir */ +/* ------------------------------------------------------------------ */ + +/** + * Tercih okunduysa, ölçüm bu derlemede mümkünse ve kart daha önce hiç + * gösterilmediyse. Kapatmış kullanıcıya da gösterilmez: bilgilendirmenin + * işi kapatma yolunu söylemek, o zaten bulmuş. + */ +export function shouldShowUsageNotice(consent: Consent | null, available: boolean): boolean { + return available && consent !== null && consent.enabled && !consent.noticeShown; +} diff --git a/src/analytics/useAnalytics.ts b/src/analytics/useAnalytics.ts index d03d571..f50c403 100644 --- a/src/analytics/useAnalytics.ts +++ b/src/analytics/useAnalytics.ts @@ -5,6 +5,7 @@ import type { Category, Question } from "../domain/question"; import { dueCountOf } from "../domain/usageMetrics"; import { analytics } from "./analytics"; import type { Consent } from "./analyticsStorage"; +import { shouldShowUsageNotice } from "./usageNotice"; /* ------------------------------------------------------------------ */ /* Kullanım ölçümünün React tarafı */ @@ -44,14 +45,19 @@ function trackAppOpen({ progress, questions, activeCategories }: DueSource): voi } export type AnalyticsSettings = { - /** Tercih okunana kadar null. */ - consent: Consent | null; + /** Bu derlemede ölçüm mümkün mü; değilse anahtar da kart da çizilmez. */ + available: boolean; + /** Ayarlar'daki anahtar; tercih okunana kadar false. */ + enabled: boolean; setEnabled: (enabled: boolean) => void; - markNoticeShown: () => void; + /** İlk açılış bilgilendirmesi bu oturumda açık mı. */ + noticeOpen: boolean; + closeNotice: () => void; }; export function useAnalytics(source: DueSource): AnalyticsSettings { const [consent, setConsent] = useState(null); + const [noticeOpen, setNoticeOpen] = useState(false); // Arka plandan dönüşte o anki ilerleme ve seçim gerekiyor; efekt yeniden kurulmasın. const sourceRef = useRef(source); useEffect(() => { @@ -61,7 +67,14 @@ export function useAnalytics(source: DueSource): AnalyticsSettings { useEffect(() => { let cancelled = false; void analytics.load().then((loaded) => { - if (!cancelled) setConsent(loaded); + if (!cancelled) { + setConsent(loaded); + // Gösterildiği an kaydedilir: kapatılmasa da bir daha çıkmaz. + if (shouldShowUsageNotice(loaded, analytics.available)) { + setNoticeOpen(true); + void analytics.markNoticeShown(); + } + } if (launchStarted) return; launchStarted = true; trackAppOpen(sourceRef.current); @@ -96,10 +109,13 @@ export function useAnalytics(source: DueSource): AnalyticsSettings { setConsent(analytics.consent()); }, []); - const markNoticeShown = useCallback(() => { - void analytics.markNoticeShown(); - setConsent(analytics.consent()); - }, []); + const closeNotice = useCallback(() => setNoticeOpen(false), []); - return { consent, setEnabled, markNoticeShown }; + return { + available: analytics.available, + enabled: consent?.enabled ?? false, + setEnabled, + noticeOpen, + closeNotice, + }; } diff --git a/src/components/Footer.tsx b/src/components/Footer.tsx index 2d97420..b190583 100644 --- a/src/components/Footer.tsx +++ b/src/components/Footer.tsx @@ -1,4 +1,4 @@ -import { platformFeatures } from "../platform"; +import { PrivacyLink } from "./PrivacyLink"; import styles from "./Footer.module.css"; /* ------------------------------------------------------------------ */ @@ -6,8 +6,6 @@ import styles from "./Footer.module.css"; /* ------------------------------------------------------------------ */ const REPO_URL = "https://github.com/Metecode/interview-prep-slots"; -/** Mobil uygulamada göreli yol işe yaramaz (bkz. platformFeatures.sameOriginPages). */ -const PRIVACY_URL_LIVE = "https://slot.meteucar.com/privacy"; export function Footer() { return ( @@ -15,18 +13,7 @@ export function Footer() {

Açık kaynak · MIT ·{" "} - {platformFeatures.sameOriginPages ? ( - /* Statik sayfa, React'in dışında: tam sayfa geçişi. Service worker - /privacy'yi SPA yedeğine düşürmüyor (vite.config.ts). */ - - Gizlilik - - ) : ( - /* Native: dış adres, Capacitor sistem tarayıcısında açar. */ - - Gizlilik - - )} + Gizlilik
{/* Hangi derlemenin çalıştığını söyler; hata bildiriminde işe yarar. */} diff --git a/src/components/PrivacyLink.tsx b/src/components/PrivacyLink.tsx new file mode 100644 index 0000000..1b73424 --- /dev/null +++ b/src/components/PrivacyLink.tsx @@ -0,0 +1,25 @@ +import type { ReactNode } from "react"; + +import { platformFeatures } from "../platform"; + +/* ------------------------------------------------------------------ */ +/* Gizlilik politikası bağlantısı — web'de göreli, native'de canlı site */ +/* ------------------------------------------------------------------ */ + +/** Mobil uygulamada göreli yol işe yaramaz (bkz. platformFeatures.sameOriginPages). */ +const PRIVACY_URL_LIVE = "https://slot.meteucar.com/privacy"; + +export function PrivacyLink({ className, children }: { className: string; children: ReactNode }) { + return platformFeatures.sameOriginPages ? ( + /* Statik sayfa, React'in dışında: tam sayfa geçişi. Service worker + /privacy'yi SPA yedeğine düşürmüyor (vite.config.ts). */ + + {children} + + ) : ( + /* Native: dış adres, Capacitor sistem tarayıcısında açar. */ + + {children} + + ); +} diff --git a/src/components/SettingsPanel.tsx b/src/components/SettingsPanel.tsx index 0d90b2e..dccb360 100644 --- a/src/components/SettingsPanel.tsx +++ b/src/components/SettingsPanel.tsx @@ -6,6 +6,7 @@ import { ChevronIcon } from "./ChevronIcon"; import { Collapse } from "./Collapse"; import { ReminderSetting } from "./ReminderSetting"; import { Switch } from "./Switch"; +import { UsageStatsSetting } from "./UsageStatsSetting"; import styles from "./SettingsPanel.module.css"; /* ------------------------------------------------------------------ */ @@ -29,6 +30,15 @@ export type SettingsPanelProps = { onReminderChange: (enabled: boolean) => void; /** İzin verilmedi ya da sistemden kaldırıldı. */ reminderDenied: boolean; + /** Ölçüm bu derlemede mümkün değilse anahtar çizilmez. */ + usageAvailable: boolean; + usageEnabled: boolean; + onUsageChange: (enabled: boolean) => void; + /** + * Değiştikçe panel açılır ve odak kullanım anahtarına gelir (bilgilendirme + * kartındaki "Ayarlar"). 0: istek yok. + */ + openRequest: number; }; export function SettingsPanel({ @@ -41,9 +51,23 @@ export function SettingsPanel({ reminderEnabled, onReminderChange, reminderDenied, + usageAvailable, + usageEnabled, + onUsageChange, + openRequest, }: SettingsPanelProps) { // Varsayılan kapalı — kimse ayar aramak zorunda kalmasın. const [open, setOpen] = useState(false); + /* + Yeni istek render sırasında işlenir (efektte değil): panelin açılması + ve odak isteği aynı commit'e düşer, anahtar odağı panel açık çizildikten + sonra alır. Odak önce inseydi içerik hâlâ inert olurdu (Collapse). + */ + const [focusRequest, setFocusRequest] = useState(openRequest); + if (openRequest !== focusRequest) { + setFocusRequest(openRequest); + setOpen(true); + } return (
@@ -85,6 +109,9 @@ export function SettingsPanel({ denied={reminderDenied} /> )} + {usageAvailable && ( + + )}
diff --git a/src/components/UsageNotice.tsx b/src/components/UsageNotice.tsx new file mode 100644 index 0000000..c5fdac5 --- /dev/null +++ b/src/components/UsageNotice.tsx @@ -0,0 +1,40 @@ +import { useId } from "react"; + +import styles from "./ReminderOffer.module.css"; + +/* ------------------------------------------------------------------ */ +/* Kullanım ölçümü bilgilendirmesi — ilk açılışta bir kez, engellemeden */ +/* ------------------------------------------------------------------ */ + +/* + Hatırlatıcı öneri kartıyla aynı görünüm ve davranış: makinenin altında, + odağı çekmez, kullanıcı turuna devam edebilir. Gösterildiği an kaydedilir + (App), kapatılmasa da bir daha çıkmaz. +*/ + +export type UsageNoticeProps = { + /** Ayarlar'ı açar ve odağı anahtara taşır. */ + onOpenSettings: () => void; + onClose: () => void; +}; + +export function UsageNotice({ onOpenSettings, onClose }: UsageNoticeProps) { + const textId = useId(); + + return ( +
+

+ Slot'u geliştirmek için kullanım istatistiği topluyoruz: hesabınla ilişkilendirilmeyen, rastgele bir + kurulum kimliğiyle. Cevap metnin gönderilmez. Ayarlar'dan kapatabilirsin. +

+
+ + +
+
+ ); +} diff --git a/src/components/UsageStatsSetting.module.css b/src/components/UsageStatsSetting.module.css new file mode 100644 index 0000000..a5de78e --- /dev/null +++ b/src/components/UsageStatsSetting.module.css @@ -0,0 +1,23 @@ +/* Hatırlatıcı anahtarıyla aynı düzen: anahtar üstte, açıklama altında. */ +.root { + display: inline-flex; + flex-direction: column; + gap: var(--space-1); + max-width: 32ch; +} + +.note { + font-size: var(--fs-label); + color: var(--text-faint); +} + +.link { + color: var(--text-dim); + text-decoration: underline; + text-underline-offset: 2px; +} + +.link:focus-visible { + outline: 2px solid var(--text); + outline-offset: 2px; +} diff --git a/src/components/UsageStatsSetting.tsx b/src/components/UsageStatsSetting.tsx new file mode 100644 index 0000000..9c51f4d --- /dev/null +++ b/src/components/UsageStatsSetting.tsx @@ -0,0 +1,47 @@ +import { useEffect, useId, useRef } from "react"; + +import { PrivacyLink } from "./PrivacyLink"; +import { Switch } from "./Switch"; +import styles from "./UsageStatsSetting.module.css"; + +/* ------------------------------------------------------------------ */ +/* "Kullanım istatistiklerini paylaş" — web ve native */ +/* ------------------------------------------------------------------ */ + +/* + Metinde "anonim" kelimesi geçmez: kalıcı bir kurulum kimliği anonim + değildir (CLAUDE.md, Kullanım ölçümü). Kapatınca kuyruk ve kimlik silinir; + karar analyticsClient.setEnabled'da. +*/ + +export type UsageStatsSettingProps = { + checked: boolean; + onChange: (checked: boolean) => void; + /** Değişince odak anahtara gelir (bilgilendirme kartındaki "Ayarlar"). */ + focusRequest: number; +}; + +export function UsageStatsSetting({ checked, onChange, focusRequest }: UsageStatsSettingProps) { + const noteId = useId(); + const rootRef = useRef(null); + + useEffect(() => { + if (focusRequest === 0) return; + rootRef.current?.querySelector('[role="switch"]')?.focus(); + }, [focusRequest]); + + return ( + + + + Hesabınla ilişkilendirilmeyen, rastgele bir kurulum kimliğiyle.{" "} + Gizlilik politikası + + + ); +} From bf942aa981b6cce8d6e36cc31b3f52540f12b17c Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 18:34:40 +0300 Subject: [PATCH 15/17] =?UTF-8?q?feat(analytics):=20hesap=20silmede=20?= =?UTF-8?q?=C3=B6l=C3=A7=C3=BCm=20kimli=C4=9Fi=20ve=20kuyru=C4=9Fu=20da=20?= =?UTF-8?q?silinir?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'Bu cihazdaki verileri de sil' işaretliyse kurulum kimliği ve kuyruk silinir; kapatma tercihi kalır. Co-Authored-By: Claude Opus 5.5 --- src/account/deleteAccount.test.ts | 37 ++++++++++++++++++++++++++++++- src/account/deleteAccount.ts | 4 ++++ 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/src/account/deleteAccount.test.ts b/src/account/deleteAccount.test.ts index 69dd8ca..9469796 100644 --- a/src/account/deleteAccount.test.ts +++ b/src/account/deleteAccount.test.ts @@ -3,7 +3,15 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { createMemoryAdapter } from "../platform/storage/memoryAdapter"; import type { StorageAdapter } from "../platform"; import type { QuestionProgress } from "../domain/progress"; -import { CORRUPT_BACKUP_PREFIX, STORE_KEY, STORE_NS } from "../storage/storeKeys"; +import { + ANALYTICS_CONSENT_KEY, + ANALYTICS_INSTALL_KEY, + ANALYTICS_NS, + ANALYTICS_QUEUE_KEY, + CORRUPT_BACKUP_PREFIX, + STORE_KEY, + STORE_NS, +} from "../storage/storeKeys"; /* ------------------------------------------------------------------ */ /* Hesap silme akışı — gerçek senkron ve oturum modülleri, sahte fetch */ @@ -169,6 +177,33 @@ describe("deleteAccount", () => { expect(reload).toHaveBeenCalledTimes(1); }); + it("kutu işaretliyken ölçüm kimliği ve kuyruğu silinir, kapatma tercihi kalır", async () => { + const { auth, account } = await loadModules(); + await signIn(auth); + const storage = createMemoryAdapter(); + const consent = { enabled: false, noticeShown: true }; + await storage.set(ANALYTICS_NS, ANALYTICS_CONSENT_KEY, consent); + await storage.set(ANALYTICS_NS, ANALYTICS_INSTALL_KEY, "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b"); + await storage.set(ANALYTICS_NS, ANALYTICS_QUEUE_KEY, []); + fetchMock.mockResolvedValueOnce(new Response(null, { status: 204 })); + + await account.deleteAccount({ clearLocal: true, storage, reload: vi.fn() }); + + expect(await storage.getAll(ANALYTICS_NS)).toEqual([{ key: ANALYTICS_CONSENT_KEY, value: consent }]); + }); + + it("kutu işaretsizken ölçüm verisine dokunulmaz", async () => { + const { auth, account } = await loadModules(); + await signIn(auth); + const storage = createMemoryAdapter(); + await storage.set(ANALYTICS_NS, ANALYTICS_INSTALL_KEY, "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b"); + fetchMock.mockResolvedValueOnce(new Response(null, { status: 204 })); + + await account.deleteAccount({ clearLocal: false, storage, reload: vi.fn() }); + + expect(await storage.get(ANALYTICS_NS, ANALYTICS_INSTALL_KEY)).toBeDefined(); + }); + it("yenileme, silme bitmeden çağrılmaz", async () => { const { auth, account } = await loadModules(); await signIn(auth); diff --git a/src/account/deleteAccount.ts b/src/account/deleteAccount.ts index b0e06bf..a5996c0 100644 --- a/src/account/deleteAccount.ts +++ b/src/account/deleteAccount.ts @@ -1,3 +1,4 @@ +import { createAnalyticsStorage } from "../analytics/analyticsStorage"; import { deleteAccount as deleteAccountOnServer } from "../auth/authClient"; import type { StorageAdapter } from "../platform"; import { STORE_NS } from "../storage/storeKeys"; @@ -50,9 +51,12 @@ export async function deleteAccount({ clearLocal, storage, reload }: DeleteAccou } // Namespace'in tamamı: store kaydı ve bozuk kayıt yedekleri birlikte. + // Kullanım ölçümünden yalnızca kurulum kimliği ve kuyruk: kapatma tercihi + // veri değil, kalır; silinseydi kapatmış kullanıcı sessizce yeniden açılırdı. // Silme bitmeden yenilenirse yarım kalabilir; bu yüzden await. try { await storage.clear(STORE_NS); + await createAnalyticsStorage(storage).clearCollected(); } catch (error) { // Yenileme YAPILMAZ: yenilenseydi veri sessizce geri gelir, kullanıcı // silindiğini sanırdı. Askı da kalkmıyor; oturum anonim, fark etmez. From cecb7cd02d755c23b51f34565a82d59d19a612cd Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 18:37:28 +0300 Subject: [PATCH 16/17] =?UTF-8?q?docs(privacy):=20kullan=C4=B1m=20istatist?= =?UTF-8?q?ikleri=20b=C3=B6l=C3=BCm=C3=BC=20(TR=20ve=20EN)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'Analitik kullanmıyoruz' ifadeleri kaldırıldı. Yeni 2a: rastgele kurulum kimliği, toplanan ve toplanmayan olaylar, IP'nin kaydedilmemesi, 13 ay saklama ve kapatma. Mobil uygulamanın 'sunucuya hiç istek göndermez' cümlesi, çerez/cihaz, sunucu kaydı, yurt dışı aktarım, hukuki dayanak ve saklama bölümleri buna göre güncellendi. Co-Authored-By: Claude Opus 5.5 --- docs/gizlilik-politikasi.md | 60 ++++++++++++++++++++-------- privacy/en/index.html | 79 ++++++++++++++++++++++++++++++++----- privacy/index.html | 78 +++++++++++++++++++++++++++++++----- 3 files changed, 182 insertions(+), 35 deletions(-) diff --git a/docs/gizlilik-politikasi.md b/docs/gizlilik-politikasi.md index 197718e..33a447b 100644 --- a/docs/gizlilik-politikasi.md +++ b/docs/gizlilik-politikasi.md @@ -10,7 +10,7 @@ # Slot — Gizlilik Politikası -Son güncelleme: 30 Eylül 2026 +Son güncelleme: 17 Kasım 2026 Bu politika, Slot'un (slot.meteucar.com ve Slot mobil uygulaması) hangi verileri işlediğini, neden işlediğini ve bu verilerle ilgili haklarını açıklar. @@ -22,26 +22,36 @@ Mete Uçar (bireysel geliştirici) ## Kısaca - Slot hesap açmadan, tam olarak çalışır. Hesapsız kullanımda ilerlemen ve ayarların cihazında saklanır ve bize gönderilmez. -- Reklam, analitik ya da takip aracı kullanmıyoruz. Verini satmıyor, pazarlama amacıyla kimseyle paylaşmıyoruz. +- Reklam ya da üçüncü taraf analitik/takip aracı kullanmıyoruz. Uygulamayı iyileştirmek için, hesabınla ilişkilendirilmeyen rastgele bir kurulum kimliğiyle kendi sunucumuzda kullanım istatistiği tutuyoruz; Ayarlar'dan kapatabilirsin. Verini satmıyor, pazarlama amacıyla kimseyle paylaşmıyoruz. - İsteğe bağlı olarak GitHub ile giriş yaparsan, ilerlemen cihazların arasında senkronlanabilmesi için sunucumuzda saklanır. Giriş yalnızca web sürümünde var. - Hesabını uygulamanın içinden istediğin zaman silebilirsin. ## 1. Hesapsız kullanım -Cevapların, puanların, ilerlemen ve ayarların cihazındaki uygulama deposunda (web sürümünde tarayıcının IndexedDB deposunda) tutulur ve bize gönderilmez. Web sürümü çevrimdışı da çalışabilmek için uygulama dosyalarını tarayıcı önbelleğinde saklar. Bu verileri tarayıcı verilerini temizleyerek ya da uygulamayı silerek kaldırabilirsin. +Cevapların, puanların, ilerlemen ve ayarların cihazındaki uygulama deposunda (web sürümünde tarayıcının IndexedDB deposunda) tutulur ve bize gönderilmez. Web sürümü çevrimdışı da çalışabilmek için uygulama dosyalarını tarayıcı önbelleğinde saklar. Bu verileri tarayıcı verilerini temizleyerek ya da uygulamayı silerek kaldırabilirsin. Kullanım istatistikleri açıksa bazı kullanım olayları sunucumuza gönderilir (bkz. 2a). Web sürümünü açtığında tarayıcın sayfayı sunucumuzdan yükler. Bu isteklere ait teknik kayıtlar 5. bölümde anlatılıyor. ## 2. Mobil uygulama -Mobil uygulamada hesap ya da giriş yok; uygulama sunucumuza hiçbir istek göndermez. +Mobil uygulamada hesap ya da giriş yok. Uygulama sunucumuza yalnızca kullanım istatistiklerini gönderir (bkz. 2a); ilerlemen ve cevapların gönderilmez. - **İlerleme ve ayarlar:** Cihazında, uygulamanın kendi klasöründeki JSON dosyalarında saklanır ve sunucumuza gönderilmez. Uygulamayı sildiğinde bu dosyalar da silinir. Android yedeklemen açıksa bu dosyalar Google hesabındaki cihaz yedeğine dahil edilebilir; bu yedeğe biz erişemeyiz. - **Hatırlatıcı:** Tekrar hatırlatıcısını açarsan bildirim cihazında yerel olarak kurulur; bildirim sunucusu kullanılmaz. Hatırlatıcıyı Ayarlar'dan kapatabilirsin. -- **Analitik ve reklam yok:** Uygulama analitik, reklam ya da çökme raporlama aracı (SDK) içermez. +- **Reklam ve üçüncü taraf araç yok:** Uygulama reklam, üçüncü taraf analitik ya da çökme raporlama aracı (SDK) içermez. - **Kendi yapay zekâna sor:** Yalnızca sen başlattığında, promptu seçtiğin üçüncü taraf servise iletir; Slot bu veriyi sunucusuna göndermez. ChatGPT, Claude ve Perplexity'ye prompt adresin içinde (`?q=`) gider ve o servisin geçmişine kendi hesabında düşebilir. Ayrıntılar 6. bölümde. -GitHub ile giriş, çerezler ve sunucu kayıtları (3–5. bölümler) yalnızca web sürümü için geçerlidir. +GitHub ile giriş, çerezler ve sunucu kayıtları (3–5. bölümler) yalnızca web sürümü için geçerlidir; kullanım istatistikleriyle ilgili kısımlar (2a, 4. ve 5. bölümlerdeki notlar) iki sürüm için de geçerlidir. + +## 2a. Kullanım istatistikleri + +Slot'un nasıl kullanıldığını anlamak için (kaç kişinin uygulamaya geri döndüğü, tekrarların tamamlanıp tamamlanmadığı, cevap kontrolünün senin değerlendirmenle ne kadar uyuştuğu) web ve mobil sürümde kullanım olaylarını kendi sunucumuzda topluyoruz. Bu ayar varsayılan olarak açıktır. + +- **Kimlik:** Uygulama ilk açılışta cihazında rastgele bir kurulum kimliği üretir. Bu kimlik hesabınla ilişkilendirilmez; giriş yapmış olsan bile olaylar GitHub hesabına ya da Slot hesabına bağlanmaz. Cihaz kimliği ya da reklam kimliği kullanılmaz. +- **Toplanan olaylar:** uygulamanın açılması (o an tekrar zamanı gelmiş soru sayısıyla), makaranın çevrilmesi (seçili kategori sayısıyla), cevap gönderilmesi (soru kimliği ve cevabın karakter sayısıyla), öz-değerlendirme (soru kimliği, cevap kontrolünün sonucu, senin değerlendirmen, sorunun yeni seviyesi ve tekrar zamanının gelmiş olup olmadığıyla). Her olayla birlikte olayın zamanı, platform (web, Android, iOS) ve uygulama sürümü gönderilir. +- **Toplanmayanlar:** Cevap metnin hiçbir zaman gönderilmez, yalnızca uzunluğu gönderilir. Ad, e-posta, IP adresi ya da tarayıcı/cihaz bilgisi (User-Agent) saklanmaz; bu istekler için sunucu erişim kaydı da tutulmaz. +- **Saklama:** Olaylar 13 ay sonra otomatik olarak silinir. +- **Kapatma:** Ayarlar → "Kullanım istatistiklerini paylaş". Kapattığında henüz gönderilmemiş olaylar ve kurulum kimliği cihazından silinir, yeni olay toplanmaz. Daha önce gönderilmiş olaylar artık seninle eşleştirilemez ve 13 ay sonra silinir. Yeniden açarsan yeni bir kurulum kimliği üretilir. Kurulum kimliğini bilmediğimiz için gönderilmiş olayları kişi bazında silemeyiz; bu olaylar 13 ay sonra otomatik olarak silinir. ## 3. GitHub ile giriş (isteğe bağlı) @@ -67,9 +77,11 @@ Takip ya da analitik çerezi kullanmıyoruz. Yalnızca giriş için gereken iki Hesapsız kullanımda hiçbir çerez yazılmaz. +- **Kurulum kimliği ve gönderilmeyi bekleyen olaylar:** Kullanım istatistikleri açıksa cihazındaki uygulama deposunda tutulur; çerez değildir. + ## 5. Sunucu kayıtları -Web sürümünü kullanırken sunucumuz her istekte şu teknik bilgileri kaydeder: IP adresi, zaman, istenen adres, yanıt kodu, yönlendiren sayfa ve tarayıcı bilgisi (User-Agent). Bu kayıtlar güvenlik ve hata ayıklama amacıyla tutulur ve en fazla 15 gün sonra otomatik olarak silinir. +Web sürümünü kullanırken sunucumuz her istekte şu teknik bilgileri kaydeder: IP adresi, zaman, istenen adres, yanıt kodu, yönlendiren sayfa ve tarayıcı bilgisi (User-Agent). Bu kayıtlar güvenlik ve hata ayıklama amacıyla tutulur ve en fazla 15 gün sonra otomatik olarak silinir. Kullanım istatistiği isteklerinde (`/api/events`) erişim kaydı tutulmaz. Uygulamanın kendi kayıtları hesap kimliğini içerebilir; cevap metinlerini içermez. Bu kayıtların boyutu sınırlıdır ve yeni kayıtlar geldikçe eskileri silinir. @@ -88,7 +100,7 @@ Uygulamayı App Store ya da Google Play'den indirirsen, bu mağazalar kendi poli ## 7. Yurt dışına aktarım (KVKK md. 9) -Web sürümünü kullandığında sunucu kayıtların (5. bölüm), GitHub ile giriş yaptığında hesap ve senkron verilerin, barındırma hizmeti aldığımız Netcup GmbH'nin Nürnberg'deki (Almanya) sunucularında saklanır. Türkiye'den kullanıyorsan bu, kişisel verilerinin yurt dışına aktarılması anlamına gelir. +Web sürümünü kullandığında sunucu kayıtların (5. bölüm), GitHub ile giriş yaptığında hesap ve senkron verilerin, kullanım istatistikleri açıksa kullanım olayların, barındırma hizmeti aldığımız Netcup GmbH'nin Nürnberg'deki (Almanya) sunucularında saklanır. Türkiye'den kullanıyorsan bu, kişisel verilerinin yurt dışına aktarılması anlamına gelir. GitHub ile giriş yaptığında giriş işlemi GitHub, Inc.'in (ABD) sunucularında gerçekleşir: tarayıcın doğrudan GitHub'a bağlanır, GitHub kimliğini doğrular ve kullanıcı kimliğini ve kullanıcı adını bize iletir. @@ -96,6 +108,7 @@ GitHub ile giriş yaptığında giriş işlemi GitHub, Inc.'in (ABD) sunucuları - Hesap ve senkron verileri: sözleşmenin kurulması ve ifası (KVKK md. 5/2-c; GDPR md. 6/1-b). - Sunucu kayıtları: hizmetin güvenliğini sağlamaya yönelik meşru menfaat (KVKK md. 5/2-f; GDPR md. 6/1-f). +- Kullanım istatistikleri: uygulamayı iyileştirmeye yönelik meşru menfaatimiz (KVKK md. 5/2-f; GDPR md. 6/1-f). İstediğin zaman Ayarlar'dan kapatarak itiraz edebilirsin. ## 9. Saklama süreleri @@ -103,6 +116,7 @@ GitHub ile giriş yaptığında giriş işlemi GitHub, Inc.'in (ABD) sunucuları - Sunucu erişim kayıtları: en fazla 15 gün. - Veritabanı yedekleri: en fazla 15 gün. Silinen hesaplar en geç bu sürenin sonunda yedeklerden de çıkar. - Oturum çerezi: kullanılmazsa 30 gün. +- Kullanım olayları: 13 ay. ## 10. Hesabını silme @@ -128,7 +142,7 @@ Bu politikayı güncellersek sayfanın başındaki tarihi değiştiririz. Öneml # Slot — Privacy Policy -Last updated: 30 September 2026 +Last updated: 17 November 2026 This policy explains what data Slot (slot.meteucar.com and the Slot mobile app) processes, why, and what your rights are. @@ -140,26 +154,36 @@ Contact: i.meteucar@gmail.com · meteucar.com ## Summary - Slot works fully without an account. Without an account, your progress and settings are stored on your device and are not sent to us. -- We use no advertising, analytics or tracking tools. We do not sell your data or share it for marketing. +- We use no advertising or third-party analytics/tracking tools. To improve the app, we keep usage statistics on our own server with a random installation ID that is not linked to your account; you can turn this off in Settings. We do not sell your data or share it for marketing. - If you choose to sign in with GitHub, your progress is stored on our server so it can sync across your devices. Sign-in is available only in the web version. - You can delete your account from within the app at any time. ## 1. Using Slot without an account -Your answers, ratings, progress and settings are kept in the app's storage on your device (in the web version, the browser's IndexedDB) and are not sent to us. To work offline, the web version stores the app's files in the browser cache. You can remove this data by clearing your browser data or uninstalling the app. +Your answers, ratings, progress and settings are kept in the app's storage on your device (in the web version, the browser's IndexedDB) and are not sent to us. To work offline, the web version stores the app's files in the browser cache. You can remove this data by clearing your browser data or uninstalling the app. If usage statistics are on, some usage events are sent to our server (see 2a). When you open the web version, your browser loads the page from our server. The technical logs of these requests are described in section 5. ## 2. Mobile app -The mobile app has no accounts or sign-in, and it sends no requests to our server. +The mobile app has no accounts or sign-in. It sends our server only usage statistics (see 2a); your progress and answers are not sent. - **Progress and settings:** Stored on your device, in JSON files in the app's own folder, and not sent to our server. Uninstalling the app deletes these files. If Android backup is turned on, these files may be included in the device backup in your Google account; we have no access to that backup. - **Reminders:** If you turn on review reminders, the notification is scheduled locally on your device; no notification server is used. You can turn reminders off in Settings. -- **No analytics or ads:** The app contains no analytics, advertising or crash-reporting SDK. +- **No ads or third-party tools:** The app contains no advertising, third-party analytics or crash-reporting SDK. - **Ask your own AI:** Only when you start it, the prompt is passed to the third-party service you choose; Slot does not send this data to its server. For ChatGPT, Claude and Perplexity the prompt travels in the address (`?q=`) and may appear in that service's history in your own account. Details in section 6. -Signing in with GitHub, cookies and server logs (sections 3–5) apply only to the web version. +Signing in with GitHub, cookies and server logs (sections 3–5) apply only to the web version; the parts about usage statistics (2a and the notes in sections 4 and 5) apply to both versions. + +## 2a. Usage statistics + +To understand how Slot is used (how many people come back, whether reviews get completed, how often the answer check agrees with your own rating), we collect usage events on our own server in the web and mobile versions. This setting is on by default. + +- **Identifier:** On first launch the app generates a random installation ID on your device. It is not linked to your account; even when you are signed in, events are not tied to your GitHub or Slot account. No device ID or advertising ID is used. +- **Events collected:** opening the app (with the number of questions due for review at that moment), spinning the reels (with the number of selected categories), submitting an answer (question ID and the answer's character count), self-rating (question ID, the answer check's result, your rating, the question's new level and whether it was due). Each event carries its time, the platform (web, Android, iOS) and the app version. +- **Not collected:** Your answer text is never sent, only its length. No name, email, IP address or browser/device information (User-Agent) is stored, and no server access log is kept for these requests. +- **Retention:** Events are deleted automatically after 13 months. +- **Turning it off:** Settings → "Share usage statistics". When you turn it off, events not yet sent and the installation ID are deleted from your device and no new events are collected. Events already sent can no longer be matched to you and are deleted after 13 months. If you turn it back on, a new installation ID is generated. Since we do not know your installation ID, we cannot delete sent events individually; they are deleted automatically after 13 months. ## 3. Signing in with GitHub (optional) @@ -185,9 +209,11 @@ We use no tracking or analytics cookies. Only two cookies are needed for sign-in No cookies are set when you use Slot without an account. +- **Installation ID and events waiting to be sent:** kept in the app's storage on your device while usage statistics are on; not a cookie. + ## 5. Server logs -When you use the web version, our server records the following for each request: IP address, time, requested URL, response code, referring page and browser information (User-Agent). These logs are kept for security and troubleshooting and are deleted automatically after at most 15 days. +When you use the web version, our server records the following for each request: IP address, time, requested URL, response code, referring page and browser information (User-Agent). These logs are kept for security and troubleshooting and are deleted automatically after at most 15 days. No access log is kept for usage statistics requests (`/api/events`). The application's own logs may contain your account ID; they never contain your answer texts. These logs are size-limited, and older entries are deleted as new ones arrive. @@ -206,7 +232,7 @@ If you download the app from the App Store or Google Play, those stores process ## 7. Transfers abroad (KVKK Art. 9) -When you use the web version, your server logs (section 5), and when you sign in with GitHub, your account and sync data, are stored on the servers of our hosting provider Netcup GmbH in Nuremberg, Germany. If you use Slot from Turkey, this means your personal data is transferred abroad. +When you use the web version, your server logs (section 5), when you sign in with GitHub, your account and sync data, and, if usage statistics are on, your usage events, are stored on the servers of our hosting provider Netcup GmbH in Nuremberg, Germany. If you use Slot from Turkey, this means your personal data is transferred abroad. When you sign in with GitHub, sign-in takes place on the servers of GitHub, Inc. (USA): your browser connects directly to GitHub, which authenticates you and passes your user ID and username to us. @@ -214,6 +240,7 @@ When you sign in with GitHub, sign-in takes place on the servers of GitHub, Inc. - Account and sync data: performance of a contract (KVKK Art. 5/2-c; GDPR Art. 6(1)(b)). - Server logs: legitimate interest in keeping the service secure (KVKK Art. 5/2-f; GDPR Art. 6(1)(f)). +- Usage statistics: our legitimate interest in improving the app (KVKK Art. 5/2-f; GDPR Art. 6(1)(f)). You can object at any time by turning it off in Settings. ## 9. Retention @@ -221,6 +248,7 @@ When you sign in with GitHub, sign-in takes place on the servers of GitHub, Inc. - Server access logs: at most 15 days. - Database backups: at most 15 days. Deleted accounts are removed from backups at the latest when this period ends. - Session cookie: 30 days if unused. +- Usage events: 13 months. ## 10. Deleting your account diff --git a/privacy/en/index.html b/privacy/en/index.html index f76b99c..77421dc 100644 --- a/privacy/en/index.html +++ b/privacy/en/index.html @@ -31,7 +31,7 @@

Slot — Privacy Policy

-

Last updated: 30 September 2026

+

Last updated: 17 November 2026

This policy explains what data Slot (slot.meteucar.com and the Slot mobile app) processes, why, and what @@ -54,7 +54,11 @@

Summary

Slot works fully without an account. Without an account, your progress and settings are stored on your device and are not sent to us. -
  • We use no advertising, analytics or tracking tools. We do not sell your data or share it for marketing.
  • +
  • + We use no advertising or third-party analytics/tracking tools. To improve the app, we keep usage + statistics on our own server with a random installation ID that is not linked to your account; you can + turn this off in Settings. We do not sell your data or share it for marketing. +
  • If you choose to sign in with GitHub, your progress is stored on our server so it can sync across your devices. Sign-in is available only in the web version. @@ -69,7 +73,8 @@

    1. Using Slot without an account

    Your answers, ratings, progress and settings are kept in the app's storage on your device (in the web version, the browser's IndexedDB) and are not sent to us. To work offline, the web version stores the app's files in the browser cache. You can remove this data by clearing your browser data or uninstalling - the app. + the app. If usage statistics are on, some usage events are sent to our server (see + 2a).

    When you open the web version, your browser loads the page from our server. The technical logs of these @@ -79,7 +84,10 @@

    1. Using Slot without an account

    2. Mobile app

    -

    The mobile app has no accounts or sign-in, and it sends no requests to our server.

    +

    + The mobile app has no accounts or sign-in. It sends our server only usage statistics (see + 2a); your progress and answers are not sent. +

    • Progress and settings: Stored on your device, in JSON files in the app's own folder, and @@ -91,7 +99,8 @@

      2. Mobile app

      your device; no notification server is used. You can turn reminders off in Settings.
    • - No analytics or ads: The app contains no analytics, advertising or crash-reporting SDK. + No ads or third-party tools: The app contains no advertising, third-party analytics or + crash-reporting SDK.
    • Ask your own AI: Only when you start it, the prompt is passed to the third-party service @@ -100,7 +109,46 @@

      2. Mobile app

      Details in section 6.
    -

    Signing in with GitHub, cookies and server logs (sections 3–5) apply only to the web version.

    +

    + Signing in with GitHub, cookies and server logs (sections 3–5) apply only to the web version; the parts + about usage statistics (2a and the notes in sections 4 and 5) apply to both versions. +

    +
    + +
    +

    2a. Usage statistics

    +

    + To understand how Slot is used (how many people come back, whether reviews get completed, how often the + answer check agrees with your own rating), we collect usage events on our own server in the web and mobile + versions. This setting is on by default. +

    +
      +
    • + Identifier: On first launch the app generates a random installation ID on your device. + It is not linked to your account; even when you are signed in, events are not tied to your GitHub or + Slot account. No device ID or advertising ID is used. +
    • +
    • + Events collected: opening the app (with the number of questions due for review at that + moment), spinning the reels (with the number of selected categories), submitting an answer (question ID + and the answer's character count), self-rating (question ID, the answer check's result, your rating, the + question's new level and whether it was due). Each event carries its time, the platform (web, Android, + iOS) and the app version. +
    • +
    • + Not collected: Your answer text is never sent, only its length. No name, email, IP + address or browser/device information (User-Agent) is stored, and no server access log is kept for these + requests. +
    • +
    • Retention: Events are deleted automatically after 13 months.
    • +
    • + Turning it off: Settings → "Share usage statistics". When you turn it off, events not + yet sent and the installation ID are deleted from your device and no new events are collected. Events + already sent can no longer be matched to you and are deleted after 13 months. If you turn it back on, a + new installation ID is generated. Since we do not know your installation ID, we cannot delete sent events + individually; they are deleted automatically after 13 months. +
    • +
    @@ -137,6 +185,12 @@

    4. Cookies and on-device storage

  • JSESSIONID: used only during the GitHub sign-in flow and deleted once sign-in completes.
  • No cookies are set when you use Slot without an account.

    +
      +
    • + Installation ID and events waiting to be sent: kept in the app's storage on your device + while usage statistics are on; not a cookie. +
    • +
    @@ -144,7 +198,8 @@

    5. Server logs

    When you use the web version, our server records the following for each request: IP address, time, requested URL, response code, referring page and browser information (User-Agent). These logs are kept - for security and troubleshooting and are deleted automatically after at most 15 days. + for security and troubleshooting and are deleted automatically after at most 15 days. No access log is + kept for usage statistics requests (/api/events).

    The application's own logs may contain your account ID; they never contain your answer texts. These logs @@ -180,8 +235,9 @@

    6. Where data is stored and who it is shared with

    7. Transfers abroad (KVKK Art. 9)

    - When you use the web version, your server logs (section 5), and when you sign - in with GitHub, your account and sync data, are stored on the servers of our hosting provider Netcup GmbH + When you use the web version, your server logs (section 5), when you sign in + with GitHub, your account and sync data, and, if usage statistics are on, your usage events, are stored on + the servers of our hosting provider Netcup GmbH in Nuremberg, Germany. If you use Slot from Turkey, this means your personal data is transferred abroad.

    @@ -195,6 +251,10 @@

    8. Legal basis

    • Account and sync data: performance of a contract (KVKK Art. 5/2-c; GDPR Art. 6(1)(b)).
    • Server logs: legitimate interest in keeping the service secure (KVKK Art. 5/2-f; GDPR Art. 6(1)(f)).
    • +
    • + Usage statistics: our legitimate interest in improving the app (KVKK Art. 5/2-f; GDPR Art. 6(1)(f)). You + can object at any time by turning it off in Settings. +
    @@ -208,6 +268,7 @@

    9. Retention

    period ends.
  • Session cookie: 30 days if unused.
  • +
  • Usage events: 13 months.
  • diff --git a/privacy/index.html b/privacy/index.html index 6b389bb..0a80f84 100644 --- a/privacy/index.html +++ b/privacy/index.html @@ -35,7 +35,7 @@

    Slot — Gizlilik Politikası

    -

    Son güncelleme: 30 Eylül 2026

    +

    Son güncelleme: 17 Kasım 2026

    Bu politika, Slot'un (slot.meteucar.com ve Slot mobil uygulaması) hangi verileri işlediğini, neden @@ -59,8 +59,9 @@

    Kısaca

    ve bize gönderilmez.
  • - Reklam, analitik ya da takip aracı kullanmıyoruz. Verini satmıyor, pazarlama amacıyla kimseyle - paylaşmıyoruz. + Reklam ya da üçüncü taraf analitik/takip aracı kullanmıyoruz. Uygulamayı iyileştirmek için, hesabınla + ilişkilendirilmeyen rastgele bir kurulum kimliğiyle kendi sunucumuzda kullanım istatistiği tutuyoruz; + Ayarlar'dan kapatabilirsin. Verini satmıyor, pazarlama amacıyla kimseyle paylaşmıyoruz.
  • İsteğe bağlı olarak GitHub ile giriş yaparsan, ilerlemen cihazların arasında senkronlanabilmesi için @@ -76,7 +77,8 @@

    1. Hesapsız kullanım

    Cevapların, puanların, ilerlemen ve ayarların cihazındaki uygulama deposunda (web sürümünde tarayıcının IndexedDB deposunda) tutulur ve bize gönderilmez. Web sürümü çevrimdışı da çalışabilmek için uygulama dosyalarını tarayıcı önbelleğinde saklar. Bu verileri tarayıcı verilerini temizleyerek ya da uygulamayı - silerek kaldırabilirsin. + silerek kaldırabilirsin. Kullanım istatistikleri açıksa bazı kullanım olayları sunucumuza gönderilir + (bkz. 2a).

    Web sürümünü açtığında tarayıcın sayfayı sunucumuzdan yükler. Bu isteklere ait teknik kayıtlar @@ -86,7 +88,10 @@

    1. Hesapsız kullanım

    2. Mobil uygulama

    -

    Mobil uygulamada hesap ya da giriş yok; uygulama sunucumuza hiçbir istek göndermez.

    +

    + Mobil uygulamada hesap ya da giriş yok. Uygulama sunucumuza yalnızca kullanım istatistiklerini gönderir + (bkz. 2a); ilerlemen ve cevapların gönderilmez. +

    • İlerleme ve ayarlar: Cihazında, uygulamanın kendi klasöründeki JSON dosyalarında saklanır @@ -98,8 +103,8 @@

      2. Mobil uygulama

      bildirim sunucusu kullanılmaz. Hatırlatıcıyı Ayarlar'dan kapatabilirsin.
    • - Analitik ve reklam yok: Uygulama analitik, reklam ya da çökme raporlama aracı (SDK) - içermez. + Reklam ve üçüncü taraf araç yok: Uygulama reklam, üçüncü taraf analitik ya da çökme + raporlama aracı (SDK) içermez.
    • Kendi yapay zekâna sor: Yalnızca sen başlattığında, promptu seçtiğin üçüncü taraf @@ -108,7 +113,47 @@

      2. Mobil uygulama

      6. bölümde.
    -

    GitHub ile giriş, çerezler ve sunucu kayıtları (3–5. bölümler) yalnızca web sürümü için geçerlidir.

    +

    + GitHub ile giriş, çerezler ve sunucu kayıtları (3–5. bölümler) yalnızca web sürümü için geçerlidir; + kullanım istatistikleriyle ilgili kısımlar (2a, 4. ve 5. bölümlerdeki notlar) iki sürüm için de + geçerlidir. +

    +
    + +
    +

    2a. Kullanım istatistikleri

    +

    + Slot'un nasıl kullanıldığını anlamak için (kaç kişinin uygulamaya geri döndüğü, tekrarların tamamlanıp + tamamlanmadığı, cevap kontrolünün senin değerlendirmenle ne kadar uyuştuğu) web ve mobil sürümde kullanım + olaylarını kendi sunucumuzda topluyoruz. Bu ayar varsayılan olarak açıktır. +

    +
      +
    • + Kimlik: Uygulama ilk açılışta cihazında rastgele bir kurulum kimliği üretir. Bu kimlik + hesabınla ilişkilendirilmez; giriş yapmış olsan bile olaylar GitHub hesabına ya da Slot hesabına + bağlanmaz. Cihaz kimliği ya da reklam kimliği kullanılmaz. +
    • +
    • + Toplanan olaylar: uygulamanın açılması (o an tekrar zamanı gelmiş soru sayısıyla), + makaranın çevrilmesi (seçili kategori sayısıyla), cevap gönderilmesi (soru kimliği ve cevabın karakter + sayısıyla), öz-değerlendirme (soru kimliği, cevap kontrolünün sonucu, senin değerlendirmen, sorunun yeni + seviyesi ve tekrar zamanının gelmiş olup olmadığıyla). Her olayla birlikte olayın zamanı, platform (web, + Android, iOS) ve uygulama sürümü gönderilir. +
    • +
    • + Toplanmayanlar: Cevap metnin hiçbir zaman gönderilmez, yalnızca uzunluğu gönderilir. + Ad, e-posta, IP adresi ya da tarayıcı/cihaz bilgisi (User-Agent) saklanmaz; bu istekler için sunucu + erişim kaydı da tutulmaz. +
    • +
    • Saklama: Olaylar 13 ay sonra otomatik olarak silinir.
    • +
    • + Kapatma: Ayarlar → "Kullanım istatistiklerini paylaş". Kapattığında henüz + gönderilmemiş olaylar ve kurulum kimliği cihazından silinir, yeni olay toplanmaz. Daha önce gönderilmiş + olaylar artık seninle eşleştirilemez ve 13 ay sonra silinir. Yeniden açarsan yeni bir kurulum kimliği + üretilir. Kurulum kimliğini bilmediğimiz için gönderilmiş olayları kişi bazında silemeyiz; bu olaylar + 13 ay sonra otomatik olarak silinir. +
    • +
    @@ -148,6 +193,12 @@

    4. Çerezler ve cihazda saklananlar

  • Hesapsız kullanımda hiçbir çerez yazılmaz.

    +
      +
    • + Kurulum kimliği ve gönderilmeyi bekleyen olaylar: Kullanım istatistikleri açıksa + cihazındaki uygulama deposunda tutulur; çerez değildir. +
    • +
    @@ -155,7 +206,8 @@

    5. Sunucu kayıtları

    Web sürümünü kullanırken sunucumuz her istekte şu teknik bilgileri kaydeder: IP adresi, zaman, istenen adres, yanıt kodu, yönlendiren sayfa ve tarayıcı bilgisi (User-Agent). Bu kayıtlar güvenlik ve hata - ayıklama amacıyla tutulur ve en fazla 15 gün sonra otomatik olarak silinir. + ayıklama amacıyla tutulur ve en fazla 15 gün sonra otomatik olarak silinir. Kullanım istatistiği + isteklerinde (/api/events) erişim kaydı tutulmaz.

    Uygulamanın kendi kayıtları hesap kimliğini içerebilir; cevap metinlerini içermez. Bu kayıtların boyutu @@ -195,7 +247,8 @@

    6. Verilerin saklandığı yer ve paylaşım

    7. Yurt dışına aktarım (KVKK md. 9)

    Web sürümünü kullandığında sunucu kayıtların (5. bölüm), GitHub ile - giriş yaptığında hesap ve senkron verilerin, barındırma hizmeti aldığımız Netcup GmbH'nin Nürnberg'deki + giriş yaptığında hesap ve senkron verilerin, kullanım istatistikleri açıksa kullanım olayların, barındırma + hizmeti aldığımız Netcup GmbH'nin Nürnberg'deki (Almanya) sunucularında saklanır. Türkiye'den kullanıyorsan bu, kişisel verilerinin yurt dışına aktarılması anlamına gelir.

    @@ -214,6 +267,10 @@

    8. Hukuki dayanak

    Sunucu kayıtları: hizmetin güvenliğini sağlamaya yönelik meşru menfaat (KVKK md. 5/2-f; GDPR md. 6/1-f). +
  • + Kullanım istatistikleri: uygulamayı iyileştirmeye yönelik meşru menfaatimiz (KVKK md. 5/2-f; GDPR md. + 6/1-f). İstediğin zaman Ayarlar'dan kapatarak itiraz edebilirsin. +
  • @@ -226,6 +283,7 @@

    9. Saklama süreleri

    Veritabanı yedekleri: en fazla 15 gün. Silinen hesaplar en geç bu sürenin sonunda yedeklerden de çıkar.
  • Oturum çerezi: kullanılmazsa 30 gün.
  • +
  • Kullanım olayları: 13 ay.
  • From 258872779f07dc324e9c242db2863a1231d7d0be Mon Sep 17 00:00:00 2001 From: Metecode Date: Tue, 17 Nov 2026 18:39:24 +0300 Subject: [PATCH 17/17] =?UTF-8?q?docs:=20istemci=20taraf=C4=B1=20=C3=B6l?= =?UTF-8?q?=C3=A7=C3=BCm=20kararlar=C4=B1=20ve=20yay=C4=B1n=20engelleri?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md'ye istemci bölümü (alanların kaynağı, namespace, kilit, kenar durumlar, VITE_API_BASE_URL notu) ve hukuki dayanak kararı; yayın engellerine host nginx bloğunun main'e birleşmeden önce uygulanması. Yol haritasında Faz 2 durumu. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 65 +++++++++++++++++++++++++++++++++++++++-- docs/roadmap-backend.md | 11 +++---- 2 files changed, 68 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2b12671..c77fc85 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -462,11 +462,21 @@ shadcn/ui bileşenleri ihtiyaç oldukça tek tek eklenir, toplu kurulmaz. ## Kullanım ölçümü (`analytics/`) -- **YAYIN ENGELİ.** Gizlilik politikası (TR ve EN, `docs/gizlilik-politikasi.md` - ve `privacy/`) ile Play veri güvenliği formu güncellenmeden istemci - tarafı yayına çıkmaz. Politika bugün "analitik kullanmıyoruz" diyor. +- **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 @@ -516,6 +526,55 @@ shadcn/ui bileşenleri ihtiyaç oldukça tek tek eklenir, toplu kurulmaz. `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 diff --git a/docs/roadmap-backend.md b/docs/roadmap-backend.md index 579c587..28af6dd 100644 --- a/docs/roadmap-backend.md +++ b/docs/roadmap-backend.md @@ -109,21 +109,22 @@ Sonraki fazlarda güvenle değişiklik yapabilmek için güvenlik ağı. Takım Kurulun ilk koşulu: aktif kullanıcı, 7/30 gün geri dönüş ve Leitner tamamlanma oranını ölçmek. Hesapsız mobil kullanıcılar dahil, hesapla ilişkilendirilmeyen, rastgele kurulum kimliğiyle; ad, e-posta, IP, user-agent tutulmadan. -**Durum (2026-11-17):** backend `feat/analytics` dalında (V4, `POST /api/events`, saklama işi, `docs/analytics/queries.sql`). İstemci ayrı adımda. +**Durum (2026-11-17):** backend ve istemci `feat/analytics` dalında (V4, `POST /api/events`, saklama işi, `docs/analytics/queries.sql`; web ve mobil istemci, Ayarlar anahtarı, ilk açılış kartı). Gizlilik politikası güncellendi. -**Yayın engeli:** gizlilik politikası (TR ve EN) ve Play veri güvenliği formu güncellenmeden istemci tarafı yayına çıkmaz. Politika bugün "analitik kullanmıyoruz" diyor. Metinlerde "anonim" değil "hesabınla ilişkilendirilmeyen, rastgele kurulum kimliği" ifadesi kullanılır. +**Yayın engelleri:** (1) Play veri güvenliği formu güncellenmeden istemci yayına çıkmaz. (2) Host nginx'teki `/api/events` bloğu (`access_log off`) uygulanmadan politika yayına alınmaz, yoksa "erişim kaydı tutulmaz" cümlesi yanlış olur; politika frontend imajıyla kurulduğu için bu, dalın main'e birleşmesinden önce yapılır. Gizlilik politikası (TR ve EN) güncellendi. Metinlerde "anonim" değil "hesabınla ilişkilendirilmeyen, rastgele kurulum kimliği" ifadesi kullanılır. **Kapsam** - [x] Olay şeması: `app_open {dueCount}`, `spin {categoryCount}`, `answer_submitted {questionId, answerLength}`, `self_eval {questionId, aliasResult, result, box, wasDue}`; kurulum kimliği, platform ve sürüm batch zarfında. Cevap metni gönderilmez. (İlk taslaktaki `self_assessed`/`review_completed` adları kullanılmadı; `leitner_review_done` da çıkarıldı, tamamlanma `self_eval.wasDue` ve `app_open.dueCount`'tan hesaplanıyor.) - [x] `POST /api/events` toplu uç: en fazla 50 olay, geçersiz olay batch'i düşürmez, kurulum başına ve genel rate limit, mobil WebView origin'leri için CORS. -- [ ] İstemci: olayları biriktirip toplu gönderir, çevrimdışıyken kuyrukta bekler (istemci adımı). +- [x] İstemci: olayları yerel kuyrukta biriktirip toplu gönderir (açılış, arka plana geçiş, 60 sn), çevrimdışıyken kuyrukta bekler; 429'da Retry-After, diğer hatalarda artan bekleme. - [x] Idempotency: olay başına `eventId`, tekrar gönderimde çift kayıt yok. - [x] Yazma yolu: tek tabloya toplu insert, 13 ay saklama. Aylık partitioning henüz yok; hacim gerektirince. - [ ] Rollup: gecelik job ile günlük aktif cihaz ve cohort tabloları; dashboard bunları okur. Şimdilik `docs/analytics/queries.sql` elle çalıştırılıyor. - [x] Cevap kontrolü ölçümü: alias eşleşmesi × öz-değerlendirme matrisi, uyuşma oranı ve Cohen's kappa (`queries.sql`). -- [ ] Uygulamada açık kullanım ölçümü ayarı ve gizlilik politikasına ekleme — **yayın engeli** (yukarıda). -- [ ] Host nginx'te `/api/events` için `access_log off` (`docs/deploy.md`, "Kullanım ölçümü ucu"). +- [x] Uygulamada açık kullanım ölçümü ayarı (varsayılan açık; kapatma hakkı + meşru menfaat) ve gizlilik politikasına ekleme. +- [ ] Play veri güvenliği formu — **yayın engeli**. +- [ ] Host nginx'te `/api/events` için `access_log off` (`docs/deploy.md`, "Kullanım ölçümü ucu") — **main'e birleşmeden önce**. **Bitti tanımı:** Grafana'da DAU, 7/30 gün retention ve Leitner tamamlanma oranı panelleri canlı veriyle çalışıyor.