108 lines
6.7 KiB
Markdown
108 lines
6.7 KiB
Markdown
# 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. |