Skip to content
BranchesTags

Repository files navigation

FiyatPilot

İkinci el elektronik ürünler için kondisyon duyarlı fiyat zekâsı.

FiyatPilot, ikinci el elektronik ürünler için gerçekçi satış fiyatı önerileri üreten modern bir web platformudur.
Kullanıcı model/teknik özellikleri ile kozmetik durumu, pil sağlığını ve garanti/fatura/kutu bilgilerini girer; sistem çok kaynaklı ilanları normalize eder, alakasız ve uç fiyatları filtreler, kondisyon etkisini hesaba katar ve sonuç olarak açıklanabilir fiyat aralığı + net satış önerisi üretir.

Hero / Durum Rozetleri

Status Stage Monorepo Frontend Backend Database Queue Normalization Pricing Engine Dashboard AI Assisted Open Source

Kısa Tanıtım

İkinci el fiyatlama, pratikte iki nedenle zordur:

  1. Veri düzensizdir: Aynı ürün farklı başlık formatları, eksik alanlar ve değişen içeriklerle listelenir.
  2. Kondisyon fiyatı belirler: Kozmetik durum, pil sağlığı, garanti/fatura/kutu gibi sinyaller “aynı model” görünse bile ciddi fiyat farkı yaratır.

FiyatPilot, manuel karşılaştırmayı yorucu olmaktan çıkarır: çok kaynaklı ilan delillerini normalize eder, benzerlik + alaka skoru üretir, aykırı fiyatları filtreler ve kondisyon düzeltmesi ile açıklanabilir bir fiyat önerisi sunar.

Problem Tanımı

  • İkinci el piyasasında fiyatlar çoğu zaman **düzensiz, ölçülemeyen ve “bağlama bağlı”**dır.
  • Aynı ürün, farklı ilan başlıkları ve eksik bilgilerle listelenir:
    • “Aynı model” sanılır ama RAM/SSD, yazılım sürümü veya aksesuarlar farklıdır.
    • Garanti/fatura/kutu bilgisi çoğu zaman metnin içinde gizlidir.
  • Kondisyon farkı, fiyatı doğrudan etkiler:
    • kozmetik durum
    • pil sağlığı
    • garanti/fatura/kutu
    • satıcı tarafından belirtilen sorunlar
  • Kullanıcılar tahmin değil, neden-sonuç ilişkisi kuran bir fiyat ister.
  • Manuel karşılaştırma hem zaman alır hem de “tutarsız” sonuç üretir.

Çözüm Yaklaşımı

FiyatPilot, fiyatı tek bir sayı olarak üretmez. Karşılaştırma mantığıyla birlikte, fiyatı bir “delil seti” üzerinden çıkarır:

  • Çok kaynaklı ilan tarama
  • İlan normalizasyonu (tek bir canonical şemaya dönüştürme)
  • Benzer ürün eşleştirme (deterministic relevance + match tier’lar)
  • Alaka skoru
  • Uç fiyat filtreleme (median + IQR + trimmed mantık)
  • Kondisyon düzeltmesi (kozmetik/pil/garanti/fatura/kutu + sorun notları)
  • Güven skoru
  • Sonuç: fiyat aralığı + net öneri + açıklama metni

Not: Bu MVP’de hedef “kesin ekspertiz” değil; gerçekçi ve açıklanabilir ikinci el fiyat zekâsıdır.

Örnek Çıktı (Demo)

Ürün: Apple MacBook Pro 14 M1 (16GB/512GB/SSD)

Hızlı satılır fiyat:   74.500 TL
Normal piyasa fiyatı:  79.900 TL
Premium fiyat:         86.200 TL
Net önerilen satış:    75.900 TL
Güven skoru:           0.78

Kısa gerekçe:
- Match tier: exact/near ilanlar ağırlıkla kullanıldı.
- Aykırı ilanlar outlier filtresiyle elendi (IQR tabanlı).
- Kozmetik ve pil sinyalleri kondisyon çarpanına yansıtıldı.

Nasıl Çalışır? (Ürün Akışı)

  1. Kullanıcı ürün bilgilerini girer (model + teknik özellikler + kondisyon).
  2. Sistem API üzerinden sorgu oluşturur.
  3. Kaynaklardan ilan adayları toplanır.
  4. İlanlar canonical şemaya normalize edilir.
  5. Eşleşme motoru benzerliği hesaplar ve include/exclude kararlarını üretir.
  6. Aykırı/uyumsuz veriler filtrelenir.
  7. Kondisyon etkisi fiyat motoruna uygulanır.
  8. Fiyat önerisi + güven skoru + açıklama üretilir ve dashboard’ta gösterilir.

