# 🤖 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._