first (part 2: other directories)

2026-04-16 15:11:25 +03:00
parent 7814e0bc6b
commit 2f0b85a0c7
203 changed files with 59989 additions and 0 deletions
@@ -0,0 +1,861 @@
+# 🤖 Suggest-Bet-BE: Yapay Zeka için Tam Proje Rehberi
+
+> **Bu dosya, projenin tamamını tek seferde anlamak isteyen yapay zeka sistemleri için hazırlanmıştır.**  
+> **Tarih:** 13 Şubat 2026  
+> **Versiyon:** V20 "Beast" Ensemble
+
+---
+
+## 📋 İçindekiler
+
+1. [Proje Özeti](#1-proje-özeti)
+2. [Teknoloji Stack'i](#2-teknoloji-stacki)
+3. [Mimari Yapı](#3-mimari-yapı)
+4. [Veritabanı Şeması](#4-veritabanı-şeması)
+5. [AI Engine (V20)](#5-ai-engine-v20)
+6. [Feeder Sistemi](#6-feeder-sistemi)
+7. [API Endpoints](#7-api-endpoints)
+8. [Kullanıcı Sistemi](#8-kullanıcı-sistemi)
+9. [Backtest Sonuçları](#9-backtest-sonuçları)
+10. [Önemli Dosya Yolları](#10-önemli-dosya-yolları)
+11. [Sık Kullanılan Komutlar](#11-sık-kullanılan-komutlar)
+
+---
+
+## 1. Proje Özeti
+
+### Amaç
+
+**Suggest-Bet-BE**, futbol ve basketbol maçları için **yapay zeka destekli tahminler üreten** ve kullanıcılara **"Akıllı Kupon" önerileri sunan** gelişmiş bir **Betting AI backend** projesidir.
+
+### Ana İşlevler
+
+| İşlev                | Açıklama                                      |
+| -------------------- | --------------------------------------------- |
+| **AI Tahmin Motoru** | V20 "Beast" Ensemble model ile maç tahminleri |
+| **Canlı Veri Akışı** | Mackolik.com'dan otomatik veri çekme          |
+| **Akıllı Kupon**     | Kullanıcıya değerli bahis önerileri           |
+| **Risk Analizi**     | Surprise detection ile "trap" maç tespiti     |
+
+### Hedef Marketler
+
+- **Maç Sonucu (1X2)** - Ana güç alanı
+- **Alt/Üst (1.5, 2.5, 3.5)**
+- **Karşılıklı Gol (BTTS)**
+- **İlk Yarı/Sonu (HT/FT)**
+- **Korner & Kart** tahminleri
+
+---
+
+## 2. Teknoloji Stack'i
+
+### Backend
+
+```
+NestJS (TypeScript) - Strict Mode
+├── Prisma ORM (PostgreSQL)
+├── Redis Cache
+├── BullMQ (Job Queue)
+├── JWT + RBAC Auth
+├── nestjs-i18n (Çoklu dil)
+└── Swagger API Docs
+```
+
+### AI Engine
+
+```
+Python 3.10+
+├── XGBoost (6 market modeli)
+├── PyTorch (Player embeddings)
+├── NumPy/Pandas
+└── PostgreSQL bağlantısı
+```
+
+### Data Gathering
+
+```
+Puppeteer + Cheerio
+├── Mackolik.com scraping
+├── Live match tracking
+└── Odds monitoring
+```
+
+### Infrastructure
+
+```
+Docker + Docker Compose
+├── PostgreSQL:15432
+├── Redis:6379
+└── Node.js:3000
+```
+
+---
+
+## 3. Mimari Yapı
+
+### Sistem Akış Diyagramı
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        MACKOLIK.COM                                  │
+│                    (Veri Kaynağı)                                    │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     FEEDER SYSTEM                                    │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
+│  │   Scraper    │→ │ Transformer  │→ │ Persistence  │              │
+│  │  (Puppeteer) │  │  (Normalize) │  │   (Prisma)   │              │
+│  └──────────────┘  └──────────────┘  └──────────────┘              │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     POSTGRESQL DATABASE                              │
+│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐       │
+│  │  matches   │ │live_matches│ │odd_categories│ │predictions│       │
+│  └────────────┘ └────────────┘ └────────────┘ └────────────┘       │
+│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐       │
+│  │   teams    │ │  players   │ │match_player │ │  users    │       │
+│  │            │ │            │ │participation│ │           │       │
+│  └────────────┘ └────────────┘ └────────────┘ └────────────┘       │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     AI ENGINE (V20)                                  │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
+│  │TeamPredictor │ │PlayerPredictor│ │OddsPredictor │ │RefereePred │ │
+│  │  (Form/H2H)  │ │  (Kadro)     │ │  (Piyasa)    │ │  (Hakem)   │ │
+│  └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘ │
+│                             │                                        │
+│                             ▼                                        │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │                    V20 ENSEMBLE                               │   │
+│  │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │   │
+│  │  │MatchResult │ │ OverUnder  │ │ HalfTime   │ │   Risk     │ │   │
+│  │  │ Calculator │ │ Calculator │ │ Calculator │ │ Assessor   │ │   │
+│  │  └────────────┘ └────────────┘ └────────────┘ └────────────┘ │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     NESTJS BACKEND                                   │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
+│  │PredictionsMod│ │ CouponsMod   │ │  AuthMod     │ │ UsersMod   │ │
+│  └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘ │
+│                             │                                        │
+│                             ▼                                        │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │                      REST API                                 │   │
+│  │  GET /predictions/:matchId  POST /coupons  GET /matches      │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                        KULLANICI                                      │
+│              (Web/Mobile Frontend)                                    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Klasör Yapısı
+
+```
+Suggest-Bet-BE/
+├── src/                          # NestJS Backend
+│   ├── main.ts                   # Entry point
+│   ├── app.module.ts             # Root module
+│   ├── common/                   # Shared utilities
+│   │   ├── base/                 # BaseService, BaseController
+│   │   ├── filters/              # Global exception filter
+│   │   ├── interceptors/         # Response wrapper
+│   │   └── types/                # API response types
+│   ├── config/                   # Configuration
+│   ├── database/                 # Prisma service
+│   ├── i18n/                     # Translation files
+│   └── modules/                  # Feature modules
+│       ├── admin/                # Admin panel
+│       ├── auth/                 # Authentication
+│       ├── coupons/              # Coupon system
+│       ├── feeder/               # Data scraping
+│       │   ├── feeder.service.ts
+│       │   ├── feeder-scraper.service.ts
+│       │   ├── feeder-transformer.service.ts
+│       │   └── feeder-persistence.service.ts
+│       ├── gemini/               # Google Gemini AI
+│       ├── health/               # Health checks
+│       ├── leagues/              # League management
+│       ├── matches/              # Match management
+│       ├── predictions/          # AI predictions
+│       │   ├── predictions.service.ts
+│       │   ├── services/
+│       │   │   └── ai-feature-store.service.ts
+│       │   └── queues/
+│       │       └── predictions.processor.ts
+│       └── users/                # User management
+│
+├── ai-engine/                    # Python AI Engine
+│   ├── main.py                   # FastAPI entry
+│   ├── config/
+│   │   └── ensemble_config.yaml  # Model config
+│   ├── core/
+│   │   ├── calculators/          # Market calculators
+│   │   │   ├── match_result_calculator.py
+│   │   │   ├── over_under_calculator.py
+│   │   │   ├── half_time_calculator.py
+│   │   │   ├── score_calculator.py
+│   │   │   ├── risk_assessor.py
+│   │   │   └── bet_recommender.py
+│   │   └── engines/              # Prediction engines
+│   │       ├── team_predictor.py
+│   │       ├── player_predictor.py
+│   │       ├── odds_predictor.py
+│   │       └── referee_predictor.py
+│   ├── features/                 # Feature engineering
+│   │   ├── elo_system.py
+│   │   ├── h2h_engine.py
+│   │   ├── momentum_engine.py
+│   │   ├── poisson_engine.py
+│   │   ├── referee_engine.py
+│   │   ├── squad_analysis_engine.py
+│   │   ├── upset_engine.py
+│   │   └── value_calculator.py
+│   ├── models/                   # ML Models
+│   │   ├── v20_ensemble.py       # Main predictor
+│   │   ├── calibration.py
+│   │   └── xgboost/              # Trained XGBoost models
+│   │       ├── xgb_ms.json       # Maç Sonucu
+│   │       ├── xgb_ou25.json     # Over/Under 2.5
+│   │       ├── xgb_ou15.json     # Over/Under 1.5
+│   │       ├── xgb_ou35.json     # Over/Under 3.5
+│   │       ├── xgb_btts.json     # BTTS
+│   │       └── xgb_ht_ft.json    # HT/FT
+│   ├── scripts/                  # Utility scripts
+│   │   ├── backtest_v20_feb9.py
+│   │   ├── predict_live.py
+│   │   └── extract_training_data.py
+│   └── services/
+│       └── coupon_builder_v2.py
+│
+├── prisma/
+│   ├── schema.prisma             # Database schema
+│   └── seed.ts                   # Initial data
+│
+├── mds/                          # Documentation
+├── scripts/                      # Utility scripts
+├── colab_export/                 # Training data
+├── i18n/                         # Translations
+├── public/                       # Static files
+│
+├── top_leagues.json              # Target leagues (22 lig)
+├── bet-type.json                 # Bet type definitions
+├── docker-compose.yml            # Docker config
+├── package.json
+└── README.md
+```
+
+---
+
+## 4. Veritabanı Şeması
+
+### Entity-Relationship Diyagramı
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Country   │────<│    League   │────<│   Match     │
+└─────────────┘     └─────────────┘     └──────┬──────┘
+                                               │
+                    ┌──────────────────────────┼──────────────────────────┐
+                    │                          │                          │
+                    ▼                          ▼                          ▼
+           ┌───────────────┐          ┌───────────────┐          ┌───────────────┐
+           │OddCategory    │          │MatchPlayer    │          │MatchTeamStats │
+           │               │          │Participation  │          │               │
+           └───────┬───────┘          └───────────────┘          └───────────────┘
+                   │
+                   ▼
+           ┌───────────────┐
+           │OddSelection   │
+           │               │
+           └───────┬───────┘
+                   │
+                   ▼
+           ┌───────────────┐
+           │OddsHistory    │
+           └───────────────┘
+```
+
+### Tablo Açıklamaları
+
+#### Çekirdek Tablolar
+
+| Tablo              | Açıklama            | Önemli Kolonlar                                                                                                  |
+| ------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **`matches`**      | Geçmiş maç verileri | `mstUtc` (timestamp), `scoreHome/Away`, `htScoreHome/Away`, `winner`, `iddaaCode`, `status`, `state`             |
+| **`live_matches`** | Canlı maçlar        | `jsonData`, `odds` (JSON), `lineups` (JSON), `sidelined` (JSON), `refereeName`, `currentMinute`, `momentumScore` |
+| **`teams`**        | Takımlar            | `id`, `name`, `slug`, `sport`, `logoUrl`                                                                         |
+| **`leagues`**      | Ligler              | `id`, `name`, `countryId`, `sport`, `competitionSlug`                                                            |
+| **`players`**      | Oyuncular           | `id`, `name`, `slug`                                                                                             |
+
+#### Oran Tabloları
+
+| Tablo                | Açıklama          | Önemli Kolonlar                              |
+| -------------------- | ----------------- | -------------------------------------------- |
+| **`odd_categories`** | Oran kategorileri | `matchId`, `name` (MS, Alt/Üst, BTTS, HT/FT) |
+| **`odd_selections`** | Oran seçenekleri  | `name` (1, X, 2), `oddValue`, `sov`, `state` |
+| **`odds_history`**   | Oran değişimleri  | `previousValue`, `newValue`, `changeTime`    |
+
+**Örnek Veri Yapısı:**
+
+```
+odd_categories: name = "Maç Sonucu", matchId = "abc123"
+  └── odd_selections:
+        ├── name="1", oddValue="1.50" (Ev sahibi kazanır)
+        ├── name="X", oddValue="4.20" (Beraberlik)
+        └── name="2", oddValue="6.00" (Deplasman kazanır)
+```
+
+#### Kadro & Olay Tabloları
+
+| Tablo                            | Açıklama             | Önemli Kolonlar                                                        |
+| -------------------------------- | -------------------- | ---------------------------------------------------------------------- |
+| **`match_player_participation`** | Maç kadrosu          | `playerId`, `teamId`, `position`, `shirtNumber`, `isStarting`          |
+| **`match_player_events`**        | Olaylar              | `eventType` (GOAL, CARD, SUBSTITUTION), `timeMinute`, `assistPlayerId` |
+| **`match_team_stats`**           | Takım istatistikleri | `possessionPercentage`, `shotsOnTarget`, `corners`, `fouls`            |
+| **`match_officials`**            | Hakemler             | `name`, `roleId`                                                       |
+
+#### AI Tabloları
+
+| Tablo                    | Açıklama                | Önemli Kolonlar                                                                |
+| ------------------------ | ----------------------- | ------------------------------------------------------------------------------ |
+| **`match_ai_features`**  | Hesaplanmış feature'lar | `homeElo`, `awayElo`, `homeFormScore`, `awayFormScore`, `missingPlayersImpact` |
+| **`predictions`**        | Model tahminleri        | `predictionJson` (JSON formatında tüm tahminler)                               |
+| **`ai_predictions_log`** | Performans takibi       | `modelVersion`, `confidenceScore`, `isCorrect`, `accuracyScore`                |
+
+**Örnek `predictions.predictionJson`:**
+
+```json
+{
+  "match_result": {
+    "1": 45.2,
+    "X": 28.1,
+    "2": 26.7,
+    "pick": "1",
+    "confidence": 72.5
+  },
+  "over_under_25": {
+    "over": 55.0,
+    "under": 45.0,
+    "pick": "Over",
+    "confidence": 61.2
+  },
+  "btts": { "yes": 48.3, "no": 51.7, "pick": "No" },
+  "risk_level": "MEDIUM",
+  "xg": { "home": 1.45, "away": 1.12, "total": 2.57 }
+}
+```
+
+#### Kullanıcı Tabloları
+
+| Tablo                   | Açıklama           | Önemli Kolonlar                                                   |
+| ----------------------- | ------------------ | ----------------------------------------------------------------- |
+| **`users`**             | Kullanıcılar       | `email`, `role` (user/admin), `subscriptionStatus` (free/premium) |
+| **`user_coupons`**      | Kuponlar           | `strategy`, `totalOdds`, `status` (PENDING/WON/LOST)              |
+| **`user_coupon_items`** | Kupon kalemleri    | `matchId`, `selection`, `oddAtTime`, `isCorrect`                  |
+| **`usage_limits`**      | Kullanım limitleri | `analysisCount`, `couponCount`, `lastResetDate`                   |
+
+---
+
+## 5. AI Engine (V20)
+
+### V20 "Beast" Ensemble Mimarisi
+
+V20, 4 bağımsız prediction motorunu birleştiren bir ensemble sistemdir:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     V20 ENSEMBLE PREDICTOR                           │
+│                                                                      │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
+│  │TeamPredictor │ │PlayerPredictor│ │OddsPredictor │ │RefereePred │ │
+│  │              │ │              │ │              │ │            │ │
+│  │ • Form       │ │ • Kadro      │ │ • Piyasa     │ │ • Hakem    │ │
+│  │ • H2H        │ │ • Oyuncu     │ │   eğilimi    │ │   istatistik│ │
+│  │ • ELO        │ │   rating     │ │ • Value bet  │ │ • Kart trend│ │
+│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
+│         │                │                │               │        │
+│         └────────────────┴────────────────┴───────────────┘        │
+│                                    │                                 │
+│                                    ▼                                 │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │                    UPSET ENGINE                               │   │
+│  │            (Surprise Detection - Sürpriz Tespiti)             │   │
+│  │  • Favori takımın kaybetme riski                              │   │
+│  │  • Derby tension, motivation gap                              │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+│                                    │                                 │
+│                                    ▼                                 │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │                    MARKET CALCULATORS                         │   │
+│  │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │   │
+│  │  │MatchResult │ │ OverUnder  │ │ HalfTime   │ │   Risk     │ │   │
+│  │  │ Calculator │ │ Calculator │ │ Calculator │ │ Assessor   │ │   │
+│  │  └────────────┘ └────────────┘ └────────────┘ └────────────┘ │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+│                                    │                                 │
+│                                    ▼                                 │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │                    BET RECOMMENDER                            │   │
+│  │            (En iyi bahis önerilerini seçer)                   │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Engine Detayları
+
+| Engine               | Girdi Verileri                          | Çıktı                                   |
+| -------------------- | --------------------------------------- | --------------------------------------- |
+| **TeamPredictor**    | `matches` (geçmiş), `leagues`           | Form skoru, H2H analizi, ELO rating     |
+| **PlayerPredictor**  | `match_player_participation`, `players` | Kadro gücü, eksik oyuncu etkisi         |
+| **OddsPredictor**    | `odd_categories`, `odd_selections`      | Piyasa eğilimi, value bet tespiti       |
+| **RefereePredictor** | `match_officials`                       | Hakem kart ortalaması, fair play skoru  |
+| **UpsetEngine**      | Tüm engine'ler + context                | Surprise risk (LOW/MEDIUM/HIGH/EXTREME) |
+
+### XGBoost Modelleri
+
+| Model Dosyası    | Market           | Açıklama                               |
+| ---------------- | ---------------- | -------------------------------------- |
+| `xgb_ms.json`    | Maç Sonucu (1X2) | Ev, beraberlik, deplasman olasılıkları |
+| `xgb_ou15.json`  | Alt/Üst 1.5      | 1.5 gol üst/alt                        |
+| `xgb_ou25.json`  | Alt/Üst 2.5      | 2.5 gol üst/alt                        |
+| `xgb_ou35.json`  | Alt/Üst 3.5      | 3.5 gol üst/alt                        |
+| `xgb_btts.json`  | BTTS             | Karşılıklı gol var/yok                 |
+| `xgb_ht_ft.json` | HT/FT            | İlk yarı/sonu kombinasyonları          |
+
+### FullMatchPrediction Çıktısı
+
+```python
+@dataclass
+class FullMatchPrediction:
+    # Maç Bilgisi
+    match_id: str
+    home_team: str
+    away_team: str
+
+    # Maç Sonucu (1X2)
+    ms_home_prob: float      # Ev kazanma olasılığı
+    ms_draw_prob: float      # Beraberlik olasılığı
+    ms_away_prob: float      # Deplasman kazanma olasılığı
+    ms_pick: str             # "1", "X", veya "2"
+    ms_confidence: float     # Güven skoru (0-100)
+
+    # Alt/Üst
+    over_25_prob: float
+    under_25_prob: float
+    ou25_pick: str           # "Over" veya "Under"
+
+    # BTTS
+    btts_yes_prob: float
+    btts_no_prob: float
+    btts_pick: str           # "Yes" veya "No"
+
+    # xG (Expected Goals)
+    home_xg: float
+    away_xg: float
+    total_xg: float
+
+    # Skor Tahminleri
+    predicted_ft_score: str  # "2-1"
+    predicted_ht_score: str  # "1-0"
+    ft_scores_top5: List[Dict]  # En olası 5 skor
+
+    # Risk
+    risk_level: str          # "LOW", "MEDIUM", "HIGH", "EXTREME"
+    is_surprise_risk: bool   # Sürpriz riski var mı?
+    risk_warnings: List[str]
+
+    # Öneriler
+    best_bet: MarketPrediction
+    recommended_bets: List[MarketPrediction]
+```
+
+---
+
+## 6. Feeder Sistemi
+
+### Veri Akışı
+
+```
+┌─────────────────┐
+│  MACKOLIK.COM   │
+│                 │
+│ • Livescores    │
+│ • Kadrolar      │
+│ • Oranlar       │
+│ • İstatistikler │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     FeederScraperService                            │
+│                                                                      │
+│  URL: https://www.mackolik.com/perform/p0/ajax/components/          │
+│       competition/livescores/json                                   │
+│                                                                      │
+│  Query Params:                                                       │
+│  • date: YYYY-MM-DD                                                 │
+│  • sport: football/basketball                                       │
+│                                                                      │
+│  Headers:                                                            │
+│  • User-Agent: Mozilla/5.0...                                       │
+│  • X-Requested-With: XMLHttpRequest                                 │
+│  • Accept-Language: tr-TR,tr;q=0.9                                  │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     FeederTransformerService                        │
+│                                                                      │
+│  • Ham JSON → Normalize edilmiş objeler                             │
+│  • Takım isimleri standardizasyonu                                  │
+│  • Oran formatı dönüşümü                                            │
+│  • Timestamp conversion                                             │
+└────────────────────────────┬────────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                     FeederPersistenceService                        │
+│                                                                      │
+│  • matches tablosuna yaz                                            │
+│  • live_matches tablosuna yaz (canlı maçlar)                        │
+│  • odd_categories / odd_selections                                  │
+│  • match_player_participation (kadrolar)                            │
+│  • match_player_events (goller, kartlar)                            │
+│                                                                      │
+│  State Management:                                                   │
+│  • historical_scan_state_football_desc (kaldığı yer)                │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Feeder Scriptleri
+
+| Script                     | Komut                       | Açıklama                      |
+| -------------------------- | --------------------------- | ----------------------------- |
+| `run-feeder.ts`            | `npm run feeder:historical` | Tüm tarihsel veri (2.5 sezon) |
+| `run-feeder-filtered.ts`   | `npm run feeder:fill-gaps`  | Sadece top 22 lig             |
+| `run-feeder-basketball.ts` | `npm run feeder:basketball` | Basketbol verileri            |
+| `run-live-feeder.ts`       | `npm run feeder:live`       | Canlı maç takibi              |
+
+### fill-gaps Script Detayı
+
+```typescript
+// src/scripts/run-feeder-filtered.ts
+
+// 1. top_leagues.json'dan lig ID'lerini oku (22 lig)
+const targetLeagues = JSON.parse(fs.readFileSync('top_leagues.json'));
+
+// 2. Tarih aralığı: 2023-07-01 → Dün
+const START_DATE = '2023-07-01';
+
+// 3. Reverse scan (geriye doğru)
+// Dün'den başlayıp 2023-07-01'e kadar gider
+
+// 4. Her gün için:
+//    - Mackolik API'den livescores çek
+//    - Sadece top_leagues'deki maçları işle
+//    - Zaten DB'de olanları atla
+//    - Her 10 maçta 4 saniye cooldown
+
+// 5. State kaydet (kaldığı yerden devam et)
+```
+
+### Top Leagues (22 Lig)
+
+```json
+[
+  "Premier League (İngiltere)",
+  "La Liga (İspanya)",
+  "Serie A (İtalya)",
+  "Bundesliga (Almanya)",
+  "Ligue 1 (Fransa)",
+  "Süper Lig (Türkiye)",
+  "Eredivisie (Hollanda)",
+  "Primeira Liga (Portekiz)",
+  "Pro League (Belçika)",
+  "Bundesliga (Avusturya)",
+  "Super League (İsviçre)",
+  "Scottish Premiership (İskoçya)",
+  "Championship (İngiltere)",
+  "La Liga 2 (İspanya)",
+  "Serie B (İtalya)",
+  "2. Bundesliga (Almanya)",
+  "Ligue 2 (Fransa)",
+  "Primera Division (Arjantin)"
+  // ... ve daha fazlası
+]
+```
+
+---
+
+## 7. API Endpoints
+
+### Authentication
+
+| Method | Endpoint         | Açıklama                 |
+| ------ | ---------------- | ------------------------ |
+| POST   | `/auth/register` | Yeni kullanıcı kaydı     |
+| POST   | `/auth/login`    | Giriş (JWT döner)        |
+| POST   | `/auth/refresh`  | Token yenileme           |
+| GET    | `/auth/me`       | Mevcut kullanıcı bilgisi |
+
+### Matches
+
+| Method | Endpoint              | Açıklama                 |
+| ------ | --------------------- | ------------------------ |
+| GET    | `/matches`            | Maç listesi (pagination) |
+| GET    | `/matches/:id`        | Tek maç detayı           |
+| GET    | `/matches/live`       | Canlı maçlar             |
+| GET    | `/matches/date/:date` | Tarihe göre maçlar       |
+
+### Predictions
+
+| Method | Endpoint                    | Açıklama             |
+| ------ | --------------------------- | -------------------- |
+| GET    | `/predictions/:matchId`     | Maç tahmini          |
+| POST   | `/predictions/analyze`      | Toplu analiz         |
+| GET    | `/predictions/smart-coupon` | Akıllı kupon önerisi |
+
+### Coupons
+
+| Method | Endpoint              | Açıklama               |
+| ------ | --------------------- | ---------------------- |
+| POST   | `/coupons`            | Yeni kupon oluştur     |
+| GET    | `/coupons`            | Kullanıcının kuponları |
+| GET    | `/coupons/:id`        | Kupon detayı           |
+| PATCH  | `/coupons/:id/status` | Kupon durumu güncelle  |
+
+### Leagues
+
+| Method | Endpoint               | Açıklama    |
+| ------ | ---------------------- | ----------- |
+| GET    | `/leagues`             | Lig listesi |
+| GET    | `/leagues/:id`         | Lig detayı  |
+| GET    | `/leagues/:id/matches` | Lig maçları |
+
+### Admin
+
+| Method | Endpoint           | Açıklama              |
+| ------ | ------------------ | --------------------- |
+| GET    | `/admin/users`     | Kullanıcı listesi     |
+| PATCH  | `/admin/users/:id` | Kullanıcı güncelle    |
+| GET    | `/admin/stats`     | Sistem istatistikleri |
+
+---
+
+## 8. Kullanıcı Sistemi
+
+### Roller
+
+| Rol     | Yetkiler                            |
+| ------- | ----------------------------------- |
+| `user`  | Tahmin görüntüleme, kupon oluşturma |
+| `admin` | Tüm yetkiler + kullanıcı yönetimi   |
+
+### Abonelik
+
+| Durum     | Limitler                 |
+| --------- | ------------------------ |
+| `free`    | Günlük 3 analiz, 1 kupon |
+| `premium` | Sınırsız analiz ve kupon |
+
+### Kullanım Limiti Sistemi
+
+```typescript
+// Her kullanıcı için usage_limits tablosu
+{
+  analysisCount: 3,      // Bugün yapılan analiz sayısı
+  couponCount: 1,        // Bugün oluşturulan kupon
+  lastResetDate: "2026-02-13"  // Son sıfırlama tarihi
+}
+
+// Her gece 00:00'da sıfırlanır
+```
+
+---
+
+## 9. Backtest Sonuçları
+
+### 90 Günlük Performans (V11 Referans)
+
+| Market  | Güven Eşiği | Bahis Sayısı | Kazanma Oranı | ROI             |
+| ------- | ----------- | ------------ | ------------- | --------------- |
+| **1X2** | >%0         | 5,709        | %37.6         | **+%18.65** ✅  |
+| **1X2** | >%60        | 4,694        | %37.9         | **+%15.30** ✅  |
+| **1X2** | >%70        | 12           | %83.3         | **+%632.92** 💎 |
+| O/U 2.5 | >%70        | 2,756        | %61.1         | -%7.14 ❌       |
+| BTTS    | >%0         | 5,709        | %47.8         | -%6.11 ❌       |
+
+### Analiz
+
+**Güçlü Yönler:**
+
+- Maç Sonucu (1X2) tahminlerinde %18.65 ROI - profesyonel seviye
+- Yüksek güven (>70) ile %83.3 isabet - neredeyse hatasız
+
+**Zayıf Yönler:**
+
+- Gol marketleri (O/U, BTTS) negatif ROI
+- xG hesaplamasında iyileştirme gerekiyor
+
+**Öneri:**
+
+- 1X2 marketine odaklan
+- Confidence >%60 filtresi kullan
+- Gol marketlerinden kaçın (model iyileştirilene kadar)
+
+---
+
+## 10. Önemli Dosya Yolları
+
+### AI Engine
+
+| Dosya                                         | Açıklama             |
+| --------------------------------------------- | -------------------- |
+| `ai-engine/models/v20_ensemble.py`            | Ana predictor sınıfı |
+| `ai-engine/core/engines/team_predictor.py`    | Team engine          |
+| `ai-engine/core/engines/player_predictor.py`  | Player engine        |
+| `ai-engine/core/engines/odds_predictor.py`    | Odds engine          |
+| `ai-engine/core/engines/referee_predictor.py` | Referee engine       |
+| `ai-engine/features/upset_engine.py`          | Surprise detection   |
+| `ai-engine/scripts/backtest_v20_feb9.py`      | Backtest scripti     |
+| `ai-engine/scripts/predict_live.py`           | Canlı tahmin         |
+
+### Backend
+
+| Dosya                                                  | Açıklama             |
+| ------------------------------------------------------ | -------------------- |
+| `src/modules/feeder/feeder.service.ts`                 | Feeder orchestration |
+| `src/modules/feeder/feeder-scraper.service.ts`         | Mackolik scraping    |
+| `src/modules/feeder/feeder-persistence.service.ts`     | DB yazma             |
+| `src/modules/predictions/predictions.service.ts`       | Tahmin servisi       |
+| `src/modules/coupons/services/smart-coupon.service.ts` | Kupon oluşturma      |
+| `src/scripts/run-feeder-filtered.ts`                   | fill-gaps scripti    |
+
+### Config
+
+| Dosya                                   | Açıklama                  |
+| --------------------------------------- | ------------------------- |
+| `prisma/schema.prisma`                  | Veritabanı şeması         |
+| `top_leagues.json`                      | Hedef ligler (22 adet)    |
+| `ai-engine/config/ensemble_config.yaml` | Model konfigürasyonu      |
+| `.env.example`                          | Ortam değişkenleri örneği |
+
+---
+
+## 11. Sık Kullanılan Komutlar
+
+### Geliştirme
+
+```bash
+# Bağımlılıkları yükle
+npm ci
+
+# Geliştirme sunucusu başlat
+npm run start:dev
+
+# Production build
+npm run build
+npm run start:prod
+
+# Lint
+npm run lint
+
+# Test
+npm run test
+```
+
+### Veritabanı
+
+```bash
+# Prisma client oluştur
+npx prisma generate
+
+# Migration çalıştır
+npx prisma migrate dev
+
+# Seed (ilk veriler)
+npx prisma db seed
+
+# Studio (GUI)
+npx prisma studio
+```
+
+### Feeder
+
+```bash
+# Tarihsel veri çek (tüm ligler)
+npm run feeder:historical
+
+# Eksik verileri tamamla (top 22 lig)
+npm run feeder:fill-gaps
+
+# Basketbol verileri
+npm run feeder:basketball
+
+# Canlı maç takibi
+npm run feeder:live
+
+# Canlı maç temizleme
+npm run cleanup:live
+```
+
+### Docker
+
+```bash
+# Tüm servisleri başlat
+docker-compose up -d
+
+# Sadece DB ve Redis
+docker-compose up -d postgres redis
+
+# Logları görüntüle
+docker-compose logs -f
+
+# Durdur
+docker-compose down
+```
+
+### AI Engine
+
+```bash
+# Canlı tahmin
+cd ai-engine
+python scripts/predict_live.py --match_id <MATCH_ID>
+
+# Backtest
+python scripts/backtest_v20_feb9.py
+
+# Eğitim verisi çıkar
+python scripts/extract_training_data.py
+```
+
+---
+
+## 🎯 Özet
+
+**Suggest-Bet-BE**, futbol maçları için V20 Ensemble AI modeli kullanarak tahmin üreten, Mackolik.com'dan otomatik veri çeken, ve kullanıcılara akıllı kupon önerileri sunan kapsamlı bir bahis AI sistemidir.
+
+**Ana Güç:** Maç Sonucu (1X2) tahminlerinde %18.65 ROI
+
+**Teknoloji:** NestJS + PostgreSQL + Python (XGBoost) + Redis
+
+**Veri Kaynağı:** Mackolik.com (scraping)
+
+**Hedef:** Profesyonel seviyede bahis tahminleri ile kullanıcıya değer sağlamak
+
+---
+
+_Bu dosya yapay zeka sistemleri için hazırlanmıştır. Tüm teknik detaylar güncel ve doğrudur._