Özellikler

  • Dashboard
    • Analiz oluşturma, durum takibi ve sonuç ekranı
    • Eşleşen/elenen ilanlar ile match gerekçeleri
  • Arama / Orkestrasyon (modüler)
    • Connector’lar bağımsız çalışır; normalization → relevance → pricing pipeline
  • Kaynak connector yapısı
    • Kaynak bazlı ayrıştırma ve normalize etme sınırları net
    • Devre dışı kalabilirlik ve circuit breaker için hazır
  • İlan normalizasyon katmanı
    • Tek bir canonical listing şeması
  • Relevance / Eşleşme motoru
    • Deterministic weighted matching + fuzzy başlık desteği
    • exact_match, near_match, weak_match, rejected
    • Açıklanabilir per-ilan gerekçe
  • Fiyat motoru
    • Outlier filtering (median/IQR/trim)
    • Recency ağırlığı + kaynak güvenilirliği sinyalleri
    • Condition adjustment ile kondisyon düzeltmesi
  • Explainability katmanı
    • Fiyatın “neden öyle çıktığı” okunabilir şekilde raporlanır
  • Admin / operasyon paneli
    • Connector health, job queue durumu, son analiz koşuları, hata logları
  • Geçmiş analizler
    • Tarihçe, detaya inme, deterministik sonuçların izlenmesi
  • Kaynak ilan inceleme görünümü
    • Kaynak + fiyat + match tier + “neden dahil/harici” görünümü

Mimari

Metinsel Mimari Açıklaması

FiyatPilot, sorumluluk ayrımını net tutar:

  • API (apps/api)
    • Request validasyonu
    • Analiz oluşturma (rate limit + duplicate caching)
    • Sonuçları ve admin endpoint’lerini sunma
  • Queue + Worker (apps/worker)
    • Redis kuyruğundan job çekme
    • Analiz pipeline’ını çalıştırma
    • Retry + DLQ + error history yazma
  • Connector’lar (packages/source_connectors)
    • Sadece kaynak payload’unu RawListing formatına çevirir
    • Normalizasyon / fiyat mantığı connector içinde değil
  • Normalization (packages/normalization)
    • RawListing → NormalizedListing dönüşümü
  • Relevance Engine (packages/relevance_engine)
    • Deterministic eşleşme ve explainable match açıklamaları
  • Pricing Engine (packages/pricing_engine)
    • Outlier filtering + weighted scoring + condition adjustment
  • Shared Domain (packages/shared)
    • API/Worker/Web arasında ortak Pydantic modeller

Veri Akışı (Yüksek Seviye)

Kullanıcı girdisi → API → Redis job → Worker → connector’lar → normalize → relevance → pricing → Postgres → dashboard.

Mimari Diyagram (Mermaid)

flowchart LR
    U[Kullanici] --> W[Web Dashboard]
    W --> A[API]
    A --> Q[Queue]
    Q --> K[Worker]
    K --> C[Connector Katmani]
    C --> N[Normalization]
    N --> R[Relevance Engine]
    R --> P[Pricing Engine]
    P --> S[Sonuc]
    S --> W
Loading

Diyagram basit tutulmustur. Teknik route ve islem detaylari:

  • POST /api/v1/analyses: analiz istegi olusturur
  • Worker, queue uzerinden is alir ve pipeline adimlarini calistirir
  • Sonuc verisi Postgres uzerinden API tarafindan dashboard a doner

Teknoloji Yığını

Katman Teknoloji
Frontend Next.js, TypeScript, Tailwind, shadcn/ui
Backend FastAPI (versioned REST + admin endpoints)
Worker Python async pipeline
Database PostgreSQL
Queue Redis (job list/queue)
Scraping / Ingestion Connector mimarisi (MVP’de fixture temelli stublar)
UI Screenshot-ready, minimal ve okunabilir kartlar
Infra Docker + Docker Compose
Observability Structured JSON logs (API + worker), admin hata logları

Önerilen ek (ilerleyen aşamalar):

  • Playwright (canlı scraping için)
  • Centralized logging (ELK/Datadog)
  • Monitoring/alerting (Prometheus/Grafana)

Monorepo Yapısı

fiyatpilot/
  apps/
    web/
    api/
    worker/
  packages/
    pricing_engine/
    normalization/
    relevance_engine/
    source_connectors/
    search_orchestrator/
    shared/
  docs/
  infra/

