STOKÇU • TECHNICAL WHITEPAPER

Stok Entegrasyon ve Dinamik Fiyatlandırma Sistemi

Bu doküman, e-ticaret operasyonlarında dağınık ve standart dışı veri kaynaklarını birleştirmek, vektörel uzayda ürün eşleştirmesi yapmak ve doğal dil işleme (NLP) tabanlı dinamik fiyatlandırma kuralları uygulamak için geliştirilmiş Stokçu (PFSM Engine) motorunun teknik detaylarını içerir.

01 Giriş ve Problem Tanımı

E-ticaret ekosisteminde, farklı tedarikçilerden (XML, Excel) gelen verilerin pazar yerleri (Trendyol, Hepsiburada) ile senkronize edilmesi karmaşık bir problemdir. Temel zorluklar şunlardır:

Veri Standardizasyonu Sorunu

Tedarikçiler aynı ürünü farklı isimlerle tanımlar (Örn: "Bosch GSB 180" vs "Gsr 180-Li Matkap"). Klasik "Exact Match" algoritmaları bu durumda başarısız olur.

Yanlış Eşleşme Riski

Fuzzy (bulanık) arama algoritmaları, "Bosch Matkap Ucu" ile "Bosch Matkap" ürününü yanlış eşleştirerek büyük finansal zararlara yol açabilir (False Positive).

Çözüm: Stokçu, deterministik ve olasılıksal yöntemleri birleştiren hibrit bir yapı kullanır. Ürünleri sadece isme göre değil, model kodu, teknik özellik ve vektörel benzerliklerine göre analiz eder.

02 Kullanıcı İşlemleri ve Teknik Karşılıkları

Aşağıdaki tablo, kullanıcının arayüzde (Frontend) gerçekleştirdiği işlemlerin arka planda (Backend) hangi Python fonksiyonları ve teknik süreçlerle yönetildiğini göstermektedir.

1
Kullanıcı Arayüzü (Adım 1) Sistem Açılışı ve Ayarlar

Kullanıcı sayfayı açtığında sistem otomatik olarak güncel kurları ve şablonları kontrol eder.

Arka Plan (Backend) XML Parsing & State Management

fetch_exchange_rates() fonksiyonu TCMB API'sine bağlanır, XML'i parse eder ve USD/EUR kurlarını hafızaya (RAM) alır.

2
Kullanıcı Arayüzü (Adım 2 & 3) Dosya Yükleme (Excel/XML/CSV)

İç stok ve tedarikçi dosyaları yüklenir. Sütun eşleşmeleri (Mapping) yapılır.

Arka Plan (Backend) Pandas ETL & Normalization

read_and_normalize_file() fonksiyonu dosyaları okur. Pandas ve OpenPyXL kullanarak; sütun isimlerini (Örn: "Stok_Adedi" -> "Stock") JSON şablonuna göre standardize eder ve temizler.

3
Kullanıcı Arayüzü (Adım 4) NLP Kural Girişi

Kullanıcı: "TÜM BOSCH ÜRÜNLERİNE %10 ZAM YAP" gibi komutlar yazar.

Arka Plan (Backend) Regex Parsing Engine

parse_natural_language_rules() fonksiyonu metni analiz eder. Target: BOSCH, Action: Multiplier, Value: 1.10 objesini oluşturur.

4
Kullanıcı Arayüzü (Sonuç) Analizi Başlat & Raporlama

Kullanıcı işlemi başlatır ve ilerleme çubuğunu takip eder.

Arka Plan (Backend) Vector Matching & Threading

UniversalSmartMatcher.run_engine() TF-IDF algoritmasını çalıştırır. İşlem uzun sürdüğü için threading ile asenkron yönetilir ve /api/jobs/status endpoint'i üzerinden durum bildirilir.

03 Sistem Mimarisi

Uygulama, ölçeklenebilirlik ve izolasyon prensipleri gözetilerek Mikroservis benzeri bir yapıda, Docker konteynerleri üzerinde çalışmaktadır.

🐳

Docker Runtime

Uygulama, python:3.10-slim imajı üzerinde çalışır. Bu imaj, gereksiz sistem dosyalarından arındırılmış, sadece uygulamanın ihtiyaç duyduğu bağımlılıkları (Pandas, Scikit-learn) barındıran izole bir ortamdır.

⚡

Gunicorn WSGI Server

Python'un tek iş parçacıklı yapısını aşmak için --workers 3 konfigürasyonu ile çalışır. Bu sayede sistem aynı anda birden fazla dosya işleme talebini (Concurrency) CPU çekirdeklerine dağıtarak karşılar.

🛡️

Traefik Reverse Proxy

