# TrafficPumper — AŞAMA 1

Laravel 13 tabanlı uygulama temeli; Filament 5, Livewire, Sanctum, Horizon,
Redis/Predis, Bootstrap 5.3 ve Vite ile hazırlanmıştır.

Tema tercihi `trafficpumper.theme` anahtarında `light`, `dark` veya `system`
olarak tutulur. `resources/js/theme-manager.js` hem Blade yerleşiminde ilk boyadan
önce hem de Filament head hook'unda kullanılır. Filament'in kendi seçicisi ortak
tercihle senkronize edilir.

Yerel Windows ortamında Horizon worker çalıştırmak için gerekli `pcntl` ve `posix`
PHP uzantıları bulunmaz. Horizon, Linux üretim ortamı için kurulu ve yapılandırılmıştır.

```powershell
composer install
npm install
php artisan test
npm test
npm run build
```

API iş rotaları ileride `routes/api/v1.php` altında ve `/api/v1/...` önekiyle
eklenecektir.

## İlk süper admin

Gerçek parola seed dosyalarına yazılmaz. İlk yetkili hesabı interaktif ve gizli
parola girişiyle oluşturun:

```powershell
php artisan trafficpumper:make-super-admin
```

Public `/register` yalnızca `customer` rolü oluşturur. `/dashboard` aktif ve
e-postası doğrulanmış oturum; `/admin` ayrıca `admin.access` yetkisi ve Filament
`canAccessPanel()` kontrolü gerektirir.

## AŞAMA 3 — Proje / Website yönetimi

Müşteri proje ekranları /projects altında çalışır. Projeler dahili integer anahtarın
yanında URL'lerde kullanılan ULID taşır ve user_id + domain birleşik benzersizlik
kuralıyla korunur. Yalnızca HTTP/HTTPS kabul eden merkezi URL normalizasyonu
www. önekini kaldırır; localhost ve IP adreslerini reddeder. Kayıt sırasında
herhangi bir ağ isteği yapılmaz.

Müşteri işlemleri sorgu seviyesinde oturum sahibine sınırlandırılır ve ayrıca
ProjectPolicy ile yetkilendirilir. Başka müşteriye ait bir ULID için tutarlı 404
döner. Silme yerine açık arşivleme/geri yükleme uçları kullanılır. Backoffice
liste/detay görünümü /admin/projects rotasındadır; sahip değiştirme ve hard delete
sunulmaz.

Doğrulama komutları: php artisan migrate, php artisan test, npm test ve npm run build.
## AŞAMA 4 — Keyword ve SERP veri altyapısı

Project → Keyword ilişkisi ULID public kimlikleri ve User → Project → Keyword
sahiplik zinciriyle kuruldu. Hedef kimliği normalize edilmiş ifade, arama motoru,
ülke, dil ve cihaz birleşimidir; aynı Project içinde DB seviyesinde benzersizdir.
Whitespace tekilleştirilir, locale bağımsız küçük harf dönüşümü uygulanır ve Türkçe
karakterler korunur. Arşivlenen hedef kimliği tutulur ve yeni kayıt yerine restore
edilir. Customer nested rotaları sorgu seviyesinde sahipliğe, Filament görünümü ise
keywords.view / keywords.manage izinlerine bağlıdır.

serp_checks hedef snapshotlarını, serp_results organik sonuç satırlarını saklayacak
veri altyapısıdır. Bu aşamada dış arama motoru sorgusu, scraping, provider, queue,
scheduler veya customer SERP endpointi eklenmemiştir.
## AŞAMA 5 — Provider-neutral SERP çalıştırma

SERP sağlayıcıları SerpProvider sözleşmesi üzerinden registry tarafından çözülür;
domain kodu provider SDK veya response biçimi bilmez. SerpQuery, SerpResponse ve
SerpResultData immutable sınırı oluşturur. Fake provider yalnız testing veya açıkça
izin verilmiş local ortamda çalışır; production ortamında sonuç üretemez. Bu aşamada
production provider ve dış SERP HTTP isteği yoktur.

