223 lines
8.7 KiB
Markdown
223 lines
8.7 KiB
Markdown
# Spor Toto Modülü — Changelog
|
||
|
||
**Tarih:** 25 Mart 2026
|
||
**Konu:** Süper Toto (parimutuel bahis) modülünün sıfırdan oluşturulması
|
||
|
||
---
|
||
|
||
## 1. Genel Bakış
|
||
|
||
Süper Toto, İddaa'dan farklı olarak **parimutuel (havuz) sistemi** ile çalışır. 15 maçın sonucunu (1/X/2) doğru tahmin etmeye dayalıdır. Bu modül, Spor Toto bültenlerini resmi API'den çekme, sistem kuponu üretme, sonuç değerlendirme ve havuz analitiği sağlar.
|
||
|
||
---
|
||
|
||
## 2. Veritabanı Değişiklikleri
|
||
|
||
### Yeni Tablolar
|
||
|
||
| Tablo | Açıklama |
|
||
|-------|----------|
|
||
| `toto_bulletins` | Haftalık bülten bilgileri (gameCycleNo, havuz, devir, tarihler) |
|
||
| `toto_bulletin_matches` | Bültendeki 15 maç (takım adları, lig, kickoff, sonuç) |
|
||
| `toto_results` | Bülten sonuçları (15/14/13/12 bilen sayıları ve ödüller) |
|
||
| `toto_coupons` | Kullanıcı kuponları (strateji, kolon sayısı, maliyet) |
|
||
| `toto_columns` | Kupon kolonları (15 karakter tahmin string'i, doğru sayısı) |
|
||
|
||
### Yeni Enumlar
|
||
|
||
- `TotoBulletinStatus`: `UPCOMING`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`
|
||
- `TotoMatchResult`: `HOME`, `DRAW`, `AWAY`
|
||
|
||
### Önemli Alanlar
|
||
|
||
- `toto_bulletin_matches.match_id` → Mevcut `matches` tablosuyla bağlantı (fuzzy match ile doldurulacak)
|
||
- `toto_columns.predictions` → `"1X2102X112X2101"` formatında 15 karakterlik string
|
||
|
||
---
|
||
|
||
## 3. Modül Yapısı
|
||
|
||
```
|
||
src/modules/spor-toto/
|
||
├── dto/spor-toto.dto.ts # CreateBulletinDto, UpdateResultsDto, GenerateColumnsDto
|
||
├── services/
|
||
│ ├── toto-fetcher.service.ts # sportotov2.iddaa.com API entegrasyonu
|
||
│ ├── toto-combinatorics.service.ts # Sistem kuponu üretme (full/reduced)
|
||
│ └── toto-analytics.service.ts # Havuz dağılımı, EV hesabı, devir analizi
|
||
├── spor-toto.controller.ts # 8 REST endpoint
|
||
├── spor-toto.service.ts # Ana iş mantığı (CRUD + orchestration)
|
||
└── spor-toto.module.ts # NestJS modül tanımı
|
||
```
|
||
|
||
---
|
||
|
||
## 4. API Endpoints
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| `POST` | `/spor-toto/sync` | Resmi API'den güncel bülteni çek ve kaydet |
|
||
| `GET` | `/spor-toto/bulletins` | Bülten listesi (status filtresi, limit) |
|
||
| `GET` | `/spor-toto/bulletins/:id` | Bülten detayı (maçlar + sonuçlar dahil) |
|
||
| `POST` | `/spor-toto/bulletins` | Manuel bülten oluşturma |
|
||
| `PATCH` | `/spor-toto/bulletins/:id/results` | Maç sonuçlarını güncelle |
|
||
| `GET` | `/spor-toto/bulletins/:id/stats` | Havuz dağılımı ve EV istatistikleri |
|
||
| `GET` | `/spor-toto/history` | Devir tarihçesi ve trendler |
|
||
| `POST` | `/spor-toto/columns/generate` | Sistem kuponu üret (full/reduced) |
|
||
| `POST` | `/spor-toto/columns/evaluate` | Kolonları sonuçlara karşı değerlendir |
|
||
|
||
---
|
||
|
||
## 5. Servis Detayları
|
||
|
||
### TotoFetcherService
|
||
|
||
- **Kaynak:** `https://sportotov2.iddaa.com/SporToto`
|
||
- `fetchCurrentBulletin()` → Güncel bülten + 15 maç verisi
|
||
- Event adlarını parse edip `homeTeamName` / `awayTeamName` çıkartır
|
||
- Desteklenen lig formatları: `"eventName": "Blackpool-Burton Albion"`
|
||
|
||
### TotoCombinatoricsService
|
||
|
||
- **Full System:** Cartesian product — tüm kombinasyonları üretir
|
||
- Örnek: 5 maçta çift seçim → 2⁵ = 32 kolon
|
||
- **Reduced System:** Belirli bir garanti seviyesiyle kolon sayısını düşürür
|
||
- `generateFullSystem(selections)` → `string[]` (her biri 15 karakter)
|
||
- `evaluateColumns(columns, results)` → `{ column, correctCount }[]`
|
||
|
||
### TotoAnalyticsService
|
||
|
||
- **Havuz dağılımı:** %35 (15 bilen), %20 (14 bilen), %20 (13 bilen), %25 (12 bilen)
|
||
- **Expected Value (EV):** `poolShare × probability - cost`
|
||
- **Devir analizi:** Son N bültenin devir trendi
|
||
|
||
---
|
||
|
||
## 6. Mevcut Durum & Bilinen Sorunlar
|
||
|
||
### ✅ Tamamlanan
|
||
- Veritabanı şeması (raw SQL ile oluşturuldu)
|
||
- Prisma Client türleri üretildi (`totoBulletin`, `totoResult` vs. FOUND)
|
||
- Tüm servisler implement edildi
|
||
- Build başarılı (`nest build` → 0 error)
|
||
- `app.module.ts`'e `SporTotoModule` kayıtlandı
|
||
- **AI Prediction Engine** implement edildi ✅
|
||
|
||
### ⚠️ Bekleyen
|
||
- **Dev server testi:** DB bağlantısı test edilmeli (`npm run start:dev`)
|
||
- **API sync testi:** `/spor-toto/sync` endpoint'inin çalıştığı doğrulanmalı
|
||
- **Canlı prediction testi:** Sync sonrası `POST /spor-toto/predict` çalıştırılmalı
|
||
|
||
---
|
||
|
||
## 7. AI Prediction Engine (Tamamlandı ✅)
|
||
|
||
### Yeni Servis: `toto-prediction.service.ts` (~490 satır)
|
||
|
||
Bülten maçlarını AI Engine ile analiz edip, **contrarian parimutuel strateji** ile akıllı sistem kuponu üreten tahmin motoru.
|
||
|
||
### Çalışma Akışı
|
||
|
||
```
|
||
POST /spor-toto/predict { bulletinId, strategy }
|
||
↓
|
||
1. Bülteni DB'den getir (15 maç)
|
||
↓
|
||
2. Her maç için:
|
||
a) Fuzzy Match Link → live_matches / matches tablosundan matchId bul
|
||
- Normalize: lowercase, Türkçe karakter çevir, ILIKE arama
|
||
- ±3 gün tarih filtresi
|
||
b) AI Engine → /v20plus/analyze/{matchId} çağır
|
||
- Maç Sonucu market'ını bul, pick + confidence al
|
||
- xG bazlı olasılık hesabı
|
||
c) Fallback: AI erişilemezse → Tarihsel form analizi (son 10 maç)
|
||
↓
|
||
3. Contrarian Strateji uygula (maç başı seçim sayısı belirle)
|
||
↓
|
||
4. Combinatorics ile sistem kuponu üret
|
||
↓
|
||
5. EV raporu hesapla → PLAY / WAIT / HIGH_VALUE önerisi
|
||
```
|
||
|
||
### Contrarian Strateji (Fading the Public)
|
||
|
||
Parimutüel'de herkesin bildiği tahmin = düşük ödül. Motor, favori yığılmasının tersine pozisyon alır:
|
||
|
||
| AI Confidence | Seçim | Parimutüel Mantık |
|
||
|--------------|-------|-------------------|
|
||
| ≥ 65% | **Tek** (1/X/2) | Güvenli, ama contrarian bias ile çift olma ihtimali |
|
||
| 50-65% | **İkili** (en olası 2) | Varyans koruması — sürprizleri yakalar |
|
||
| < 50% | **Üçlü** (1X2 kapatma) | Maç çok belirsiz, herkes yanılabilir |
|
||
|
||
### 4 Strateji Modu
|
||
|
||
| Strateji | Max Kolon | Tek Eşiği | Çift Eşiği | Contrarian Bias | Açıklama |
|
||
|----------|----------|-----------|-----------|-----------------|----------|
|
||
| `CONSERVATIVE` | 100 | 55% | 35% | %0 | Düşük bütçe, güvenli |
|
||
| `BALANCED` | 500 | 60% | 40% | %15 | Orta risk, önerilen |
|
||
| `AGGRESSIVE` | 2.500 | 70% | 50% | %30 | Yüksek varyans, 15 bilme şansı |
|
||
| `FORMULA_6PCT` | 2.500 | 60% | 40% | %20 | Tam sistemden %6 örnekleme |
|
||
|
||
### EV-Bazlı Oynama Önerisi
|
||
|
||
Devir miktarına göre otomatik tavsiye:
|
||
- Devir > 50M TL → 🔥 **HIGH_VALUE** — Agresif oyna
|
||
- Devir > 5M TL → ✅ **PLAY** — Oynamaya değer
|
||
- Devir < 5M TL → ⏳ **WAIT** — Havuz büyümesini bekle
|
||
|
||
### Yeni Endpoint
|
||
|
||
| Method | Endpoint | Açıklama |
|
||
|--------|----------|----------|
|
||
| `POST` | `/spor-toto/predict` | AI tahmin + contrarian strateji + sistem kuponu üret |
|
||
|
||
**Request:**
|
||
```json
|
||
{
|
||
"bulletinId": "<uuid>",
|
||
"strategy": "BALANCED",
|
||
"maxBudget": 500
|
||
}
|
||
```
|
||
|
||
**Response:** Match analizi (maç başı AI pick, confidence, contrarian skor), kupon (kolonlar, maliyet), EV raporu (havuz, devir, öneri)
|
||
|
||
---
|
||
|
||
## 8. Dosya Değişiklikleri Özeti
|
||
|
||
| Dosya | Değişiklik |
|
||
|-------|-----------|
|
||
| `prisma/schema.prisma` | +112 satır (5 model, 2 enum) |
|
||
| `src/modules/spor-toto/services/toto-prediction.service.ts` | **YENİ** — AI tahmin motoru (~490 satır) |
|
||
| `src/modules/spor-toto/services/toto-fetcher.service.ts` | Bülten çekici |
|
||
| `src/modules/spor-toto/services/toto-combinatorics.service.ts` | Kolon üretim motoru |
|
||
| `src/modules/spor-toto/services/toto-analytics.service.ts` | Havuz & EV analizi |
|
||
| `src/modules/spor-toto/dto/spor-toto.dto.ts` | +`GeneratePredictionDto`, +`EvaluateColumnsDto` |
|
||
| `src/modules/spor-toto/spor-toto.controller.ts` | +`POST /predict` endpoint |
|
||
| `src/modules/spor-toto/spor-toto.service.ts` | +`TotoPredictionService` entegrasyonu |
|
||
| `src/modules/spor-toto/spor-toto.module.ts` | +`HttpModule`, `ConfigModule`, `TotoPredictionService` |
|
||
| `src/app.module.ts` | `SporTotoModule` import |
|
||
|
||
---
|
||
|
||
## 9. Swagger & Endpoint Summary Güncellemesi
|
||
|
||
### Controller Swagger Dekoratörleri
|
||
|
||
Tüm 10 endpoint'e kapsamlı Swagger dekoratörleri eklendi:
|
||
- `@ApiOperation({ summary, description })` — Her endpoint için detaylı açıklama
|
||
- `@ApiParam({ name, description })` — Path parametreleri (`:id` → Bulletin UUID)
|
||
- `@ApiBody({ type: DtoClass })` — POST/PATCH body DTO referansları
|
||
- `@ApiResponse({ status, description })` — Başarı ve hata durumları (200, 201, 404, 409)
|
||
|
||
### backend_endpoints_swagger_summary.json
|
||
|
||
| Değişiklik | Detay |
|
||
|-----------|-------|
|
||
| Endpoint sayısı | 50 → **60** |
|
||
| Yeni tag | `Spor Toto` (10 endpoint) |
|
||
| Eklenen endpointler | `sync`, `bulletins` (CRUD), `stats`, `history`, `columns/generate`, `columns/evaluate`, `predict` |
|
||
| Yeni DTO şemaları | `CreateBulletinDto`, `UpdateResultsDto`, `GenerateColumnsDto`, `EvaluateColumnsDto`, `GeneratePredictionDto` |
|
||
| Tarih | `2026-02-17` → `2026-03-25` |
|
||
|