first (part 2: other directories)

mds/archive/01_project_status_and_overview.md

@@ -0,0 +1,82 @@
+# 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`