Ölücüler Diyarı - Kurulum ve Çalıştırma Rehberi (Ultra Detaylı)

Bu rehber, Oluculer.com (Deterministik Fırsat Avcısı) projesini sıfırdan canlıya almak, veritabanını kurmak, scraping (veri kazıma) botlarını yapılandırmak ve n8n ile otomasyona bağlamak için gereken tüm adımları içerir.

Proje 3 temel bacaktan oluşur:

1. Frontend / Web: Next.js (App Router), Tailwind CSS
2. Backend / Veritabanı: Supabase (PostgreSQL)
3. Data Pipeline / Otomasyon: Node.js (Playwright Stealth Scraper) & n8n (Cron/Scheduler)

---

1. Supabase (Veritabanı) Kurulumu

Projenin tüm verileri ve deterministik kuralları Supabase (PostgreSQL) üzerinde tutulur.

Adım 1: Proje Oluşturma

1. Supabase'e gidin ve yeni bir proje oluşturun.
2. Proje ayarlarından (Project Settings -> API) URL, anon (public) key ve service_role (secret) key bilgilerini kopyalayın.

Adım 2: Tabloları ve Şemayı Kurma

1. Supabase panosunda sol menüden SQL Editor'e girin.
2. Proje dizininde yer alan supabase/database_schema.sql dosyasının içindeki tüm kodları kopyalayıp SQL Editor'e yapıştırın ve çalıştırın.
3. Bu işlem; categories, products, product_offers, price_history, coupons tablolarını, gerekli foreign-key kurallarını, B-Tree Indekslerini ve Row Level Security (RLS) ayarlarını otomatik olarak kuracaktır.

---

2. Next.js (Frontend) Kurulumu

Adım 1: Çevre Değişkenleri (.env.local)

Proje kök dizininde (package.json ile aynı yerde) bir .env.local dosyası oluşturun ve aşağıdaki değişkenleri doldurun:

# Supabase Ayarları (Zorunlu)
NEXT_PUBLIC_SUPABASE_URL=https://[PROJE_ID].supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR...

# Sunucu Tarafı Güvenli İşlemler İçin (Zorunlu)
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR...

# SEO ve Site Haritası İçin (Opsiyonel - Canlıya alırken zorunlu)
NEXT_PUBLIC_BASE_URL=https://oluculer.com

# Kazıma İşlemi İçin Proxy (Eğer kullanılacaksa)
RESIDENTIAL_PROXY_URL=http://username:password@proxy.example.com:8080

Adım 2: Bağımlılıkların Yüklenmesi

Terminali açın ve proje dizininde şu komutları çalıştırın:

npm install

Adım 3: Çalıştırma ve Build

• Geliştirme Modu (Localhost): npm run dev komutunu çalıştırın. http://localhost:3000 adresinden siteye erişebilirsiniz.
• Canlı (Production) Build: Vercel veya kendi sunucunuza çıkmadan önce projeyi derlemek için npm run build komutunu çalıştırın. (Proje sıfır hata toleransıyla yapılandırıldığı için npm run lint ve build komutları başarıyla "0 hata" ile tamamlanmalıdır).
• Production Server Başlatma: Build sonrası npm run start ile projeyi canlı modda test edebilirsiniz.

---

3. Data Scraping (Kazıma) Sistemi

Fiyat verileri, anti-bot sistemlerini atlatmak için Playwright ve puppeteer-extra-plugin-stealth kullanılarak kazınır.

Kazıma Betiğinin Konumu

Kazıma kodları src/scripts/scraper.ts dosyasında bulunur. Bu dosya:

1. Belirtilen (veya dinamik alınan) ürün hedeflerine gider.
2. Playwright kullanarak sayfayı tam bir insan gibi donanım ivmelendirmeli olarak çizer.
3. Fiyat bilgisini HTML DOM üzerinden Regex ile ayrıştırıp temizler.
4. Çektiği fiyatı src/utils/algorithms.ts içerisindeki deterministik kural motorundan (Sıcak Fırsat / SMA 30 kuralı) geçirir.
5. Fırsat olarak etiketlenip etiketlenmeyeceğine karar verir.
6. Veriyi doğrudan SUPABASE_SERVICE_ROLE_KEY yetkisi ile veritabanına upsert eder ve fiyat geçmişi (price_history) logu oluşturur.