Sistem, dış dünyaya doğrudan değil, Traefik üzerinden açılır. Traefik, gelen trafiği karşılar, SSL sertifikalarını (Let's Encrypt) otomatik yeniler ve yük dengeleme (Load Balancing) yapar.

04 Algoritmik Metodoloji

Sistemin çekirdeğini UniversalSmartMatcher sınıfı oluşturur. Bu sınıf, ürün eşleştirmesinde 3 katmanlı bir filtreleme uygular.

Katman 1: Normalizasyon ve Tokenizasyon

Ham metin verisi temizlenir. Türkçe karakterler (ı->i, ş->s) dönüştürülür, ölçü birimleri (mm, watt, volt) standartlaştırılır ve gürültü kelimeler (kargo, bedava) atılır.

Katman 2: TF-IDF ve Kosinüs Benzerliği

Ürün isimleri, Term Frequency-Inverse Document Frequency (TF-IDF) yöntemiyle vektör uzayına taşınır. İki ürün arasındaki anlamsal mesafe hesaplanır.

  • Vektör Uzayı: Her kelime bir boyut olarak kabul edilir.
  • Benzerlik Skoru: 0.0 ile 1.0 arasında bir değer üretilir. (1.0 = Tam Eşleşme).

Katman 3: Heuristic Kurallar ve Güvenlik Duvarı

Yüksek benzerlik skoru tek başına yeterli değildir. Aşağıdaki mantıksal kurallar devreye girer:

Kural Adı Açıklama Örnek Durum
Brand Conflict Farklı markaların eşleşmesini engeller. Bosch ≠ Makita (Skor 0.95 olsa bile RED)
Set Conflict Paket miktarlarını kontrol eder. 10'lu Set ≠ Tekli (RED)
Golden Code Ürün isminde geçen benzersiz model kodunu yakalar. "GSR-120-LI" kodu her iki tarafta varsa ONAY.

05 NLP Fiyatlandırma Motoru

Kullanıcıların SQL veya Python kodu yazmadan, doğal dil ile karmaşık fiyatlandırma senaryoları oluşturmasını sağlayan kural tabanlı bir motordur. parse_natural_language_rules fonksiyonu metni analiz eder.

Desteklenen Komut Yapıları

Döviz İşlemleri

Komut: BOSCH GUNCEL KURA ESITLE

Aksiyon: TCMB'den anlık USD/EUR kurunu çeker ve ürünün baz fiyatını bu kurla çarpar.

Kur Çevrimi (Cross Rate)

Komut: ESKI_KUR=32.50 YENI KURA CEVIR

Formül: (Fiyat / 32.50) * Güncel_Kur

Matematiksel İşlemler

Komut: MAKITA %10 ZAM YAP

Formül: Fiyat * 1.10

Sabitleme

Komut: R18-256 5000 TL OLSUN

Aksiyon: Ürünün fiyatını doğrudan 5000 TL yapar.

06 Teknoloji Yığını

Projede kullanılan kütüphaneler ve versiyon bilgileri:

Bileşen Teknoloji / Kütüphane Kullanım Amacı
Core Python 3.10 Ana programlama dili.
Web Framework Flask 2.x REST API endpoint yönetimi.
Data Processing Pandas, NumPy Vektörel veri işleme ve matris operasyonları.
Machine Learning Scikit-Learn TF-IDF Vektörleştirme ve Cosine Similarity.
File I/O OpenPyXL, Xlrd Excel dosyalarını (.xlsx, .xls) okuma ve yazma modülleri.
Integration Requests TCMB (Merkez Bankası) API XML entegrasyonu.
Server Gunicorn Production seviyesi WSGI uygulama sunucusu.
Deployment Docker, Traefik Konteynerizasyon ve SSL Proxy.

07 Rapor Yorumlama ve Sorumluluk

Sistem çıktısı olan Excel dosyası 3 ana sayfadan oluşur. Ancak bu sonuçlar nihai karar olarak değil, öneri olarak değerlendirilmelidir.

⚠️ YASAL UYARI VE SORUMLULUK REDDİ

Bu yazılım (Stokçu), stok ve fiyat eşleştirmeleri için bir Karar Destek Sistemi (Decision Support System) olarak tasarlanmıştır. Algoritmik eşleştirmeler %100 doğruluk garantisi vermez.

Kullanıcı, pazar yerine veri yüklemeden önce özellikle Algoritma Skoru düşük olan satırları, fiyat farklarını ve stok miktarlarını manuel olarak kontrol etmekle yükümlüdür. Yazılımın ürettiği sonuçlardan doğabilecek ticari zararlardan (yanlış fiyatla satış vb.) geliştirici sorumlu tutulamaz.

Algoritma Skoru Nasıl Yorumlanmalı?

  • Skor > 85 (Yeşil Bölge): Çok Yüksek Güven. Metinler ve kodlar büyük oranda uyuşuyor.
  • Skor 50 - 85 (Sarı Bölge): Orta Güven. İsim benzerliği var ancak model kodu veya paket içeriği farklı olabilir. Kontrol edilmelidir.
  • Skor < 50 (Kırmızı Bölge): Düşük Güven. Eşleşme zayıftır, büyük ihtimalle farklı ürünlerdir. Manuel müdahale şarttır.

08 Kurulum ve Kendi Sunucunuzda Çalıştırma

Stokçu, açık kaynaklı yapısı sayesinde kendi Linux (Ubuntu/Debian) sunucunuzda veya yerel makinenizde Docker kullanılarak kolayca ayağa kaldırılabilir.

Gereksinimler

  • Docker ve Docker Compose
  • Git
  • Minimum 2GB RAM (Pandas işlemleri için)

Adım 1: Projeyi Klonlayın

git clone https://github.com/AhmetKorkmazMe/stok-projesi.git
cd stok-projesi

Adım 2: Yapılandırma ve Derleme

Docker imajını oluşturun ve konteynerleri başlatın. İlk derleme işlemi internet hızınıza bağlı olarak 2-5 dakika sürebilir.

docker-compose build
docker-compose up -d

Adım 3: Erişim

Kurulum tamamlandığında tarayıcınızdan aşağıdaki adrese gidin:

http://localhost:5000

Eğer sunucuda çalıştırıyorsanız http://SUNUCU_IP_ADRESI:5000 adresini kullanın.