83 lines
3.8 KiB
Markdown
Executable File
83 lines
3.8 KiB
Markdown
Executable File
# 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`
|