Proje Genel Bakış ve Durum Raporu

Tarih: 4 Şubat 2026 Durum: Aktif Geliştirme / Stabilizasyon

1. Proje Özeti

Suggest-Bet-BE, futbol ve basketbol maçları için yapay zeka destekli tahminler üreten, canlı veri akışı sağlayan ve kullanıcıya "Akıllı Kupon" önerileri sunan gelişmiş bir "Betting AI" backend projesidir.

Ana Teknoloji Yığını

Backend: NestJS (TypeScript)
Database: PostgreSQL (Prisma ORM)
AI Engine: Python (PyTorch, V17 Player-Aware Model)
Data Gathering: Puppeteer/Cheerio (Feeder Scraper)
Job Queue: Cron Jobs (NestJS Schedule)

2. Kritik Modüller ve Mimari

A. AI Engine (V17 Player-Aware Model)

Projenin beyni ai-engine/ klasöründedir.

Model: PlayerDeepModelV17 (player_model_v17.py). Oyuncuları embedding vektörleri olarak ele alır, takım kadrosunu toplayarak "takım gücü" çıkarır ve bunu oranlar/form durumu ile birleştirir.
Girdi: Ev/Deplasman ilk 11 ID'leri + 24 boyutlu Context Vektörü (Oranlar, Form, H2H).
Çıktı: Maç Sonucu (1X2), Toplam Gol (Home/Away), BTTS, HT/FT, Alt/Üst Olasılıkları.
Servis: smart_coupon_service.py üzerinden argparse ile CLI olarak çalışır ve JSON çıktı verir.

B. Feeder System (Canlı Veri Akışı)

Canlı ve maç öncesi verileri toplar.

Scraper: FeederScraperService, Mackolik.com üzerinden HTML parse eder.
Persistence: FeederPersistenceService, veriyi DB'ye normalize eder.
Live Sync: Canlı maçlarda veri eksikliği (kadro, oran) durumunda live_matches tablosundaki JSON kolonlarına (odds, lineups) yazar ve oradan okur.

C. Smart Coupon Service (NestJS)

Kullanıcı ile AI arasındaki köprüdür.

Analyze Match: Tek bir maç için Python scriptini çalıştırır.
Kadro Kontrol: Eğer kadro yoksa "Yetersiz Veri" hatası döner (veya auto-fetch dener).
Oran Kontrol: Oran yoksa auto-fetch dener.

3. Son Yapılan Kritik Geliştirmeler (Güncel Durum)

1. Live Sync & DB Safety (Sorun: FK Hataları)

Durum: Canlı maçlar bazen ana matches tablosunda ve ilişkisel tablolarda (match_player_participation) bulunmuyor, sadece live_matches tablosunda oluyordu.
Çözüm: FeederPersistenceService, ana tabloda maç yoksa ilişkisel insert yapmayı durdurdu. Veriyi sadece live_matches.jsonData (lineups/odds) içine yazıyor.
Fallback: Python servisi ve NestJS, veri okurken önce ilişkisel tabloya bakıyor, boşsa JSON kolonuna başvuruyor.

2. Score & Label Consistency (Sorun: Hatalı Skor/Oran Eşleşmesi)

Durum: Modelin 1/1 tahmini X/X çıkıyordu. Mackolik'ten gelen "Beraberlik" oranı X etiketiyle geldiği için model bunu 0 görüp sapıtıyordu.
Çözüm:
- HT/FT etiket sıralaması ht*3 + ft mantığına oturtuldu.
- Oran parse işleminde X ve 0 etiketleri eşitlendi.
- Analiz çıktısına home_team_name ve away_team_name eklendi (Doğrulama için).

3. Score Calibration (Sorun: Uçuk Deplasman Skorları)

Durum: Model deplasman takımlarına çok fazla gol şansı veriyordu (Örn: Deplasman Favori olmasa bile 3-4 gol).
Çözüm: 679 maçlık backtest ile optimizasyon yapıldı.
- HOME_GOAL_SCALE = 1.00 (Değişmedi)
- AWAY_GOAL_SCALE = 0.85 (%15 Törpüleme)
Sonuç: Skor isabeti %16.34'e yükseldi, gol dengesi sağlandı.

4. Önemli Dosya Yolları

AI Model Class: ai-engine/models/player_model_v17.py
Main Prediction Service: ai-engine/services/smart_coupon_service.py
Backtest / Calibration: ai-engine/scripts/backtest_v17_scores.py
Feeder Persistence: src/modules/feeder/feeder-persistence.service.ts
Scraper: src/modules/feeder/feeder-scraper.service.ts
NestJS Coupon Service: src/modules/coupons/services/smart-coupon.service.ts

3.8 KiB Executable File Raw Blame History Unescape Escape