mirror of
https://github.com/nethunterzist/trendyol-analiz
synced 2026-07-01 09:27:03 +00:00
c7be57064b
- FastAPI backend with Python - React + Vite admin panel - PostgreSQL database - Trendyol marketplace analytics - GitHub Actions CI/CD workflow Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
190 lines
6.6 KiB
Markdown
190 lines
6.6 KiB
Markdown
# 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ı
|
||
|
||
```bash
|
||
# 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:**
|
||
|
||
```jsx
|
||
// ✅ 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**:
|
||
```jsx
|
||
// 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
|
||
```jsx
|
||
// 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):
|
||
```python
|
||
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 |
|