# 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`