Kontroller serp kuyruğunda RunSerpCheck job'ıyla çalışır: 3 deneme, 60 saniye
timeout ve 10/60/300 saniye backoff. Transient timeout/rate-limit hataları yeniden
denenir; kalıcı hatalar güvenli kodla failed olur. Keyword başına atomik cache lock,
DB active-slot unique constraint ve job lock birlikte duplicate/eşzamanlı çalışmayı
engeller. Provider çağrısı transaction dışında, sonuç tamamlama transaction içindedir.

Manuel kontroller kullanıcı rate-limit'i, 15 dakika keyword cooldown'u, günlük 25
kontrol kotası ve pending/running engeline tabidir. Otomatik takip daily/weekly olup
UTC next_check_at kullanır. Scheduler her dakika due kayıtları chunk ile kuyruğa
alır, overlap ve tek-sunucu kilidi kullanır. Domain eşleşmesi exact domain veya
gerçek subdomain kabul eder; www eşdeğerdir, metinsel sahte suffix eşleşmez.

Production provider eklemek için SerpProvider adaptörü yazılır, service container
registry'sine kaydedilir ve SERP_PROVIDER değeri adaptör anahtarına ayarlanır.

## AŞAMA 6 — DataForSEO Google Organic adaptörü

Production adaptörü `dataforseo` anahtarıyla kayıtlıdır. Manuel kontroller Google Organic Live Advanced, zamanlanmış daily/weekly kontroller Standard `task_post` ve gecikmeli `task_get/advanced` poll akışını kullanır. Payload ülke, dil ve cihaz allowlist değerlerinden sunucu tarafında üretilir; `depth` daima 10'dur. Organik sonuç sırası DataForSEO `rank_group` alanından normalize edilir; sağlayıcıya özgü JSON domain modeline veya veritabanına yazılmaz.

HTTP istemcisi yalnız `https://api.dataforseo.com` taban adresini, Basic Auth kimlik bilgilerini, TLS doğrulamasını, bağlantı/istek timeout'larını ve redirectsiz çağrıları kullanır. HTTP status ile DataForSEO `status_code` zarfı ayrı doğrulanır. Kimlik bilgileri yalnız environment/config üzerinden alınır ve loglanmaz.

Kurulum güvenli varsayılanla gelir: `SERP_CHECKS_ENABLED=false`. Production kimlik bilgileri girilse bile operasyonel onay verilmeden bu değer açılmamalıdır. Gerçek API çağrısı testlerde yapılmaz; `Http::preventStrayRequests()` ve `Http::fake()` kullanılır.


## ASAMA 7 — Kontrollu production aktivasyonu

SERP operasyonu disabled, validation_only, canary, enabled ve DB kill-switch ile emergency_stopped durumlarini ayirir. Normal ucretli akis icin hem SERP_CHECKS_ENABLED=true hem SERP_OPERATION_MODE=enabled gerekir; bilinmeyen durum fail-closed davranir.

Maliyetler mikro-USD ledgerda UTC gunluk/aylik atomik rezervasyon ve gercek maliyetle tekil reconciliation kullanir. Kill switch ve circuit breaker yeni Live/submit islemlerini engeller, mevcut Standard task polling sonucunu kurtarir. Remote health ve canary execute calistirilmamistir.

Filament /admin/serp-operations support/admin icin salt okunur, emergency stop/clear yalniz super_admin icindir. Ayrintilar: docs/production-serp-runbook.md.

## AŞAMA 8 — Güvenli production hazırlığı

Dış HTTP yapmayan production preflight ve 24 saatlik scrubbed operasyon snapshot komutları ile atomik 5/25/100 ramp-up kapısı eklendi. Başlangıç ve mevcut durum güvenli biçimde `disabled` kalır; remote health, tek canary ve limited production birbirinden ayrı açık onay kapılarıdır. Deployment ve recovery ayrıntıları `docs/production-serp-runbook.md` içindedir.