Kısa özet:

  • apps/web: Ürün UI ve kullanıcı akışı
  • apps/api: Analiz oluşturma + sonuç + admin operasyon endpoint’leri
  • apps/worker: Pipeline + retry + DLQ + circuit breaker state
  • packages/*: Deterministic engine’ler ve domain modeller
  • infra/: (planlı) production altyapı parçaları (migrations, kural setleri vb.)

Modül Açıklamaları

  • packages/shared
    • Pydantic DTO’lar: analiz request/result, normalizasyon çıktıları, relevance açıklamaları
    • Deterministic sistem boyunca tip uyumu sağlar
  • packages/normalization
    • RawListing → NormalizedListing dönüşümü
    • Metin/alan parse + unit normalization
  • packages/relevance_engine
    • Brand/model/spec karşılaştırmaları
    • Weighted scoring + fuzzy title desteği
    • exact/near/weak/rejected tier’ları ve explainability üretimi
  • packages/pricing_engine
    • Outlier filtering (median + IQR + trim)
    • Recency weight + source reliability ile ağırlıklandırma
    • Condition adjustment çarpanları
    • Sonuç: hızlı satılır / piyasa / premium / net + güven skoru + gerekçe
  • packages/source_connectors
    • Kaynak sınırı: yalnızca connector → RawListing
    • Connector failures izole edilir (ops paneli ile görünür olur)
  • packages/search_orchestrator
    • (planlı/örnek) pipeline orkestrasyon arayüzleri ve akışın tek noktadan yönetimi

Kurulum (Detaylı, Gerçekçi)

1) Repoyu klonlayın

git clone https://github.com/<owner>/fiyatpilot.git
cd fiyatpilot

2) Ortam dosyası hazırlayın

Copy-Item .env.example .env

Bağımlılıklar (yerel UI / geliştirme ve test akışı için):

pnpm install

3) Docker Compose ile servisleri ayağa kaldırın

docker compose up --build

Sadece API + Worker (UI olmadan hızlı doğrulama):

docker compose up --build -d api worker

Durdurma ve yerel veriyi temizleme:

docker compose down -v

Beklenen servisler:

  • postgres (PostgreSQL)
  • redis (queue + caching + circuit breaker state)
  • api (FastAPI)
  • worker (Redis job tüketicisi)
  • web (Next.js)

4) Uygulamayı kullanın

  • Dashboard: http://localhost:3000/dashboard
  • Admin: http://localhost:3000/dashboard/admin (Basic Auth)

Demo:

  • Boş veritabanında API, demo analizlerini otomatik seed eder (configurable).

5) Geliştirme ortamı mantığı

  • MVP’de “deterministic engines” Python paketleri içinde yer alır.
  • Web katmanı UI’ı sunar; API sonuçları üretir/queue’lar.
  • Worker pipeline’ı çalıştırır ve Postgres’e yazar.

Bu ayrım, canlı scraping veya ek connector’larda bile mimarinin çabuk büyümesini sağlar.

Önerilen yerel geliştirme akışı:

  • Hızlı test: Docker Compose
  • UI iterasyonu: Web servisini ayağa kaldırıp dashboard üzerinden geri bildirim al
  • Motor geliştirme: Python paketlerini güncelle, sonra worker/API container’larını yeniden başlat

Ortam Değişkenleri (Örnek .env.example)

DATABASE_URL=postgresql+asyncpg://user:pass@postgres:5432/fiyatpilot
REDIS_URL=redis://redis:6379/0
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
APP_ENV=development
LOG_LEVEL=INFO

# Scraping / ingestion mod
SCRAPER_MODE=fixture

# Feature toggles
FEATURE_FLAGS="demo_seeding=true,admin_auth=true"

Not: Projeyi ayağa kaldırmak için gerekenler .env.example dosyasında kapsamlı şekilde bulunur.

Fiyat Motoru Mantığı (Kısa ama Teknik)

Fiyat motoru, fiyatı “delil seti” üzerinden hesaplar:

  1. Outlier filtering
    • Aday fiyatlar bir set olarak alınır.
    • Median baz alınır.
    • IQR yaklaşımıyla uçlar kesilir:
      • Q1 (1. çeyrek), Q3 (3. çeyrek)
      • IQR = Q3 - Q1
      • outlier aralığı: [Q1 - 1.5*IQR, Q3 + 1.5*IQR]
    • Trim mantığı: filtrelenen aralığın dışındaki fiyatlar kırpılır/elenir.
  2. Weighted scoring
    • Match tier: exact/near daha yüksek ağırlık alır, weak/rejected azalır.
    • Recency weight: ilan yaşlandıkça ağırlık düşer.
    • Source reliability: kaynak kalitesi/sağlığına göre ek çarpan uygulanır.
  3. Condition adjustment
    • Kozmetik skor (0–10)
    • Pil sağlığı (yüzde)
    • Garanti / fatura / kutu
    • Sorun notları (downside etkisi)
    • Bu sinyaller, delil seti üstünde bir condition multiplier olarak uygulanır.

Sonuçlar:

  • Hızlı satılır fiyat (daha agresif satış profili)
  • Normal piyasa fiyatı
  • Premium fiyat (daha yüksek kabul eşiği)
  • Net önerilen satış fiyatı
  • Güven skoru + açıklama metni

Sonuç Ekranı / Çıktı Mantığı

Kullanıcıya aşağıdaki çıktılar gösterilir:

  • Hızlı satılır fiyat
  • Normal piyasa fiyatı
  • Premium ilan fiyatı
  • Net önerilen satış fiyatı
  • Güven skoru (0-1)
  • Açıklama (fiyatlama gerekçesi)
  • Dahil edilen / hariç tutulan ilanlar
    • Her ilan için match tier
    • “Neden dahil/elenmiş” gerekçesi (explainability)

Bu yapı, kullanıcı için “kara kutu fiyat” hissini ortadan kaldırır.

MVP Kapsamı

İlk sürüm odakları (MVP):

  • laptop
  • telefon
  • tablet
  • oyun konsolu

Amaç:

  • Kesin ekspertiz yapmak değil,
  • Kullanıcının girdilerine dayanarak gerçekçi fiyat zekâsı üretmek.

Bu sayede ürün, kullanıcı geri bildirimiyle daha da güçlenebilir.

Yol Haritası (Faz Bazlı)

Faz 1: Temel iskelet

  • web dashboard + analiz akışı
  • temel connector stubları
  • deterministik relevance/pricing iskeleti

Faz 2: Connector genişlemesi

  • daha fazla kaynak
  • kaynak bazlı daha sağlam parse stratejileri
  • ingestion quality sinyalleri

Faz 3: Daha güçlü eşleşme

  • daha iyi fuzzy başlık eşleştirme
  • spec karşılaştırmalarında genişletilmiş ağırlıklar

Faz 4: Kondisyon zekâsı

  • kondisyon sinyallerini daha ince modelleme
  • pil sağlığı + garanti/fatura etkilerini rafine etme

Faz 5: Açıklanabilirlik ve admin

  • pricing evidence view
  • detaylı ops paneli
  • daha zengin hata görselleştirme

Faz 6: Ürünleşmiş MVP

  • doğrulanmış live connector’lar
  • daha gelişmiş caching ve rate limit stratejileri
  • daha güçlü kalite metrikleri ve izleme

Kullanım Senaryoları

  1. Bireysel satıcı
    • “Benzer ürünlerden yola çıkarak net fiyat önerisi istiyorum.”
  2. Küçük ikinci el mağazası
    • Aynı kategoride düzenli fiyat kontrolü + geçmiş analizler
  3. Telefon/laptop al-sat yapan kullanıcı
    • Kondisyona göre fiyat stratejisini hızlı güncelleme
  4. Fiyat kontrolü yapan alıcı
    • İlanı değerlendirirken “beklenen bant” bilgisini kullanma
  5. Toplu analiz ihtiyacı olan operasyon ekibi
    • Çoklu analiz akışı + admin ops görünümü

FiyatPilot Ne Değildir?

  • Rastgele fiyat tahmin aracı değildir.
  • Basit bir scraper değildir.
  • Tek bir siteye bağlı ilan sayfası değildir.
  • Açıklamasız sayı üreten bir kara kutu değildir.

FiyatPilot’un tasarımı: delil seti + deterministik mantık + açıklanabilir çıktı.

Durum

Proje, üretim odaklı MVP’ye giden aktif geliştirme sürecindedir.
Mimarisi modülerdir; connector’lar, normalizasyon, relevance ve pricing katmanları bağımsız olarak genişletilebilir.

Katkı

Katkılarınızı memnuniyetle bekliyoruz:

  • Hata/bug bildirimi
  • Mimari veya modül önerileri
  • Yeni connector parse önerileri

Önerilen akış:

  1. Açık bir issue aç
  2. Değişiklik için kısa bir PR tanımı yap
  3. Test + doğrulama adımlarını ekle

Lisans

Bu proje için lisans bilgisi: TBD.

Kapanış

İkinci el piyasasında fiyatlar çoğu zaman “görünür” ama “ölçülemez”dir.
FiyatPilot; kondisyonu hesaba katan, delil setiyle çalışan ve açıklanabilir sonuç üreten bir fiyat zekâsı inşa ediyor.

About

İkinci el laptop, telefon ve benzeri ürünler için akıllı fiyatlandırma motoru.

okwn.cc

Topics

aianalizfiyatfiyat-analizifiyat-motoruikinci-elmvp

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages