trendyol-analiz/docs/DASHBOARD_ARCHITECTURE.md

Dashboard Geliştirme Rehberi

Dashboard frontend geliştirme için kritik dokümantasyon.

Tab Yapısı (7 Tab)

Tab ID	Tab Adı	Veri Kaynağı
overview	Genel Bakış	kpis, charts.top_*
brand	Marka	charts.top_brands
category	Kategori	charts.top_categories
origin	Menşei	charts.origin_countries
barcode	Barkod	charts.barcode_*
keyword	Keyword Aracı	/keyword-analysis endpoint
product-finder	Ürün Bulma	/product-finder endpoint

Veri Akışı

Backend API → dashboardData → { kpis, charts, all_products }

KRİTİK: Veri Kullanım Kuralları

Öncelik Sırası

1. İlk: dashboardData.kpis - KPI kartları için
2. İkinci: dashboardData.charts.* - Liste ve grafikler için
3. Son Çare: dashboardData.all_products - Sadece özel analiz için

DOĞRU Kullanım

// KPI'lar
const kpis = dashboardData?.kpis || {};

// Top listeler
const topBrands = dashboardData?.charts?.top_brands || [];
const topProducts = dashboardData?.charts?.top_products || [];
const topCategories = dashboardData?.charts?.top_categories || [];

YANLIŞ Kullanım

// all_products'tan hesaplama YAPMA!
const topProducts = useMemo(() => {
  const products = dashboardData?.all_products || [];
  return products
    .filter(p => p.orders > 0)
    .sort((a, b) => b.orders - a.orders)
    .slice(0, 10);
}, [dashboardData]);
// Bu veri zaten charts.top_products'ta HAZIR!

API Response Yapısı

{
  "kpis": {
    "total_products": 19043,
    "total_orders": 145680,
    "total_views": 2456789,
    "average_price": 249.99,
    "unique_brands": 234
  },
  "charts": {
    "top_products": [...],
    "top_brands": [...],
    "top_categories": [...],
    "origin_countries": [...],
    "price_distribution": [...],
    "rating_distribution": [...]
  },
  "all_products": [...]
}

Yeni Tab Ekleme Rehberi

Adım 1: Tab Config'e Ekle

src/constants/tabGroups.js:

tabs: [
  // ... mevcut tablar
  { id: 'new-tab', name: 'Yeni Tab' }
]

Adım 2: Component Oluştur

src/components/dashboard-tabs/NewTab.jsx:

const NewTab = ({ dashboardData }) => {
  console.log('📊 NewTab Data:', dashboardData);

  const kpis = dashboardData?.kpis || {};
  const chartData = dashboardData?.charts?.relevant_chart || [];

  return (
    <div className="tab-container">
      {/* KPI Kartları */}
      <div className="kpi-grid">
        <div className="kpi-card">
          <h3>KPI Başlığı</h3>
          <p>{kpis.metric_name?.toLocaleString('tr-TR') || 0}</p>
        </div>
      </div>

      {/* Chart/Liste */}
      <div className="chart-container">
        {chartData.map(item => (
          <div key={item.id || item.name}>
            {/* Item içeriği */}
          </div>
        ))}
      </div>
    </div>
  );
};

export default NewTab;

Adım 3: ReportDashboard.jsx'te Import

import NewTab from './dashboard-tabs/NewTab';

// Render bloğunda
{activeTab === 'new-tab' && <NewTab dashboardData={dashboardData} />}

Adım 4: Console Log ile Doğrula

console.log('🎯 Tab Data:', dashboardData);
console.log('📊 Chart Data:', chartData);
console.log('✅ Items:', items.length);

Field Name Mapping Pattern

Backend ve frontend arasında alan adı uyumsuzluğu olabilir. Çözüm:

// Backend: { name: 'Türkiye', productCount: 1234 }
// Component: { country: ..., count: ... } bekliyor

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
}));

Detaylı örnek: bug-fixes/ORIGINTAB_BUG_FIX.md

Yaygın Hatalar

1. Veri Yok / Boş Gösterim

Sebep: Yanlış property adı kullanımı

// YANLIŞ
const products = dashboardData?.products || [];

// DOĞRU
const products = dashboardData?.charts?.top_products || [];

2. "bilinmiyor" Gösteriyor

Sebep: all_products'tan hesaplama yapılıyor

// YANLIŞ
const categories = products.map(p => p.category);

// DOĞRU
const categories = dashboardData?.charts?.top_categories || [];

3. Alan Adı Uyumsuzluğu

Sebep: Backend ve component farklı field adları bekliyor

Çözüm: Mapping layer pattern kullan (yukarıya bak)

Debugging

Her tab'a console.log ekle:

useEffect(() => {
  console.log('📊 Tab loaded with data:', {
    kpis: dashboardData?.kpis,
    charts: Object.keys(dashboardData?.charts || {}),
    productCount: dashboardData?.all_products?.length
  });
}, [dashboardData]);

Referans Dosyalar

Dosya	Satırlar	İçerik
ReportDashboard.jsx	-	Ana dashboard component
tabGroups.js	-	Tab yapılandırması
backend/main.py	~2710-2950	get_dashboard_data fonksiyonu

Performans İpuçları

1. Gereksiz hesaplama yapma - Backend'in hazır verilerini kullan
2. useMemo kullan - Sadece all_products'tan özel analiz yaparken
3. Console log'ları kaldır - Production'da

---

Son Güncelleme: Ocak 2025