862 lines
41 KiB
Markdown
Executable File
862 lines
41 KiB
Markdown
Executable File
# 🤖 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._
|