Kazıma Betiğini Manuel Çalıştırma

Kazıyıcıyı terminalden test etmek için ts-node kullanabilirsiniz (öncesinde global kurulu olmalıdır npm i -g ts-node):

ts-node src/scripts/scraper.ts

Not: Büyük ölçekli taramalar yapacaksanız, IP banlarından kaçınmak için .env.local içine RESIDENTIAL_PROXY_URL değişkenini tanımladığınızdan emin olun.

---

4. n8n ile Otomasyon Mimarisi (Flows)

Kazıma betiğinin elle çalıştırılması yerine, sistemi tam otonom hale getirmek için n8n (Node-base otomasyon aracı) kullanmalısınız. n8n ister yerel Docker konteynerinizde isterseniz bulut (n8n.cloud) üzerinde çalışabilir.

Adım 1: n8n Workflow Tasarımı (Cron Job)

1. n8n ara yüzünü açın ve yeni bir Workflow oluşturun.
2. İlk Node olarak "Schedule Trigger" (Cron) ekleyin. (Örneğin: Her 60 dakikada bir çalış - 0 * * * * şeklinde ayarlayın).

Adım 2: Hedeflerin Belirlenmesi

3. Supabase'den Kazınacak URL'leri çekmek için "PostgreSQL" veya "HTTP Request" node'u ekleyin. (Supabase REST API'sine GET /rest/v1/product_offers?select=original_url,product_id şeklinde istek atabilirsiniz).

Adım 3: Kazıma İşlemini (Scraper) Tetikleme

Burada birden fazla mimari seçilebilir:

• A Yöntemi (execute command): Eğer n8n aynı sunucuda/Docker'da koşuyorsa "Execute Command" node'u ekleyip içine npx ts-node /app/oluculer.com/src/scripts/scraper.ts yazarak scripti direkt tetikleyebilirsiniz.
• B Yöntemi (API Dönüşümü - Tavsiye Edilen): Next.js tarafında src/app/api/scrape/route.ts şeklinde bir API Endpoint açabilirsiniz. Bot koruması olmaması için bu endpoint sadece BEARER TOKEN veya özel SUPABASE_SERVICE_ROLE_KEY ile çalışmalıdır. n8n üzerinden "HTTP Request" node'u ile bu API'ye POST isteği göndererek scraper'ı bulut üzerinden tetikleyebilirsiniz.

Adım 4: Telegram / Discord Bildirimleri (Opsiyonel Eklenti)

4. Kazıma sonucu Supabase'de is_hot_deal = true olan yeni bir kayıt eklendiğinde (Supabase Realtime Webhook kullanılarak), n8n üzerindeki başka bir "Webhook" node'una veri gönderilir.
5. Bu veriyi n8n'de "Telegram" veya "Discord" node'una bağlayıp "🔥 YENİ DİP FİYAT GELDİ 🔥" şeklinde kullanıcılarınıza/kendinize anında alarm verebilirsiniz.

---

5. Gelir ve Reklam Katmanı Yönetimi (Google AdSense)

Projenizde Google AdSense tam uyumlu olarak (lazy-load) çalışmaktadır. Kodu aktifleştirmek için:

1. src/app/layout.tsx dosyasını açın.
2. <meta name="google-adsense-account" content="ca-pub-0000000000000000" /> kısmındaki ca-pub-00... kimliğini kendi AdSense kimliğinizle değiştirin.
3. Aynı dosyadaki adsbygoogle.js URL'si içindeki client id'yi yine kendinize göre güncelleyin.
4. Bileşenlerde yer alan <AdSlot type="..." /> modülü sayfa düzenini asla kaydırmayacak (zero-CLS) şekilde CSS yapılarına sahiptir.

Artık sistem kendi kendine veri çeken, işleyen, sunan ve bunlardan gelir elde eden tamamen otonom bir yapıdadır. Tebrikler! 🎉