trendyol-analiz/CLAUDE.md

CLAUDE.md

Bu dosya Claude Code (claude.ai/code) için proje rehberidir.

Proje Özeti

Trendyol Product Dashboard: Trendyol e-ticaret platformu için kategori bazlı ürün analiz sistemi. 7 tab'lı dashboard, otomatik rapor oluşturma ve sosyal kanıt metrikleri.

Stack: FastAPI + React 19 + Vite + SQLite + Tailwind CSS

Geliştirme Komutları

# Uygulamayı başlat (önerilen - dependency, port, env otomatik)
python3 start.py

# Manuel başlatma (iki terminal)
cd backend && python3 main.py                    # Terminal 1 - Backend
cd admin-panel && npm run dev                    # Terminal 2 - Frontend

# Dependency kurulumu
cd backend && pip install -r requirements.txt   # Python
cd admin-panel && npm install                    # Node.js

# Diğer komutlar
cd admin-panel && npm run build                  # Frontend build
cd admin-panel && npm run lint                   # Lint
cd backend && python3 -c "from database import init_db; init_db()"  # DB init

Erişim URL'leri:

• Frontend: http://localhost:5173
• Backend API: http://127.0.0.1:8001
• API Docs: http://127.0.0.1:8001/docs

Port çakışması: start.py kullan veya lsof -ti:8001 | xargs kill -9

Mimari

3 Katmanlı Yapı

React Frontend (admin-panel/)     →  FastAPI Backend (backend/)  →  SQLite + JSON
├── CategoryManagement.jsx            ├── main.py (~4400 satır)       ├── trendyol.db
├── ReportGeneration.jsx              ├── database.py                 ├── categories/*.json
├── ReportList.jsx                    └── scraper.py                  └── reports/*.json
└── ReportDashboard.jsx (7 tab)

Dashboard Tab'ları (7 adet)

Tab ID	Tab Adı	Component	Açıklama
overview	Genel Bakış	OverviewTab	KPI'lar, özet grafikler
brand	Marka	BrandTab	Marka analizi, pazar payı
category	Kategori	CategoryTab	Kategori dağılımı
origin	Menşei	OriginTab	Ülke bazlı analiz
barcode	Barkod	BarcodeTab	Barkod veri analizi
keyword	Keyword Aracı	KeywordTab	Anahtar kelime analizi
product-finder	Ürün Bulma	ProductFinderTab	Ürün arama/filtreleme

Veri Akışı

Rapor Oluşturma (uzun süren arka plan görevi):

1. POST /api/reports/create → task_id döner, BackgroundTask başlar
2. Client GET /api/reports/progress/{task_id} ile poll eder (1s→5s backoff)
3. Backend her alt kategori için Trendyol API'yi tarar
4. JSON'u reports/ klasörüne kaydeder, DB kaydı oluşturur

Dashboard Veri Pipeline:

• Backend JSON okur, on-demand işler/toplar
• Sonuçlar cache'lenir: BoundedCache (maxsize=100, TTL=3600s)
• Frontend hazır kpis ve charts objeleri alır

Dashboard Geliştirme (KRİTİK)

Veri Kullanım Kuralları

Backend'den gelen hazır objeleri kullan, ham hesaplama YAPMA:

// ✅ DOĞRU - Hazır veriyi kullan
const kpis = dashboardData?.kpis || {};
const topProducts = dashboardData?.charts?.top_products || [];
const topBrands = dashboardData?.charts?.top_brands || [];

// ❌ YANLIŞ - all_products'tan hesaplama yapma
const total = dashboardData?.all_products.reduce((sum, p) => sum + p.price, 0);

Öncelik Sırası:

1. dashboardData.kpis - KPI kartları
2. dashboardData.charts.* - Liste ve grafikler
3. dashboardData.all_products - Sadece özel analiz için (son çare)

Alan Adı Uyumsuzluğu

Frontend hesaplamalı veri, alan adı uyumsuzluğuna yol açabilir. Detay için: docs/bug-fixes/ORIGINTAB_BUG_FIX.md

Çözüm Pattern - Mapping Layer:

// Veriyi component beklentilerine dönüştür
const transformed = sourceData.map(item => ({
  country: item.name,           // Beklenen alana map'le
  name: item.name,              // Orijinali koru
  count: item.productCount,     // Beklenen alana map'le
  productCount: item.productCount  // Orijinali koru
}));

Yeni Tab Ekleme

1. Tab config'i src/constants/tabGroups.js'e ekle
2. Tab component'ini src/components/dashboard-tabs/ altına oluştur
3. ReportDashboard.jsx'te import et ve render bloğu ekle
4. Her zaman veri dönüşümü için console.log ekle

API Entegrasyonu

Timeout Konfigürasyonu (src/config/api.js)

Tip	Süre	Kullanım
STANDARD	30s	Genel istekler
DASHBOARD	180s	Dashboard veri yükleme
ENRICHMENT	120s	Sosyal kanıt zenginleştirme
KEYWORD_ANALYSIS	300s	Keyword analizi

Polling Pattern

// Exponential backoff with jitter (1s → 5s max)
import { fetchWithTimeout, API_BASE_URL } from '../config/api';

Rate Limit

• Sosyal kanıt API: 2 istek/saniye
• Exponential backoff kullanılır (%75 istek azaltımı sağlandı)

Kod Değişiklik Kuralları

Backend (main.py)

• Request/response için Pydantic BaseModel kullan
• Hata yönetimi için HTTPException kullan
• Uzun işlemler: BackgroundTasks + progress polling endpoint
• Harici API çağrıları: Her zaman timeout parametresi ekle
• Cache: BoundedCache kullan (asla sınırsız dict kullanma)

Frontend

• fetchWithTimeout kullan (src/config/api.js'den)
• Async işlemler için loading state göster
• Eşzamanlı çağrılar için request deduplication uygula

CORS Değişiklikleri

Yeni frontend portları için main.py'deki CORS allowlist'e ekle (satır 34-45):

allow_origins=["http://localhost:5173", "http://localhost:5174", ...]

Kaynak Limitleri

Kaynak	Limit
Cache	100 item, 1 saat TTL
Frontend pagination	150 item/sayfa
Backend pagination	200 item/sayfa
Sosyal kanıt batch	5 ürün/istek
Rate limit	2 istek/saniye (sosyal kanıt)

Kritik Dependency'ler

Backend: FastAPI 0.104.1, SQLAlchemy 2.0.45, Uvicorn 0.24.0, Requests 2.31.0, Pytrends 4.9.2

Frontend: React 19.2.0, Vite 7.2.2, Recharts 3.4.1, Tailwind CSS 4.1.17, Axios 1.13.2

Database Modelleri

Model	Amaç	Anahtar Alanlar
Category	Hiyerarşik kategori ağacı	parent_id (self-ref), trendyol_category_id
Snapshot	Aylık veri görüntüleri	category_id, json_file_path
Report	Kayıtlı raporlar	category_id, json_file_path
EnrichmentError	API hata logları	endpoint, error_type, status_code

Dokümantasyon

Dosya	Amaç
docs/DASHBOARD_ARCHITECTURE.md	Önemli - Dashboard veri yapıları
docs/bug-fixes/ORIGINTAB_BUG_FIX.md	Kritik - Alan adı uyumsuzluk pattern'i
docs/API_DOCUMENTATION.md	Tam API referansı
docs/ARCHITECTURE.md	Sistem mimarisi (Türkçe)
docs/SETUP_GUIDE.md	Kurulum rehberi